콘텐츠로 이동

CLI 참조

aigo CLI 도구는 Backend.AI GO 관리 API에 대한 커맨드라인 접근을 제공합니다. 이 도구를 사용하여 터미널에서 로컬 모델을 관리하고, 추론 서버를 제어하며, 시스템 리소스를 모니터링하고, 로드된 모델과 상호 작용할 수 있습니다.

설치

CLI는 Backend.AI GO 배포판에 포함되어 있습니다. 소스에서 빌드하는 경우 다음 명령을 사용합니다:

cd cli
cargo install --path .

사용법

aigo [OPTIONS] <COMMAND>

자동 발견 (Auto-Discovery)

--endpoint를 지정하지 않으면, CLI는 관리 API 서버가 시작 시 기록한 발견 파일을 읽어 실행 중인 Backend.AI GO 인스턴스를 자동으로 발견합니다. 로컬에서 실행 중인 인스턴스에 연결하는 일반적인 경우 별도의 설정이 필요하지 않습니다.

엔드포인트 결정 우선순위:

  1. --endpoint 플래그 또는 BACKEND_AI_GO_ENDPOINT 환경 변수 (명시적 재정의)
  2. 구성 파일 엔드포인트 (aigo config set endpoint ...로 기본값을 변경한 경우)
  3. 자동 발견 파일 (로컬 인스턴스가 실행 중이고 정상인 경우)
  4. 기본 폴백: 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로 식별)가 여전히 실행 중인지 확인하고 엔드포인트가 상태 확인에 응답하는지 검증하여 발견 파일을 유효성 검사합니다. 충돌한 인스턴스로부터 남겨진 오래된 파일은 자동으로 무시됩니다.

최상위 명령어 인덱스

CLI에는 많은 최상위 명령어가 있습니다. 아래 표는 cli/src/commands/mod.rs에서 가져온 현재 명령어 그룹의 기준 인덱스입니다.

정확한 플래그와 중첩 하위 명령은 항상 aigo <command> --help와 필요시 aigo <command> <subcommand> --help를 사용하세요. 아래 본문은 자주 쓰는 흐름의 예제를 유지하지만, 전체 플래그 덤프를 대신하지는 않습니다.

명령어 용도
bench 벤치마크 관리
events 관리 API 이벤트 스트림과 follow 모드
config CLI 설정
model 로컬 모델 관리
loaded 로드된 모델 작업
pool 모델 풀 관리
router 라우터 제어
system 시스템 모니터링과 버전 정보
hf Hugging Face 연동
engine 추론 엔진 관리
provider 클라우드 프로바이더 관리와 capability probe
settings 애플리케이션 설정 관리
storage 저장소 사용량과 디스크 지표
monitor 모니터링 서비스 제어
search-key 검색 API 키 관리
stats API 사용 통계
log 로그 파일 관리
conversation 대화 관리
folder 대화 폴더 관리
memory 메모리 네임스페이스, 항목, 컨텍스트, 유지보수
data 데이터 허브 문서 관리
plugin 플러그인 관리
mcp MCP 서버 관리
schedule 작업 스케줄 관리
lifecycle 모델 수명주기 작업
key 액세스 키 관리
diffusion diffusion 모델 관리와 이미지 생성
image 생성 이미지 관리
audio 오디오 전사와 처리
translate 텍스트 번역
glossary 번역 용어집 관리
agent-profile 에이전트 프로필 관리
agent-registry 에이전트 레지스트리 관리
agent 에이전트 런타임 실행
autonomous autonomous-agent 프로바이더 작업
node 노드 공유와 분산 라우팅
mesh mesh 연결 관리
squad 멀티 에이전트 squad 관리
supervisor supervisor 정책, 감사, 웹훅
cowork 협업 워크스페이스 관리
extension extension skill과 AGENTS 가져오기
session 추론 및 squad-agent 세션
chat 단발성 채팅 완성
complete 단발성 텍스트 완성

전역 옵션 (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 - 단발성 채팅 완성

로드된 모델에 메시지 하나를 보내고 응답을 출력합니다.

aigo chat [OPTIONS] [MESSAGE]

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 - 단발성 텍스트 완성

텍스트 완성 형식(비채팅)으로 프롬프트를 전송합니다.

aigo complete [OPTIONS] [PROMPT]

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 아티팩트를 탐색합니다.

events - 실시간 이벤트 스트림

관리 API 이벤트 버스를 스크립트에서 따라갑니다. aigo events는 버스 전체를 전달하며 admin 스코프가 필요하고, 아래의 도메인별 감시 명령은 해당 도메인의 읽기 스코프만 있으면 됩니다. 데이터 허브를 읽을 수 있는 키는 데이터 허브만 감시할 수 있고 다른 영역은 볼 수 없습니다.

두 전송 방식이 동일한 이벤트를 전달하므로, 명령은 파싱을 바꾸지 않고 전송만 바꿀 수 있습니다. SSE(--transport sse)는 평범한 GET입니다. 업그레이드가 필요 없고 TLS 엔드포인트에서도, 유닉스 소켓에서도 동작합니다. WebSocket(--transport ws)은 안전한 재개 앵커를 담은 stream:ready 프레임을 먼저 보냅니다. 이 앵커 덕분에 밀린 이벤트뿐 아니라 첫 제품 이벤트가 오기 전의 구간도 잃지 않고 재연결할 수 있습니다. 런의 결과를 잃으면 곤란한 곳에서는 이쪽이 기본값입니다. 소켓은 여기서 TLS를 지원하지 않으므로 https:// 엔드포인트는 SSE로 대체됩니다.

  • aigo events [--types <A,B>] [--since <ID>] [--transport sse|ws] [--raw]: 버스의 모든 이벤트를 따라갑니다. 콘솔 출력은 이벤트당 한 줄로 HH:MM:SS.mmm <type> <요약> 형식이며, --raw, -o json, -o yaml은 대신 한 줄에 JSON 객체 하나씩 출력합니다. Ctrl-C는 0으로 종료합니다.
  • aigo squad events [<SQUAD_ID>] [OPTIONS]: ID를 주면 해당 스쿼드의 이벤트를, 주지 않으면 모든 스쿼드와 모든 토론 룸의 이벤트를 따라갑니다. 두 형식 모두 SSE와 WebSocket을 지원합니다.
  • aigo schedule events [OPTIONS]: 자동화 런의 시작, 완료, 실패를 알리는 schedule:* 계열입니다.
  • aigo memory events [OPTIONS]: memory:* 계열입니다.
  • aigo data events [OPTIONS]: data:* 계열이며, --follow 모드가 사용하는 수집·폴더 가져오기·임베딩 진행 이벤트가 모두 포함됩니다.

--types는 이벤트 타입 이름을 정확히 지정하고 서버가 검증합니다. 해당 경로의 도메인 밖 이름은 400으로 거부되며, 연결만 되고 아무것도 전달하지 않는 스트림으로 받아들여지지 않습니다. --since <ID>는 이벤트 ID부터 재개하여 서버가 재생 버퍼에 아직 들고 있는 것을 먼저 전달합니다. 재개 지점이 버퍼에서 밀려났다면 stream:gap 이벤트가, 클라이언트가 뒤처졌다면 stream:lagged가 발생합니다. 둘 다 --types로 걸러지지 않습니다. 이벤트 타입 하나만 요청한 클라이언트라도 이벤트를 잃었다는 사실은 들어야 하기 때문입니다.

연결이 끊기면 가장 최근의 안전한 커서부터 다시 구독하며, 1, 2, 4, 8, 16초로 물러났다가 다섯 번 시도 후 포기합니다. 보통은 실제로 받은 가장 큰 제품 이벤트 ID이고, 첫 제품 이벤트 전에는 새 WebSocket의 시작 앵커입니다. 서버가 재시작한 뒤에는 stream:gap 다음에 재생된 첫 이벤트가 이전 프로세스의 낡은 커서를 새 ID 기준으로 바꿉니다. 재연결할 때마다 재개 지점을 알리는 줄이 표준 오류로 출력됩니다.

이 문서의 다른 follow 모드도 같은 스트림을 사용합니다. aigo squad execute --follow, aigo squad execution --follow, aigo squad message --wait, aigo squad discussion watch, 그리고 세 가지 aigo data ... --follow 대기입니다.

이 엔드포인트가 생기기 전에 만들어진 서버는 404로 답합니다. aigo events와 도메인별 감시 명령은 달리 할 수 있는 일이 없으므로 이를 오류로 보고하며 어느 버전부터 제공되는지 알려 줍니다. --follow 모드는 이전의 폴링 동작으로 되돌아가고 그 사실을 표준 오류로 알리므로, 구 버전 서버에서도 --follow는 계속 동작합니다. 401이나 403은 실제 실패이며, 조용히 폴링으로 대체되는 일은 없습니다.

aigo events --types squad:task-completed,data:ingest-progress
aigo squad events sq-1 --transport ws --raw | jq -r 'select(.type == "squad:task-failed") | .payload.error'

schedule - 자동화(예약 작업)

자동화를 생성하고 관리합니다. 크론 기반으로 추론을 실행하는 기능이며, 데스크톱 UI에서는 자동화(Automations), 관리 API에서는 schedules라고 부릅니다. create와 update는 플래그를 기본 형식으로 받으며, --json <BODY> 또는 --file <PATH>로 요청 본문 전체를 전달할 수도 있습니다. --file -는 표준 입력에서 본문을 읽습니다. 1 MiB 제한은 --file과 표준 입력에만 적용되며, --json으로 직접 넘긴 본문은 셸의 인자 길이 제한만 받습니다.

크론 표현식은 요청을 보내기 전에 검증하므로, 잘못된 표현식은 4xx 대신 서버가 알려준 사유와 함께 거부됩니다.

이 명령들이 호출하는 엔드포인트, 스케줄과 실행 기록의 와이어 형식, 크론과 시간대 규칙은 자동화 API 레퍼런스에 있습니다.

  • aigo schedule list: 자동화를 나열합니다(ID, 이름, 크론, 시간대, 모델, 활성 여부, 다음 실행, 마지막 실행).
  • aigo schedule show <ID>: 자동화 하나를 프롬프트 템플릿과 시스템 프롬프트까지 모두 표시합니다.
  • aigo schedule create --name <NAME> --cron <EXPR> --model <MODEL> (--prompt <TEMPLATE> | --prompt-file <PATH>) [OPTIONS]: 자동화를 생성합니다. 서버의 CreateScheduleRequest에 기본값이 없는 네 필드이므로 모두 필수입니다.
  • aigo schedule update <ID> [OPTIONS]: 자동화를 수정합니다. 지정한 플래그만 전송하며, 플래그를 하나도 주지 않으면 인자 오류입니다.
  • aigo schedule delete <ID> [-y]: 자동화와 실행 기록을 삭제합니다.
  • aigo schedule toggle <ID>: 자동화의 활성 상태를 반전합니다.
  • aigo schedule run <ID> [--no-wait]: 자동화를 즉시 실행하고 실행 기록을 출력합니다. 실행이 끝날 때까지 호출이 대기하며, --no-wait를 주면 실행이 접수되는 즉시 반환합니다. 기본 콘솔 출력에서는 실행 ID만 출력하므로 aigo schedule execution show로 바로 연결할 수 있지만, -o json이나 -o yaml에서는 {"executionId": ...} 객체 전체를 출력하므로 파이프라인에서 값을 꺼내야 합니다.
  • aigo schedule executions <ID> [--status <STATUS>] [--limit <N>] [--offset <N>]: 자동화 하나의 실행 기록을 나열합니다.
  • aigo schedule enable <ID> / aigo schedule disable <ID>: 활성 상태를 절대값으로 지정합니다. toggle과 달리 멱등이라 enable을 두 번 실행해도 자동화는 활성 상태로 남고 두 번 모두 0으로 종료하므로, 프로비저닝 스크립트에 적합합니다.
  • aigo schedule export <ID> [-o <PATH>] / aigo schedule export --all [-o <PATH>]: 자동화 하나 또는 전체를 이식 가능한 문서로 씁니다. -o가 없으면 표준 출력으로 내보냅니다. 여기서 -o는 저장할 경로이며 전역 -o/--output 형식 플래그가 아닙니다. aigo schedule import가 읽는 입력이므로 형식 플래그와 무관하게 항상 JSON입니다.
  • aigo schedule import <PATH> [--on-conflict skip|rename|replace]: export가 만든 문서 또는 CreateScheduleRequest 배열에서 자동화를 가져옵니다. -는 표준 입력을 읽고, --json <BODY>로 문서를 인라인 전달할 수도 있습니다. 생성/건너뜀/교체 개수를 출력합니다.
  • aigo schedule duplicate <ID> [--name <NAME>]: 자동화를 복제합니다. 복제본은 실행 전에 편집할 수 있도록 비활성 상태로 생성되며, --name을 주지 않으면 <이름> (copy)로 이름이 붙습니다.
  • aigo schedule validate-cron <EXPR>: 크론 표현식을 검증하고 설명을 출력합니다.
  • aigo schedule events [--types <A,B>] [--since <ID>] [--raw]: schedule:* 생명주기 스트림을 이벤트당 한 줄로 Ctrl-C까지 따라갑니다. events를 참고하세요.

실행 기록은 aigo schedule execution으로 실행 ID를 직접 지정해 다룹니다.

  • aigo schedule execution list [--schedule <SCHEDULE_ID>] [--status <STATUS>] [--limit <N>] [--offset <N>](별칭 ls): 모든 자동화의 실행 기록을 최근 순으로 나열합니다.
  • aigo schedule execution show <EXECUTION_ID>: 실행 하나를 렌더링된 프롬프트와 결과 전문까지 모두 표시합니다.
  • aigo schedule execution output <EXECUTION_ID>: 실행 결과 텍스트만 출력하므로 그대로 파이프에 넘길 수 있습니다. 성공하지 못한 실행도 기록된 결과가 있으면 그대로 출력한 뒤, 상태와 오류 메시지를 표준 오류로 보내고 종료 코드 3으로 끝납니다. 따라서 표준 출력이 비어 있다는 것은 실패했다는 뜻이 아니라 결과가 없다는 뜻입니다.
  • aigo schedule execution cancel <EXECUTION_ID> [--schedule <SCHEDULE_ID>] [-y]: 실행 중인 작업을 취소합니다. --schedule을 생략하면 실행 기록에서 소속 자동화를 읽어옵니다.

--status에는 실행 상태를 지정합니다. pending, running, success, failed, skipped, cancelled 중 하나입니다. 서버를 페이지 형식으로 전환하는 플래그는 두 목록에서 서로 다릅니다. aigo schedule executions <ID>에서는 --status나 --offset이고, aigo schedule execution list에서는 --status나 --schedule이며 --offset만 주면 페이지 형식으로 바뀌지 않습니다. 페이지 형식이 되면 표 아래 요약이 Total: N of M executions로 바뀌며, 여기서 M은 필터에 걸린 전체 실행 수입니다.

이 전환은 aigo schedule executions <ID>의 행 순서도 바꿉니다. 필터 없이 호출하면 최근 --limit개를 오래된 순으로 반환하며 이는 이전과 같고, 필터를 하나라도 주면 최근 순으로 반환합니다. --limit 0도 같은 이유로 달라져, 필터가 없으면 "행 없음", 있으면 "상한 없음"을 뜻합니다. 페이지 형식이 기본값이 되면 둘 다 사라지며, 그전까지 최신 행을 먼저 보려면 --offset 0을 함께 주면 됩니다.

aigo schedule execution output은 실행이 success가 아닌 모든 경우에 종료 코드 3으로 끝나며, 아직 끝나지 않은 실행도 포함합니다. 전송 실패도 같은 3을 쓰므로, 둘을 구분해야 하는 스크립트는 코드만 보지 말고 표준 오류의 메시지를 함께 읽어야 합니다.

aigo schedule execution cancel은 레코드를 cancelled로 표시하지만, 진행 중인 추론은 그 실행을 소유한 프로세스 안에서만 중단합니다. 다른 프로세스로 보낸 취소는 레코드만 뒤집고 소유 프로세스가 다음 쓰기 시점에 그것을 존중하므로, 레코드는 올바르게 남지만 모델은 생성을 마칠 때까지 계속합니다. 이미 종료 상태인 실행에 대한 취소는 거부됩니다. 프로세스가 비정상 종료해 running으로 남은 레코드는 시작 시에 정리되지 않으므로, 실행 시간으로 설명되지 않을 만큼 오래된 running 실행은 살아 있는 것이 아니라 남은 흔적입니다.

create와 update가 공유하는 옵션:

  • --system-prompt <TEXT> / --system-prompt-file <PATH>: 추론에 사용할 시스템 프롬프트입니다.
  • --agent <AGENT_ID>: 지정한 에이전트 프로필로 자동화를 실행합니다.
  • --input <SPEC>: {{input}} 자리에 넣을 입력의 출처입니다. none, file:<PATH>, dir:<PATH>, url:<URL>, command:<CMD> 중 하나입니다. 첫 번째 콜론만 구분자로 쓰므로 URL의 스킴은 그대로 유지됩니다.
  • --output <SPEC>: 결과 처리 방식입니다. store(실행 기록에만 저장), notify(데스크톱 알림), file:<PATH>, webhook:<URL> 중 하나입니다.
  • --tool <NAME>: 실행에 사용할 도구를 켭니다. 반복 지정할 수 있고, 같은 이름을 여러 번 주어도 한 번만 전송합니다. 수정 시에는 목록 전체를 교체하므로 유지할 도구도 모두 나열해야 합니다.
  • --tool-permission <NAME>=<VALUE>: 도구별 권한 재정의입니다. 반복 지정할 수 있습니다. 수정 시에는 저장된 맵을 먼저 읽어 지정한 항목만 덮어쓰므로 나머지 재정의는 유지되며, 맵 전체를 비우려면 --clear-tool-permissions를 씁니다.
  • --temperature <F>, --max-tokens <N>, --top-p <F>: 샘플링 파라미터입니다. 하나도 주지 않으면 서버 기본값(0.7 / 2048 / 0.9)이 적용됩니다. 수정 시에는 서버가 파라미터 블록 전체를 교체하므로, 현재 값을 먼저 읽어 지정한 항목만 바꿉니다.
  • --timezone <TZ>: 크론 계산에 사용할 IANA 시간대입니다. 서버 기본값은 UTC입니다.
  • --catch-up-missed, --auto-load-model, --unload-after: 각각 앱이 꺼져 있는 동안 놓친 실행을 시작 시 실행할지, 실행 전에 모델을 적재할지, 실행 후 모델을 내릴지를 지정합니다. update에서는 값을 함께 지정해(--unload-after false) 끌 수도 있습니다.

내보내기, 가져오기, 복제:

  • 내보내기 문서에는 create가 받는 필드만 담깁니다. ID도, 타임스탬프도, 활성 상태도, 실행 기록도 없습니다. 그래서 가져오기가 곧 생성이며, 원본 장비에서 어떤 상태였든 가져온 자동화는 활성 상태로 도착합니다. 중요한 경우 가져온 직후 aigo schedule disable <ID>로 꺼 두세요.
  • 내보내기 파일은 자격 증명입니다. webhook: 출력 동작에는 그 자체가 비밀인 경우가 많은 URL이 담기고(Slack, Discord 웹훅이 정확히 그렇습니다), command: 입력 소스에는 비밀을 포함할 수 있는 셸 명령줄이, url: 입력 소스에는 쿼리 문자열에 토큰이 들어갈 수 있습니다. 세 값 모두 그대로 기록합니다. 이 값이 빠지면 가져온 자동화가 동작하지 않기 때문입니다. 자유 입력 필드는 넣은 내용을 그대로 담으므로 프롬프트나 시스템 프롬프트에 붙여 넣은 키도 함께 나가며, --model과 file:, dir:, saveToFile: 경로는 원본 장비의 디렉터리 구조를 드러냅니다. 가리는 처리는 하지 않으므로, 파일 안의 자격 증명을 다루듯 파일을 다루세요.
  • --on-conflict는 들어오는 이름이 이미 있을 때의 동작을 정합니다. 내보내기에는 ID가 없으므로 두 장비가 맞출 수 있는 기준은 이름뿐입니다. skip(기본값)은 저장된 자동화를 그대로 두고 이름을 보고합니다. rename은 들어온 자동화를 <이름> (2), <이름> (3) 형태로 만듭니다. replace는 수정과 같은 경로로 저장된 자동화의 설정을 덮어쓰며, ID와 활성 상태, 실행 기록은 유지합니다.
  • 본문은 아무것도 쓰기 전에 전체를 검증합니다. 크론 표현식 하나가 잘못되면 절반만 남기는 대신 가져오기 전체를 거부합니다. 요청당 최대 500개입니다.

create 전용 옵션:

  • --disabled: 생성 직후 자동화를 비활성화합니다. 서버는 모든 자동화를 활성 상태로 생성하므로 생성 본문의 필드가 아니라 후속 토글 호출이며, --json 및 --file과 함께 쓸 수 있습니다.

update 전용 옵션:

  • --clear-agent, --clear-system-prompt, --clear-tools, --clear-tool-permissions: 해당 필드에 명시적인 null을 보냅니다. 값을 해제하는 유일한 방법입니다. 플래그를 생략하면 저장된 값을 그대로 둡니다.
  • --enable / --disable: 수정을 적용한 뒤 활성 상태를 지정합니다. 둘 중 하나만 단독으로 주는 것도 유효한 호출이며, 이때는 수정 요청을 보내지 않습니다.
# 파일을 매일 밤 요약해 다른 파일로 저장
aigo schedule create --name nightly --cron "0 2 * * *" --model /models/qwen3-8b.gguf \
  --prompt "Summarize {{input}}" --input file:/tmp/in.txt --output file:/tmp/out.md

# 실행 시각을 한 시간 늦추고 에이전트를 해제
aigo schedule update <ID> --cron "0 3 * * *" --clear-agent

# 표준 입력으로 요청 본문을 전달하고 비활성 상태로 생성
echo '{"name":"n","cronExpression":"0 2 * * *","modelPath":"/m.gguf","promptTemplate":"p"}' \
  | aigo schedule create --file - --disabled

# 대기하지 않고 실행을 시작한 뒤 ID로 추적
EXECUTION=$(aigo schedule run <ID> --no-wait)
aigo schedule execution show "$EXECUTION"

# 모든 자동화에서 최근 실패한 실행을 확인하고, 그중 하나의 결과만 저장
aigo schedule execution list --status failed --limit 20
aigo schedule execution output "$EXECUTION" > result.md
# 자동화 전체를 다른 장비로 옮기면서 이름이 겹치면 양쪽 모두 유지
aigo schedule export --all -o /tmp/automations.json
aigo schedule import /tmp/automations.json --on-conflict rename

# 편집용으로 하나를 복제한 뒤 활성화
aigo schedule duplicate <ID> --name staging
aigo schedule enable <NEW_ID>

data - 데이터 허브 문서

데스크톱 데이터 페이지가 사용하는 문서 코퍼스를 수집하고, 정리하고, 검색합니다. ingest, update, card, summarize, organize는 타입이 있는 플래그를 받습니다. 대신 --json <BODY>와 --file <PATH>로 요청 본문 전체를 보낼 수 있고, --file -는 표준 입력에서 읽습니다. 1 MiB 상한은 --file과 --summary-file / --notes-file에 적용되고, 인라인 --json 본문은 셸의 인자 길이 제한만 받습니다. ingest가 읽는 파일에는 별도의 상한 50 MiB가 적용되는데, 이는 요청 본문 상한이 아니라 서버의 파일당 상한을 따른 값입니다.

문서는 UUID id로 지정합니다. list가 출력하는 짧은 핸들(D42)은 카드 안의 [[handle]] 링크가 가리키는 값이고, show --handle로 조회합니다.

아래 명령은 모두 관리 API 엔드포인트를 감쌉니다. 각 명령이 호출하는 엔드포인트와 스코프, 응답 형태, 그리고 서버가 거부하지 않고 버리는 요청 필드는 데이터 허브 API 레퍼런스에 있습니다.

  • aigo data document list [--status <STATUS>] [--source <SOURCE>] [--collection <ID>] [--tag <TAG>] [--include-trashed] [--limit <N>] [--offset <N>] (별칭 ls): 문서 목록(ID, 핸들, 제목, 종류, 상태, 소스, 태그, 갱신 시각). 휴지통에 있는 문서는 --include-trashed를 주지 않으면 숨겨집니다.
  • aigo data document counts: 코퍼스의 정확한 수명 주기 카운트를 출력합니다. 여기에는 지금 trash --all이 허용되는지를 결정하는 미종료 작업 수도 포함됩니다.
  • aigo data document show <ID> / aigo data document show --handle <HANDLE>: 문서 하나를 전체 출력합니다.
  • aigo data document body <ID>: 변환된 마크다운 본문만 출력하므로 파이프나 리다이렉트로 넘길 수 있습니다.
  • aigo data document card <ID>: 주석 카드를 출력합니다. 쓰기 플래그가 하나라도 있으면 카드를 수정합니다: --summary <TEXT> / --summary-file <PATH>, --key-point <TEXT>(반복 가능) / --clear-key-points, --notes <TEXT> / --notes-file <PATH>. --expected-updated-at <RFC3339>는 저장된 카드가 여전히 그 타임스탬프를 가지고 있을 때만 쓰기를 허용하므로, 동시에 일어난 편집을 덮어쓰지 않고 보고합니다.
  • aigo data document ingest (<PATH> | -) [--title <T>] [--kind <KIND>] [--source <SOURCE>] [--filename <NAME>] [--source-uri <URI>] [--tag <TAG>]... [--collection <ID>]... [--base64]: 파일 또는 표준 입력을 문서로 수집합니다. --base64는 텍스트로 읽을 수 없는 형식(PDF, DOCX)의 원본 바이트를 그대로 보냅니다. 지정하지 않으면 파일을 UTF-8로 읽습니다. --filename의 기본값은 경로의 파일 이름이고, 서버는 이 값에서 종류와 원본 확장자를 추론합니다. 따라서 표준 입력으로 수집할 때는 이 값을 직접 지정하거나, 제목을 프런트매터와 첫 제목에서 가져오도록 서버에 맡겨야 합니다.
  • aigo data document update <ID> [--title <T>] [--tag <TAG>]... [--clear-tags] [--collection <ID>]... [--clear-collections]: 문서 메타데이터를 수정합니다. --tag와 --collection은 집합 전체를 교체하므로 유지할 값을 모두 나열해야 하고, --clear-* 플래그가 집합을 비웁니다. 플래그를 하나도 주지 않으면 인자 오류입니다.
  • aigo data document trash [<ID>... | --all | --matching [--status <STATUS>] [--collection <ID>] [--tag <TAG>] [--include-trashed]] [-y]: 문서를 휴지통으로 보냅니다. id가 하나면 DELETE /data/documents/{id}를, 여러 개면 벌크 엔드포인트를 한 트랜잭션으로 사용하며 상한은 500개입니다. --all은 살아 있는 문서 전체를 처리하는데, 수집이나 폴더 가져오기, 감시 스캔이 진행 중이면 서버가 거부합니다. --matching은 범위 필터에 해당하는 문서를 실행 시점에 서버가 다시 해석해 처리합니다. 선택 방식 세 가지는 서로 배타적이고, 맞지 않는 방식에 필터를 붙이면 조용히 무시되는 대신 인자 오류가 납니다.
  • aigo data document restore <ID>...: 휴지통에서 문서를 복구합니다. 명시적인 id 목록만 받습니다. 복구는 각 문서의 카드와 본문을 디스크에서 읽어 검색 색인을 다시 만들기 때문에, 서버에는 범위가 무한한 형태가 없습니다.
  • aigo data document organize <ID>... [--add-collection <ID>]... [--remove-collection <ID>]... [--add-tag <TAG>]... [--remove-tag <TAG>]...: 여러 문서의 컬렉션과 태그를 한 번에 더하거나 뺍니다. update와 달리 델타이므로, 지정하지 않은 소속은 그대로 남습니다.
  • aigo data document reconvert <ID>: 저장된 원본으로 변환기를 다시 실행해 새 본문 리비전을 만듭니다. 카드는 건드리지 않습니다.
  • aigo data document refetch <ID>: URL에서 온 문서를 다시 가져옵니다. 큐에 등록된 작업을 반환합니다.
  • aigo data document summarize <ID> [--model <MODEL_ID>] [--overwrite-user-edits]: 카드의 요약과 핵심 항목을 LLM으로 초안 작성하는 작업을 큐에 넣습니다. --overwrite-user-edits가 없으면 비어 있거나 이전 초안이 쓴 필드만 채웁니다. 사용할 모델이 없어도 요청은 접수되며, 반환된 작업이 그 이유를 담습니다. 이는 전송 실패가 아니라 화면에 표시할 상태입니다.
  • aigo data document related <ID>: 문서 주변의 [[handle]] 링크 그래프를 보여줍니다. 나가는 링크, 역링크, 그리고 아무 문서로도 해석되지 않는 핸들이 포함됩니다.
  • aigo data document chunks <ID>: 문서의 검색용 청크를 제목 경로, 그리고 각 청크가 벡터를 가진 임베딩 모델과 함께 나열합니다.
  • aigo data document revisions <ID>: 문서의 카드 리비전을 최신순으로 나열합니다. REVERTIBLE 열은 revert가 받아들이는 id를 알려줍니다. 본문 리비전은 카드 스냅숏이 없어 거부됩니다.
  • aigo data document revert <ID> <REVISION_ID> [-y]: 이전 카드 리비전으로 되돌립니다.
  • aigo data search <QUERY> [--collection <ID>] [--tag <TAG>] [--limit <N>] [--preset <PRESET_ID>]: 코퍼스 전체를 어휘 검색합니다. 일반 단어는 AND로 묶이고, "따옴표로 감싼 구절"은 그대로 일치하며, 질의문 안의 tag: / collection: 접두사는 문자 그대로 검색하지 않고 필터로 해석됩니다. 휴지통으로 보낸 문서는 그 시점에 색인에서 빠지므로 결과에 나타나지 않습니다. --preset은 컬렉션 범위와 어휘/하이브리드 모드를 정하는 검색 프리셋을 선택합니다.

--matching에는 --status, --collection, --tag 중 최소 하나가 필요합니다. --include-trashed는 함께 쓸 수 있지만 그 조건을 혼자 만족시키지는 못합니다. 범위를 좁히는 것이 아니라 넓히기 때문에, --matching --include-trashed만 쓰면 코퍼스 전체를 뜻하게 되고 그것은 --all이 할 일이며 필수 필터 규칙이 막으려는 것이기도 합니다.

열거형 값은 서버의 타입에서 그대로 가져오며, 철자가 틀리면 인자 오류(종료 코드 2)로 거부됩니다.

  • --status: processing, ready, warning, failed, trashed.
  • --source: upload, url, folder, chat, agent, wiki. ingest --source에서는 wiki가 빠지는데, 이 소스는 위키 파이프라인이 관리하는 페이지 전용입니다.
  • --kind: markdown, text, html, pdf, docx, spreadsheet, code, presentation, workbook, word_processing, ebook, other.

컬렉션, 태그, 검색 프리셋

컬렉션은 문서가 속하는 이름 있는 묶음이고, 태그는 자유 형식이며 자체 수명 주기가 없어서 살아 있는 문서 하나가 달고 있는 동안에만 존재합니다. 검색 프리셋은 search와 grounding이 사용하는 범위, 모드, 예산입니다. 셋 다 타입이 있는 플래그를 받고, --json <BODY>와 --file <PATH>가 탈출구입니다.

  • aigo data collection list (별칭 ls): 컬렉션 목록을 설명, 살아 있는 문서 수, 민감 여부, 갱신 시각과 함께 출력합니다. 민감으로 표시된 컬렉션은 암묵적 그라운딩과, 그 컬렉션을 직접 지정하지 않은 도구 읽기에서 제외됩니다. 상세 정보가 아니라 열로 둔 이유입니다.
  • aigo data collection create --name <NAME> [--description <TEXT> | --description-file <PATH>] [--sensitive]: 컬렉션을 만듭니다. 이름은 서버에서 정규화되고(앞뒤 공백 제거, 내부 공백 축약) 대소문자를 무시하고 이미 쓰이는 이름이면 거부됩니다.
  • aigo data collection update <ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--clear-description] [--sensitive | --not-sensitive]: 컬렉션을 수정합니다. 설명을 완전히 없애는 방법은 --clear-description뿐이라서, 설명을 지정하는 두 플래그와 배타적입니다. 플래그를 하나도 주지 않으면 인자 오류입니다.
  • aigo data collection delete <ID> [-y] (별칭 rm): 컬렉션을 삭제합니다. 소속 문서는 연결만 끊길 뿐 삭제되지 않으며, 응답이 연결이 끊긴 문서 수를 알려줍니다.
  • aigo data collection summarize <ID> [--model <MODEL_ID>] [--start-offset <N>]: 요약이 없는 컬렉션 문서에 대해 한 회차 분량의 LLM 요약 초안 작업을 큐에 넣습니다. 한 회차는 범위가 정해져 있어 응답에 nextOffset이 들어 있습니다. 그 값을 --start-offset으로 되먹이면 스캔 창보다 큰 컬렉션도 끝까지 처리할 수 있고, 초안이 방금 실패한 문서를 바로 다음 회차가 다시 집어 들지도 않습니다. GenerateSummaryRequest에 필드가 있는데도 여기에는 --overwrite-user-edits가 없습니다. 배치가 큐에 넣기 전에 그 값을 false로 갈아치우기 때문입니다. 사람이 쓴 카드를 대량으로 덮어쓰는 사고는 일괄 작업에서 가장 크게 다칩니다. 카드 하나를 덮어쓰려면 단일 문서 경로가 실제로 존중하는 aigo data document summarize <ID> --overwrite-user-edits를 쓰세요.
  • aigo data tag list (별칭 ls): 살아 있는 문서를 하나 이상 가진 태그를 개수와 함께 나열합니다.
  • aigo data preset list (별칭 ls): 검색 프리셋을 나열합니다. 컬렉션이 없는 프리셋의 SCOPE 열은 (all)로 표시되는데, 빈 범위는 아무것도 아니라 전체 컬렉션을 뜻하기 때문입니다.
  • aigo data preset create --name <NAME> [--collection <ID>]... [--mode <MODE>] [--wiki-pages <POLICY>] [--top-k <N>] [--token-budget <N>] [--embedding-model <MODEL_ID>]: 검색 프리셋을 만듭니다. 이름을 뺀 모든 필드는 기본 제공 프리셋의 값을 따릅니다. 임베딩 모델이 없으면 --mode가 무엇이든 어휘 검색으로 동작합니다.
  • aigo data preset update <ID> [--name <NAME>] [--collection <ID>]... [--all-collections] [--mode <MODE>] [--wiki-pages <POLICY>] [--top-k <N>] [--token-budget <N>] [--embedding-model <MODEL_ID>] [--clear-embedding-model]: 검색 프리셋을 수정합니다. --collection은 범위 전체를 교체하므로 유지할 컬렉션을 모두 나열해야 하고, --all-collections는 범위를 다시 전체로 넓힙니다. --clear-embedding-model은 모델을 다시 없음으로 되돌리는데, 이는 일반 필드로는 JSON에서 표현할 수 없습니다.
  • aigo data preset delete <ID> [-y] (별칭 rm): 검색 프리셋을 삭제합니다. 기본 제공 프리셋은 삭제할 수 없고 서버가 이름으로 거부합니다.

그라운딩, 인용, 지표

  • aigo data grounding <QUERY> [--preset <PRESET_ID>] [--memory-budget-tokens <N>] [--grounding-fraction <F>] [--no-record-reference]: 그 메시지에 대해 채팅 턴이 주입할 그라운딩 블록을 만듭니다. 콘솔 출력은 블록 텍스트뿐이라 aigo data grounding "load balancing" > block.md로 실제 주입될 내용을 그대로 저장할 수 있습니다. -o json은 출처, 확정된 예산, 성능 저하 사유까지 담긴 컨텍스트 전체를 출력합니다. 블록이 비어 있는 이유는 표준 오류로 나가므로 리다이렉트에 섞이지 않습니다. --memory-budget-tokens는 호출자가 이번 턴에 메모리 주입에 쓸 토큰이며, 서버가 이를 공동 예산에서 뺍니다. --no-record-reference는 문서에 참조 표시를 남기지 않는 미리보기를 만듭니다.
  • aigo data citation export [<DOC_ID>...] [--collection <ID>] [--format <FORMAT>] [--out <PATH>]: 카드의 서지 메타데이터로 참고문헌을 만들며, 인용 키는 문서 핸들입니다. 선택을 지정하지 않으면 살아 있는 문서 전체가 대상입니다. 콘솔 출력은 참고문헌 자체라서 리다이렉트할 수 있고, --out <PATH>는 파일에 쓰고 대신 요약을 출력합니다(전역 출력 형식 플래그인 -o가 아니라 --out이며, --out -은 -라는 이름의 파일이 아니라 표준 출력을 뜻합니다). 서지 정보가 전혀 없는 카드도 제목만 있는 항목으로 포함되며 표준 오류에 그 목록이 나오고, 서버 상한인 2000건에서 멈춘 경우도 같은 방식으로 알려줍니다.
  • aigo data metrics: 로컬 데이터 허브 카운터를 출력합니다. 형식별 수집 결과, 검색 가능해지기까지 걸린 시간, 검색 사용량, 도구별 호출과 승인 횟수가 들어갑니다. 이 값들은 프로세스 로컬이고 개발 빌드에서만 기록되며, 릴리스 빌드는 측정한 척하지 않고 Recording: disabled와 구조적으로 0인 값을 보고합니다.

그라운딩의 범위를 좁히는 수단은 --preset 하나뿐입니다. --collection, --tag, --limit이 있을 법하지만 일부러 없습니다. 이 셋은 어떤 엔드포인트도 받지 않는 검색 요청 타입의 필드이고, POST /data/grounding-context는 이 값들을 읽지도 거부하지도 않기 때문에, 클라이언트가 보내도 조용히 버려졌을 것입니다. 컬렉션 범위는 프리셋 쪽에 지정하십시오.

추가 열거형 값이며, 철자가 틀리면 인자 오류(종료 코드 2)로 거부됩니다.

  • --mode: lexical, hybrid.
  • --wiki-pages: include, exclude, prefer.
  • --format: bibtex, csl_json.

파이프라인 명령

그룹의 운영자 쪽 절반입니다. 수집 작업 큐, URL 수집, 폴더 가져오기, 감시 폴더, 임베딩, 유지보수 일정, 휴지통 비우기, 저장소 점검, 백필, 생성된 위키를 다룹니다. 여기서 생성하거나 수정하는 명령은 모두 --json <BODY>와 --file <PATH>도 받고, --file -는 같은 1 MiB 상한 아래에서 표준 입력에서 본문을 읽습니다.

--follow는 데이터 허브 이벤트 스트림(GET /data/events, events 참고)을 구독하고, 관련 이벤트가 도착할 때마다 해당 상태 엔드포인트를 다시 읽어 값이 바뀔 때만 출력합니다. 상태가 무엇인지는 상태 엔드포인트가 판단하고, 이벤트는 언제 볼지만 알려 줍니다. 스트림이 조용하더라도 30초마다 다시 읽으므로, 이벤트를 내지 않은 종료 전이 때문에 대기가 멈춰 버리는 일은 없습니다. 스트리밍 엔드포인트가 없는 서버에서는 2초 폴링으로 대체되고 그 사실을 표준 오류로 알립니다.

어느 쪽이든 작업이 성공으로 끝나면 0, 실패하거나 취소되었거나 명시적인 resume을 기다리며 멈추면 3으로 종료하므로, 스크립트는 요청의 성패가 아니라 작업 자체의 결과로 분기할 수 있습니다. --timeout <SECONDS>는 대기 시간을 제한하고 아직 진행 중이던 대상을 이름으로 알리며 3으로 종료합니다. 지정하지 않으면 무한정 기다리는데, 특히 job list에서 문제가 됩니다. 작업 하나가 누군가 doctor --repair fail_stuck_jobs를 돌릴 때까지 미종료 상태로 남아 있을 수 있기 때문입니다.

두 방식의 동작이 한 가지 다릅니다. 스트림에서는 job list --follow가 작업이 아직 진행 중일 때 각 단계 변화를 보므로, 큐에 들어갔다가 실패한 작업을 목격하고 3으로 종료합니다. 폴링 대체 경로는 두 번의 폴링 사이에서 그 전이를 통째로 놓칠 수 있고, 그러면 그 실패를 남이 남긴 예전 실패로 보고합니다.

  • aigo data events [--types <A,B>] [--since <ID>] [--raw]: 모든 data:* 이벤트를 상태 재조회 없이 Ctrl-C까지 따라갑니다. 명령별 --follow 대기가 좁혀 보는 하나의 파이프라인이 아니라 코퍼스 전체를 대상으로 합니다.
  • aigo data job list [--follow] [--timeout <SECONDS>] (별칭 ls): 수집 작업을 최신순으로 나열합니다(ID, 종류, 파일, 상태, 진행률, 문서, 갱신 시각). 이 엔드포인트에는 필터가 없고 최신순으로 최대 200행까지만 돌려주며 잘렸다는 표시도 없으므로, 가득 찬 페이지는 "최소 이만큼"이라는 뜻이고 명령이 그 사실을 알려줍니다. --follow는 그 페이지가 비워질 때까지 기다리고, 진행 중이던 작업이 실패로 끝나면 3으로 종료합니다. 관찰을 시작하기 전에 이미 실패해 있던 작업은 이전에 난 다른 실패이므로 종료 코드에 영향을 주지 않습니다.
  • aigo data job enqueue (--json <BODY> | --file <PATH>): 문서를 비동기 수집 큐에 넣습니다. 본문은 IngestDocumentRequest로, aigo data document ingest가 타입 있는 플래그로 만드는 것과 같은 형태입니다. 이 명령은 아직 존재하지 않는 문서 대신 작업을 반환합니다.
  • aigo data job retry <JOB_ID>: 실패한 작업을 다시 실행합니다.
  • aigo data backfill [-y]: 본문이 없거나 실패한 문서를 다시 수집하도록 큐에 넣습니다. 큰 코퍼스에서는 변환 워커 두 개를 오래 점유하므로 먼저 확인을 받습니다. 서버는 한 번에 최대 100개까지만 큐에 넣고 이 동작은 이어서 실행할 수 있으므로, 상한에 걸린 실행은 그 사실을 알리고 큐가 비워진 뒤 다시 실행하면 멈춘 지점부터 이어집니다.
  • aigo data url ingest <URL> [--title <T>] [--tag <TAG>]... [--collection <ID>]...: URL을 가져와 페이지를 문서로 저장합니다. http://와 https://만 받고, URL 길이는 서버와 같은 4096자로 제한되며, 가져오기는 서버의 SSRF 방어를 거칩니다. 아직 아무것도 가져오지 않았으므로 큐에 등록된 작업을 반환합니다.
  • aigo data folder-import run <PATH> [--no-recursive] [--include-hidden] [--max-depth <N>] [--tag <TAG>]... [--collection <ID>]... [--restrict-to-permitted-folders] [--sync [--max-files <N>]] [--follow] [--timeout <SECONDS>]: API 호스트의 폴더를 파일 하나당 수집 작업 하나로 가져옵니다. 기본값은 재귀입니다. 서버는 --max-depth를 24로 잘라내며 더 큰 값을 거부하지는 않습니다. --sync는 요청 안에서 폴더 전체를 훑고 건너뛴 항목을 모두 반환하는 예전 동기 엔드포인트를 씁니다. 실행 기록을 남기지 않으므로 --follow와 함께 쓸 수 없습니다. --max-files는 --sync가 있어야 하며 거기서 1에서 500 사이로 잘립니다. 영속 실행에는 설정할 파일 상한이 없습니다. 요청을 저장하기 전에, 그리고 재개할 때마다 maxFiles에 자체 배치 크기를 넣기 때문에 보낸 값은 버려지고, 50개에서 멈추라고 한 실행이 오히려 폴더 전체를 배치로 훑게 됩니다. 영속 실행은 aigo data folder-import cancel <RUN_ID>로 멈추세요.
  • aigo data folder-import list [--limit <N>] (별칭 ls): 최근 실행을 나열합니다(ID, 경로, 상태, 완료/대기, 실패, 갱신 시각).
  • aigo data folder-import show <RUN_ID> [--follow] [--timeout <SECONDS>]: 실행 하나를 결과별 카운터까지 전체 출력합니다. 멈춘 실행은 이어서 진행하는 방법을 알려주고, 절대 안전 상한에 도달한 경우에는 resume이 거부하는 유일한 정지 상태이므로 새 가져오기를 시작하라고 안내합니다.
  • aigo data folder-import cancel <RUN_ID> [-y]: 이후 배치를 중단합니다. 이미 가져온 문서는 유지됩니다.
  • aigo data folder-import resume <RUN_ID>: 일시 정지되었거나 중단된 실행을 이어서 진행합니다.
  • aigo data watch-folder list (별칭 ls): 감시 중인 폴더를 나열합니다(ID, 경로, 재귀, 활성화, 태그, 연속 실패 횟수, 마지막 스캔).
  • aigo data watch-folder add <PATH> [--no-recursive] [--include-hidden] [--tag <TAG>]... [--collection <ID>]...: 유지보수 일정이 다시 스캔하도록 폴더를 감시 목록에 넣습니다. 스캔은 같은 워커와 같은 이미-가져옴 건너뛰기를 쓰는 평범한 폴더 가져오기입니다.
  • aigo data watch-folder update <ID> [--recursive | --no-recursive] [--include-hidden | --no-include-hidden] [--tag <TAG>]... [--clear-tags] [--collection <ID>]... [--clear-collections] [--enable | --disable]: 감시 폴더를 수정합니다. 경로는 수정할 수 없습니다. 폴더가 다르면 다른 감시이고, 경로를 그 자리에서 바꾸면 스캔이 이어받는 이미-가져옴 집합의 키가 달라지기 때문입니다.
  • aigo data watch-folder remove <ID> [-y] (별칭 rm): 폴더 감시를 중단합니다. 이미 가져온 문서는 유지되지만, 폴더를 다시 추가하면 처음부터 다시 스캔합니다.
  • aigo data watch-folder scan: 일정을 기다리지 않고 지금 모든 대상 감시 폴더를 스캔합니다.
  • aigo data embedding run [--preset <PRESET_ID>] [--model <MODEL_ID>] [--follow] [--timeout <SECONDS>]: 코퍼스 임베딩 작업을 시작합니다. 두 플래그가 모두 없으면 기본 프리셋의 임베딩 모델을 씁니다. --follow는 실행이 실제로 시작한 모델의 상태를 다시 읽으며, 요청이 --json이나 --file로 들어온 경우에도 마찬가지입니다.
  • aigo data embedding status [--preset <PRESET_ID>] [--model <MODEL_ID>] [--follow] [--timeout <SECONDS>]: 임베딩 진행 상황을 보여줍니다. 상태, 모델, 완료 수, 전체 수, 그리고 새 작업을 돌릴 필요가 있는지 알려주는 남은 수가 포함됩니다.
  • aigo data embedding cancel [-y]: 워커에 중단을 요청합니다. 이미 쓴 벡터는 유지되고 다음 실행이 그 지점부터 이어갑니다.
  • aigo data maintenance show: 유지보수 일정을 보여줍니다. 예약 작업(watch, refetch, purge, wiki)마다 한 행이 나오고, 그 아래에 수치 설정과 cron 표현식을 해석할 시간대가 붙습니다.
  • aigo data maintenance set [--watch-enabled | --watch-disabled] [--watch-cron <EXPR>] [--refetch-enabled | --refetch-disabled] [--refetch-cron <EXPR>] [--refetch-min-age-hours <N>] [--refetch-batch-size <N>] [--purge-enabled | --purge-disabled] [--purge-cron <EXPR>] [--purge-retention-days <N>] [--wiki-enabled | --wiki-disabled] [--wiki-cron <EXPR>] [--timezone <TZ>]: 일정을 수정합니다. 지정한 플래그만 전송되고, 하나도 주지 않으면 인자 오류입니다. 마지막 실행 시각 네 개는 러너가 소유하며 플래그가 없습니다. 주기를 그 값에서부터 재기 때문입니다.
  • aigo data trash purge [<DOC_ID>... | --all | --retention-days <N>] [-y]: 휴지통의 문서와 그로부터 파생된 것을 영구히 삭제합니다. 원본, 본문, 카드, 청크, 벡터, 리비전, 링크가 모두 사라지고 복구할 방법은 없습니다. 범위를 지정하지 않으면 설정된 보관 기간이 이미 지난 문서를 삭제하고, --retention-days 0은 --all과 똑같이 휴지통을 비우므로 같은 문구로 확인을 받습니다. 세 범위는 서로 배타적입니다. 서버가 조합을 거부하는 대신 우선순위로 해석하므로, --all --retention-days 30이 그대로 통과했다면 지정한 기간이 조용히 무시된 채 휴지통 전체가 비워졌을 것이기 때문입니다.
  • aigo data doctor [--repair <KIND>]... [-y]: 저장소 무결성을 점검합니다. --repair가 없으면 보고만 합니다. prune_orphan_rows와 complete_interrupted_purges는 데이터를 삭제하며, 그중 요청한 항목을 확인 문구가 이름으로 알려줍니다.
  • aigo data wiki build [--collection <ID>] [--language <LANG>] [--model <MODEL_ID>]: 지정한 범위에 대해 위키를 만들고 계획된 페이지를 모두 다시 씁니다. --collection이 없으면 코퍼스 전체가 대상이며, 민감 컬렉션은 제외됩니다.
  • aigo data wiki update [--language <LANG>] [--model <MODEL_ID>]: 인용한 출처가 바뀐 페이지만 다시 씁니다.
  • aigo data wiki continue [--collection <ID>] [--language <LANG>] [--model <MODEL_ID>]: 마지막 실행이 페이지 없이 남긴 계획 클러스터를 작성합니다.
  • aigo data wiki status: 위키 전체 상태를 보여줍니다. 사용할 모델이 있는지, 페이지 수, 작성되지 않은 클러스터 수, 워터마크, 마지막 빌드 시각, 진행 중인 작업이 포함됩니다.
  • aigo data wiki pages (별칭 ls): 위키 페이지를 나열합니다(ID, 핸들, 제목, 종류, 신선도, 인용 수, 역링크 수, 작성 시각). CITES는 저장된 링크 미러가 기록한 인용 수로, 데스크톱 서명줄에 표시되는 독자 기준 수와는 다릅니다.
  • aigo data wiki refresh <PAGE_ID> [--language <LANG>] [--model <MODEL_ID>]: 페이지 하나를 다시 씁니다.
  • aigo data wiki related <PAGE_ID>: 페이지가 인용한 문서와 그 페이지를 인용한 페이지를 보여줍니다.

위키를 바꾸는 명령은 모두 작업을 큐에 넣고 그 작업을 반환합니다. 페이지 작성이 모델 호출이기 때문입니다. 로컬 모델에서는 코퍼스 빌드 하나가 기기를 몇 분 동안 붙잡으며, 예약된 위키 갱신이 기본으로 꺼져 있는 이유도 이것입니다. 사용할 모델이 있는지는 aigo data wiki status가 알려주므로, 아무것도 만들지 못할 빌드는 시작하기 전에 확인할 수 있습니다.

--repair는 서버가 쓰는 이름을 그대로 받고, 철자가 틀리면 인자 오류(종료 코드 2)가 납니다.

  • reindex_search: 디스크의 카드와 본문 파일로 검색 색인을 다시 만듭니다. 삭제는 없습니다.
  • prune_orphan_rows: 주인이 사라진 파생 행을 삭제합니다. 다시 만들 수 있는 데이터만 지웁니다.
  • quarantine_orphan_files: 소유 문서가 없는 파일을 삭제하지 않고 격리 디렉터리로 옮깁니다.
  • fail_stuck_jobs: 끝나지 않은 작업을 실패로 표시해 진행 중으로 보이지 않게 합니다.
  • complete_interrupted_purges: 중단된 삭제를 마무리합니다. 삭제가 일어나지만 이미 삭제 대상으로 표시된 문서만 건드립니다.
  • resync_frontmatter: 어긋난 카드 파일의 제목을 SQLite 값으로 다시 씁니다.
  • backfill_wiki_meta: 위키 파이프라인이 놓친 위키 소스 문서를 등록합니다.

memory - 메모리 네임스페이스와 항목

데스크톱 Memory 페이지 뒤에 있는 메모리 뱅크를 읽고 씁니다. 네임스페이스, 그 안의 항목, 채팅 턴이 주입하는 컨텍스트, 그리고 이들을 관리하는 추출/통합 패스를 다룹니다. create와 update 계열은 타입 플래그를 기본으로 하고, --json <BODY>와 --file <PATH>는 전체 요청 본문을 대신 전달하며, --file -은 공유 1 MiB 상한 아래에서 표준 입력을 읽습니다. memory import나 namespace import가 읽는 내보내기 문서는 요청 본문이 아니라 페이로드이므로 50 MiB라는 별도 상한을 씁니다. POST /memory/import도 라우트 자체 상한으로 같은 50 MiB를 쓰므로, 명령이 읽는 파일은 서버도 받습니다. 문서가 담을 수 있는 메모리 뱅크 수나 항목 수에는 상한이 없습니다. 가져오기가 걸 수 있는 개수 제한은 모두 내보내기가 넘길 수 있는 제한이고, 복원할 수 없는 백업은 큰 백업보다 나쁘기 때문입니다.

네임스페이스와 항목은 UUID id로 지정하며, 이 id는 namespace list와 entry list의 첫 열에 출력됩니다.

아래 모든 명령은 관리 API 엔드포인트를 감쌉니다. 각 명령이 호출하는 엔드포인트, 스코프, 응답 형태, 그리고 플래그가 이름 붙이지 않지만 서버가 요구하는 필드는 메모리 API 레퍼런스에 있습니다.

  • aigo memory namespace list (별칭 ls): 네임스페이스 목록(ID, 이름, 상태, 설명, 갱신 시각)을 출력합니다.
  • aigo memory namespace show <NS_ID>: 네임스페이스 하나를 전체 출력합니다.
  • aigo memory namespace create (<NAME> | --name <NAME>) [--description <TEXT> | --description-file <PATH>]: 네임스페이스를 만듭니다. 설명은 선택 사항이지만 서버가 필수 필드로 선언하므로, 생략하면 빈 문자열로 항상 전송됩니다.
  • aigo memory namespace update <NS_ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--enable | --disable]: 네임스페이스를 부분 수정합니다. 지정한 필드만 전송되며, 플래그를 하나도 주지 않으면 인자 오류입니다.
  • aigo memory namespace delete <NS_ID> [-y] (별칭 rm): 네임스페이스와 그 안의 모든 항목을 삭제합니다.
  • aigo memory namespace toggle <NS_ID>: 활성/비활성 상태를 반전합니다. 현재 상태를 먼저 읽어 반대 값을 보내므로, 스크립트에서 멱등한 결과가 필요하면 enable 또는 disable을 쓰세요.
  • aigo memory namespace enable <NS_ID> / aigo memory namespace disable <NS_ID>: 상태를 명시적으로 설정합니다. 비활성 네임스페이스는 항목을 그대로 유지한 채 주입 컨텍스트에서만 빠집니다.
  • aigo memory namespace clear <NS_ID> [-y]: 네임스페이스는 남기고 그 안의 항목만 모두 삭제합니다.
  • aigo memory namespace consolidate <NS_ID> [--similarity-threshold <F>] [--max-entry-age-days <N>]: 한 네임스페이스의 자동 추출 항목에 어휘 기반 중복 제거 패스를 실행합니다. 두 재정의 값은 하나만 줘도 되며, 나머지는 서버 기본값을 씁니다.
  • aigo memory namespace export <NS_ID> [-o <PATH>]: 네임스페이스와 항목을 JSON으로 표준 출력이나 파일에 내보냅니다. 내보내기가 메모리 항목을 그대로 담으므로 파일은 소유자만 읽을 수 있게 씁니다. -o는 디렉터리를 만들지 않습니다. 상위 디렉터리가 없으면 요청 전에 인자 오류로 거부합니다.
  • aigo memory namespace import (<PATH> | -): 단일 네임스페이스 내보내기 문서를 새 네임스페이스로 가져옵니다. 문서는 텍스트 그대로 전송되며, JSON이 아닌 파일은 요청 전에 로컬에서 거부됩니다. 스토어 전체 문서는 생성/병합/건너뜀/거부를 보고하는 aigo memory import를 안내하며 거부합니다.
  • aigo memory entry list (<NS_ID> | --enabled) [--tag <TAG>] [--source auto|manual] [--query <TEXT>] [--limit <N>] [--offset <N>] [--sort created|updated] [--order asc|desc] (별칭 ls): 한 네임스페이스의 항목을 나열하고, --enabled를 주면 활성 네임스페이스에 속한 모든 항목, 즉 주입 컨텍스트가 참조하는 집합을 나열합니다. 두 형태는 서로 다른 엔드포인트를 호출하므로 함께 쓸 수 없으며, 필터는 네임스페이스 형태에만 적용됩니다. --tag은 항목의 태그와 정확히 일치하는지 보고 --query는 내용에 대한 대소문자 무시 부분 일치이므로, 네임스페이스를 가로지르는 관련도 검색은 aigo memory search를 씁니다. 필터를 하나라도 주면 응답이 전체 일치 개수를 담은 페이지로 바뀌어 푸터가 "표시 중 / 전체"를 보고하고, 하나도 주지 않으면 네임스페이스 전체를 저장 순서 그대로 반환합니다. --limit의 기본값은 100이고 상한은 1000입니다.
  • aigo memory entry show <NS_ID> <ENTRY_ID>: 태그와 메타데이터를 포함해 항목 하나를 출력합니다.
  • aigo memory entry create <NS_ID> (<CONTENT> | --content <TEXT> | --content-file <PATH>) [--source auto|manual] [--tag <TAG>]... [--metadata <JSON>]: 항목을 만듭니다. --source의 기본값은 명령줄에서 직접 입력한 메모리를 뜻하는 manual이고, auto는 추출 결과를 재현하는 스크립트용입니다.
  • aigo memory entry update <NS_ID> <ENTRY_ID> [--content <TEXT> | --content-file <PATH>] [--tag <TAG>]... [--clear-tags] [--metadata <JSON>]: 항목을 부분 수정합니다. --tag는 태그 집합 전체를 교체하므로 유지할 태그를 모두 나열해야 하고, --clear-tags는 집합을 비웁니다. 플래그를 하나도 주지 않으면 인자 오류입니다.
  • aigo memory entry delete <NS_ID> <ENTRY_ID>... [-y] (별칭 rm): 항목을 하나 또는 여러 개 삭제합니다. ID가 하나면 그 항목만 삭제하고, 둘 이상이면 대량 삭제 엔드포인트를 호출해 네임스페이스 파일을 한 번만 다시 쓰며, 찾지 못한 ID에서 멈추지 않고 목록으로 보고하므로 일부가 이미 사라진 선택도 나머지는 그대로 삭제됩니다.
  • aigo memory entry move <NS_ID> <ENTRY_ID>... --to <TARGET_NS_ID> (별칭 mv): 항목을 다른 메모리 뱅크로 옮깁니다. 각 항목은 ID, 내용, 태그, 메타데이터, 타임스탬프를 그대로 유지합니다. 다른 곳에서 다시 만들면 잃게 되는 것이 바로 이 이력입니다. 대상은 존재해야 하고 출발 네임스페이스와 달라야 합니다. 되돌리려면 다시 옮기면 되므로 확인 프롬프트는 없습니다.
  • aigo memory export (<NS_ID> | --all) [-o <PATH>]: 메모리 뱅크 하나를, --all을 주면 전체를 JSON으로 표준 출력이나 파일에 내보냅니다. 전체 문서는 {"version", "exportedAt", "namespaces"} 형태이고 각 원소가 뱅크와 그 항목을 담으며, 뱅크 하나를 지정하면 memory namespace export가 쓰는 {"namespace", "entries"} 객체를 그대로 씁니다. 파일에는 메모리가 그대로 담기므로 Unix에서는 소유자만 읽을 수 있게 기록하고, Windows에서는 디렉터리의 ACL을 상속합니다. -o는 디렉터리를 만들지 않으므로 존재하지 않는 상위 경로는 요청 전에 인자 오류로 거부합니다. 뱅크도 --all도 지정하지 않은 호출은 전체 덤프가 아니라 인자 오류입니다.
  • aigo memory import (<PATH> | - | --json <BODY>) [--on-conflict merge|skip]: 두 형태의 문서를 모두 가져옵니다. --on-conflict는 전체 문서에만 적용되며, 뱅크는 이름으로 대응됩니다. merge(기본값)는 들어온 항목을 저장된 뱅크에 덧붙이고 skip은 그대로 둡니다. 가져온 뱅크와 항목에는 모두 새 ID를 부여하므로 같은 문서를 두 번 가져오면 덮어쓰지 않고 덧붙습니다. 설명에 예약된 에이전트 경험 마커가 들어 있는 뱅크는 들어온 쪽이든 저장된 쪽이든 거부하고 목록으로 보고합니다. 에이전트별 읽기 경로가 그 마커를 시스템 프롬프트로 해석하기 때문입니다.
  • aigo memory search <QUERY> [--namespace <NS_ID>] [--limit <N>]: 네임스페이스 전체에서 항목을 검색해 관련도 순으로 반환합니다. --namespace는 검색을 한 네임스페이스로 제한하고 --limit은 결과 수를 제한합니다.
  • aigo memory stats: 집계 통계를 출력합니다. 항목/네임스페이스 수, 출처별과 종류별 분포, 추정 토큰 총합, 네임스페이스별 표가 포함됩니다. 에이전트 경험 네임스페이스는 별도로 보고되며 대표 합계에는 들어가지 않습니다.
  • aigo memory context [--max-tokens <N>] [--no-record-reference]: 채팅 턴이 주입할 메모리 블록을 만듭니다. 콘솔 출력은 블록 본문뿐이므로 aigo memory context > block.md는 실제 주입될 내용을 그대로 파일에 씁니다. -o json은 토큰 수와 항목 수를 함께 줍니다. 컨텍스트를 만들면 그 항목들이 참조된 것으로 기록되어 최신성 순위에 반영되므로, 확인 목적으로만 읽을 때는 --no-record-reference를 쓰세요.
  • aigo memory extract --messages-file (<PATH> | -) [--model <MODEL_ID>] [--target-namespace <NS_ID>] [--trigger-interval <N>] [--context-window <N>] [--max-context-tokens <N>] [--config <JSON>]: 대화 기록에 추출 파이프라인을 실행합니다. 파일은 {"role", "content"} 객체의 JSON 배열이고 최대 100개이며, 요청 전에 로컬에서 검증합니다. --config는 ExtractionConfig 전체를 전달하며 네 개의 타입 재정의 플래그와 함께 쓸 수 없습니다. 라우터가 실행 중이어야 합니다.
  • aigo memory consolidation run [--model <MODEL_ID>]: 대상 네임스페이스 전체에 LLM 통합 패스를 실행해, 유사한 자동 추출 항목 묶음을 대표 사실 하나로 병합합니다. 수동 항목은 건드리지 않습니다. --model이 없으면 서버가 설정과 로드된 풀에서 모델을 찾고, 아무것도 찾지 못하면 실행을 거부합니다.
  • aigo memory consolidation status: 예약 실행이 도래했는지, 설정된 주기, 마지막 실행과 마지막 시도 시각, 그리고 마지막 유지보수 오류가 있었다면 그 내용을 보고합니다.
  • aigo memory ensure-model [--model <MODEL_ID>]: 추출 모델이 로드되어 있지 않으면 로드하고 결과(alreadyLoaded, loaded, disabled, modelNotFound, insufficientRam, timedOut, failed)를 출력합니다.
  • aigo memory events [--types <A,B>] [--since <ID>] [--raw]: 항목과 네임스페이스가 바뀔 때마다 memory:* 스트림을 Ctrl-C까지 따라갑니다. events를 참고하세요.

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)은 aigo session 명령으로 제공되지 않습니다. 대신 aigo events --types session:added,session:updated,session:removed로 따라가세요. 공유 버스에서 같은 세 이름을 읽습니다. events를 참고하세요.

squad - 스쿼드 관리

멀티 에이전트 스쿼드를 생성, 조회, 수정합니다. create와 update는 플래그를 기본 형식으로 받으며, 플래그로 표현하지 않는 필드(에이전트별 도구 설정, 컨테이너 실행 모드 등)는 --json <BODY> 또는 --file <PATH>로 요청 본문 전체를 전달합니다. --file -는 표준 입력에서 본문을 읽습니다. 1 MiB 제한은 --file과 표준 입력에만 적용되며, --json으로 직접 넘긴 본문은 셸의 인자 길이 제한만 받습니다.

이 그룹 전체는 관리 API의 스쿼드 표면을 감싸며, 엔드포인트별 설명은 스쿼드에 있습니다. 유닉스에서는 CLI가 디스커버리 파일에 적힌 유닉스 도메인 소켓을 TCP보다 우선 사용하므로, 로컬 인스턴스에는 엔드포인트 플래그가 필요 없습니다. --output console|json|yaml은 전역 플래그이므로 명령 그룹 앞에 두어야 합니다(aigo --output json squad list). 뒤에 두면 clap이 예상치 못한 인자로 거부합니다. 콘솔 포매터는 표로 출력하며, jq로 넘길 때는 --output json을 쓰세요.

  • aigo squad list: 스쿼드를 나열합니다(ID, 이름, 상태, 에이전트 수, 플래너, 작업 공간).
  • aigo squad show <SQUAD_ID>: 스쿼드를 표시합니다. 에이전트 표(ID, 이름, 역할, 모델, 실행 모드, 메모리)를 함께 출력합니다.
  • aigo squad create --name <NAME> --workspace <PATH> [--description <TEXT> | --description-file <PATH>] [--template <TEMPLATE_ID>] [--agent <SPEC>]... [--planner <AGENT>]: 스쿼드를 생성합니다.
  • aigo squad update <SQUAD_ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--workspace <PATH>] [--planner <AGENT_ID> | --clear-planner]: 스쿼드를 수정합니다. 지정한 플래그만 전송하며, --clear-planner는 플래너를 해제합니다.
  • aigo squad delete <SQUAD_ID> [--delete-workspace] [-y]: 스쿼드를 삭제합니다. --delete-workspace를 주지 않으면 작업 공간 디렉터리는 남습니다.
  • aigo squad restore <WORKSPACE_PATH>: 작업 공간 매니페스트에서 스쿼드를 복원합니다.

--template <TEMPLATE_ID>는 스쿼드 템플릿에서 에이전트를 채웁니다(ID는 aigo squad template list로 확인). 템플릿에서 역할이 planner인 에이전트가 플래너가 됩니다. --agent를 하나라도 지정하면 템플릿의 에이전트 목록을 완전히 대체합니다.

--agent <SPEC>는 반복 지정할 수 있으며 name[:role[:model]] 형식을 받습니다.

  • 역할은 planner, developer, reviewer, writer, custom:<label> 중 하나이며 기본값은 developer입니다.
  • 모델은 모델 ID이며 콜론을 포함할 수 있습니다(dev:developer:llama3:8b). 다만 custom 라벨에는 콜론을 쓸 수 없습니다. 라벨 다음 구간을 모델로 읽기 때문이며, 콜론이 든 라벨이 필요하면 --json을 쓰세요.
  • --planner에는 --agent 항목의 이름(요청 전송 전에 해당 에이전트로 치환됩니다) 또는 에이전트 ID를 지정합니다. --agent 항목이 최소 하나는 있어야 합니다. --template만 지정한 경우에는 템플릿에서 역할이 planner인 에이전트가 자동으로 선택되며, 템플릿이 만드는 에이전트 ID는 서버가 부여합니다.
# 템플릿으로 생성
aigo squad create --name demo --workspace /tmp/demo --template builtin-fullstack-dev-team

# 에이전트를 직접 지정해 생성
aigo squad create --name demo2 --workspace /tmp/demo2 \
  --agent lead:planner:qwen3-8b --agent dev:developer:qwen3-8b --planner lead

# 표준 입력으로 요청 본문 전달
echo '{"name":"demo3","workspacePath":"/tmp/demo3"}' | aigo squad create --file -

squad agent - 스쿼드 에이전트 구성

기존 aigo squad 그룹 아래에서 에이전트를 하나씩 추가, 조회, 변경, 제거합니다. 이 명령이 생기기 전에는 에이전트 하나를 고치려면 aigo squad update <ID> <JSON>에 전체 구성을 다시 적어 보내야 했습니다.

  • aigo squad agent list <SQUAD_ID> (별칭 ls): 스쿼드의 에이전트를 나열합니다(ID, 이름, 역할, 모델, 실행 모드, 메모리).
  • aigo squad agent show <SQUAD_ID> <AGENT_ID>: 에이전트 하나를 시스템 프롬프트와 표준 지시문까지 전부 표시합니다.
  • aigo squad agent add <SQUAD_ID> --name <NAME> [FLAGS]: 에이전트를 추가합니다. --role planner|developer|reviewer|writer|custom:<label>, --model <MODEL_ID>, --description <TEXT>, --icon <EMOJI>, --system-prompt <TEXT> 또는 --system-prompt-file <PATH>, --instructions <TEXT> 또는 --instructions-file <PATH>, --tool <NAME>(반복 가능), --memory / --no-memory, --execution-mode in_process|container, --from-profile <PROFILE_ID>.
  • aigo squad agent set <SQUAD_ID> <AGENT_ID> [FLAGS]: 에이전트 하나를 변경합니다. --from-profile을 뺀 add의 플래그를 모두 선택적으로 받고, --clear-settings-overrides와 --clear-container-config가 추가됩니다. 전달하지 않은 항목은 그대로 유지됩니다.
  • aigo squad agent remove <SQUAD_ID> <AGENT_ID> [-y] (별칭 rm): 에이전트를 제거합니다. 해당 에이전트가 스쿼드의 플래너이거나(먼저 plannerAgentId를 해제하세요) 채팅 세션 또는 실행 중인 작업에 묶여 있으면 409로 거부됩니다.

--model과 --tool은 서버에서 객체 전체를 교체하므로, set은 에이전트를 먼저 읽어 병합합니다. --model은 컨텍스트 요구치와 기능 요구 사항을 유지하고 기록된 프로바이더만 지웁니다(교체되는 모델에 속한 값이기 때문입니다). --tool은 비활성 목록과 권한 재정의를 유지합니다. 나머지 플래그는 이 추가 조회가 필요 없습니다.

add와 set은 타입 플래그 대신 --json <BODY> 또는 --file <PATH>도 받습니다(--file -는 표준 입력을 읽습니다). 두 방식은 함께 쓸 수 없고, 본문은 1 MiB로 제한됩니다.

squad task - 관리 작업

기존 aigo squad 그룹 아래의 작업 서브커맨드입니다. create와 update는 타입이 있는 플래그를 받으며, 전체 요청 본문이 필요하면 --json <BODY>와 --file <PATH>(-는 표준 입력)를 사용합니다.

  • aigo squad task create <SQUAD_ID> --title <TEXT> (--description <TEXT> | --description-file <PATH>) [--priority low|medium|high|critical] [--depends-on <TASK_ID>]... [--assign <AGENT_ID>] [--max-retries <N>]: 작업을 생성합니다.
  • aigo squad task update <SQUAD_ID> <TASK_ID> [--title <TEXT>] [--description <TEXT> | --description-file <PATH>] [--priority <P>] [--depends-on <TASK_ID>]... [--clear-depends-on] [--assign <AGENT_ID> | --unassign] [--max-retries <N>]: 작업을 수정합니다. 실행 중인 작업은 --description, --priority, --max-retries만 받으며, 종료된 작업은 수정할 수 없습니다(대신 retry를 사용).
  • aigo squad task delete <SQUAD_ID> <TASK_ID> [--force] [-y]: 작업을 삭제합니다. --force는 실행 중인 작업을 먼저 취소하며, 이 작업에 의존하던 작업은 해당 의존성을 잃습니다.
  • aigo squad task retry <SQUAD_ID> <TASK_ID> [--force]: 실패했거나 취소된 작업을 다시 대기열에 넣습니다. --force는 재시도 한도를 모두 쓴 경우 한 번 더 허용합니다.
  • aigo squad task assign <SQUAD_ID> <TASK_ID> <AGENT_ID> / unassign <SQUAD_ID> <TASK_ID>: 작업 담당 에이전트를 바꾸거나 담당을 해제합니다.
  • aigo squad task list <SQUAD_ID> [--status pending|ready|assigned|in_progress|review|done|failed|cancelled]: 작업 목록을 보여주며 상태로 걸러낼 수 있습니다.
  • aigo squad task show <SQUAD_ID> <TASK_ID> / graph <SQUAD_ID>: 작업 하나 또는 의존성 그래프를 보여줍니다.
  • aigo squad task status <SQUAD_ID> <TASK_ID> <STATUS>: 작업 상태를 바꿉니다.

squad execution - 플랜 실행 제어

요청을 제출한 뒤 실행 중인 런을 제어합니다. 모든 제어는 작업 사이에서 적용되며, 이미 실행 중인 작업을 중단시키지는 않습니다.

  • aigo squad execute <SQUAD_ID> <REQUEST> [--auto-approve] [--wait | --follow]: 스쿼드 플래너에 요청을 제출합니다. --wait는 런이 종료 상태에 이르거나 승인 대기로 멈출 때까지 2초마다 상태를 폴링합니다. --follow는 제출 전에 스쿼드 이벤트 스트림을 구독하고, 계획 수립, 플랜, 작업과 웨이브별 한 줄, 그리고 결과를 발생하는 대로 출력합니다. --auto-approve가 없으면 플랜이 준비될 때 Approve this plan? [y/N/r(eject with feedback)]를 묻고 대신 승인 또는 거부를 호출합니다. 명시적인 y가 아니면 거부입니다. 완료된 런은 0으로, 실패·취소·거부된 런은 3으로 종료합니다. 두 플래그는 함께 쓸 수 없으며, 스트리밍 엔드포인트가 없는 서버에서 --follow는 --wait 폴링으로 대체됩니다.
  • aigo squad approve <SQUAD_ID> <EXECUTION_ID> [--plan-file <PATH>]: 대기 중인 플랜을 승인합니다. --plan-file은 플래너가 만든 작업 목록을 먼저 교체하며, 파일에는 요청 본문 전체({"planOverride": {"tasks": [...]}}) 또는 오버라이드만({"tasks": [...]}) 담을 수 있고 -는 표준 입력을 읽습니다. 태스크에는 직접 정한 id를 넣을 수 있고 dependsOn은 그 파일이 기술한 계획의 id를 기준으로 해석되므로, 플래너가 만든 id를 몰라도 파일 하나로 여러 태스크를 새로 넣고 순서를 지정할 수 있습니다. 직접 정한 id가 지켜야 할 규칙은 스쿼드 API 레퍼런스를 보세요.
  • aigo squad reject <SQUAD_ID> <EXECUTION_ID> --feedback <TEXT>: 플랜을 거부하고 플래너에게 다시 맡깁니다.
  • aigo squad execution <SQUAD_ID> <EXECUTION_ID> [--follow]: 런을 보여줍니다. 상태와 웨이브, 웨이브 표(웨이브, 작업, 제목, 담당, 상태, 시도 횟수), 운영자가 건너뛴 작업, 런이 전달받은 운영자 지시가 포함됩니다. --follow는 이미 진행 중인 런에 붙습니다. 먼저 실시간 스트림을 구독한 뒤 런의 영구 이벤트 원장을 밀린 기록으로 재생하고, 그 뒤를 이어 실시간으로 계속합니다. 두 출처 사이로 이벤트가 빠지지 않고, 이음매에서 같은 이벤트가 두 번 출력되지도 않습니다.
  • aigo squad pause <SQUAD_ID> <EXECUTION_ID> / resume <SQUAD_ID> <EXECUTION_ID>: 다음 작업 전에 런을 멈추거나 다시 진행시킵니다. 둘 다 멱등입니다.
  • aigo squad steer <SQUAD_ID> <EXECUTION_ID> (<MESSAGE> | --file <PATH>) [--task <TASK_ID> | --agent <AGENT_ID>]: 운영자 지시를 보냅니다. 범위 플래그가 없으면 상시 지시가 되어 이후 모든 작업 턴에 덧붙고, --task와 --agent는 작업 하나 또는 에이전트 하나로 범위를 좁힙니다. --file -는 표준 입력에서 지시를 읽습니다.
  • aigo squad skip-task <SQUAD_ID> <EXECUTION_ID> <TASK_ID>: 아직 시작하지 않은 작업을 건너뛰어 아예 실행되지 않게 합니다. 이미 실행 중이거나 끝난 작업은 거부됩니다.
  • aigo squad retry-task <SQUAD_ID> <EXECUTION_ID> <TASK_ID>: 실패한 작업을 현재 웨이브에서 다시 실행합니다. 실행 중이거나 일시 중지된 런이 필요합니다.
  • aigo squad cancel <SQUAD_ID> <EXECUTION_ID>: 런을 취소합니다. 일시 중지 상태에서도 동작합니다.

aigo squad events [<SQUAD_ID>]는 아무것도 제출하지 않고 같은 스트림을 따라가고, aigo squad message <SQUAD_ID> <AGENT_ID> <TEXT> --wait는 턴 ID를 돌려주는 대신 에이전트 한 명의 답변을 스트리밍되는 대로 출력합니다. 둘 다 events에서 설명합니다.

이 제어들은 두 런타임 모두에서 실제 런을 대상으로 합니다. execute는 플래너를 실행하고 --auto-approve가 있으면 실행기까지 시작하며, 없으면 approve가 실행기를 시작합니다. 헤드리스 aigo-server도 데스크톱 앱과 같은 방식으로 런을 구동합니다. 플래너는 서버의 라우터를 거치는 LLM 호출이고, 태스크가 호출하는 도구는 POST /api/v1/tools/execute와 같은 기능 게이트와 정책 게이트를 거치므로, 데스크톱 앱이 필요한 도구는 시도되지 않고 도구 카탈로그가 알리는 사유와 함께 거부됩니다.

플랜 오버라이드는 패치가 아니라 교체입니다. 파일에 없는 기존 작업은 제거되고, 기존 id를 가진 작업은 정체성을 유지하며, id가 없는 작업은 새로 추가됩니다. 담당자는 해당 스쿼드의 에이전트여야 하고, 의존성은 결과 플랜 안에서 해석되어야 하며, 순환이 있으면 런이 시작되기 전에 거부됩니다.

EXEC=$(aigo --output json squad execute sq-1 "Refactor the parser" | jq -r .executionId)
aigo squad pause sq-1 "$EXEC"
aigo squad steer sq-1 "$EXEC" "Keep the public API unchanged"
aigo squad resume sq-1 "$EXEC"

squad workspace - 작업 공간, 파일, 활동 로그

스쿼드의 에이전트가 공유하는 디렉터리와 그 위의 조회 명령입니다.

  • aigo squad workspace init <SQUAD_ID> <PATH>: 작업 공간 디렉터리와 plans/, tasks/, memory/, artifacts/, logs/, sessions/ 하위 디렉터리를 만듭니다.
  • aigo squad workspace status <SQUAD_ID>: 작업 공간의 존재 여부, 쓰기 가능 여부, 구조가 갖춰졌는지를 표시합니다.
  • aigo squad workspace validate <PATH>: 스쿼드를 만들기 전에 후보 경로를 검사합니다. 읽기 전용입니다.
  • aigo squad workspace clean <SQUAD_ID> [--archive] [-y]: 작업 공간을 제거합니다. --archive를 주면 먼저 아카이브를 만듭니다.
  • aigo squad files <SQUAD_ID> [PATH]: 작업 공간 파일을 나열합니다. PATH는 작업 공간 기준 상대 경로입니다.
  • aigo squad cat <SQUAD_ID> <FILE_PATH>: 작업 공간 파일 하나를 출력합니다.
  • aigo squad search <SQUAD_ID> <QUERY>: 작업 공간 파일 내용을 검색합니다.
  • aigo squad activity <SQUAD_ID> [--persisted]: 활동 로그를 표시합니다. 플래그가 없으면 메모리 버퍼만 반환하므로 서버 재시작 후에는 비어 있습니다. --persisted는 작업 공간의 logs/events.jsonl을 먼저 다시 읽습니다.

squad memory - 에이전트 메모리

memory/ 아래에 있는 에이전트별 마크다운 메모리 파일이며, 이름 있는 섹션으로 나뉩니다.

  • aigo squad memory init <SQUAD_ID>: 스쿼드의 메모리 뱅크를 만듭니다.
  • aigo squad memory read <SQUAD_ID> <AGENT_ID>: 에이전트의 메모리를 출력합니다.
  • aigo squad memory sections <SQUAD_ID> <AGENT_ID>: 해당 에이전트의 섹션 이름을 나열합니다.
  • aigo squad memory write <SQUAD_ID> <AGENT_ID> --section <SECTION> (--content <TEXT> | --from-file <PATH>) [--overwrite]: 섹션에 덧붙이거나, --overwrite로 교체합니다.
  • aigo squad memory search <SQUAD_ID> <QUERY> [--agent <AGENT_ID>] [--section <SECTION>] [--case-sensitive] [--limit <N>]: 스쿼드의 에이전트 전체를 검색합니다.

squad session - 에이전트 세션과 1:1 채팅

스쿼드 에이전트는 계획 실행과 별개로 자체 저장 이력을 가진 1:1 채팅 세션을 유지할 수 있습니다.

  • aigo squad session start <SQUAD_ID> <AGENT_ID> / stop <SQUAD_ID> <AGENT_ID>: 에이전트의 현재 세션을 시작하거나 중지합니다.
  • aigo squad session status <SQUAD_ID> <AGENT_ID>: 세션이 실행 중인지와 무엇을 하고 있는지 표시합니다.
  • aigo squad session list <SQUAD_ID> <AGENT_ID>: 에이전트의 저장된 세션을 나열합니다.
  • aigo squad session new <SQUAD_ID> <AGENT_ID>: 이전 세션을 남겨 둔 채 새 세션을 시작합니다.
  • aigo squad session show <SQUAD_ID> <AGENT_ID> <SESSION_ID> / delete <SQUAD_ID> <AGENT_ID> <SESSION_ID> [-y]: 저장된 세션 하나를 읽거나 삭제합니다.
  • aigo squad message <SQUAD_ID> <AGENT_ID> <TEXT>: 현재 세션의 에이전트에게 메시지를 보냅니다.
  • aigo squad conversation <SQUAD_ID> <AGENT_ID>: 에이전트의 현재 대화를 출력합니다.

squad history - 이력, 분석, 예산, 긴급 정지

  • aigo squad history list <SQUAD_ID>: 지난 실행을 나열합니다.
  • aigo squad history show <SQUAD_ID> <EXECUTION_ID>: 실행 레코드 하나를 표시합니다.
  • aigo squad history logs <SQUAD_ID> <EXECUTION_ID>: 해당 실행의 로그를 표시합니다.
  • aigo squad history report <SQUAD_ID> <EXECUTION_ID>: 마크다운 리포트를 생성하고 서버에 기록된 경로를 출력합니다.
  • aigo squad analytics <SQUAD_ID>: 토큰, 비용, 처리량을 표시합니다.
  • aigo squad budget show <SQUAD_ID> / usage <SQUAD_ID>: 예산 설정, 또는 현재 실행의 사용량을 표시합니다.
  • aigo squad budget set <SQUAD_ID> <BODY_JSON>: 예산 설정을 교체합니다.
  • aigo squad emergency-stop <SQUAD_ID>: 스쿼드의 종료되지 않은 실행을 모두 취소합니다.

이벤트 경로 두 개는 아직 CLI 명령이 없습니다. 실시간 SSE 스트림(GET /api/v1/squads/{id}/events)과 실행별 타입 원장(GET /api/v1/squads/{id}/history/{eid}/events) 모두 관리 API에서 직접 읽어야 합니다. CLI에는 아직 스트리밍 전송 방식이 없습니다.

squad template - 스쿼드 템플릿

템플릿은 작업 공간 없이 재사용할 수 있는 에이전트 구성입니다.

  • aigo squad template list: 사용 가능한 템플릿을 나열합니다.
  • aigo squad template show <TEMPLATE_ID>: 템플릿 하나를 표시합니다.
  • aigo squad template import <FILE>: 파일에서 템플릿을 가져옵니다.
  • aigo squad template export <TEMPLATE_ID> [--output <PATH>]: 템플릿 JSON을 표준 출력 또는 파일로 내보냅니다.
  • aigo squad template delete <TEMPLATE_ID> [-y]: 템플릿을 삭제합니다.
  • aigo squad template save <SQUAD_ID> --name <NAME> [--description <TEXT>] [--icon <ICON>]: 기존 스쿼드의 구성을 새 템플릿으로 저장합니다.
  • aigo squad template install --path <PATH> [--source-id <ID>]: 공유 레지스트리 카탈로그에서 템플릿을 설치합니다.

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 discussion watch <ID> [--types <A,B>] [--since <ID>] [--raw]: 룸 하나를 실시간으로 따라갑니다. 턴 시작과 종료, 스트리밍 콘텐츠 델타, 도구 호출과 결과, 게시된 메시지, 큐와 상태 변경, 합성된 결론을 출력합니다. 순서가 어긋나 도착한 델타는 두 번 출력하지 않고 버립니다. 룸이 completed, cancelled, error에 도달하거나 Ctrl-C를 누르면 종료합니다.

autonomous - Autonomous-Agent 프로바이더

aigo autonomous 그룹은 프로바이더 수준 autonomous-agent REST API를 감쌉니다. 프로바이더 탐색, 가용성 확인, 게이트웨이 수명주기 제어, 모델 브리지 동기화, 메시징, 프로바이더 이벤트, Hermes 전용 운영 작업을 다룹니다.

CLI는 요청을 보내기 전에 프로바이더 종류를 검증합니다. 현재 허용 값은 claw와 hermes이며, 다른 값은 거부하고 허용 값을 출력합니다.

읽기 명령:

  • aigo autonomous providers: API 서버에 등록된 프로바이더를 나열합니다.
  • aigo autonomous availability: 현재 런타임에서 각 알려진 프로바이더를 사용할 수 있는지 표시합니다. 사용할 수 없으면 unavailableReason도 보여줍니다.
  • aigo autonomous capabilities <KIND>: 프로바이더가 선언한 기능을 표시합니다.
  • aigo autonomous environment <KIND>: 런타임, 이미지, 게이트웨이, 환경 이슈를 표시합니다.
  • aigo autonomous gateway status <KIND>: 게이트웨이 상태와 엔드포인트를 표시합니다.
  • aigo autonomous gateway logs <KIND> [--tail <N>] [--since <RFC3339>] [--follow]: 최근 게이트웨이 로그를 표시합니다. --follow는 Ctrl-C를 누를 때까지 2초마다 조회하고, 타임스탬프를 지원하는 프로바이더에서는 --since를 갱신하며, 스냅샷만 지원하는 프로바이더에서는 겹치는 줄을 제거해 이전 로그를 다시 출력하지 않습니다.
  • aigo autonomous channels <KIND>: 메시징 채널을 나열합니다.
  • aigo autonomous channel messages <KIND> <CHANNEL_ID> [--limit <N>] [--before <MESSAGE_ID>]: 채널 하나의 최근 메시지를 나열합니다.
  • aigo autonomous skills <KIND>: 프로바이더 스킬을 나열합니다.

변경 및 스트림 명령:

  • aigo autonomous install <KIND> [--follow]: 프로바이더 선행 조건을 설치합니다. --follow를 주면 CLI가 설치 요청을 보내기 전에 /autonomous/events를 구독하고, 검증 단계가 100%에 도달하거나 오류 이벤트가 올 때까지 install_progress 프레임을 출력합니다.
  • aigo autonomous gateway start <KIND> --image <IMAGE> [--mount HOST:CONTAINER[:ro]]... [--timeout SECS] [--idle-timeout SECS] [--host HOST] [--port PORT]: 타입이 있는 플래그로 프로바이더 게이트웨이를 시작합니다.
  • aigo autonomous gateway start <KIND> --json <BODY> / --file <PATH>: 전체 gateway-start JSON 본문을 보냅니다. 본문은 서버의 flattened GatewayStartOptions wire shape를 따라야 하며, top-level 키는 provider, containerConfig, host, port입니다.
  • aigo autonomous gateway stop <KIND>: 프로바이더 게이트웨이를 중지합니다.
  • aigo autonomous gateway restart <KIND>: 현재 설정으로 프로바이더 게이트웨이를 재시작합니다.
  • aigo autonomous skill enable|disable <KIND> <SKILL_ID>: 프로바이더 스킬 하나의 활성화 상태를 변경합니다.
  • aigo autonomous models sync <KIND> --model <ID>...: 모델 ID를 동기화합니다. 각 ID는 displayName을 ID와 같게, contextWindow를 0으로 둔 완전한 ModelSummary로 전송됩니다.
  • aigo autonomous models sync <KIND> --json <BODY> / --file <PATH>: 전체 SyncModelsBody를 보냅니다.
  • aigo autonomous message <KIND> <CHANNEL_ID> <TEXT> [--idempotency-key KEY]: 프로바이더 채널로 메시지를 보냅니다.
  • aigo autonomous message <KIND> <CHANNEL_ID> --file <PATH> [--idempotency-key KEY]: 파일에서 메시지 본문을 읽습니다. 표준 입력은 -를 사용합니다.
  • aigo autonomous events [--types a,b] [--raw]: 프로바이더 이벤트를 따라갑니다. --types는 install_progress 같은 이벤트 태그를 받고, --raw는 압축된 콘솔 줄 대신 파싱된 이벤트 JSON을 출력합니다.

Hermes 프로필 명령:

  • aigo autonomous hermes profile list: Hermes 프로필을 나열합니다. ls 별칭도 사용할 수 있습니다.
  • aigo autonomous hermes profile create --name <NAME> [--description <TEXT>]: 타입이 있는 플래그로 프로필을 만듭니다.
  • aigo autonomous hermes profile create --json <BODY> / --file <PATH>: 전체 CreateProfileRequest 본문을 보냅니다. 설명만 파일에서 읽으려면 --description-file <PATH>를 사용합니다.
  • aigo autonomous hermes profile activate <NAME>: 활성 Hermes 프로필을 설정합니다.
  • aigo autonomous hermes profile settings <NAME>: 한 프로필의 폴더 권한과 컨테이너 제한을 표시합니다.

Hermes MCP 명령:

  • aigo autonomous hermes mcp list: 등록된 MCP 서버를 나열합니다. ls 별칭도 사용할 수 있습니다.
  • aigo autonomous hermes mcp add --id <ID> --name <NAME> --command <CMD> [--arg <ARG>]... [--env KEY=VALUE]... [--scope profile|user|system] [--disabled]: 타입이 있는 플래그로 MCP 서버를 등록하거나 교체합니다.
  • aigo autonomous hermes mcp add --json <BODY> / --file <PATH>: 전체 HermesMcpServer 본문을 보냅니다.
  • aigo autonomous hermes mcp remove <ID> [-y]: 확인 후 MCP 서버를 제거합니다. rm 별칭도 사용할 수 있습니다.
  • aigo autonomous hermes mcp reload: 실행 중인 Hermes daemon에 MCP 등록 reload를 요청합니다.

Hermes 설정 및 승인 명령:

  • aigo autonomous hermes permissions set <PROFILE> --allow PATH[:read|:read_write|:full][:recursive]...: 프로필의 폴더 권한을 교체합니다.
  • aigo autonomous hermes permissions set --json <BODY> / --file <PATH>: 전체 SetFolderPermissionsRequest 본문을 보냅니다.
  • aigo autonomous hermes limits set <PROFILE> [--cpu-shares <N>] [--memory-mib <N>] [--pids-limit <N>]: 프로필의 컨테이너 리소스 제한을 교체합니다.
  • aigo autonomous hermes limits set --json <BODY> / --file <PATH>: 전체 SetContainerLimitsRequest 본문을 보냅니다.
  • aigo autonomous hermes approvals list: 대기 중인 승인 요청을 나열합니다. ls 별칭도 사용할 수 있습니다.
  • aigo autonomous hermes approvals history [--limit <N>]: 적용된 승인 결정을 나열합니다.
  • aigo autonomous hermes approvals decide <REQUEST_ID> (--approve | --deny [--reason <TEXT>]): 승인 결정을 적용합니다.
  • aigo autonomous hermes approvals decide --json <BODY> / --file <PATH>: 전체 ApprovePendingActionRequest 본문을 보냅니다.
  • aigo autonomous hermes approvals watch: /autonomous/events의 governance_event frame을 따라갑니다. 표준 입력이 TTY이면 CLI가 [a]pprove, [d]eny, [s]kip을 묻고, 아니면 이벤트만 출력합니다.

Hermes 플랫폼 및 마이그레이션 명령:

  • aigo autonomous hermes platform set <PLATFORM> --field KEY=VALUE...: 플랫폼 credential을 저장합니다. credential 값은 요청 본문으로 보내지만 출력하지 않습니다.
  • aigo autonomous hermes platform set <PLATFORM> --file <PATH>: 파일에서 credential KEY=VALUE 줄을 읽습니다. 빈 줄과 # 주석은 무시하고, -는 표준 입력을 뜻합니다.
  • aigo autonomous hermes platform set <PLATFORM> --json <BODY>: 전체 SetPlatformCredentialsRequest 본문을 보냅니다. 지원 platform 값은 whatsapp, telegram, slack, discord, imessage, signal, teams, matrix, mattermost, email, sms, dingtalk, feishu, wecom, bluebubbles, home_assistant, google_chat입니다.
  • aigo autonomous hermes platform clear <PLATFORM> [-y]: 확인 후 저장된 credential을 지웁니다.
  • aigo autonomous hermes platform test <PLATFORM>: 플랫폼 credential 연결을 테스트합니다.
  • aigo autonomous hermes migrate-claw --target-profile <NAME> [--preset user_data|full] [--dry-run]: OpenClaw에서 Hermes로 마이그레이션합니다.
  • aigo autonomous hermes migrate-claw --json <BODY> / --file <PATH>: 전체 MigrateClawOptions 본문을 보냅니다.

gateway start, models sync, Hermes create/update 명령은 raw JSON 본문이 있을 때 타입이 있는 플래그를 함께 받지 않습니다. message도 <TEXT>와 --file을 함께 받지 않습니다. 모호한 요청 본문을 막기 위한 fail-closed 동작입니다.

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 형식으로 나열: 

aigo model list -o json

특정 모델 로드 (GPU 레이어 지정): 

aigo loaded load "gemma-3n-E4B-it-Q4_K_M" --gpu-layers 33

시스템 GPU 상태 확인: 

aigo system gpu

설치된 확장 스킬을 JSON으로 나열: 

aigo extension skill list -o json

토론 룸 생성 후 시작: 

aigo squad discussion create --json '{"squadId":"sq-1","topic":"릴리스 계획"}'
aigo squad discussion start <DISCUSSION_ID>

컨테이너 vLLM 엔진 세션 시작: 

aigo engine container start --json '{"engineId":"vllm","modelId":"org/model","modelPath":"/models/org/model"}'