noninteractive.md +109 −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
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
125## Resume a non-interactive session164## Resume a non-interactive session
126 165
127If 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:
195 234
196 - name: Run Codex235 - name: Run Codex
197 run: |236 run: |
198237 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."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."
200 239
201 - name: Verify tests240 - name: Verify tests
213#### Alternative: Use the Codex GitHub Action252#### Alternative: Use the Codex GitHub Action
214 253
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.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```