Codex: Codex Command-Line Tool
Last updated: 2026-08-31
Codex CLI is the most popular method for developers. This lesson covers advanced CLI usage and configuration.
📋 Prerequisites: CLI installed (see Lesson 2), basic command knowledge
1. What You Will Learn
- CLI advanced parameters
- CLI configuration files
- Output format control
- Integration with other tools
2. CLI Advanced Parameters
(1) Complete Parameter List
| Parameter | Description | Example |
|---|---|---|
--model |
Specify model | --model o3 |
--sandbox |
Sandbox mode | --sandbox readonly |
--approval-policy |
Approval policy | --approval-policy approve |
--auto-edit |
Auto Edit mode | — |
--full-auto |
Full Auto mode | — |
--quiet |
Quiet mode, less output | — |
--json |
JSON format output | — |
--context |
Specify context files | --context AGENTS.md |
--system-prompt |
Custom system prompt | --system-prompt "You are..." |
--max-tokens |
Max output token count | --max-tokens 4096 |
--temperature |
Temperature parameter | --temperature 0.2 |
(2) Common Combinations
BASH
# Read-only code review
codex --sandbox readonly "Review code security"
# Auto-fix lint errors
codex --full-auto --approval-policy approve "Fix all lint errors"
# Specific model + quiet mode
codex --model o3 --quiet "Refactor auth module"
# Custom system prompt
codex --system-prompt "You are a Rust expert, follow Rust API Guidelines" "Optimize algorithm performance"
3. CLI Configuration Files
(1) Global Configuration
TOML
# ~/.codex/config.toml
model = "gpt-5-codex"
approval_policy = "ask"
sandbox_mode = "workspace-write"
[output]
format = "text" # text / json / markdown
color = true
progress = true
[context]
auto_compact = true
max_files = 50
exclude = ["node_modules/", ".git/", "dist/"]
(2) Project Configuration
TOML
# .codex/config.toml
model = "deepseek-coder"
approval_policy = "approve"
[context]
include = ["src/**/*.ts", "tests/**/*.ts"]
▶ Example 1: Alice's CLI Configuration
TOML
# Alice's global config
model = "gpt-5-codex"
approval_policy = "ask"
[output]
format = "text"
color = true
[context]
auto_compact = true
exclude = ["node_modules/", ".next/", "dist/", "coverage/"]
[sandbox]
mode = "workspace-write"
blocked_paths = [".env", ".env.local", "secrets/"]
4. Non-Interactive Mode
Codex CLI supports non-interactive mode, ideal for script integration:
(1) Single Execution
BASH
# Pass task directly, exits after execution
codex --quiet "Add type annotations to app.py"
# Output to file
codex --quiet "Generate API documentation" > api-docs.md
(2) Pipe Input
BASH
# Read from stdin
echo "Explain this code" | codex --quiet
# Read from file
cat error.log | codex --quiet "Analyze error log, find root cause"
# Combine with git
git diff | codex --quiet "Review these changes"
(3) JSON Output
BASH
# JSON format output, suitable for programmatic parsing
codex --json "List all TODO comments" > todos.json
JSON output example:
JSON
{
"task": "List all TODO comments",
"status": "completed",
"files_modified": [],
"files_read": ["src/main.ts", "src/utils.ts"],
"result": "Found 5 TODO comments:\n- src/main.ts:12\n- src/utils.ts:45\n..."
}
5. Integration with Other Tools
(1) Git Hooks
BASH
# pre-commit hook: auto-fix lint
# .git/hooks/pre-commit
#!/bin/bash
codex --full-auto --quiet "Fix all lint errors"
git add -A
(2) CI/CD Integration
YAML
# GitHub Actions
- name: Code Review
run: |
codex --sandbox readonly --quiet "Review PR changes, focusing on security and performance"
(3) Makefile Integration
MAKEFILE
# Makefile
lint-fix:
codex --full-auto "Fix all lint errors"
test-gen:
codex --full-auto "Generate unit tests for all files under src/"
review:
codex --sandbox readonly "Review current changes"
▶ Example 2: Bob's Automation Workflow
BASH
# Bob's daily-dev.sh script
#!/bin/bash
# Pull latest code
git pull origin main
# Auto-fix lint
codex --full-auto --quiet "Fix all lint errors"
# Generate missing tests
codex --full-auto --quiet "Generate unit tests for source files without tests"
# Run tests
npm test
# If all pass, commit
if [ $? -eq 0 ]; then
git add -A
git commit -m "chore: auto lint-fix and test generation"
fi
6. Debugging & Logging
BASH
# Verbose output mode
codex --verbose "Fix bug"
# Save log
codex --log-file codex.log "Fix bug"
# View audit records
cat ~/.codex/audit.log
❓ FAQ
Q Can CLI and App run simultaneously?
A Yes, but not recommended on the same project simultaneously. Different projects can be used in parallel.
Q Does non-interactive mode support all features?
A Most features are supported, but interactive confirmation features like Computer Use are limited in non-interactive mode.
Q How do I limit CLI execution time?
A Use the system timeout command:
timeout 300 codex --quiet "Fix bug".Q What is the complete JSON output format?
A Contains task, status, files_modified, files_read, result fields. Run
codex --json --help to see the full schema.Q Can Codex modify files in pipe mode?
A Yes, but requires
--approval-policy approve or --full-auto mode. Default ask mode will hang waiting for confirmation in a pipe.📖 Summary
- CLI advanced parameters:
--model/--sandbox/--quiet/--json - Non-interactive mode: single execution, pipe input, JSON output
- Integration scenarios: Git Hooks, CI/CD, Makefile
- Configuration priority: CLI args > env vars > project > global
📝 Exercises
- Basic (⭐): Use CLI non-interactive mode for a code review, output to a file.
- Intermediate (⭐⭐): Create a Makefile integrating common Codex tasks.
- Advanced (⭐⭐⭐): Write a Git Hook that has Codex automatically review change quality before each commit.
