noninteractive.md +102 −0
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:
111 124
112`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:125`codex exec` reuses saved CLI authentication by default. In CI, it's common to provide credentials explicitly:
113 126
127### Use API key auth (recommended)
128
114- Set `CODEX_API_KEY` as a secret environment variable for the job.129- 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.130- Keep prompts and tool output in mind: they can include sensitive code or data.
116 131
122 137
123`CODEX_API_KEY` is only supported in `codex exec`.138`CODEX_API_KEY` is only supported in `codex exec`.
124 139
140Use ChatGPT-managed auth in CI/CD (advanced)
141
142Read this if you need to run CI/CD jobs with a Codex user account instead of an
143API key, such as enterprise teams using ChatGPT-managed Codex access on trusted
144runners or users who need ChatGPT/Codex rate limits instead of API key usage.
145
146API keys are the right default for automation because they are simpler to
147provision and rotate. Use this path only if you specifically need to run as
148your Codex account.
149
150Treat `~/.codex/auth.json` like a password: it contains access tokens. Don't
151commit it, paste it into tickets, or share it in chat.
152
153Do not use this workflow for public or open-source repositories. If `codex login`
154is not an option on the runner, seed `auth.json` through secure storage, run
155Codex on the runner so Codex refreshes it in place, and persist the updated file
156between runs.
157
158See [Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).
159
125## Resume a non-interactive session160## Resume a non-interactive session
126 161
127If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:162If you need to continue a previous run (for example, a two-stage pipeline), use the `resume` subcommand:
213#### Alternative: Use the Codex GitHub Action248#### Alternative: Use the Codex GitHub Action
214 249
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.250If 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.
251
252## Advanced stdin piping
253
254When 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.
255
256### Use prompt-plus-stdin
257
258Prompt-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.
259
260```bash
261npm test 2>&1 \
262 | codex exec "summarize the failing tests and propose the smallest likely fix" \
263 | tee test-summary.md
264```
265
266More prompt-plus-stdin examples
267
268### Summarize logs
269
270```bash
271tail -n 200 app.log \
272 | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \
273 > log-triage.md
274```
275
276### Inspect TLS or HTTP issues
277
278```bash
279curl -vv https://api.example.com/health 2>&1 \
280 | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \
281 > tls-debug.md
282```
283
284### Prepare a Slack-ready update
285
286```bash
287gh run view 123456 --log \
288 | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
289 | pbcopy
290```
291
292### Draft a pull request comment from CI logs
293
294```bash
295gh run view 123456 --log \
296 | codex exec "summarize the failure in 5 bullets for the pull request thread" \
297 | gh pr comment 789 --body-file -
298```
299
300### Use `codex exec -` when stdin is the prompt
301
302If you omit the prompt argument, Codex reads the prompt from stdin. Use `codex exec -` when you want to force that behavior explicitly.
303
304The `-` 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.
305
306```bash
307cat prompt.txt | codex exec -
308```
309
310```bash
311printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \
312 | codex exec -
313```
314
315```bash
316generate_prompt.sh | codex exec - --json > result.jsonl
317```