Understand the interactive CLI and scripted runs

Understand the approach

The command-line interface lets Codex work from a terminal against local project files. Running codex opens an interactive terminal user interface, often shortened to TUI. You can give an initial request and continue with follow-ups, inspect commands and steer the task. The desktop app is still the default learning surface for this course; use the CLI when terminal navigation or repeatable execution makes the work easier.

A scripted run uses codex exec rather than Claude’s print-mode flags. It accepts a task and finishes without opening the interactive conversation UI. This is useful for a bounded summary or structured extraction. It is not automatically safe because it lacks a chat window: the working directory, authentication, permissions and available tools still determine what the agent can do. Begin with a read-only task that produces an inspectable result.

Install through an option documented on the official Codex CLI page if the CLI is absent, using your normal software-approval process. The current guide includes standalone installation for supported operating systems and package-manager alternatives. This course does not run installation for you. If the CLI is already available, check its version and help rather than installing another copy. Multiple installations can make documentation and observed behavior disagree.

Compare one-shot execution with a continuing app chat

The dry-run planner prints run:false, the exact red project path and a fixed codex exec argument array. It launches no child. Inspect the directory and output artifacts before an optional authenticated task: events.jsonl, stderr.txt and final.json, accompanied by process.json.

The app chat can be steered with follow-ups. A one-shot process needs enough input and a verification contract up front. The optional runner captures process exit separately from event contents; the local exercise never claims that a Codex account or model ran.

A terminal is another project surface

Your shell’s current directory matters just as much as the folder selected in the app. Quote paths containing spaces and confirm whether commands run on the local computer, a remote host or a container. If a scripted run refuses a non-Git folder, use an appropriate disposable Git project rather than disabling repository checks casually. An environment mismatch should be diagnosed before model settings are changed.

Try it step by step

1. Open the fictional red project in the app and identify its actual source facts.
2. Inspect the dry-run plan: directory, fixed argument array and new output artifacts; no Codex child starts.
3. Compare app follow-up interaction with the one-shot prompt and process boundary.
4. If independently choosing an existing authenticated CLI, inspect help first and record actual output; otherwise mark the client run unexecuted.

A useful starting example

Illustration · adapt before use.

node labs/cli-pipeline/capture-codex.cjs --project red

codex --version
codex --help
codex --sandbox read-only "Read README.md and explain this scratch project without editing it."
codex exec --sandbox read-only "Read README.md and list missing setup information. Do not edit files."

Check your result

• The installed executable and version are identified, with no unnecessary global installation or settings change.
• Both tasks inspect the same intended project and produce source-grounded answers.
• You can explain why interactive codex and codex exec differ from each other and from desktop navigation.

Common mistakes

• Using claude -p style flags in Codex without consulting the current command reference.
• Assuming an unattended run has no permission or verification requirements.