Codex CLI flags · AI coding agents

Flags are passed to the codex binary in the terminal (see Codex CLI terminal commands); most global flags propagate to subcommands such as codex exec --oss. For in-session controls, see Codex CLI slash commands. Most flags map to config.toml keys — see Codex CLI configuration.

Session

Flag	Purpose	Example
`-p, --profile <name>`	Layer `$CODEX_HOME/<name>.config.toml` on top of the base user config	`codex --profile work`
`-C, --cd <path>`	Set the working directory before processing	`codex --cd services/api`
`-c, --config key=value`	Override config values; parsed as TOML if possible, repeatable, dot-notation for nested keys	`codex -c model_reasoning_effort=high`
`--enable <feature>` / `--disable <feature>`	Force-enable/disable a feature flag (translates to `-c features.<name>=true/false`), repeatable	`codex --enable unified_exec`
`--no-alt-screen`	Disable the TUI alternate screen (overrides `tui.alternate_screen`)	`codex --no-alt-screen`
`--strict-config`	Error on unrecognized `config.toml` fields (supported by `codex`, `exec`, `review`, `resume`, `fork`, `app-server`, `mcp-server`, `exec-server`)	`codex --strict-config`
`--remote <endpoint>`	Connect the TUI to a remote app-server (`ws://`, `wss://`, `unix://`, `unix://PATH`; supported by `codex`, `resume`, `fork`, `archive`, `delete`, `unarchive`)	`codex --remote ws://10.0.0.5:8080`
`--remote-auth-token-env <ENV_VAR>`	Bearer token env var for `--remote`	`codex --remote ws://... --remote-auth-token-env CODEX_TOKEN`

Models

Flag	Purpose	Example
`-m, --model <name>`	Override the configured model	`codex -m gpt-5.6-terra`
`--oss`	Use a local open-source model provider (LM Studio or Ollama); interactive CLI prompts if unset, `codex exec` errors	`codex --oss`
`--local-provider <lmstudio\|ollama>`	Choose the local provider used with `--oss`	`codex --oss --local-provider ollama`

Permissions

Flag	Purpose	Example
`-s, --sandbox <mode>`	Sandbox for model-generated shell commands: `read-only`, `workspace-write`, `danger-full-access`	`codex -s workspace-write`
`-a, --ask-for-approval <policy>`	When Codex pauses for human approval: `untrusted`, `on-request`, `never`	`codex -a on-request`
`--add-dir <path>`	Grant extra directories write access alongside the workspace; repeatable	`codex --add-dir ../shared-lib`
`--full-auto`	DEPRECATED compatibility flag on `codex exec`; prints a warning — use `--sandbox workspace-write` instead	`codex exec --sandbox workspace-write "..."`
`--dangerously-bypass-approvals-and-sandbox`, `--yolo`	Run every command with no approvals and no sandbox — only inside an externally hardened environment. See the warning in Codex CLI permissions, sandbox, and approvals	not recommended as a default

The approval_policy value on-failure is deprecated in config.toml — use on-request (interactive) or never (non-interactive).

Context

Flag	Purpose	Example
`-i, --image <path[,path...]>`	Attach image(s) to the initial prompt; comma-separated or repeat the flag	`codex -i mockup.png,flow.png`
`--search`	Enable live web search (sets `web_search = "live"` instead of the default `"cached"`)	`codex --search "latest Next.js API changes"`

Output

Flag	Purpose	Example
`--json` / `--experimental-json`	(`codex exec`) Emit newline-delimited JSON events: `thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.*`, `error`	`codex exec --json "..."`
`-o, --output-last-message <path>`	(`codex exec`) Write the final agent message to a file	`codex exec -o out.md "..."`
`--output-schema <path>`	(`codex exec`) JSON Schema for the final response	`codex exec --output-schema schema.json "..."`
`--color <always\|never\|auto>`	(`codex exec`) Control colored output	`codex exec --color never "..."`

Debugging

Flag	Purpose	Example
`--skip-git-repo-check`	(`codex exec`) Allow running outside a Git repo	`codex exec --skip-git-repo-check "..."`
`--ephemeral`	(`codex exec`) Don’t persist rollout files	`codex exec --ephemeral "..."`
`--ignore-rules`	(`codex exec`) Skip execpolicy `.rules` files	`codex exec --ignore-rules "..."`
`--ignore-user-config`	(`codex exec`) Skip `$CODEX_HOME/config.toml` (auth still uses `CODEX_HOME`)	`codex exec --ignore-user-config "..."`

Automation

Recommended CI/scripting combos from the official docs:

Flag	Purpose	Example
`--json` + `-o`	Pair JSONL events with the final message in CI	`codex exec --json -o result.txt "Summarize PR changes"`
`--sandbox workspace-write`	Prefer this for unattended local work	`codex exec --sandbox workspace-write "run tests"`
`--add-dir`	Prefer over `--sandbox danger-full-access` when the agent needs more than the workspace	`codex exec --add-dir ../fixtures "..."`
`--dangerously-bypass-hook-trust`	Run enabled hooks without persisted hook trust (automation only)	`codex --dangerously-bypass-hook-trust`

Auth in automation: the CODEX_API_KEY env var provides single-run API-key auth for codex exec, codex review, and the TypeScript SDK. The GitHub Action openai/codex-action is recommended over manual CLI install in Actions; avoid exposing job-level OPENAI_API_KEY/CODEX_API_KEY in untrusted workflows.

Integrations

Flag	Purpose	Example
`--remote` / `--remote-auth-token-env`	Connect the TUI to a remote app-server (see Session above)	`codex resume --remote ws://...`
`--oss` / `--local-provider`	Local model providers (see Models above)	`codex exec --oss --local-provider lmstudio "..."`

Official safety tips: avoid --dangerously-bypass-approvals-and-sandbox outside a dedicated sandbox VM; prefer --sandbox workspace-write for unattended local work; prefer --add-dir over --sandbox danger-full-access.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.