Use Codex in a repeatable pipeline

Use codex exec for a bounded task that ends with a reviewable artifact. Keep scope approval, downstream decisions, and retries in the coordinator. A successful model answer still needs the task's acceptance checks.

The CLI flags below were checked with Codex CLI 0.153.4 on 2026-09-08. The download's transport parser is tested with synthetic output. A credentialed provider run has not been verified for this guide.

Prepare one explicit task

Start with the reference package. Its retry fixture contains a configuration file and a short contract. The request names the allowed change and includes a JSON schema. It contains no credentials.

Create an import run, review its scope packet, and approve that exact digest. After the coordinator reaches an eligible Codex stage, export the request:

node cli.mjs export ./my-run --stage implement --file implement-request.json

This command applies to the implementation recipe. The preceding plan and design decision must already be complete. A request is bound to its recipe, source snapshot, dependencies, stage, and attempt.

For a native invocation, write the exported schema to a JSON file and pass the exported prompt through standard input:

codex exec --ignore-user-config --skip-git-repo-check --sandbox read-only --json \
  --output-schema result-schema.json --model YOUR_AVAILABLE_MODEL -

The line breaks illustrate the argument list; use your shell's continuation syntax. The package's invocation() builds the actual argument array without shell interpolation.

--skip-git-repo-check lets this JSON-only fixture run from a prepared directory outside Git. It does not change the sandbox or approve access to additional files.

This fixture asks Codex to propose JSON data. The coordinator validates and applies that data to its candidate artifact. Repository editing tasks need an appropriate writable sandbox and isolated checkout.

Separate events from the final result

Standard output with --json is JSONL: one event per line. Preserve process exit status and standard error separately. Find the completed agent message and parse its text as JSON. Require successful terminal completion and reject error events or an incomplete turn.

Validate the final object again in your own code. Schema-constrained output does not prove that a cited line exists or that the proposed configuration satisfies the contract.

The reference adapter checks the envelope, then the coordinator checks allowed fields, paths, evidence quotes, and the fixed retry cases. A forged field such as approve: true is invalid data.

Keep configuration and access deliberate

--ignore-user-config skips the ordinary user configuration while retaining the selected Codex home's authentication. It is useful for reducing accidental personal configuration dependencies. Inspect the effective project, managed, and execution policies too; this flag is not a complete isolation boundary.

Local runs can reuse supported saved CLI authentication. API-key access and ChatGPT-backed access have different accounting and policy implications. See local, IDE, cloud, and account choices. Never export a credential file as a pipeline artifact.

A read-only sandbox constrains writes according to the actual host's sandbox implementation. Put only approved input in the execution environment, keep coordinator records outside the agent's writable area, and test the policy on that platform.

Choose the interface that fits the interaction

Use the CLI when the job has a clear beginning and final artifact. The Codex SDK adds programmatic thread handling. App Server suits a host that needs streamed interactions and actual approval requests.

Do not infer a human decision from a progress event or from an agent saying that someone approved. The coordinator must receive and record the decision. Native session identifiers remain specific to their tool; a Gemini or Claude stage receives an artifact handoff instead.

The package now supports supervised CLI execution through an explicit launcher/model profile. Use that walkthrough to automate dispatch and observe process outcomes while retaining human decisions. Its local subprocess tests do not establish credentialed provider behavior.

What goes wrong

Treating every JSONL event as an answer loses terminal failures. Accepting JSON without checking evidence admits invented file references. Reusing a native session ID in another provider does not transfer its context. Keep the original packet and validate the final result before dispatch.

How to check

Run node --test test.mjs from the extracted package. The Codex fixture must normalize to a review object; a turn.failed event must prevent completion. Then try an invalid evidence quote and confirm that no downstream gate opens.

For a live trial, use the same synthetic packet and record the CLI version, requested model, observable actual model, exit status, and task checks. Record unknown model metadata as unknown. Compare the result against the recorded baseline before widening the task.