12.9. CLI 참조¶
aigo CLI 도구는 Backend.AI GO 관리 API에 대한 커맨드라인 접근을 제공합니다. 이 도구를 사용하여 터미널에서 로컬 모델을 관리하고, 추론 서버를 제어하며, 시스템 리소스를 모니터링하고, 로드된 모델과 상호 작용할 수 있습니다.
설치¶
CLI는 Backend.AI GO 배포판에 포함되어 있습니다. 소스에서 빌드하는 경우 다음 명령을 사용합니다:
사용법¶
자동 발견 (Auto-Discovery)¶
--endpoint를 지정하지 않으면, CLI는 관리 API 서버가 시작 시 기록한 발견 파일을 읽어 실행 중인 Backend.AI GO 인스턴스를 자동으로 발견합니다. 로컬에서 실행 중인 인스턴스에 연결하는 일반적인 경우 별도의 설정이 필요하지 않습니다.
엔드포인트 결정 우선순위:
--endpoint플래그 또는BACKEND_AI_GO_ENDPOINT환경 변수 (명시적 재정의)- 구성 파일 엔드포인트 (
aigo config set endpoint ...로 기본값을 변경한 경우) - 자동 발견 파일 (로컬 인스턴스가 실행 중이고 정상인 경우)
- 기본 폴백:
http://127.0.0.1:8001
OS별 발견 파일 위치:
- macOS:
~/Library/Application Support/ai.backend.go/mgmt-api.json - Linux:
$XDG_RUNTIME_DIR/ai.backend.go/mgmt-api.json(폴백:~/.config/ai.backend.go/mgmt-api.json) - Windows:
%APPDATA%\ai.backend.go\mgmt-api.json
연결하기 전에 CLI는 서버 프로세스(PID로 식별)가 여전히 실행 중인지 확인하고 엔드포인트가 상태 확인에 응답하는지 검증하여 발견 파일을 유효성 검사합니다. 충돌한 인스턴스로부터 남겨진 오래된 파일은 자동으로 무시됩니다.
전역 옵션 (Global Options)¶
| 옵션 | 단축 | 환경 변수 | 설명 |
|---|---|---|---|
--endpoint | -e | BACKEND_AI_GO_ENDPOINT | 관리 API 엔드포인트 (URL 또는 설정된 이름). 자동 발견을 재정의합니다. |
--token | -t | BACKEND_AI_GO_TOKEN | API 인증 토큰. |
--output | -o | BACKEND_AI_GO_OUTPUT | 출력 형식: console, json, yaml. |
--quiet | -q | 필수적이지 않은 출력을 억제합니다. | |
--verbose | -v | 상세 출력을 활성화합니다. | |
--no-verify-ssl | SSL 인증서 검증을 건너뜁니다. |
명령어 (Commands)¶
chat - 단발성 채팅 완성¶
로드된 모델에 메시지 하나를 보내고 응답을 출력합니다.
MESSAGE를 생략하면 stdin에서 입력을 읽습니다 (최대 1 MiB).
옵션:
| 옵션 | 단축 | 설명 |
|---|---|---|
--model <MODEL> | -m | 완성에 사용할 모델. |
--max-tokens <INT> | 생성할 최대 토큰 수 (기본값: 1024). | |
--temperature <FLOAT> | 샘플링 온도 0.0–2.0 (기본값: 0.7). --reasoning-effort 설정 시 무시됩니다. | |
--system <PROMPT> | -s | 앞에 추가할 시스템 프롬프트. |
--reasoning-effort <LEVEL> | 하이브리드 사고 모델의 추론 노력 수준. 허용 값: none, low, medium, high, xhigh. none으로 설정하면 chat_template_kwargs를 통해 사고 모드를 비활성화합니다. | |
--no-think | 사고 모드 비활성화 (chat_template_kwargs.enable_thinking=false 설정). --reasoning-effort보다 우선 적용됩니다. | |
--thinking-budget <N> | <think> 블록 안에서 모델이 출력할 수 있는 토큰 수의 요청별 상한값으로, 요청 본문에 thinking_budget_tokens 필드로 전송됩니다. -1이면 무제한(엔진 기본값), 0이면 즉시 종료(thinking 비활성화), N>0이면 N개 토큰의 하드 캡입니다. 엔진 비종속적이라 llama-server와 mlxcel-server 양쪽에서 동일하게 동작합니다. | |
--preserve-thinking | 이전 어시스턴트 턴들의 <think> 블록을 제거하지 않고 그대로 유지합니다(Qwen3.6+ 기능). chat_template_kwargs.preserve_thinking=true를 설정하는데, --no-think / --reasoning-effort와는 직교 관계라서 플래그를 함께 쓰면 양쪽 kwarg가 공존합니다. 그 이전 Qwen3/3.5 모델들은 플래그를 받기는 하지만 동작은 보장되지 않습니다. |
--reasoning-effort를 none 이외의 값으로 설정하면 요청에 reasoning_effort와 chat_template_kwargs: {"enable_thinking": true}가 함께 전송됩니다. none으로 설정하거나 --no-think를 사용하면 chat_template_kwargs: {"enable_thinking": false}만 전송되는데, 이것이 Qwen3/3.5 하이브리드 사고 모델에서 <think> 블록을 억제하는 올바른 방법입니다.
--thinking-budget와 --preserve-thinking는 --reasoning-effort와 독립적으로 동작하는데, 전자는 모델이 <think> 안에서 출력할 수 있는 토큰 수를 제한하고 후자는 이전 <think> 블록을 프롬프트에 남겨둘지를 결정합니다. 두 필드 모두 요청 본문에 그대로 실려가기 때문에 llama-server와 mlxcel-server로 변형 없이 전달되고, 중간에 continuum-router가 있어도 그대로 통과합니다.
예제:
# 기본 채팅
aigo chat "프랑스의 수도는 어디입니까?"
# Qwen3 모델에서 사고 모드 비활성화
aigo chat --no-think "이 문서를 요약해 주세요" < report.txt
# 중간 노력으로 사고 활성화
aigo chat --reasoning-effort medium "단계별로 풀어보세요: ..."
# thinking을 64토큰으로 제한 (간결한 추론 강제)
aigo chat --thinking-budget 64 --reasoning-effort high "빠르게: 2+2=?"
# 예산으로 thinking 비활성화 (이 기능을 구현한 엔진에서는 --no-think와 동등)
aigo chat --thinking-budget 0 "그냥 바로 답해주세요."
# Qwen3.6+에서 턴 간 <think> 블록 보존 (에이전트 KV 캐시 재사용 향상)
aigo chat --preserve-thinking --reasoning-effort high "방금 풀던 문제 이어서 풀어줘."
# 시스템 프롬프트와 함께 stdin 입력 파이프
echo "SELECT * FROM users" | aigo chat --system "당신은 SQL 전문가입니다."
complete - 단발성 텍스트 완성¶
텍스트 완성 형식(비채팅)으로 프롬프트를 전송합니다.
PROMPT를 생략하면 stdin에서 입력을 읽습니다.
옵션:
| 옵션 | 단축 | 설명 |
|---|---|---|
--model <MODEL> | -m | 사용할 모델. |
--max-tokens <INT> | 생성할 최대 토큰 수 (기본값: 256). | |
--temperature <FLOAT> | 샘플링 온도 0.0–2.0 (기본값: 0.7). |
config - 구성 관리¶
CLI 구성 설정을 관리합니다.
aigo config path: 구성 파일 경로를 표시합니다.aigo config get <KEY>: 구성 값을 가져옵니다.aigo config set <KEY> <VALUE>: 구성 값을 설정합니다.aigo config list: 모든 구성 값을 나열합니다.aigo config reset: 구성을 기본값으로 초기화합니다.
model - 로컬 모델 관리¶
로컬 디스크에 저장된 모델을 관리합니다.
aigo model list: 모든 로컬 모델을 나열합니다.aigo model info <MODEL_ID>: 특정 모델에 대한 자세한 정보를 가져옵니다.aigo model refresh: 모델 인덱스를 새로 고침합니다 (새 파일 검색).
loaded - 로드된 모델 작업¶
현재 추론을 위해 메모리에 로드된 모델을 제어합니다.
aigo loaded list: 현재 로드된 모델을 나열합니다.aigo loaded info <ID>: 로드된 모델 인스턴스의 세부 정보를 가져옵니다.aigo loaded load [OPTIONS] <MODEL_ID>: 모델을 메모리에 로드합니다.- 옵션:
-c, --context-length <INT>: 컨텍스트 길이 재설정.-g, --gpu-layers <INT>: GPU로 오프로드할 레이어 수 (-1은 전체).-t, --threads <INT>: 사용할 스레드 수.-a, --alias <STRING>: 라우팅을 위한 모델 별칭.--tool-calling: 도구 호출(Tool calling) 기능 활성화.--mmproj <PATH>: 비전 모델을 위한 mmproj 파일 경로.
- 옵션:
aigo loaded unload <ID>: 리소스를 확보하기 위해 모델을 언로드합니다.aigo loaded health <ID>: 로드된 모델의 상태를 확인합니다.
router - 라우터 제어¶
Continuum Router 서비스를 관리합니다.
aigo router status: 라우터의 현재 상태를 가져옵니다.aigo router start: 라우터 서비스를 시작합니다.aigo router stop: 라우터 서비스를 중지합니다.aigo router restart: 라우터 서비스를 다시 시작합니다.aigo router verify-endpoint --json <BODY>: Anthropic 호환 엔드포인트를 프로브합니다. 본문(--json또는--file)에는baseUrl,apiKey,model이 담기며, API 키는 요청에만 실리고 출력으로 다시 노출되지 않습니다.
system - 시스템 모니터링¶
하드웨어 리소스 및 API 상태를 모니터링합니다.
aigo system info: 일반 시스템 정보(OS, 아키텍처)를 가져옵니다.aigo system metrics: 현재 시스템 지표(CPU, RAM 사용량)를 가져옵니다.aigo system gpu: 상세 GPU 정보를 가져옵니다.aigo system health: 전체 API 상태를 확인합니다.aigo system version: API 서버 버전을 가져옵니다.
extension - 확장 스킬 및 가져오기¶
Claude Code / Codex 스킬을 관리하고 서브에이전트 / AGENTS.md 정의를 가져옵니다. 본문이 복잡한 명령은 --json <STRING> 또는 --file <PATH>를 받습니다.
aigo extension skill list: 설치된 스킬을 나열합니다.aigo extension skill show <ID>: 스킬을 표시합니다.aigo extension skill create --json <BODY>: 스킬을 생성합니다(ExtensionSkill 형태).aigo extension skill update <ID> --json <BODY>: 스킬을 수정합니다.aigo extension skill delete <ID> [-y]: 스킬을 삭제합니다.aigo extension skill enable <ID>/disable <ID>: 스킬을 켜거나 끕니다.aigo extension skill invoke <ID> [--json <BODY>]: 스킬을 호출용으로 렌더링합니다(본문 미지정 시{}).aigo extension skill import-file <PATH>: 서버의 파일 경로에서 스킬을 가져옵니다.aigo extension skill import-url <URL>:https://URL에서 스킬을 가져옵니다.aigo extension skill parse --json <BODY>: 스킬 콘텐츠를 파싱합니다(content/sourceHint).aigo extension skill activation-preview --json <BODY>: 스킬 콘텐츠의 권한 매핑을 미리 봅니다.aigo extension skill fork preview --json <BODY>/fork run --json <BODY>:context: fork스킬을 미리 보거나 실행합니다.aigo extension agent parse --json <BODY>/agent import --json <BODY>: 서브에이전트 /AGENTS.md를 에이전트 프로필로 미리 보거나 가져옵니다.aigo extension discover: 디스크에서 가져올 수 있는 Claude Code / Codex 아티팩트를 탐색합니다.
session - 세션 관리¶
추론 및 스쿼드 에이전트 세션을 관리합니다(전역 세션 영역으로, aigo squad session과 구분됩니다).
aigo session list: 활성 세션을 나열합니다.aigo session show <ID>: 세션을 표시합니다.aigo session terminate <ID> [-y]: 활성 세션을 종료합니다.aigo session alias <ID> <ALIAS>: 실행 중인 LLM 서빙 세션의 모델 별칭을 변경합니다.aigo session diagnostics <ID>: 진단 스냅샷을 표시합니다.aigo session history list: 종료된 세션 기록을 나열합니다.aigo session history show <ID>: 기록 항목을 표시합니다.aigo session history delete <ID> [-y]: 기록 항목을 삭제합니다.aigo session history clear [-y]: 모든 기록 항목을 삭제합니다.
실시간 SSE 테일(GET /api/v1/sessions/events)은 CLI 명령으로 제공되지 않습니다. 실시간 추적이 필요하면 관리 API 이벤트 스트림을 직접 구독하세요.
squad discussion - 토론 룸¶
기존 aigo squad 그룹 아래의 토론 룸 하위 명령입니다.
aigo squad discussion create --json <BODY>: 룸을 생성합니다(본문에squadId/topic포함).aigo squad discussion list <SQUAD_ID>/list-completed <SQUAD_ID>: 룸을 나열합니다.aigo squad discussion show <ID>/delete <ID> [-y]: 룸을 표시하거나 삭제합니다.aigo squad discussion start|pause|resume|stop <ID>: 오케스트레이터를 제어합니다.aigo squad discussion post <ID> --message <TEXT>: 메시지를 큐에 넣습니다(또는--json/--file).aigo squad discussion cancel-message <ID> <MESSAGE_ID>: 큐에 있는 메시지를 취소합니다.aigo squad discussion mode <ID> <MODE>: 모드를 설정합니다(moderated/brainstorm).aigo squad discussion strategy <ID> [STRATEGY]: 전략 재정의를 설정하거나 해제합니다(moderated/brainstorm/roundRobin/autonomous; 생략하거나none/clear로 초기화).aigo squad discussion turn-budget <ID> <N>: 턴 예산을 설정합니다.aigo squad discussion conclude <ID> [--force]: 결론을 합성합니다.aigo squad discussion handoff <ID>: 핸드오프 요청을 만듭니다.aigo squad discussion export <ID> [--format <FMT>]: 전사본을 내보냅니다(markdown/json/plainText).aigo squad discussion analytics <ID>: 토론 분석을 표시합니다.aigo squad template install --path <PATH> [--source-id <ID>]: 레지스트리 카탈로그에서 스쿼드 템플릿을 설치합니다.
engine container - 컨테이너 추론 엔진¶
기존 aigo engine 그룹 아래의 컨테이너 추론 엔진 세션(vLLM / SGLang)입니다.
aigo engine container start --json <BODY>: 세션을 시작합니다(본문에engineId/modelId/modelPath포함).aigo engine container stop <SESSION_ID>: 세션을 중지합니다.aigo engine container readiness [--json <BODY>]: 준비 상태 보고서를 표시합니다.aigo engine container logs <SESSION_ID>: 엔진 로그를 출력합니다.aigo engine container image inspect <ENGINE_ID>: 이미지를 점검합니다(존재 여부, 크기, 레퍼런스).aigo engine container image pull <ENGINE_ID> [--force]: 이미지를 받거나 갱신합니다.aigo engine container image remove <ENGINE_ID> [-y]: 이미지를 제거합니다.
provider login / provider capabilities¶
기존 aigo provider 그룹 아래의 Codex OAuth 디바이스 플로우 및 기능 탐지입니다.
aigo provider login start <PROVIDER_ID>: 디바이스 플로우 로그인을 시작합니다(verificationUri/userCode반환; 토큰은 서버에 저장되며 출력되지 않습니다).aigo provider login poll <LOGIN_SESSION_ID>: 디바이스 토큰 엔드포인트를 한 번 폴링합니다.aigo provider login cancel <LOGIN_SESSION_ID>: 로그인 세션을 취소합니다.aigo provider login revoke <PROVIDER_ID>: 저장된 토큰을 폐기합니다.aigo provider capabilities show <ID>: 캐시된 프로바이더 기능을 표시합니다.aigo provider capabilities detect <ID> [--force]: 프로바이더 수준 기능을 탐지합니다.aigo provider capabilities detect-with-models <ID> [--force]: 프로바이더와 모델별 레코드를 함께 탐지합니다.aigo provider capabilities models <ID>: 캐시된 모델별 레코드를 나열합니다.aigo provider capabilities model <ID> <MODEL_ID>: 한 모델의 레코드를 표시합니다.aigo provider capabilities model-detect <ID> <MODEL_ID> [--force]: 한 모델의 기능을 탐지합니다.aigo provider capabilities override <ID> <MODEL_ID> --json <BODY>: 수동 재정의를 설정합니다(ModelCapabilityOverrideInput).
예제¶
모든 사용 가능한 모델을 JSON 형식으로 나열:
특정 모델 로드 (GPU 레이어 지정):
시스템 GPU 상태 확인:
설치된 확장 스킬을 JSON으로 나열:
토론 룸 생성 후 시작:
aigo squad discussion create --json '{"squadId":"sq-1","topic":"릴리스 계획"}'
aigo squad discussion start <DISCUSSION_ID>
컨테이너 vLLM 엔진 세션 시작: