FIELD MANUAL / 18 CLI + 06 ARCHIVE
Eighteen CLI lessons, plus the API archive.
The complete primary track teaches how to operate Codex in a real repository. The separately numbered archive preserves the original API architecture atlas.
Codex CLI core
Codex CLI complete curriculum
Run lessons 01–18 in order, from installation and permissions through automation, Cloud tasks, sandbox policy testing, and diagnostics.
- 01 Read the guide↗
Foundation / 10 min / Stable
Install Codex and prove the toolchain
A reliable Codex workflow starts before the first prompt. Install from the official standalone script, identify the binary you are actually running, update deliberately, and use the built-in diagnostic report instead of guessing about configuration, authentication, Git, or terminal failures.
- 02 Read the guide↗
Foundation / 11 min / Stable
Choose authentication without leaking credentials
Codex supports ChatGPT sign-in for subscription access and API-key sign-in for usage-based local work. The safe path is to choose the flow deliberately, pipe secrets through stdin, verify the active method, and treat local auth storage like a password.
- 03 Read the guide↗
Foundation / 12 min / Stable
Run the first repository session like an engineer
The first useful Codex session begins in the right repository with a bounded permission mode and a prompt that states goal, context, constraints, and done condition. Codex can explore, edit, run checks, and report evidence, but only when the task boundary is explicit.
- 04 Read the guide↗
Safety / 14 min / Stable
Set authority before autonomy
Codex security is the combination of an OS-enforced sandbox and an approval policy. Workspace-write with on-request approvals is a practical local default; read-only is for inspection and planning. Web search does not automatically grant network access to spawned commands.
- 05 Read the guide↗
Workflow / 13 min / Stable
Control a long-running CLI session
Codex CLI exposes keyboard-first controls for live work plus top-level commands for saved-session lifecycle. Plan mode improves ambiguous work; status and diff expose state; compact preserves key context; review creates a dedicated inspection pass. Resume, fork, archive, unarchive, and permanent delete keep persisted work explicit.
- 06 Read the guide↗
Repository setup / 15 min / Stable
Make repository knowledge durable with AGENTS.md
Codex reads an instruction chain before work begins: global guidance, then project files from repository root toward the working directory. Closer guidance appears later and overrides broader guidance. AGENTS.override.md wins at a level, and the combined project guidance has a default size limit.
- 07 Read the guide↗
Repository setup / 22 min / Stable
Plan Codex work by model, effort, and scope
Model-aware planning is more than selecting the largest model. Keep the CLI that already holds the repository and conversation context, map each task to a role, select only an effort advertised by that model, and keep subagent orchestration separate from single-task depth. Codex configuration still resolves by scope, while model access can drift by release, account, authentication method, quota, and rollout.
- 08 Read the guide↗
Workflow / 14 min / Stable
Turn changes into reviewable evidence
Codex can implement, run checks, show the working-tree diff, and launch a dedicated reviewer. Review scopes are mutually exclusive: uncommitted work, a base-branch comparison, a commit, or custom instructions. The reviewer reports findings without changing the tree.
- 09 Read the guide↗
Extension / 16 min / Stable
Connect external systems through MCP
Codex supports local STDIO and Streamable HTTP MCP servers. CLI, IDE extension, and desktop app share host configuration. A reliable connection names its transport, authentication source, timeouts, required status, enabled tools, and approval behavior before a workflow depends on it.
- 10 Read the guide↗
Extension / 15 min / Stable
Package repeatable work as skills
Skills package instructions, references, scripts, and optional assets. Codex discovers them through concise metadata and loads full instructions only when selected. Plugins distribute skills and optional MCP connections through configured marketplaces; list and review a marketplace before installing a named plugin.
- 11 Read the guide↗
Guardrails / 17 min / Mixed: hooks stable; rules experimental
Add guardrails with hooks and rules
Hooks run trusted command handlers at lifecycle events such as PreToolUse, PostToolUse, Stop, and SessionStart. Rules decide whether matching command prefixes are allowed, prompted, or forbidden outside the sandbox. Hooks are stable; rules remain experimental and the most restrictive matching decision wins.
- 12 Read the guide↗
Automation / 19 min / Stable core; custom-agent authoring may evolve
Scale from subagents to safe automation
Subagents protect the main thread from noisy exploration and can run independent read-heavy work in parallel. For non-interactive workflows, codex exec defaults to a read-only sandbox, streams progress to stderr, and prints the final message to stdout; JSONL and output schemas support machine consumers. GitHub Actions should use the official action and narrow privileges.
- 13 Read the guide↗
Automation / 12 min / Runtime-confirmed in Codex 0.147.0
Run repeatable headless work with codex exec
codex exec is the non-interactive entry point for scripts and CI. It accepts a prompt as an argument or stdin, uses the same repository guidance and sandbox model as interactive Codex, returns a meaningful process status, and can resume saved exec sessions. Reliability comes from a bounded working directory, explicit permissions, isolated credentials, and verification that does not depend on a conversational transcript.
- 14 Read the guide↗
Automation / 11 min / Runtime-confirmed in Codex 0.147.0
Stream JSONL and constrain the final result
With --json, codex exec emits newline-delimited JSON events to stdout. --output-schema constrains the final response with a JSON Schema, while --output-last-message writes the final message to a chosen file. These are distinct surfaces: event streaming supports progress and diagnostics; the final artifact supports a stable consumer contract. Neither proves the underlying code change is correct.
- 15 Read the guide↗
Operations / 10 min / Runtime-confirmed in Codex 0.147.0
Resume, fork, archive, and restore Codex sessions
Codex persists interactive and exec sessions so work can continue later. resume continues a lineage; fork creates a branch; archive and unarchive provide reversible housekeeping; delete permanently removes the selected saved session. The safe unit of continuation is the pair of an exact session and a compatible repository state.
- 16 Read the guide↗
Cloud operations / 12 min / Experimental Cloud surface; commands runtime-confirmed
Review Codex Cloud tasks before applying them locally
The experimental cloud command can submit a task to a named environment, list or inspect task state, display a selected attempt’s unified diff, and apply that diff to the local working tree. Applying is not merging and does not prove the patch fits the current branch. Inspect the exact task, attempt, local status, and resulting tests before accepting anything.
- 17 Read the guide↗
Security / 13 min / Sandbox command stable; execpolicy is evolving
Test commands in the sandbox and audit execpolicy
codex sandbox runs a command inside a Codex-provided sandbox and can resolve a named permission profile, narrow readable roots or network, and log macOS denials. execpolicy check evaluates a command against rule files and explains the decision. These tools diagnose and test authority; they do not make an unsafe command safe or replace operating-system enforcement.
- 18 Read the guide↗
Operations / 10 min / Runtime-confirmed in Codex 0.147.0
Diagnose Codex, inspect features, and generate completions
Codex provides doctor for layered installation and runtime health, features for staged feature state, completion for shell integration, and debug utilities for targeted evidence such as the bundled model catalog. Start with read-only inspection, preserve version context, and review generated or diagnostic output before placing it in tickets or startup files.
OpenAI Platform / API
OpenAI Platform / API archive
Separately numbered companion guidance for API and SDK builders; not part of the CLI curriculum.
- A01 Read the guide↗
Platform architecture / 9 min / Stable
Make Responses the system boundary
The Responses API is the recommended starting point for new OpenAI integrations. Treat it as an application boundary—not a thin text-generation wrapper—so messages, tool calls, tool results, and future input types remain explicit.
- A02 Read the guide↗
Platform architecture / 11 min / Stable
Give every tool a narrow contract
OpenAI tools can search, retrieve files, execute code, connect through MCP, or call your own functions. Reliability comes from the boundary around each action: a small schema, explicit authority, idempotency, and a result the model can interpret.
- A03 Read the guide↗
Platform architecture / 8 min / Stable
Treat schema as user experience
Structured Outputs can constrain model responses to a supplied JSON Schema. That removes a class of parsing failures, but it does not prove that values are true, useful, authorized, or safe to apply.
- A04 Read the guide↗
Platform architecture / 12 min / Stable
Choose who owns the agent loop
An agent plans, calls tools, carries state, and may hand work to specialists. The key architecture decision is not how many agents exist—it is who owns the run loop, tool policy, state, approvals, and trace.
- A05 Read the guide↗
Platform architecture / 10 min / Stable
Design Realtime as a live system
Realtime sessions are designed for low-latency live interactions. A production voice experience is more than streaming audio: it needs a transport chosen for the client, explicit session state, interruption behavior, tool latency budgets, and recovery from partial turns.
- A06 Read the guide↗
Platform architecture / 9 min / Stable
Keep model choice at the edge
The OpenAI model catalog changes over time. Product code should ask for a tested capability profile—quality, latency, modalities, tool support, and budget—then resolve that profile through configuration and evaluations.