Codex CLI Getting Started: Install, Sign In, First Task

Install

Codex ships as a standalone binary, an npm package, and a Homebrew cask. The standalone installer is the path OpenAI documents first and the one that updates itself with the same command.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm install -g @openai/codex
brew install --cask codex

codex login status

Authenticate

There are two supported sign-in paths. They are not interchangeable: they change billing, which admin controls apply, and which features are available.

ChatGPT sign-in opens a browser window and returns credentials to the CLI. It is the default when no valid session exists. API-key auth is the right choice for CI and other programmatic runs; OpenAI explicitly advises against exposing Codex execution to untrusted or public environments.

Enterprise workspaces can also use a Codex access token for trusted automation:

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

Check what is active, and clear it when you are done:

codex login status
codex logout

Credentials are cached in ~/.codex/auth.json or the OS credential store. Control that with cli_auth_credentials_store = "file" | "keyring" | "auto" | "ephemeral" in config.toml. Treat auth.json like a password if you use file storage; it contains access tokens.

Choose a model and effort

Model selection changes cost, latency, and how much planning the agent does before it edits. As of October 2026 the documented recommendations are:

Switch inside a session with /model, or launch with a model explicitly:

codex --model gpt-6.1-sol
codex exec -m gpt-6-luna "summarize the open TODOs in src/"

Reasoning effort is separate from the model. model_reasoning_effort accepts levels the selected model supports — low, medium, high, xhigh, max, or ultra. Start at the model default and raise it when the task needs deeper planning; raising it on a mechanical edit mostly buys latency. Availability depends on your plan and sign-in method, so a model that works with a ChatGPT login may not be selectable under an API key.

Trust the repository

Codex loads project-scoped .codex/ layers — project config, hooks, and rules — only when the project is trusted. Global and system configuration still load for an untrusted project, but the project layer is skipped.

To keep a repository on the stricter path, pin it in your user-level config rather than the project's:

[projects."/absolute/path/to/repo"]
trust_level = "untrusted"

Commands then require approval unless an execution-policy rule allows them. Do not set approval_policy = "on-request" in that same layer if the goal is strict approval, because the explicit policy overrides the project-derived behavior.

Trust is a convenience boundary, not a security boundary against a hostile repo. A trusted project can add instructions and configuration that shape the agent's behavior; read .codex/ and AGENTS.md before you grant trust.

Your first task

Start from the repository root:

cd /path/to/repo
codex

Ask for something read-only first, so you can see how the agent explores before it edits:

Tell me about this project. List the entry points, the test command, and anything that looks risky. Do not change files.

Then give it one bounded change. The prompt should name the file, the behavior, and the check that proves success:

In src/api/handlers/create-user.ts, add validation that rejects an email without an @ sign with a 400 response. Add one test to src/api/handlers/create-user.test.ts and run that test file only.

Two habits keep the first session honest:

• Checkpoint with Git. Commit or stash before the run. Codex edits the working tree; a clean git diff is your review surface.
• Watch the permissions. /permissions shows the active sandbox and writable roots. If the agent asks to leave the workspace, decide before approving rather than after.

If the task needs a dependency install and the sandbox blocks network access, the run stops at that command. That is expected in workspace-write.

Resume and inspect

Interactive sessions can be reopened:

codex resume

Codex lists recent chats from the current repository and lets you search across local chats for older work. Non-interactive runs have their own resume path:

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

To inspect which instruction files a session loaded, ask directly inside the session:

List the instruction sources you loaded, in precedence order.

That is faster than inferring behavior from the diff. Prompt engineering covers the discovery order and the size cap.

Update and diagnose

Updates reuse the install command. When something is broken and the cause is not obvious, generate a diagnostic report before changing configuration:

codex doctor

The report checks installation, configuration, authentication, runtime, Git, terminal, app-server, and thread inventory health. It is the closest thing to a support bundle, and it is safer to share than a session transcript.

TODO: capture from real run — paste a codex doctor summary from a healthy install, trimmed to the section headers.

Comparing harnesses before you commit to one? The tool comparison covers Codex against Claude Code and OpenCode, including which surfaces each client supports.

Sources

• Codex CLI
• Authentication
• Config basics
• Custom instructions with AGENTS.md
• openai/codex README