skip to content

What does Codex's `codex exec` command do, and what must you add before it may edit files in your repository?

level: juniorimportance: should knowfreq 12%

answer

  1. no TUI, no prompts
  2. stdout versus stderr
  3. default sandbox is read-only
  4. one flag widens the sandbox
  5. Git repository check

basics

~20 s

codex exec runs one Codex task without the interactive terminal UI, streaming progress to stderr and printing only the final message to stdout. It starts in a read-only sandbox, so it edits nothing until you pass --sandbox workspace-write.

solid answer

~40 s

`codex exec "<task>"` is Codex's non-interactive mode for scripts and CI. It runs the task to the end without stopping for approval, streams progress to stderr and prints only the final agent message to stdout, so you can pipe or redirect the answer. The prompt is an argument, or stdin when you pass `-`; piped stdin plus a prompt argument becomes extra context. By default it runs in a **read-only** sandbox: it can read files and run commands that only read, but it cannot write. Pass `--sandbox workspace-write` (short `-s workspace-write`) to let it edit inside the working directory. It also refuses to start outside a Git repository unless you add `--skip-git-repo-check`. Scripts that still pass `--full-auto` need the explicit sandbox flag: Codex 0.159.3 defines no such option.

code

bash · 11 lines
bash
# Read-only by default: it can explain, it cannot edit
codex exec "summarize the failing tests in this repository"

# Allow edits inside the working directory
codex exec --sandbox workspace-write "fix the lint errors in src/"

# Keep the final answer in a file as well as on stdout
codex exec -s workspace-write -o result.md "update CHANGELOG.md for the last release"

# Feed a generated prompt through stdin
./make_prompt.sh | codex exec -

go deeper

for a junior

Recall the shape of a run: prompt in, progress on stderr, final message on stdout, read-only until you pass --sandbox workspace-write, and a Git repository required.

for a middle

Explain why the defaults are read-only and never-ask, how stdin combines with a prompt argument, and what --json, -o and --output-schema each give a script.

for a senior

Show you would pin the sandbox flag explicitly in every script, avoid relying on --full-auto, and decide when --skip-git-repo-check is acceptable.

for a principal

Weigh a shared wrapper that fixes sandbox, output and resume conventions for every team against letting each pipeline call codex exec its own way.

## What `codex exec` is **`codex exec`** (short alias `codex e`) is the non-interactive entry point of Codex, OpenAI's open-source coding agent. The plain `codex` command opens a terminal UI where you chat, approve actions and watch the agent work. `codex exec` instead takes one task, runs it to completion and exits, which makes it the form you use in shell scripts, scheduled jobs and CI pipelines. The documentation lists its uses as running inside a pipeline, producing output that other tools consume, and running with **pre-set sandbox and approval settings** instead of a person answering prompts. The prompt arrives in one of three ways: - as a single argument: `codex exec "summarize the repository structure"`; - from stdin, when you omit the argument or pass `-` (`cat prompt.txt | codex exec -`); - as an argument **plus** piped stdin, in which case the argument is the instruction and the piped text is appended as context, for example `npm test 2>&1 | codex exec "summarize the failing tests"`. ## Where the output goes The split between the two output streams is deliberate, so a script can capture the answer without the progress noise. | Stream or option | What it carries | |---|---| | `stderr` | progress while the agent works | | `stdout` | only the final agent message | | `--json` | turns `stdout` into a JSON Lines stream of every event | | `-o` / `--output-last-message <file>` | also writes the final message to a file | | `--output-schema <file>` | asks for a final response that matches a JSON Schema | So `codex exec "generate release notes for the last 10 commits" | tee notes.md` captures just the notes. ## The default permissions Codex has two separate controls. The **sandbox mode** decides what model-generated commands can technically do; the **approval policy** decides when Codex stops to ask a person. In `codex exec` both defaults suit an unattended run that must not change anything by accident: 1. **Sandbox: read-only.** The documentation states that `codex exec` runs in a read-only sandbox by default. The agent can read files and run commands that only read, but writes are blocked. 2. **Approval: never.** The 0.159.3 source sets the headless default to `never`: Codex does not stop for a prompt, and anything the sandbox blocks fails and is reported back to the model instead of waiting for a human. That pairing is safe but limited: a run that is meant to fix something will explain the fix and change nothing. ## Letting it edit The `--sandbox` option (short `-s`) takes the three sandbox modes: - `read-only` — the default for `codex exec`; - `workspace-write` — commands may write inside the working directory and its temporary directories, while network access stays off unless configured; - `danger-full-access` — no sandbox at all; the documentation reserves it for an environment that is already isolated, such as a disposable CI runner or container. The right flag for an editing job is therefore `codex exec --sandbox workspace-write "<task>"`. The current documentation still describes `--full-auto` as a deprecated compatibility flag that prints a warning, but the **0.159.3 source defines no `--full-auto` option**, so a script pinned to that release should use the explicit sandbox flag. Note also that `-p` in Codex means `--profile`, which layers a `<name>.config.toml` file from the Codex home directory; it is not a prompt flag. ## Checks before the task starts - **Git repository required.** `codex exec` exits with an error ("Not inside a trusted directory and --skip-git-repo-check was not specified") when the working directory is not inside a Git repository. The documentation gives the reason as preventing destructive changes. `--skip-git-repo-check` overrides it; `--dangerously-bypass-approvals-and-sandbox` (alias `--yolo`) skips the check as well, because that flag assumes an externally sandboxed environment. - **No saved session, if you ask.** `--ephemeral` runs without persisting session files to disk. - **Clean configuration, if you ask.** `--ignore-user-config` skips `$CODEX_HOME/config.toml`, and `--ignore-rules` skips user and project execpolicy rule files. ## Continuing a run A second pipeline step can continue the same session: `codex exec resume --last "fix what you found"` picks the most recent session from the current working directory, and `codex exec resume <SESSION_ID>` targets one by id. Together with the stdout contract and the explicit sandbox flag, that is all a junior engineer needs to script Codex safely.

  • How do you hand `codex exec` a long prompt that another script generates?
    Omit the prompt argument or pass `-`, and pipe the text in: `./make_prompt.sh | codex exec -`. If you pass a prompt argument and also pipe stdin, Codex treats the argument as the instruction and appends the piped content as context, which suits `npm test 2>&1 | codex exec "summarize the failures"`.
  • How does a second pipeline step continue the session the first `codex exec` started?
    Run `codex exec resume --last "<next instruction>"` to continue the most recent session from the current working directory (add `--all` to search every session), or `codex exec resume <SESSION_ID>` for a specific one. A run started with `--ephemeral` persists no session files, so it leaves nothing to resume.

  • codex exec -p takes the prompt text, the way some other agents' print flag does
  • codex exec can edit files by default because it is meant to run unattended
  • --full-auto is the current way to let codex exec write files
  • codex exec prints its whole progress log on stdout, so piping it captures noise
  • codex exec runs in any directory; a Git repository is never required

Assumes Codex 0.159.3: codex exec defaults to never asking for approval, and the source defines no --full-auto flag even though current docs still mention it.