noninteractive.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-13 00:57 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 

144<ToggleSection title="Use ChatGPT-managed auth in CI/CD (advanced)">

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

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

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

148 

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

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

151your Codex account.

152 

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

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

155 

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

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

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

159between runs.

160 

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

162 

163</ToggleSection>

164 

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

128 166 

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

197 235 

198 - name: Run Codex236 - name: Run Codex

199 run: |237 run: |

200 codex exec --full-auto --sandbox workspace-write \238 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."239 "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 240 

203 - name: Verify tests241 - name: Verify tests

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

216 254 

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.255If 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.

256 

257## Advanced stdin piping

258 

259When 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.

260 

261### Use prompt-plus-stdin

262 

263Prompt-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.

264 

265```bash

266npm test 2>&1 \

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

268 | tee test-summary.md

269```

270 

271<ToggleSection title="More prompt-plus-stdin examples">

272 

273### Summarize logs

274 

275```bash

276tail -n 200 app.log \

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

278 > log-triage.md

279```

280 

281### Inspect TLS or HTTP issues

282 

283```bash

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

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

286 > tls-debug.md

287```

288 

289### Prepare a Slack-ready update

290 

291```bash

292gh run view 123456 --log \

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

294 | pbcopy

295```

296 

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

298 

299```bash

300gh run view 123456 --log \

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

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

303```

304 

305</ToggleSection>

306 

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

308 

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

310 

311The `-` 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.

312 

313```bash

314cat prompt.txt | codex exec -

315```

316 

317```bash

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

319 | codex exec -

320```

321 

322```bash

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

324```