이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

헤드리스 CLI (ax-code run)

상태: 활성 범위: 현재 상태 최종 검토: 2026-09-22 담당: AX Code 런타임 유지관리자

ax-code run은 AI 코딩 에이전트와 스크립트를 위한 일회성, 비대화형 진입점입니다. 프롬프트 하나를 제출하고, 어시스턴트의 최종 답변을 인쇄한 뒤 종료합니다. 터미널 UI도 대화형 프롬프트도 없습니다. 이 안내는 옵션 표면, 출력 계약, 종료 코드, 스크립트와 CI를 위한 복사해 쓰는 조리법을 다룹니다.

실행을 호출합니다

프롬프트를 주는 방법은 네 가지입니다. 순서대로 합쳐집니다. --prompt-file, 그다음 -p/--prompt, 그다음 위치 메시지, 그다음 파이프된 stdin입니다.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

stdin이 TTY가 아니면 그 내용이 합쳐진 프롬프트에 덧붙으므로, 다른 것이 없으면 그것 전체가 프롬프트입니다. stdin 읽기는 열린 파이프를 포기하기 전에 300 ms의 조용한 창을 기다립니다. 프롬프트를 바로 쓰고 stdin을 닫으십시오. 크거나 천천히 만들어지는 프롬프트에는 --prompt-file를 사용합니다. --prompt-file -는 stdin에서 프롬프트를 명시적으로 읽습니다(stdin이 TTY이면 사용 오류). 그 호출에서는 암시적인 파이프 stdin 덧붙이기가 두 번 실행되지 않습니다.

-f/--file은 메시지에 파일을 첨부하며 프롬프트를 대체하지 않습니다. 반복할 수 있습니다.

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

첨부는 프로젝트 디렉터리 안에 있어야 합니다. 서버는 권한 규칙과 관계없이 밖 첨부를 거부하므로, CLI는 사용 오류로 미리 거부합니다. 파일을 프로젝트로 복사하거나 --prompt-file로 내용을 전달합니다. --add-dir은 도구에 추가 디렉터리 접근을 부여하지만 이 규칙을 바꾸지 않습니다.

첨부 MIME 유형은 확장자에서 추론됩니다. png, jpg, jpeg, gif, webp은 자신의 image/* 유형으로, pdf는 application/pdf으로 대응하므로, 바이너리 첨부는 text/plain이 아니라 실제 유형으로 서버에 도달합니다. 그 밖 — 인식되는 확장자가 없는 파일 포함 — 은 text/plain로 보내지고, 디렉터리 첨부는 application/x-directory로 분류됩니다.

실행을 조향합니다

세 플래그가 프롬프트 텍스트를 바꾸지 않고 실행을 조향합니다. 모두 긴 형태만 있고 kebab-case입니다.

--append-system-prompt TEXT / --append-system-prompt-file PATH

에이전트와 환경 시스템 프롬프트 뒤에 추가 텍스트를 시스템 프롬프트에 붙입니다. 덧붙일 뿐 내장 시스템 프롬프트를 대체하지 않습니다. 두 형태는 서로 배타적입니다. 더 긴 지시에는 파일 형태가 편리합니다. 끝의 줄바꿈은 정확히 하나만 잘리고, 빈 텍스트(또는 읽을 수 없는 파일)는 무엇이든 제출하기 전에 사용 오류입니다.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

실행에서 ID로 도구를 끕니다(쉼표로 구분, 반복 가능). 두 서버 메커니즘을 통해 적용됩니다. 만든 세션의 거부 규칙이 새 실행을 다루고, 요청별 도구 맵이 재개된 --session/--continue 실행도 다룹니다. bash를 거부하면 같은 셸 실행기를 통해 도는 monitor 도구의 명령도 거부됩니다. 거부 규칙에 걸린 호출은 도구 오류로 실패하고 차단된 실행 상태에 대한 거부로 셉니다. 알 수 없는 ID는 오류가 아닙니다. MCP 도구 ID는 동적입니다. 다만 기본 형식에서는 내장 도구 집합 밖의 각 ID가 stderr 경고를 하나 인쇄합니다(--quiet이 억제).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

에이전트에게 추가 디렉터리 하나의 접근을 부여합니다(반복 가능). 새 세션의 권한 규칙에 external_directory 허용 규칙이 <resolved-path>/*에 대해 추가되며, 그 디렉터리와 그 아래 전부를 다룹니다. 각 경로는 존재해야 하고 디렉터리여야 합니다(--file처럼 호출자 cwd에 대해 해석). 규칙은 세션이 만들어질 때 적용되므로, --session/--continue 아래에서는 효과가 없습니다. CLI는 stderr에 --add-dir applies only to new sessions를 인쇄하고 계속합니다. --file 격리를 바꾸지 않습니다. 첨부는 여전히 프로젝트 디렉터리 안에 있어야 합니다. 파일 도구(read, glob, grep, list, edit, write)를 다룹니다. 동적 경로로 그 디렉터리에 닿는 셸 명령은 여전히 대화형 전용 경로 접근 프롬프트를 일으키고, 헤드리스 실행은 그것을 자동 거부하므로, 파일 도구를 선호하거나 파일 내용을 명시적으로 전달하십시오.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

모델을 고릅니다

쓸 수 있는 ID는 ax-code models으로 나열합니다. 결과 provider/model 값을 --model(-m)에 전달합니다.

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json은 다음 형태의 문서 하나를 인쇄합니다. {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

가족 이름 deepseek, glm, qwen는 Flash 기본값으로 해석되므로, ax-code run --model qwen -- "..."는 전체 provider/model ID를 풀어 쓰지 않아도 동작합니다. --model을 생략하면 구성된 기본값을 사용합니다. 유효 에이전트와 모델은 stderr에 > Agent · model로 인쇄됩니다.

출력 형식

--format는 default(기본값), json, jsonl 또는 ndjson을 받습니다(jsonl와 ndjson는 json의 별칭).

기본값(텍스트)

기본 형식은 stdout에 최종 어시스턴트 텍스트만 인쇄합니다. 모든 진행, 도구 활동, 진단은 stderr로 가며, 세션 ID가 들어 있는 > Agent · model · ses_... 헤더로 시작합니다. 그래서 여러 턴 호출자가 --session로 재개할 수 있고 --format json로 바꿀 필요가 없습니다(--quiet은 헤더를 억제). stderr가 TTY가 아니거나 NO_COLOR이 설정되면(어떤 값이든) ANSI 색이 꺼지므로, 파이프된 실행은 이스케이프 코드를 내지 않습니다.

JSON 스트림 (--format json)

--format json은 줄로 구분된 JSON(NDJSON) 이벤트 스트림을 인쇄합니다. 줄마다 JSON 객체 하나이며, JSON 문서 하나가 아닙니다. 이벤트에는 step_start, text, tool_use, reasoning(--thinking이 있을 때만), permission_denied, error, step_finish이 있습니다. 스트림은 항상 정확히 하나의 result 줄로 끝납니다.

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status은 completed, blocked 또는 error입니다. usage은 토큰 수만 담습니다. input, output, reasoning, cacheRead, cacheWrite입니다. 횟수를 알 수 없으면 완전히 생략됩니다. 비용 필드는 없습니다. 제출 전에 실행이 실패하면(잘못된 플래그, 알 수 없는 모델 등) 스트림 형식은 종료 전에 한 줄을 인쇄합니다.

{ "type": "error", "error": { "code": "usage", "message": "..." } }

error.code은 다음 중 하나입니다.

종료 코드

샌드박스

--sandbox read-only|workspace-write|full-access가 격리 모드를 고릅니다(기본 full-access). 헤드리스 실행에서 권한 질문은 자동 거부되고 permission_denied 이벤트로 보고되므로, 허용되지 않은 쓰기가 필요한 실행은 blocked를 보고하고 3으로 종료합니다. 서브에이전트도 포함됩니다. task 도구가 만든 자식 세션의 질문은 같은 방식으로 거부되고, 그 permission_denied 이벤트는 자식 sessionID을 담습니다. 권한 거부 규칙(예를 들어 --disallowed-tools에서)이나 읽기 전용 샌드박스가 거부한 도구 호출도 거부로 셉니다. 대화형 question과 plan_exit 도구는 재개된 세션을 포함해 헤드리스 실행에서 항상 꺼집니다. 변경이 예상되지 않을 때만 read-only를 사용합니다. workspace-write은 쓰기를 프로젝트 안에 유지합니다.

--attach 아래에서는 플래그가 모든 프롬프트 본문의 요청별 격리 정책으로도 보내집니다. 서버는 자신의 모드와 요청된 정책 중 더 엄격한 쪽을 적용하므로, 더 조이기만 할 수 있습니다. 같은 요청별 정책이 로컬이 소유한 서버에도 보내져 동작이 균일합니다.

구조화된 출력

-o/--output-file <path>는 최종 어시스턴트 텍스트를 파일에 씁니다. --output-schema <file>은 최종 텍스트를 JSON Schema 파일에 대해 JSON으로 검증합니다. 불일치는 error 이벤트로 보고되며, 함께 result.status error가 있고 종료 코드는 1입니다. 스키마 파일은 모델이 실행되기 전에 사전 점검됩니다. 읽을 수 없거나, 파싱할 수 없거나, 객체가 아닌 스키마는 무엇이든 제출하기 전에 사용 오류입니다. 성공하면 파싱된 스키마가 실행의 json_schema 출력 형식으로 모델에도 보내지고, 서버는 CLI 자신의 최종 검증이 안전장치로 실행되기 전에 유효하지 않은 답변을 최대 두 번 재시도합니다. 최종 출력은 직렬화된 구조화 객체입니다(JSON 한 줄). stdout, --output-file, result.text가 담는 것이 그것입니다.

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

세션과 재개

• -c/--continue — 가장 최근 세션을 이어갑니다.
• -s/--session <id> — ID로 특정 세션을 이어갑니다.
• --fork — 이어가기 전에 세션을 포크합니다(--continue 또는 --session이 필요).
• --show-history — 재개할 때 보이는 세션 기록을 인쇄합니다(--continue 또는 --session이 필요).
• --attach <url> — 새로 시작하지 않고 이미 실행 중인 서버에 붙습니다. --dir와 함께 그 서버의 프로젝트 디렉터리를 겨냥합니다. AX_CODE_SERVER_PASSWORD으로 보호된 서버는 --password(또는 호출자 쪽의 같은 변수)를 받습니다. 관리형 런타임은 AX_CODE_RUNTIME_TOKEN에서 토큰을 받습니다.
• --runtime — 프로젝트 디렉터리(--dir 또는 호출자 cwd)의 관리형 런타임에 붙습니다. 그 런타임은 ax-code runtime start로 시작되었고, 비공개 런타임 기록에서 URL과 토큰을 해석합니다. 실행 중인 런타임이 없으면 시작 명령을 이름 붙인 메시지와 함께 오류 코드 attach로, 어떤 요청보다 먼저 실패합니다. --runtime과 --attach은 서로 배타적입니다.

조리법

일회성

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

시간 제한으로 실행을 묶습니다

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

실행이 한도를 넘기면 --timeout <seconds>가 서버에서 실행을 중단하고 124로 종료합니다(result.status은 timeout). 그래서 멈춘 에이전트가 CI 작업을 무한정 붙잡지 못합니다. 한도는 호출 전체를 다룹니다. 첫 서버 호출 전에 무장되므로, 블랙홀이 된 --attach 호스트나 멈춘 시작도 시간에 맞춰 끝납니다(그 이른 경우에는 결과 줄의 sessionID이 비어 있습니다).

백그라운드 서브에이전트를 기다립니다

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds>은 이 호출을, 그 세션이 만든 백그라운드 task 자식과 그 결과가 일으킨 부모 후속 턴 동안 열어 둡니다. 선택이며 3600초로 제한됩니다. 최종 답변과 JSON result.text는 마지막으로 완료된 부모 턴에서 옵니다. 자식이나 그 후속이 대기 한도 안에 안정되지 않으면 실행은 오류를 보고하고 1로 종료합니다. --timeout이 전체 한도로 남습니다. 프로젝트 예약 작업은 별도 세션에서 실행되며 이 대기의 일부가 아닙니다. 이 일회성 명령은 도래한 프로젝트 일정을 주장하지 않습니다. 지속 백엔드가 그 발송을 소유합니다.

JSON 스트림을 파싱합니다

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

result 줄은 항상 마지막 줄이므로, 스트림이 일찍 끝나도 tail -n 1가 그것을 분리합니다.

읽기 전용 검토

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

스키마가 있는 구조화 JSON 출력

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

세션을 재개합니다

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

파일을 첨부합니다

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

기계가 읽을 수 있는 명령

ax-code run --format json은 줄로 구분된 이벤트 스트림을 내보냅니다(JSON 스트림 참조). 스트리밍하는 유일한 --json 표면입니다. --json 플래그가 있는 다른 모든 읽기 전용 명령은 더 엄격한 계약을 따릅니다. 성공하면 stdout에 JSON 문서 정확히 하나를 쓰고, 실패하면 stdout은 비어 있으며 {"error":{"code","message"}} 문서 하나가 stderr로 가고 종료 코드는 1입니다.

--json이 있는 명령:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status는 JSON 문서를 무조건 인쇄합니다. --json 플래그는 일관성을 위해 받아들여지지만 상태 동작은 항상 stdout에 JSON을 내보냅니다.

다른 에이전트에서 ax-code를 호출합니다

스크립트, CI 단계, 다른 에이전트에서 ax-code run을 감쌀 때:

• --format json를 사용하고 마지막 줄을 읽습니다. result 기록은 스트림이 일찍 끝나도 항상 최종 줄입니다.
• 후속 턴을 위해 그 결과 줄에서 sessionID를 캡처합니다. --session로 다시 전달합니다.
• 동시 호출자에서 --continue을 쓰지 마십시오. 가장 최근 세션을 재개하므로 여러 호출자가 활성이면 경주합니다. 명시적인 --session ID를 전달합니다.
• 실행이 바뀔 수 있는 구성된 기본값에 의존하지 않도록 명시적인 --model을 전달합니다.
• 멈춘 에이전트가 호출자를 붙잡지 못하도록 항상 --timeout를 전달합니다.
• stdin을 닫거나 --prompt-file / --prompt-file -을 사용합니다. 암시적 파이프 읽기는 300 ms의 조용한 창 뒤에 포기하고 느린 파이프를 조용히 자릅니다.
• NO_COLOR=1를 설정하거나 TTY가 아닌 감지에 의존해, 파이프된 실행이 ANSI 이스케이프 코드를 내지 않게 합니다.
• 프로젝트 디렉터리에서 실행합니다. 홈이나 여러 저장소의 부모 디렉터리는 비대화형 모드에서 거부됩니다. 그 가드를 재정의하려면 AX_CODE_ALLOW_BROAD_DIR=1을 설정합니다.
• 사용 실패는 stdout에 아무것도 인쇄하지 않습니다(도움말과 한 줄 오류는 stderr로 갑니다). 그래서 잘못 친 명령은 stdout이 비고 종료 코드는 1입니다. --format json 아래에서는 사용 실패가 stdout의 error 한 줄로도 쓰입니다.
• run 명령이 활성이기 전, 프로세스가 아직 불러오는 동안 도착한 신호는 출력 없이 종료 130으로 프로세스를 끝냅니다. 명령이 활성이면 SIGINT와 SIGTERM은 항상 단일 종료 result 줄을 만들며, 상태는 cancelled입니다.