Codex CLI workflows and commands

When to use interactive sessions, exec, resume, review, profiles, slash commands, and machine-readable output.

Codex CLI supports several workflows around the same core agent. Choosing the right entry point reduces prompting overhead and prevents an interactive task from turning into fragile automation.

Interactive work

Launch codex when the task may change as you learn more. The terminal interface is designed for exploration, implementation, and review in one session.

Useful session commands include:

/status to confirm the model, permissions, writable roots, and context use;
/plan for a planning pass before implementation;
/diff to inspect tracked and untracked changes;
/review for a focused review of the working tree;
/permissions to tighten or relax the current boundary;
/compact to summarize a long transcript and free context;
/resume or codex resume to continue saved work;
/fork to explore a different approach without replacing the original thread.

While Codex is working, pressing Enter sends a message into the current run. Use this to correct direction or add missing context. Pressing Tab queues the message for the next turn, which is better for a follow-up that should wait for the current change to finish.

Non-interactive work

Use codex exec for a stable task with defined inputs and permissions:

codex exec "review the current changes and report correctness risks"

The default sandbox for codex exec is read-only. Add --sandbox workspace-write only when the automation is meant to edit files. Avoid full host access unless the process already runs inside a separately hardened container or runner.

For scripts that only need the final response, standard output is sufficient. Use --json when another program needs structured events for commands, file changes, tool calls, failures, and token usage. Use --ephemeral when the run should not persist session rollout files.

Configuration and profiles

Personal defaults belong in ~/.codex/config.toml; repository-specific settings can live in .codex/config.toml after the project is trusted. Named profile files are useful when CI, review, and interactive development need different defaults.

CLI flags and -c key=value overrides should remain one-off. If the same override appears repeatedly, move it into the appropriate configuration layer so future runs are easier to reproduce.

Diagnose before guessing

When behavior differs from expectations, inspect /status and the active config layers before changing the prompt. Common causes include the wrong working directory, an untrusted project, a missing tool, a read-only sandbox, disabled network access, or a higher-precedence configuration value.

codex doctor can produce a diagnostic report for installation, authentication, runtime, Git, terminal, configuration, app-server, and session inventory issues.