명령줄 옵션
이 페이지는 문서화된 Codex CLI 명령과 flag를 정리한 reference입니다.
CLI는 대부분의 기본값을 ~/.codex/config.toml에서 상속합니다. 명령줄에 전달한 -c key=value override는 해당 실행에서 우선합니다. 우선순위는 설정 기초를 참고하십시오.
Global flags
이 옵션은 기본 codex 명령에 적용되며, 아래 섹션에서 다르게 설명하지 않는 한 하위 명령에도 전달됩니다. 하위 명령을 실행할 때는 codex exec --oss ...처럼 global flag를 하위 명령 뒤에 둡니다.
| Flag | 타입 | 기본값 | 설명 |
|---|---|---|---|
PROMPT | string | 없음 | 세션을 시작할 선택적 텍스트 지침입니다. 생략하면 pre-filled message 없이 TUI를 시작합니다. |
--image, -i | path[,path...] | 없음 | 초기 prompt에 하나 이상의 이미지 파일을 첨부합니다. 여러 path는 comma로 구분하거나 flag를 반복합니다. |
--model, -m | string | config 값 | 구성에 설정된 모델을 오버라이드합니다. 예: gpt-5.4. |
--oss | boolean | false | 로컬 open source model provider를 사용합니다. -c model_provider="oss"와 같습니다. Ollama 실행 여부를 검증합니다. |
--profile, -p | string | 없음 | ~/.codex/config.toml에서 로드할 구성 profile 이름입니다. |
--sandbox, -s | read-only, workspace-write, danger-full-access | config 값 | 모델이 생성한 shell command에 적용할 sandbox policy를 선택합니다. |
--ask-for-approval, -a | untrusted, on-request, never | config 값 | 명령 실행 전에 Codex가 언제 human approval을 위해 멈출지 제어합니다. on-failure는 deprecated입니다. |
--dangerously-bypass-approvals-and-sandbox, --yolo | boolean | false | 모든 명령을 승인과 sandbox 없이 실행합니다. 외부에서 강화된 환경 안에서만 사용하십시오. |
--cd, -C | path | 현재 디렉터리 | 에이전트가 요청 처리를 시작하기 전에 작업 디렉터리를 설정합니다. |
--search | boolean | false | live web search를 활성화합니다. web_search = "live"를 설정하는 것과 같습니다. |
--add-dir | path | 없음 | 기본 workspace 외에 추가 디렉터리에 write access를 부여합니다. 여러 path에는 반복 사용합니다. |
--no-alt-screen | boolean | false | TUI alternate screen mode를 비활성화합니다. |
--remote | ws://host:port 또는 wss://host:port | 없음 | Interactive TUI를 원격 app-server WebSocket endpoint에 연결합니다. codex, codex resume, codex fork에서 지원됩니다. |
--remote-auth-token-env | ENV_VAR | 없음 | --remote 연결 시 이 환경 변수에서 bearer token을 읽어 전송합니다. Token은 wss:// 또는 localhost 계열 ws:// URL에서만 전송됩니다. |
--enable | feature | 없음 | Feature flag를 강제로 켭니다. -c features.{name}=true로 변환됩니다. 반복 가능합니다. |
--disable | feature | 없음 | Feature flag를 강제로 끕니다. -c features.{name}=false로 변환됩니다. 반복 가능합니다. |
--config, -c | key=value | 없음 | 구성 값을 오버라이드합니다. 값은 가능한 경우 JSON/TOML로 parse되고, 실패하면 literal string으로 사용됩니다. |
Command overview
| 명령 | Maturity | 설명 |
|---|---|---|
codex | Stable | Terminal UI를 시작합니다. Global flag와 선택적 prompt, image attachment를 받습니다. |
codex app-server | Experimental | Local development 또는 debugging용 Codex app server를 시작합니다. |
codex app | Stable | macOS 또는 Windows에서 Codex desktop app을 시작합니다. |
codex debug app-server send-message-v2 | Experimental | Built-in test client로 app-server에 단일 V2 message를 보내 protocol 동작을 debug합니다. |
codex debug models | Experimental | Codex가 보는 raw model catalog를 출력합니다. Bundled catalog만 inspect할 수도 있습니다. |
codex apply | Stable | Codex cloud task가 생성한 최신 diff를 local working tree에 적용합니다. Alias는 codex a입니다. |
codex cloud | Experimental | Terminal에서 Codex cloud task를 탐색하거나 실행합니다. Alias는 codex cloud-tasks입니다. |
codex completion | Stable | Bash, Zsh, Fish, PowerShell용 shell completion script를 생성합니다. |
codex features | Stable | Feature flag 목록을 보고 config.toml에 enable/disable 상태를 저장합니다. |
codex exec | Stable | Script 또는 CI-style non-interactive 실행을 수행합니다. Alias는 codex e입니다. |
codex execpolicy | Preview | Exec policy rule 파일을 저장하기 전에 검사합니다. |
codex login | Stable | ChatGPT 계정 또는 API key로 CLI를 인증합니다. |
codex logout | Stable | API key와 ChatGPT 인증의 저장된 credential을 제거합니다. |
codex mcp | Stable | ~/.codex/config.toml에 저장된 MCP server entry를 관리합니다. |
codex plugin marketplace | Stable | Codex가 탐색하고 설치할 수 있는 plugin marketplace source를 관리합니다. |
codex mcp-server | Stable | 다른 tool이 연결할 수 있도록 Codex를 stdio MCP server로 실행합니다. |
codex resume | Stable | 저장된 interactive session을 이어서 실행합니다. |
codex fork | Stable | 이전 interactive session을 새 thread로 fork합니다. |
codex sandbox | Stable | Codex 내부와 같은 policy로 command를 sandbox 안에서 실행합니다. |
codex update | Stable | 설치된 release가 self-update를 지원하면 Codex CLI update를 확인하고 적용합니다. |
Command details
codex
하위 명령 없이 codex를 실행하면 interactive terminal UI(TUI)가 시작됩니다. Agent는 global flag와 image attachment를 받습니다. Web search는 기본적으로 cached mode이며, live browsing에는 --search를 사용합니다. 마찰이 적은 local work에는 --sandbox workspace-write --ask-for-approval on-request를 사용합니다.
--remote ws://host:port 또는 --remote wss://host:port로 codex app-server --listen ws://IP:PORT로 시작한 app server에 TUI를 연결합니다. 서버가 WebSocket authentication에 bearer token을 요구하면 --remote-auth-token-env ENV_VAR를 추가합니다.
codex app-server
Local Codex app server를 시작합니다. 주로 development와 debugging을 위한 기능이며 예고 없이 바뀔 수 있습니다.
주요 옵션:
| Option | 설명 |
|---|---|
--listen | stdio:// 기본 JSONL-over-stdio, ws://IP:PORT WebSocket transport, off를 지정합니다. |
--ws-auth | WebSocket auth mode입니다. capability-token 또는 signed-bearer-token을 사용할 수 있습니다. |
--ws-token-file | Capability token 파일 경로입니다. |
--ws-shared-secret-file | Signed bearer token용 공유 비밀 파일 경로입니다. |
--ws-issuer, --ws-audience, --ws-max-clock-skew-seconds | Signed bearer token 검증 옵션입니다. |
codex app-server --listen stdio://는 기본 JSONL-over-stdio 동작을 유지합니다. --listen ws://IP:PORT는 app-server client용 WebSocket transport를 활성화합니다. Client가 wss://로 연결해야 하면 TLS termination 또는 secure proxy를 사용하십시오.
Schema를 client binding으로 생성하려면 codex app-server generate-ts --out ./schemas 또는 codex app-server generate-json-schema --out ./schemas를 사용합니다. Gated field와 method를 포함하려면 --experimental을 추가합니다.
codex app
Terminal에서 Codex Desktop을 시작합니다. macOS에서는 특정 workspace path를 열 수 있고, Windows에서는 설치 후 열 path를 출력합니다.
주요 옵션:
| Option | 설명 |
|---|---|
PATH | 열 workspace path입니다. |
--download-url | Installer download URL을 오버라이드합니다. |
codex debug app-server send-message-v2
Built-in app-server test client로 app-server의 V2 thread/turn flow에 단일 message를 보냅니다. 이 debug flow는 experimentalApi: true로 initialize하고, thread를 시작하고, turn을 보낸 뒤 server notification을 stream합니다.
주요 입력은 USER_MESSAGE입니다.
codex debug models
Codex가 보는 raw model catalog를 JSON으로 출력합니다.
| Option | 설명 |
|---|---|
--bundled | Remote model endpoint를 refresh하지 않고 현재 binary에 bundled된 catalog만 inspect합니다. |
codex apply
Codex cloud task의 최신 diff를 local repository에 적용합니다. 인증되어 있어야 하고 해당 task에 접근 권한이 있어야 합니다.
| Option | 설명 |
|---|---|
TASK_ID | 적용할 cloud task ID입니다. |
Codex는 patched file을 출력하고, conflict 등으로 git apply가 실패하면 non-zero로 종료합니다.
codex cloud
Terminal에서 Codex cloud task와 상호작용합니다. 기본 명령은 interactive picker를 열고, codex cloud exec는 task를 직접 제출하며, codex cloud list는 최근 task를 script 또는 빠른 확인용으로 반환합니다.
codex cloud exec:
| Option | 설명 |
|---|---|
QUERY | 제출할 task prompt입니다. |
--env | Cloud environment ID입니다. |
--attempts | 1-4 범위의 best-of-N attempt 수입니다. |
codex cloud list:
| Option | 설명 |
|---|---|
--env | Environment로 filtering합니다. |
--limit | 반환할 task 수입니다. |
--cursor | 다음 page cursor입니다. |
--json | Automation용 JSON output을 사용합니다. |
Plain text output은 task URL 뒤에 status detail을 출력합니다. JSON payload에는 tasks array와 optional cursor가 포함됩니다.
codex completion
Shell completion script를 생성합니다.
codex completion bash
codex completion zsh
codex completion fish
codex completion powershell
예: codex completion zsh > "${fpath[1]}/_codex".
codex features
~/.codex/config.toml에 저장되는 feature flag를 관리합니다. enable과 disable은 이후 세션에 적용되도록 변경을 저장합니다. --profile로 시작했다면 root configuration 대신 해당 profile에 씁니다.
codex features list
codex features enable FEATURE
codex features disable FEATURE
codex exec
Human interaction 없이 끝나야 하는 scripted 또는 CI-style 실행에는 codex exec 또는 short form codex e를 사용합니다.
주요 옵션:
| Option | 설명 |
|---|---|
PROMPT | 실행할 prompt입니다. |
--image, -i | 입력 이미지입니다. |
--json, --experimental-json | 상태 변경마다 newline-delimited JSON event를 출력합니다. |
--output-last-message, -o | 최종 assistant message를 파일에 씁니다. |
--output-schema | Structured output schema를 지정합니다. |
--skip-git-repo-check | Git repository check를 건너뜁니다. |
--ephemeral | 실행 후 session state를 보존하지 않습니다. |
--ignore-user-config | 사용자 config를 무시합니다. |
--ignore-rules | Rules를 무시합니다. |
--color | Output color mode를 지정합니다. |
resume 하위 명령으로 non-interactive task를 계속할 수 있습니다.
codex exec resume --last "continue the previous task"
codex exec resume SESSION_ID "continue with new instructions"
--last는 현재 작업 디렉터리의 최신 session을 선택하고, --all은 모든 session을 검색합니다.
codex execpolicy
저장 전 execpolicy rule file을 검사합니다. codex execpolicy check는 하나 이상의 --rules flag를 받고, 가장 엄격한 decision과 matching rule을 JSON으로 출력합니다. --pretty를 추가하면 출력이 format됩니다.
codex login
ChatGPT 계정 또는 API key로 CLI를 인증합니다. Flag 없이 실행하면 ChatGPT OAuth flow용 browser를 엽니다.
| Option | 설명 |
|---|---|
--with-api-key | API key 기반 login을 사용합니다. |
--device-auth | Device code flow를 사용합니다. |
status | Credential이 있으면 exit code 0으로 종료합니다. Automation에 유용합니다. |
codex logout
API key와 ChatGPT authentication의 saved credential을 제거합니다. Flag는 없습니다.
codex mcp
~/.codex/config.toml에 저장된 Model Context Protocol server entry를 관리합니다.
| Command | 설명 |
|---|---|
list | 구성된 MCP server 목록을 표시합니다. |
get NAME | 특정 MCP server 구성을 표시합니다. |
add NAME -- COMMAND... | stdio MCP server를 추가합니다. |
add NAME --url URL | streamable HTTP MCP server를 추가합니다. |
remove NAME | MCP server entry를 제거합니다. |
login NAME | OAuth 지원 HTTP server에 로그인합니다. |
logout NAME | OAuth credential을 제거합니다. |
add는 --env KEY=VALUE, --bearer-token-env-var, --url을 지원합니다. OAuth action은 streamable HTTP server에서만 동작하며 server가 OAuth를 지원해야 합니다.
codex plugin marketplace
Codex가 browse/install할 수 있는 plugin marketplace source를 관리합니다.
| Command | 설명 |
|---|---|
add SOURCE | Marketplace source를 추가합니다. |
upgrade [marketplace-name] | Git marketplace 하나 또는 전체를 refresh합니다. |
remove MARKETPLACE_NAME | Marketplace source를 제거합니다. |
add는 owner/repo, owner/repo@ref, HTTP/HTTPS Git URL, SSH Git URL, local marketplace root directory를 받습니다. --ref로 Git ref를 고정하고 --sparse PATH를 반복해 sparse checkout을 사용할 수 있습니다.
codex mcp-server
다른 tool이 연결할 수 있도록 Codex를 stdio MCP server로 실행합니다. Global configuration override를 상속하고 downstream client가 연결을 닫으면 종료됩니다.
codex resume
ID로 interactive session을 이어서 실행하거나 가장 최근 대화를 재개합니다. codex resume --last는 기본적으로 현재 작업 디렉터리로 범위를 제한하며, --all을 전달하면 모든 session에서 찾습니다. codex와 같은 global flag를 받습니다.
codex fork
이전 interactive session을 새 thread로 fork합니다. 기본적으로 session picker를 열고, --last를 추가하면 가장 최근 session을 fork합니다.
codex sandbox
Codex 내부에서 사용하는 것과 같은 policy로 command를 sandbox 안에서 실행합니다.
codex sandbox macos [--permissions-profile NAME] [--log-denials] [COMMAND]...
codex sandbox linux [--permissions-profile NAME] [COMMAND]...
codex sandbox windows [--permissions-profile NAME] [COMMAND]...
공통 option에는 --cd, --include-managed-config, --config가 있습니다. macOS에는 --allow-unix-socket과 --log-denials가 추가로 있습니다.
codex update
설치된 release가 self-update를 지원하면 Codex CLI update를 확인하고 적용합니다. Debug build에서는 release build를 설치하라는 메시지를 출력합니다.
안전한 flag 조합
- Workspace 안에서 끝나는 unattended local work에는
--sandbox workspace-write를 사용하고, dedicated sandbox VM 안이 아니라면--dangerously-bypass-approvals-and-sandbox를 피하십시오. - 더 많은 directory에 write access가 필요하면
--sandbox danger-full-access보다--add-dir를 선호하십시오. - CI에서는
--json과--output-last-message를 함께 사용해 machine-readable progress와 최종 natural-language summary를 모두 캡처할 수 있습니다.