noninteractive.md +112 −3
11 11
12- 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).
13- 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.
14- Run with explicit, pre-set sandbox and approval settings.15- Run with explicit, pre-set sandbox and approval settings.
15 16
16## Basic usage17## Basic usage
33codex exec --ephemeral "triage this repository and suggest next steps"34codex exec --ephemeral "triage this repository and suggest next steps"
34```35```
35 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
36## Permissions and safety49## Permissions and safety
37 50
38By 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:
39 52
4053- Allow edits: `codex exec --full-auto "<task>"`- Allow edits: `codex exec --sandbox workspace-write "<task>"`
41- Allow broader access: `codex exec --sandbox danger-full-access "<task>"`54- Allow broader access: `codex exec --sandbox danger-full-access "<task>"`
42 55
43Use `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).
44 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
45If 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.
46 63
47## Make output machine-readable64## Make output machine-readable
63{"type":"turn.started"}80{"type":"turn.started"}
64{"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"}}
65{"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."}}
6683{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}
67```84```
68 85
69If 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).
111 128
112`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:
113 130
131### Use API key auth (recommended)
132
114- 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.
115- 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.
116 135
122 141
123`CODEX_API_KEY` is only supported in `codex exec`.142`CODEX_API_KEY` is only supported in `codex exec`.
124 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
125## Resume a non-interactive session165## Resume a non-interactive session
126 166
127If 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:
195 235
196 - name: Run Codex236 - name: Run Codex
197 run: |237 run: |
198238 codex exec --full-auto --sandbox workspace-write \ codex exec --sandbox workspace-write \
199 "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."
200 240
201 - name: Verify tests241 - name: Verify tests
213#### Alternative: Use the Codex GitHub Action253#### Alternative: Use the Codex GitHub Action
214 254
215If 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```