Master reference for OpenAI Codex CLI — the terminal coding agent from OpenAI. Use this skill whenever you need to run Codex commands, write scripts with `codex exec`, automate coding with Codex, configure sandbox modes, parse JSON streaming output, or integrate Codex into CI/Gradle. Also triggers on: 'codex exec', 'codex full-auto', 'codex yolo mode', 'codex JSON stream', 'codex sandbox', 'OpenAI coding agent CLI', 'codex non-interactive'.
OpenAI Codex CLI is a terminal coding agent. The exec subcommand is the key to non-interactive, scriptable automation with JSON streaming output.
Codex ships as an npm package (@openai/codex). Two primary modes:
codex launches a terminal UIcodex exec "prompt" runs the task and exitsAuth via CODEX_API_KEY environment variable or codex login.
codex exec)# Basic execution
codex exec "fix the build errors"
# Full auto (on-request approval + workspace-write sandbox)
codex exec "refactor utils/" --full-auto
# YOLO (no approvals, no sandbox — total autonomy)
codex exec "deploy to staging" --yolo
# JSON streaming output (JSONL to stdout)
codex exec "add input validation" --json
# Save final message to file
codex exec "generate API docs" -o ./output.md
# Structured output with schema
codex exec "list dependencies" --output-schema deps-schema.json --json
# Ephemeral (no state persisted locally)
codex exec "one-off analysis" --ephemeral
# Resume a session
codex exec --resume SESSION_ID "continue the work"
# Attach images
codex exec "implement this UI" -i screenshot.png
# Custom model
codex exec "task" -m gpt-5-codex
| Mode | Flag | Description |
|---|---|---|
| Untrusted (default) | -a untrusted | Sandboxed, prompts for everything |
| On-request | -a on-request | Prompts only for unusual actions |
| Never | -a never | Never prompt |
| Full auto | --full-auto | On-request + workspace-write sandbox |
| YOLO | --yolo | No approvals, no sandbox |
Sandbox levels:
| Level | Flag | Description |
|---|---|---|
| Read-only | -s read-only | No writes |
| Workspace-write | -s workspace-write | Writes only to project |
| Full access | -s danger-full-access | Unrestricted |
When --json is used, stdout emits newline-delimited JSON:
| Event | Description |
|---|---|
thread.started | Session begins |
turn.started / turn.completed / turn.failed | Agent reasoning cycles |
item.started / item.completed | Individual items |
Item types: agent_message, reasoning, command_execution, file_change, mcp_tool_call, web_search, plan_update
| Flag | Short | What it does |
|---|---|---|
--model | -m | Override model |
--ask-for-approval | -a | untrusted/on-request/never |
--sandbox | -s | read-only/workspace-write/danger-full-access |
--full-auto | On-request + workspace-write | |
--yolo | No approvals, no sandbox | |
--image | -i | Attach images (repeatable) |
--add-dir | Additional write access dirs | |
--cd | -C | Working directory |
--profile | -p | Config profile from ~/.codex/config.toml |
--search | Enable live web search | |
--oss | Use local model (Ollama) |
codex exec Flags| Flag | Short | What it does |
|---|---|---|
--json | JSONL streaming output | |
--output-last-message | -o | Write final message to file |
--output-schema | JSON Schema for structured response | |
--ephemeral | Don't persist session | |
--resume | Resume session by ID | |
--color | always/never/auto |
// Exec task
tasks.register<Exec>("codexFix") {
commandLine("codex", "exec", "fix compilation errors", "--full-auto", "--json")
workingDir = projectDir
environment("CODEX_API_KEY", providers.environmentVariable("CODEX_API_KEY").get())
}
// Streaming JSON parse
val proc = ProcessBuilder("codex", "exec", prompt, "--full-auto", "--json")
.directory(projectDir).start()
proc.inputStream.bufferedReader().forEachLine { line ->
val event = JSONObject(line)
when (event.getString("type")) {
"turn.completed" -> println("Turn done")
"item.completed" -> println("Item: ${event.getJSONObject("item")}")
}
}
val exitCode = proc.waitFor()
| ❌ Don't | ✅ Do Instead |
|---|---|
Use --yolo in CI without understanding risks | Use --full-auto for safer automation |
Parse --json output with rigid schemas | Parse defensively — format may evolve |
| Assume spending caps exist | There's no --max-budget — monitor externally |
Forget --ephemeral for throwaway tasks | Use it to avoid polluting session history |
Skip --json when parsing output | Always use --json for programmatic consumption |
--yolo is completely unsandboxed — full filesystem and shell access--output-schema validation is best-effort, not guaranteed~/.codex/config.toml with profile supportCODEX_API_KEY or codex login)codex exec for non-interactive (not bare codex)--full-auto, --yolo, or -a)--json flag present when parsing output programmatically