Codex CLI Patterns
Use this reference when designing the command surface for a new CLI Codex should run.
Mental model
The CLI is Codex's command layer. It should turn a service, app, API, log source, or database into shell commands Codex can run repeatedly from any repo.
Good CLIs for Codex expose composable primitives. Avoid a single command that tries to "do the whole investigation" when smaller discover, read, resolve, download, inspect, draft, and upload commands would compose better.
Help is interface
Write --help for a future Codex thread that only has the binary and a vague task. Each command should have a short description and flags with literal names from the product or API.
Good top-level help should answer:
- What containers can I discover?
- What exact objects can I read?
- What stable IDs can I resolve?
- What files can I download or upload?
- Which write actions exist?
- What is the raw escape hatch?
Prefer this command shape
Use product nouns, then verbs:
bash
tool-name --json doctor
tool-name --json accounts list
tool-name --json projects list
tool-name --json channels resolve --name codex
tool-name --json messages search "exact phrase"