CLI and terminal reference

Commands is the quick reference. This page explains terminal sessions, non-interactive output, remote app-server connections and diagnostics.

#Working directory

Start at the project root so the workspace boundary is clear:

cd /path/to/project
codex

Select a directory for a single run:

codex -C /path/to/project
codex --cd /path/to/project "Explain this project"

For multiple directories, prefer a worktree, the monorepo root or --add-dir rather than granting whole-disk access.

#Common startup combinations

--dangerously-bypass-approvals-and-sandbox belongs only in isolated, recoverable environments. Do not make it the default in production or secret-bearing directories.

#Interactive habits

Threads can be continued, forked, archived or deleted. Do not have two threads edit the same files unless they use independent worktrees.

#Non-interactive exec

Use codex exec for scripts, CI and one-off batches:

codex exec "review the current diff and list P0/P1 risks"

Continue a previous run:

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

Or select a session:

codex exec resume <SESSION_ID> "continue with the same constraints"

Non-interactive runs normally require a Git repository. Use --skip-git-repo-check only when deliberately running outside one.

#stdin pipelines

Pass generated context through stdin together with a task prompt:

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix"

Inspect logs:

tail -n 200 app.log \
  | codex exec "identify the likely root cause and next three debugging steps"

Explain a CI failure:

gh run view 123456 --log \
  | codex exec "write a concise PR comment explaining the CI failure"

#Output and automation

For GitHub Actions, see Non-interactive, CI and SDK.

#app-server and remote connections

codex app-server provides the protocol used by richer clients such as desktop and IDE integrations. It is useful for integration/debugging rather than ordinary one-off CI.

codex app-server
codex app-server --listen ws://127.0.0.1:4500
codex app-server --listen unix://

Connect to a server:

codex --remote ws://127.0.0.1:4500

Keep WebSocket listeners on localhost or behind an SSH tunnel. Remote exposure requires authentication; do not expose an unauthenticated listener on a public or local network.

#Diagnostics

codex doctor
codex debug models
codex features
codex mcp list

Inside the TUI:

/debug-config
/mcp
/status
/usage
/feedback

Logs:

RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

Use codex-login.log for authentication troubleshooting where the installed client provides it. Non-interactive runs normally include diagnostics in command output.

#Shell completion

Inspect the installed version's completion options:

codex completion --help

If a command is missing, update the client or consult codex --help and codex <subcommand> --help for that version.

#Official references

• CLI reference
• Codex manual: slash commands
• Non-interactive mode
• Codex manual: app-server