Getting started with Codex CLI

This guide is for readers who want to run Codex from a terminal, both by hand and from scripts. By the end you will have installed the CLI, signed in, run a one-off task with codex exec, and know which sandbox and approval settings to choose. The last section describes how we use it in TellWorld.

What Codex CLI is

Codex CLI is OpenAI's command-line client for Codex. You run codex in a project directory to start an interactive session. You can also run codex exec to hand it one task non-interactively, from a script or a CI job, without opening the interactive interface.^[2][5]

Before you start

There are three install routes. On macOS and Linux the README gives curl -fsSL https://chatgpt.com/codex/install.sh | sh. On Windows it gives powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". You can also use npm install -g @openai/codex or brew install --cask codex.^[2]

Sign-in decides what you pay. Codex supports two sign-in methods for OpenAI models: Sign in with ChatGPT for subscription access, and Sign in with an API key for usage-based access.^[4] The README recommends the ChatGPT account for Plus, Pro, Business, Edu or Enterprise plans.^[2] The ChatGPT desktop app, the CLI and the IDE extension accept both methods for local work, but Codex cloud requires signing in with ChatGPT.^[4]

Install and sign in

Install with one of the commands above, then run codex and choose Sign in with ChatGPT. That is the README's route.^[2] On the CLI the browser flow is also available directly from the shell:^[4]

codex login

To sign in with an API key instead, the docs pipe the key through stdin:^[4]

printenv OPENAI_API_KEY | codex login --with-api-key

To update later, the CLI docs list brew upgrade --cask codex for Homebrew and npm install -g @openai/codex for npm.^[3]

Interactive use and one-off tasks

Run codex in a project directory for an interactive session. Use /permissions inside the session to change the active permissions profile.^[9]

For a single task, codex exec takes the prompt as an argument. The non-interactive page's example is:^[5]

codex exec "summarize the repository structure and list the top 5 risky areas"

While codex exec runs, Codex streams progress to stderr and prints only the final agent message to stdout, so you can redirect or pipe the result.^[5] If you only need the final message in a file, -o <path> or --output-last-message <path> writes it there and still prints it to stdout.^[5] For scripts that parse output, --json makes stdout a JSON Lines stream. Its event types include thread.started, turn.started, turn.completed, turn.failed, item.* and error.^[5]

Two flags keep runs from leaving traces. --ephemeral does not save session rollout files to disk. --ignore-user-config skips $CODEX_HOME/config.toml.^[5] The CLI reference says codex exec can be shortened to codex e, and that a prompt is required when you pass images, --output-schema, --output-last-message or --ephemeral.^[6]

Sandbox and approvals

codex exec runs in a read-only sandbox by default.^[5] The sandbox page names three common modes: read-only, workspace-write and danger-full-access, the last of which runs without sandbox restrictions.^[7] The approvals docs say that for non-interactive runs you use codex exec --sandbox workspace-write.^[8] The page also says --full-auto is no longer supported.^[5]

Approval policies control when Codex stops to ask. The sandbox page names on-request and never, and says Codex no longer supports untrusted as a selectable policy.^[7] For safe read-only browsing the approvals page gives --sandbox read-only --ask-for-approval on-request. For read-only non-interactive CI it gives --sandbox read-only --ask-for-approval never, which can be shortened to -a never.^[8]

Be careful with the bypass flag. --dangerously-bypass-approvals-and-sandbox, also written --yolo, means no sandbox and no approvals.^[8]

Git is another guardrail. Codex requires commands to run inside a Git repository, which prevents some destructive changes. You can override the check with codex exec --skip-git-repo-check.^[5]

Configuration

User-level settings live in ~/.codex/config.toml. Project-scoped overrides go in .codex/config.toml, which Codex loads only when you trust the project.^[11] Values resolve in this order, highest first: CLI flags and --config overrides, then project .codex/config.toml files, then --profile files, then ~/.codex/config.toml, then cloud-managed defaults, then /etc/codex/config.toml on Unix, then built-in defaults.^[11] The basics page uses approval_policy = "on-request" and sandbox_mode = "workspace-write" as examples.^[11]

requirements.toml is an admin-enforced file that constrains security-sensitive settings, which users cannot override. Under sandbox_mode = "workspace-write", sandbox_workspace_write.writable_roots lists extra writable directories.^[12]

Codex also reads AGENTS.md before doing any work. It starts from the global Codex home, which defaults to ~/.codex unless CODEX_HOME is set, and reads AGENTS.override.md if it exists, otherwise AGENTS.md. At project scope it walks from the project root down to the working directory. The combined instructions stop growing at project_doc_max_bytes, which is 32 KiB by default.^[10]

Rules are a newer feature and the docs say they may change. Rule files end in .rules and live in a rules/ folder beside an active config layer, such as ~/.codex/rules/default.rules. prefix_rule() takes a decision of allow, prompt or forbidden, and codex execpolicy check tests how the rules apply to a command.^[13]

Images

Codex can take images as input. Attach one or more with -i or --image. For example:^[15]

codex -i screenshot.png "Explain this error and suggest the smallest fix"

Passing several files works too, as in codex --image before.png,after.png "Compare these states and list the regressions".^[15] Common formats such as PNG and JPEG are accepted.^[15]

Codex can also generate images. Built-in generation uses gpt-image-2 and counts toward your general Codex usage limits. For larger batches, you can set OPENAI_API_KEY and generate through the API, so API pricing applies instead.^[14] Image generation is not available on the Free plan.^[16]

How we use it at TellWorld

We call Codex non-interactively from Claude Code to draw cover images. Each call uses this form:^[1]

codex exec -C <dir> --skip-git-repo-check --sandbox workspace-write "<task>"

Each call runs in its own empty scratch directory. The task asks Codex to use its image generation tool to create one landscape 16:9 image, save it as cover.png, and do nothing else.^[1] To make several covers at once, we start one codex exec process per image in the background and wait for all of them. On November 13, 2026, we produced three covers this way.^[1]

The choices here are ours, not a general recommendation. The empty scratch directory keeps each run from touching the project. --skip-git-repo-check is needed because the scratch directory is not a Git repository. --sandbox workspace-write lets Codex write the file while keeping the rest of the system out of reach.^[1][5][7]

Limits and common problems

Interactive approvals depend on the approval policy you chose. A non-interactive run that needs approval may stop, so pick a sandbox and approval combination before you put codex exec in a script.^[8]

Commands fail outside a Git repository unless you pass --skip-git-repo-check.^[5]

Built-in image generation counts toward usage limits, and larger batches through the API are billed by API pricing.^[14]

Next steps

The official CLI page is the place to start for every command and flag.^[3] For the non-interactive mode, read the non-interactive page.^[5] For sandbox and approvals, read the sandbox and approvals pages.^[7][8] For config files, read the config basics and configuration reference.^[11][12] For instruction files, read the AGENTS.md page.^[10]