Manual Interacting With Codex Via CLI

Interacting With Codex Via CLI

Workflow skill for evidence-based manual verification through real codex commands.

Use this as a companion to manual-testing when runtime proof depends on Codex CLI behavior.

References:

• CLI: https://developers.openai.com/codex/cli
• Command reference: https://developers.openai.com/codex/cli/reference
• Sandboxing: https://developers.openai.com/codex/concepts/sandboxing
• Open source repo: https://github.com/openai/codex

Core Rule

Choose sandbox and approval behavior explicitly.

• Preserve user Codex setup when Codex is only a helper agent or a user-specific repro.
• Isolate aggressively when testing Codex behavior, config, profiles, skills, plugins, MCP, hooks, rules, permissions, or sandbox semantics.
• Use --cd for every non-interactive run so the workspace is explicit.
• Default to network-capable workspace-write runs for trusted helper, verification, and edit scenarios.
• Add -c sandbox_workspace_write.network_access=true unless the task is explicitly testing network denial or untrusted code isolation.
• Treat danger-full-access and --dangerously-bypass-approvals-and-sandbox as valid only inside externally hardened disposable environments or when user/instructions explicitly allow this. Treat older --yolo examples as legacy guidance unless installed help still exposes that flag.
• Do not use deprecated --full-auto as a default; use explicit sandbox and approval flags.
• Never claim compatibility without fresh command output or JSON evidence.

Scenario Matrix

Command Selection

First inspect local availability and installed behavior:

type -a codex
codex --version
codex --help
codex exec --help
codex login status

If codex is not installed, stop and report missing CLI bootstrap unless the task is docs-only research.

Use the user's normal codex command for helper-agent work and user-specific repros. Use temp CODEX_HOME, --ignore-user-config, or --ignore-rules only when inherited configuration would contaminate the test.

For complex prompts that might break shell interpolation, prefer prompt files or stdin:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" \
  --json \
  - < prompt.md

Isolation Building Blocks

Codex behavior can come from config, profiles, project trust, hooks, rules, MCP, skills, plugins, auth, and session history.

Strict temp-state pattern:

tmp="$(mktemp -d /tmp/codex-cli-test.XXXXXX)"
mkdir -p "$tmp/codex-home" "$tmp/project"

CODEX_HOME="$tmp/codex-home" \
codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --ignore-user-config \
  --cd "$tmp/project" \
  --skip-git-repo-check \
  --json \
  "Reply with exactly: ok"

On Codex 0.134.0, approval policy is a top-level flag, not an exec option. Prefer putting global flags before exec for portability across installed versions:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" --json "Reply with exactly: ok"

If real paid-provider auth is needed, preserve only the required auth source and isolate unrelated config, hooks, rules, project context, skills, plugins, MCP, and sessions.

Helper Agent Runs

Use this when Codex is just another AI helper.

Default: preserve the user's normal Codex setup.

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" \
  --json \
  "Research this question and report concise findings: <task>"

When edits are expected, run in an isolated worktree or temp copy. For no-edit helper runs, instruct Codex not to modify files and verify the diff afterward.

Background shelling with &, PID files, and logs can still be useful for long tasks, but non-interactive codex exec is already script-friendly. Prefer JSONL artifacts and --output-last-message over ad hoc tail checks.

Checking A Generic Run

Use this when the task is simply generation through codex exec.

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" \
  --json \
  "Reply with exactly: ok"

For downstream scripting:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" \
  --json \
  --output-last-message "$tmp/final.md" \
  "Summarize the repository structure."

Verify exit code, JSON events, final output, and absence of auth/sandbox/approval failures.

Checking Tool Or File Effects

Use this when runtime compatibility depends on tool execution or file changes.

• Do not rely on final prose alone.
• Require a deterministic action such as reading a named file, running a safe command, or making a small isolated edit.
• Use --json events and inspect changed files or --output-last-message.
• Keep write checks inside a temp repo or git worktree.

Read-only pattern:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$repo" \
  --json \
  "Read README.md and report only its first heading. Do not modify files."

Workspace-write pattern:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$worktree" \
  --json \
  --output-last-message "$tmp/final.md" \
  "Make the smallest requested edit, then report the exact files changed."

Checking Sandbox And Approvals

Sandbox and approval policies work together.

Network access is separate from filesystem sandboxing. For this repo's Codex helper workflows, networked command execution is usually expected, so enable it by default in workspace-write runs:

codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  exec --cd "$repo" \
  --json \
  "Run the dependency check that requires network."

Use read-only only when intentionally blocking writes and command side effects. If a nominally read-only task may need package-manager, test, documentation, or web-backed shell commands, use network-enabled workspace-write, instruct Codex not to edit files, and verify git diff afterward.

Disable command network access only for sandbox/security tests, untrusted code, or when reproducing network-denial behavior.

Do not mix newer permission-profile features with older sandbox_mode assumptions unless the installed Codex version and docs confirm how they compose.

Checking Resume And Sessions

Use official resume syntax.

codex exec resume --last \
  "Continue with the verification step only."

Or resume a known session:

codex exec resume <session-id> \
  "Continue from the previous result and report only remaining risks."

Before resuming a backgrounded process, verify the previous process ended. Do not send a follow-up to a session that is still running.

Use --ephemeral when session persistence is undesirable.

Checking Skills, Plugins, MCP, Hooks, And Rules

Skills/plugins/MCP features move quickly; verify against installed codex --help, codex exec --help, and current official docs.

MCP inspection:

codex mcp list --json
codex mcp get <server-name> --json

MCP add pattern:

codex mcp add context7 -- npx -y @upstash/context7-mcp

Rules check pattern, only when installed help exposes codex execpolicy:

codex execpolicy --help
codex execpolicy check --pretty \
  --rules "$HOME/.codex/rules/default.rules" \
  -- gh pr view 123 --json title,body

When testing MCP/plugin/skill/hook behavior, isolate config so only the target component is active. If a component must initialize for the run to count, configure it to fail loudly where supported and inspect JSON events or command output.

CI And Automation

Prefer official Codex automation when it fits. For raw CLI use:

• install or pin Codex explicitly
• check codex --version
• set model/config explicitly when needed
• use --cd "$GITHUB_WORKSPACE"
• choose explicit sandbox and approval policy
• emit --json and save artifacts
• scope CODEX_API_KEY or OPENAI_API_KEY to the single invocation when possible
• never print secrets or config files containing credentials

Example:

CODEX_API_KEY="$CODEX_API_KEY" \
codex --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  --ask-for-approval never \
  exec --cd "$GITHUB_WORKSPACE" \
  --json \
  "Review repository state and report high-confidence findings only."

Env And Secrets

Set only env needed for the run.

• Prefer documented auth flows: codex login, codex login status, or scoped API key env.
• Do not expose API keys job-wide in CI unless unavoidable.
• Do not print CODEX_HOME auth files, full config, or environment dumps.
• Report credential presence or absence without values.

Failure Classes

Name the failure; do not say only "it failed".

• Missing CLI bootstrap: codex is not installed or not on PATH.
• Missing auth / bootstrap precondition: codex login status fails or required API env is absent.
• Unsafe autonomy: danger-full-access, --dangerously-bypass-approvals-and-sandbox, or legacy bypass aliases used outside a hardened environment.
• Interactive deadlock: non-interactive run uses an approval policy that can prompt.
• Flag placement mismatch: installed Codex accepts global flags such as --ask-for-approval only before exec.
• Config contamination: user/project .codex, hooks, rules, MCP, skills, plugins, profile, or history affected a behavior test.
• Over-isolation: temp CODEX_HOME hid config/auth needed for a user repro.
• Wrong working directory: missing or wrong --cd selected the wrong repo/session.
• Git repo guard: non-repo run failed without --skip-git-repo-check.
• Network confusion: expected networked commands failed because the workspace-write network config was omitted or unsupported by the installed version.
• MCP/plugin/skill false positive: configured component was not actually initialized or used.
• Tool/file effect issue: final text did not match actual JSON events or filesystem state.
• Version drift: docs mention flags/features missing from installed help.

Evidence And Reporting

Collect the smallest complete evidence set for the claim.

Report:

• scenario run
• exact commands with secrets redacted
• installed version and command path when relevant
• layers preserved, isolated, or bootstrapped
• sandbox and approval settings
• pass/fail for each step
• key output snippets and failure class

Common Mistakes

• Using --full-auto from old notes instead of explicit sandbox/approval flags.
• Using danger-full-access, --dangerously-bypass-approvals-and-sandbox, or legacy bypass aliases outside a disposable external sandbox.
• Forgetting --cd and testing the wrong project.
• Letting user/project config, hooks, rules, MCP, skills, or plugins leak into behavior tests.
• Over-isolating and then reporting a user-specific repro cannot be reproduced.
• Treating final prose as proof of tool use or file effects.
• Running non-interactively with a policy that can request approval.
• Forgetting -c sandbox_workspace_write.network_access=true for Codex helper runs that may need networked commands.
• Printing API keys, auth files, config, JSON events, or env dumps containing secrets.