noninteractive.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-02 00:48 UTC

1# Non-interactive mode1# Non-interactive mode

2 2 

3Use `codex exec` to run Codex in scripts and CI

4 

5Non-interactive mode lets you run Codex from scripts (for example, continuous integration (CI) jobs) without opening the interactive TUI.3Non-interactive mode lets you run Codex from scripts (for example, continuous integration (CI) jobs) without opening the interactive TUI.

6You invoke it with `codex exec`.4You invoke it with `codex exec`.

7 5 

13 11 

14- Run as part of a pipeline (CI, pre-merge checks, scheduled jobs).12- Run as part of a pipeline (CI, pre-merge checks, scheduled jobs).

15- Produce output you can pipe into other tools (for example, to generate release notes or summaries).13- Produce output you can pipe into other tools (for example, to generate release notes or summaries).

14- Fit naturally into CLI workflows that chain command output into Codex and pass Codex output to other tools.

16- Run with explicit, pre-set sandbox and approval settings.15- Run with explicit, pre-set sandbox and approval settings.

17 16 

18## Basic usage17## Basic usage

35codex exec --ephemeral "triage this repository and suggest next steps"34codex exec --ephemeral "triage this repository and suggest next steps"

36```35```

37 36 

37If stdin is piped and you also provide a prompt argument, Codex treats the prompt as the instruction and the piped content as additional context.

38 

39This makes it easy to generate input with one command and hand it directly to Codex:

40 

41```bash

42curl -s https://jsonplaceholder.typicode.com/comments \

43 | codex exec "format the top 20 items into a markdown table" \

44 > table.md

45```

46 

47For more advanced stdin piping patterns, see [Advanced stdin piping](#advanced-stdin-piping).

48 

38## Permissions and safety49## Permissions and safety

39 50 

40By default, `codex exec` runs in a read-only sandbox. In automation, set the least permissions needed for the workflow:51By default, `codex exec` runs in a read-only sandbox. In automation, set the least permissions needed for the workflow:

41 52 

42- Allow edits: `codex exec --full-auto "<task>"`53- Allow edits: `codex exec --sandbox workspace-write "<task>"`

43- Allow broader access: `codex exec --sandbox danger-full-access "<task>"`54- Allow broader access: `codex exec --sandbox danger-full-access "<task>"`

44 55 

45Use `danger-full-access` only in a controlled environment (for example, an isolated CI runner or container).56Use `danger-full-access` only in a controlled environment (for example, an isolated CI runner or container).

46 57 

58Codex keeps `codex exec --full-auto` as a deprecated compatibility flag and prints a warning. Prefer the explicit `--sandbox workspace-write` flag in new scripts.

59 

60Use `--ignore-user-config` when you need a run that doesn't load `$CODEX_HOME/config.toml`, and `--ignore-rules` when you need to skip user and project execpolicy `.rules` files for a controlled automation environment.

61 

47If you configure an enabled MCP server with `required = true` and it fails to initialize, `codex exec` exits with an error instead of continuing without that server.62If you configure an enabled MCP server with `required = true` and it fails to initialize, `codex exec` exits with an error instead of continuing without that server.

48 63 

49## Make output machine-readable64## Make output machine-readable

65{"type":"turn.started"}80{"type":"turn.started"}

66{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}81{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}

67{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}82{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}

68{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}83{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

69```84```

70 85 

71If you only need the final message, write it to a file with `-o <path>`/`--output-last-message <path>`. This writes the final message to the file and still prints it to `stdout` (see [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) for details).86If you only need the final message, write it to a file with `-o <path>`/`--output-last-message <path>`. This writes the final message to the file and still prints it to `stdout` (see [`codex exec`](https://developers.openai.com/codex/cli/reference#codex-exec) for details).

113 128 

114`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:129`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:

115 130 

131### Use API key auth (recommended)

132 

116- Set `CODEX_API_KEY` as a secret environment variable for the job.133- Set `CODEX_API_KEY` as a secret environment variable for the job.

117- Keep prompts and tool output in mind: they can include sensitive code or data.134- Keep prompts and tool output in mind: they can include sensitive code or data.

118 135 

124 141 

125`CODEX_API_KEY` is only supported in `codex exec`.142`CODEX_API_KEY` is only supported in `codex exec`.

126 143 

144Use ChatGPT-managed auth in CI/CD (advanced)

145 

146Read this if you need to run CI/CD jobs with a Codex user account instead of an

147API key, such as enterprise teams using ChatGPT-managed Codex access on trusted

148runners or users who need ChatGPT/Codex rate limits instead of API key usage.

149 

150API keys are the right default for automation because they are simpler to

151provision and rotate. Use this path only if you specifically need to run as

152your Codex account.

153 

154Treat `~/.codex/auth.json` like a password: it contains access tokens. Don't

155commit it, paste it into tickets, or share it in chat.

156 

157Do not use this workflow for public or open-source repositories. If `codex login`

158is not an option on the runner, seed `auth.json` through secure storage, run

159Codex on the runner so Codex refreshes it in place, and persist the updated file

160between runs.

161 

162See [Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).

163 

127## Resume a non-interactive session164## Resume a non-interactive session

128 165 

129If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:166If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:

197 234 

198 - name: Run Codex235 - name: Run Codex

199 run: |236 run: |

200 codex exec --full-auto --sandbox workspace-write \237 codex exec --sandbox workspace-write \

201 "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated files."238 "Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated files."

202 239 

203 - name: Verify tests240 - name: Verify tests

215#### Alternative: Use the Codex GitHub Action252#### Alternative: Use the Codex GitHub Action

216 253 

217If you want to avoid installing the CLI yourself, you can run `codex exec` through the [Codex GitHub Action](https://developers.openai.com/codex/github-action) and pass the prompt as an input.254If you want to avoid installing the CLI yourself, you can run `codex exec` through the [Codex GitHub Action](https://developers.openai.com/codex/github-action) and pass the prompt as an input.

255 

256## Advanced stdin piping

257 

258When another command produces input for Codex, choose the stdin pattern based on where the instruction should come from. Use prompt-plus-stdin when you already know the instruction and want to pass piped output as context. Use `codex exec -` when stdin should become the full prompt.

259 

260### Use prompt-plus-stdin

261 

262Prompt-plus-stdin is useful when another command already produces the data you want Codex to inspect. In this mode, you write the instruction yourself and pipe in the output as context, which makes it a natural fit for CLI workflows built around command output, logs, and generated data.

263 

264```bash

265npm test 2>&1 \

266 | codex exec "summarize the failing tests and propose the smallest likely fix" \

267 | tee test-summary.md

268```

269 

270More prompt-plus-stdin examples

271 

272### Summarize logs

273 

274```bash

275tail -n 200 app.log \

276 | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \

277 > log-triage.md

278```

279 

280### Inspect TLS or HTTP issues

281 

282```bash

283curl -vv https://api.example.com/health 2>&1 \

284 | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \

285 > tls-debug.md

286```

287 

288### Prepare a Slack-ready update

289 

290```bash

291gh run view 123456 --log \

292 | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \

293 | pbcopy

294```

295 

296### Draft a pull request comment from CI logs

297 

298```bash

299gh run view 123456 --log \

300 | codex exec "summarize the failure in 5 bullets for the pull request thread" \

301 | gh pr comment 789 --body-file -

302```

303 

304### Use `codex exec -` when stdin is the prompt

305 

306If you omit the prompt argument, Codex reads the prompt from stdin. Use `codex exec -` when you want to force that behavior explicitly.

307 

308The `-` sentinel is useful when another command or script is generating the entire prompt dynamically. This is a good fit when you store prompts in files, assemble prompts with shell scripts, or combine live command output with instructions before handing the whole prompt to Codex.

309 

310```bash

311cat prompt.txt | codex exec -

312```

313 

314```bash

315printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \

316 | codex exec -

317```

318 

319```bash

320generate_prompt.sh | codex exec - --json > result.jsonl

321```