Skip to main content

Codex CLI Commands Explained

Calculating read time…

Codex CLI is OpenAI's official open-source terminal coding agent — a command-line tool, published as the npm package @openai/codex, that reads your codebase, proposes edits, and runs commands directly in your local shell. If you've only used AI coding inside a browser tab or an IDE plugin, Codex CLI moves that same intelligence into the one place every engineer already lives: the terminal. 🖥️

Why does this matter beyond convenience? Because the five commands most beginners hit first — install, verify, help, login, and model-switching — are also the exact points where enterprise rollouts succeed or stall. OpenAI has reported Codex usage growing more than 5x in a single year, with named customers like Notion, Ramp, and Virgin Atlantic building it into real engineering workflows, not side projects. Get the fundamentals wrong here — a bad install, a broken auth flow, a misunderstood model choice — and a team burns its first week fighting the tool instead of shipping with it. Get them right, and onboarding a whole engineering org takes an afternoon. ⚡

Codex CLI install to session flow diagram

🔀 Quick Comparison — Codex CLI's Four Interfaces

Interface Launch Command Interactive? Best For
Terminal TUI codex Yes — full slash-command control Day-to-day pair-programming in a repo
Non-interactive automation codex exec "task" No — runs to completion and exits CI/CD pipelines, scripts, batch jobs
Desktop App codex app Yes — GUI, macOS/Windows Developers who prefer a windowed app to a terminal
Codex Cloud codex cloud / codex cloud exec No — runs in a remote sandboxed environment Long-running or parallel tasks you don't want tying up your machine

1. What Is Codex CLI (and Why It's Different From ChatGPT)

Codex CLI is a Rust-based binary, distributed through the npm package @openai/codex, that runs a full interactive terminal UI (TUI). Instead of copy-pasting code between a chat window and your editor, you launch codex in a project folder and it reads your files, proposes multi-file changes, runs shell commands, and executes tests — all inside a sandboxed session that asks for approval before doing anything risky. A real production example: Notion's engineering team uses Codex to quickly build new product features directly from the terminal, while companies like GitHub and Nextdoor are wiring it into multi-agent systems that carry engineering tasks end-to-end.

Why this design matters in production: a chat-based assistant only ever sees what you paste in. A terminal agent sees your actual repository structure, your actual test output, and your actual error messages — which is why enterprises evaluating "AI pair programmers" increasingly compare Codex CLI against IDE-native tools like GitHub Copilot rather than against ChatGPT itself.

💡 Key distinction: Codex is available on four different surfaces — the terminal CLI, an IDE extension, a cloud-based agent inside ChatGPT ("Codex Web"), and a desktop app. This post focuses entirely on the terminal CLI, since that's where --version, --help, and login --device-auth actually live.

🎯 Use this when you want an AI agent that operates on your real file system and shell — not a chat window you manually relay code through.

2. Installing & Updating Codex CLI

Production example: official Codex CLI documentation and enterprise adoption guides consistently list npm install -g @openai/codex as the primary install path across macOS, Linux, and native Windows, alongside a Homebrew cask and standalone binary releases for teams that can't run npm globally.

npm install -g @openai/codex

Line by line, here's what actually happens when this runs:

  1. npm resolves the @openai/codex package from the public npm registry.
  2. The -g flag installs it globally, so the codex command becomes available from any directory, not just inside a specific project's node_modules.
  3. Under the hood, the npm wrapper downloads a platform-specific Rust binary and creates a thin shim at your global npm bin path (for example /usr/local/bin/codex or ~/.npm-global/bin/codex) that executes that binary.
  4. npm validates the package's declared Node.js engine requirement (Node 18 or later; some guides recommend Node 22+) and refuses to install if your Node version is too old.

✅ Worked example: On a fresh Ubuntu box, install Node 20 first (curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - then sudo apt-get install -y nodejs), then run npm install -g @openai/codex. A successful install leaves you able to run codex --version immediately from any folder.

💡 The single most common failure: running npm i -g codex (without the @openai/ scope). That unscoped package is an unrelated, decade-old project with no connection to OpenAI — it installs "successfully" and then does nothing useful, wasting far more debugging time than the typo itself should.

What breaks in production without this step done correctly: CI pipelines that pin the wrong package name silently succeed at "install" while every downstream codex invocation fails or runs the wrong tool entirely — a failure mode that's hard to notice until someone actually reads the agent's output.

🎯 Use this when setting up a new machine, a Docker image, or a CI runner for the first time, or when explicitly upgrading to a pinned version with npm install -g @openai/codex@<version>.

Checking and updating the version

Production example: Codex CLI ships a new release roughly every week, and enterprise-focused installation guides treat codex --version as the mandatory first sanity check immediately after any install or upgrade step — precisely because version drift across a team causes silent behavioral differences in agent output.

codex --version
codex update

codex --version queries the binary's embedded version string and prints it — nothing more. But that one line answers three questions at once: did the install actually put a working binary on your PATH, which shim is your shell resolving to if you have multiple installs, and does this machine match the version your team has standardized on. codex update is a newer convenience subcommand that upgrades the CLI to the latest release in a single step, without you re-running the full npm install command by hand.

✅ Worked example: after installing on a fresh Ubuntu box, codex --version printing a version string (rather than "command not found") confirms the classic PATH-resolution problems don't apply to you. A week later, run codex update to pick up the newest release without repeating the npm command from scratch.

💡 Warning: if you have multiple Node version managers (nvm, volta, system Node) or ran both Homebrew and npm installs, codex --version may resolve to a stale shim from an old install rather than your latest one. If the version looks wrong, check which codex (macOS/Linux) or where codex (Windows) before assuming the upgrade failed.

What breaks without this check: teams debug "the agent behaves differently than the docs describe" for hours before realizing half the team is on a version several releases behind.

🎯 Use this when right after any install, before filing a bug report (maintainers will ask for this output first), and periodically to stay current with codex update.

3. Discovering Commands — codex --help, codex <subcommand> --help, and codex doctor

Production example: Codex CLI's own cheat sheets and enterprise onboarding guides consistently recommend codex --help as the fastest way to discover subcommands like codex exec (non-interactive automation), codex login, and the various sandbox and approval flags — rather than memorizing documentation that changes weekly. A newer codex doctor subcommand exists specifically to produce support-ready diagnostics when something doesn't work.

codex --help
codex exec --help
codex login --help
codex doctor

What these return: codex --help lists top-level subcommands (login, logout, exec, resume, fork, apply, cloud, mcp, app, features, update, and more) plus global flags (--model/-m, --sandbox, --ask-for-approval, --cd). Running --help after any specific subcommand (for example codex exec --help) drills into that subcommand's own flags, since global flags don't always propagate down. All of this is generated directly from the CLI's own argument parser, so it never drifts out of sync with the actual binary you have installed. codex doctor instead runs environment checks — Node version, PATH resolution, sandbox availability — and prints a diagnostic report you can paste into a support request.

✅ Worked example: forgetting whether the flag to pick a model at launch is --model or -m? Run codex --help and both are listed side by side, confirming codex -m gpt-5.3-codex-spark "pair with me on this component" is valid shorthand. If codex won't launch afterward, codex doctor is the next step before asking for help.

💡 Contrast: codex --help documents CLI-launch flags, but it will not show you in-session slash commands like /model or /diff — those only appear inside a running session's own slash popup (covered fully in Section 8). Beginners often search --help output looking for /model and don't find it, because it belongs to a different interface layer entirely.

🎯 Use this when you're unsure which flag controls approval mode, sandboxing, or model selection before you've even started a session, or when something breaks and you need a diagnostic report.

4. Authentication Commands — codex login, codex logout, and Every Sign-In Method

Production example: enterprise Codex knowledge bases document four distinct sign-in paths — browser-based ChatGPT OAuth, device-code flow for headless environments, direct API-key authentication, and status/logout management — each with different capabilities and billing models, which is exactly the kind of decision a team should make deliberately rather than let each engineer improvise.

codex login
codex login --device-auth
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
codex logout

What each one does:

  1. codex login — the default flow. It opens a local browser, completes a ChatGPT sign-in, and relies on a localhost callback to hand the resulting access token back to the CLI. This is the recommended path whenever a browser is available, since your Codex usage is then billed through your existing ChatGPT plan rather than metered API calls.
  2. codex login --device-auth — for remote servers, Docker containers, or SSH sessions where the local browser can never reach a localhost callback. It prints a short one-time code and a device-login URL; you open that URL on any other device — your phone, your laptop, a colleague's machine — sign in there, and enter the code. The CLI on the original headless machine then polls and receives its access token without ever needing a local browser or an open port.
  3. printenv OPENAI_API_KEY | codex login --with-api-key — pipes an existing OpenAI API key into the CLI instead of using ChatGPT OAuth at all. This is the standard pattern for CI/CD pipelines, since it needs no interactive browser step of any kind, but billing runs through standard per-token API rates rather than a ChatGPT subscription.
  4. codex login status — checks whether the current machine has a valid, non-expired session and which method (OAuth, device-code, or API key) it's using. Run this before debugging anything else if Codex starts behaving as if it isn't authenticated.
  5. codex logout — removes all stored credentials from the local machine. Use it when decommissioning a shared machine, rotating a compromised API key, or switching a session between two different ChatGPT accounts.

✅ Worked example: inside a Docker container or a remote SSH session, running codex login --device-auth prints something like "Open this link in your browser… Enter this one-time code (expires in 15 minutes): ABCD-EFGHI." Approve it from your phone's browser, and the container-side session authenticates automatically — the same environment set up with the Ubuntu install and Node.js steps from Section 2, just without a display attached. Run codex login status immediately afterward to confirm it took effect.

💡 Key warning: device-code login is opt-in, not default. A personal ChatGPT account must first enable "Allow device code login" under Security Settings, and on a managed ChatGPT Team/Enterprise workspace, a workspace admin must enable it in Workspace Permissions — individual members can't override this themselves. If the toggle is off, the code is silently rejected server-side even though the CLI shows the prompt correctly. Treat the one-time code itself like a PIN: never paste it into tickets, chat, or screenshots, since device codes are a known phishing target.

What breaks without understanding all four methods: teams default every CI runner to the same ChatGPT OAuth flow a human uses interactively, hit constant timeout failures in headless pipelines, and never realize --with-api-key or --device-auth existed specifically to solve that exact problem.

🎯 Use this when choosing (deliberately, at the team level) how each class of machine — laptop, remote dev box, CI runner — should authenticate, rather than letting every engineer improvise their own method.

5. Launching a Session — codex, Prompts, Images, and --cd

Production example: Codex CLI's own reference documentation shows the base codex command accepting an optional starting prompt, an explicit working directory, and even image attachments — letting a developer skip the "open the tool, then explain what you want" two-step entirely.

codex
codex "Explain the architecture of this project"
codex --cd /path/to/project
codex -i mockup.png "Implement this UI"
codex app

What each variant does: plain codex opens the interactive TUI in your current directory with an empty composer. Passing a quoted string launches the TUI with that prompt already queued as the first turn, saving a step. --cd lets you point Codex at a project folder without first cd-ing there yourself — useful in scripts or shell aliases that launch Codex against a fixed repo path. -i attaches one or more image files (a screenshot, a design mockup) to the initial prompt, which the model can then reference visually. codex app launches the separate desktop application instead of the terminal TUI, for developers who'd rather work in a windowed GUI.

✅ Worked example: a designer hands you a UI mockup screenshot. Instead of describing it in words, run codex -i mockup.png "Implement this UI in our existing React components" — the same authenticated session from Section 4 now has direct visual context to work from.

💡 Warning: always confirm you're in (or have pointed --cd at) the correct project folder before starting a session. Codex reads and can edit whatever directory it's launched against, and launching it accidentally at your home directory or a parent monorepo gives it a much wider — and slower to review — surface than you intended.

🎯 Use this when starting any new task; use --cd specifically for scripts and aliases that always target the same repo, and -i whenever a visual reference beats a written description.

6. Automating Without the TUI — codex exec

Production example: Codex CLI cheat sheets built for CI/CD workflows treat codex exec as the standard automation entry point — running a task to completion and exiting, with structured JSON output, rather than the always-open interactive TUI used for day-to-day coding.

codex exec "fix the failing tests"
codex exec --json "list all API endpoints"
codex exec -o result.txt "summarize the architecture"
codex exec --full-auto "run tests and fix any failures"
codex exec resume --last "now add error handling"

What this does: unlike plain codex, which opens a persistent TUI and waits for follow-up turns, codex exec runs a single task non-interactively and exits when it's done — exactly the behavior a CI job or shell script needs. --json streams machine-readable JSONL events instead of formatted terminal text, so another script can parse the output. -o saves just the final response to a file. --full-auto is a shortcut that grants workspace-write sandboxing with on-request approvals, letting Codex edit files and run commands without pausing for confirmation on every step — appropriate for CI, risky for your primary laptop. codex exec resume --last continues the most recent exec session with a new instruction instead of starting from zero context.

✅ Worked example: a nightly CI job authenticated with --with-api-key from Section 4 runs codex exec --full-auto "run tests and fix any failures", then a follow-up step calls codex exec resume --last "now update the changelog for this diff" — reusing the same session context instead of re-explaining the codebase from scratch.

💡 Key limitation: codex exec uses a single model for the entire run — there's no /model slash command mid-run, since there's no interactive session to type into. Set the model up front with -m/--model or your config.toml default instead. OpenAI's own CLI reference is also explicit that --yolo is not "a faster form of workspace-write" — it disables both sandboxing and approvals entirely, and should be reserved for environments that are already isolated by other means.

What breaks without this distinction: teams try to script the interactive codex TUI directly with piped input, hit inconsistent behavior, and don't realize codex exec exists specifically as the automation-safe alternative.

🎯 Use this when the task should run unattended — CI pipelines, scheduled jobs, or any script that needs a clean exit code rather than an open terminal session.

7. Managing Sessions — resume, fork, apply, and cloud

Production example: Codex CLI's session-management commands mirror the same "don't repeat context" principle enterprises expect from any professional tooling — a developer shouldn't have to re-explain a 40-file refactor from scratch just because their terminal closed.

codex resume
codex resume --last
codex fork --last
codex apply TASK_ID
codex cloud
codex cloud apply TASK_ID

What each does: codex resume opens an interactive picker listing your past sessions so you can choose one to continue; codex resume --last skips the picker and jumps straight into the most recent one. codex fork --last branches a new thread off an existing session's context — useful for trying two different approaches without losing the original transcript. codex apply TASK_ID applies a diff produced by a specific local session, letting you review and land the changes deliberately rather than mid-conversation. codex cloud opens Codex's remote, sandboxed task runner for work you'd rather not tie up your own machine to run; codex cloud apply TASK_ID pulls a finished cloud task's diff down into your local working tree.

✅ Worked example: you close your laptop mid-refactor from Section 6's CI example. The next morning, codex resume --last picks up exactly where you left off, with full file and decision history intact — no need to re-paste the original task description.

💡 Contrast: resume continues the same thread; fork branches a new one while preserving the original untouched — reach for fork specifically when you want to try a second, different solution without losing your first attempt as a fallback.

🎯 Use this when a task spans multiple sittings, you want to explore two approaches in parallel, or you're reviewing and landing a cloud-run task's output deliberately.

8. The Full Slash-Command Toolkit — /model and Everything Else Inside a Session

Production example: OpenAI's own slash-command documentation lists /model among the core session-control commands — alongside /permissions, /status, and /fast — that let a developer steer an active Codex session without restarting it, which enterprise onboarding workshops now teach as a standard part of "safe delegation" practice.

/model

This isn't a shell command — it only works typed inside a running interactive Codex session (the TUI you get by just running codex). Here's what happens:

  1. Type / in the composer to open the slash-command popup.
  2. Select or type /model and press Enter.
  3. A picker appears listing available models — for example a flagship reasoning-heavy model versus a smaller, faster, cheaper "mini" variant — along with a reasoning-effort selector for models that support it.
  4. Codex confirms the switch in the session transcript, and every following turn in that same session now uses the new model, with reasoning effort reset to that model's default rather than carrying over the previous level.

✅ Worked example: start a session, use /model to switch to a lightweight "mini" model for a quick, low-stakes research question, then switch back with /model to a full-capability model once you're ready to implement the real change — combining this with /permissions (Read Only while exploring, Agent when you're ready to let it edit files) is the pattern enterprise workshops teach as the default safe workflow.

💡 Key limitation: /model only exists in the interactive TUI. Non-interactive automation via codex exec (used for CI pipelines and scripted tasks) locks in a single model for the entire run — if you need a specific model there, you set it with the --model/-m flag at launch, or in ~/.codex/config.toml, not with a slash command.

What breaks without understanding this: engineers write onboarding docs that say "just use /model to pick the right model for CI" — advice that silently fails, because codex exec never shows a slash popup at all.

🎯 Use this when a task turns out to need more (or less) reasoning power than the model you started with, without losing the context already built up in your session.

The rest of the slash-command toolkit

OpenAI's own slash-command reference documents dozens of these — far more than any beginner needs on day one, but a learner shouldn't have to leave this post to find the common ones. Type / in the composer at any time to open the live, searchable popup; the table below groups the ones worth knowing by what they're for.

Category Command What It Does
Model & speed/modelSwitch the active model and reasoning effort mid-session
/fastToggle a faster-response mode at higher credit cost (model-dependent)
Safety & permissions/permissionsPick an approval preset: Auto, Read Only, or Full Access
/approveApprove one retry of an action automatic review just denied
Reviewing changes/diffShow the Git diff of everything changed so far, tracked or not
/reviewAsk a dedicated Codex reviewer to inspect the working tree and return findings
/planSwitch into planning mode before large or multi-file changes
Context/mentionAdd a specific file to the conversation (e.g. /mention src/lib/api.ts)
/idePull in context from your IDE — open files, current selection
/initGenerate a starter AGENTS.md with project instructions
Session control/newStart a fresh conversation without leaving the CLI (unlike /clear, doesn't clear the terminal view)
/clearClear the terminal view and start a new conversation
/compactSummarize a long exchange to free up context while keeping key details
/sideOpen an ephemeral side conversation to ask a quick question without touching the main thread
/quit or /exitClose the interactive session (save or commit work first)
Utility & info/statusShow active model, approval mode, working directory, and token usage
/mcpList connected MCP tool servers and their available tools
/themePreview and save a preferred color theme for the TUI
/logoutSign out from inside an active session
Advanced & experimental/agentManage or switch between sub-agent threads working in parallel
/personalityAdjust Codex's response tone/style (e.g. friendly, pragmatic, none)
/goalSet a persistent objective Codex keeps working toward across turns (experimental)
/skillsList and invoke packaged workflows (skills); a skill can also be run directly with $skill-name
/appsInsert a connector/app mention into the composer for immediate use
/rawSend a message with no system framing added — the literal text only
/copyCopy Codex's last completed output to your clipboard

✅ Worked example: the canonical flow enterprise teams are taught is /plan (propose an approach) → review it yourself → switch to execute mode → /review (validate) → /diff (inspect the actual changes) — the same discipline as a human PR process, just compressed into one terminal session.

💡 Contrast worth remembering: /clear starts a brand-new conversation and wipes the terminal view; /new also starts a new conversation but leaves your terminal scrollback visible; /compact doesn't start anything new at all — it just compresses the existing conversation so you can keep going without hitting a context limit. Confusing these three is one of the most common in-session mix-ups for beginners.

/side vs. /fork — the distinction beginners miss most

Both branch off your current conversation, but for different jobs. /fork clones the entire session into a new, persistent thread with its own ID — the original transcript stays untouched, and both threads continue to exist afterward, which is why codex fork --last can also resume a saved fork later from outside the TUI. /side instead opens an ephemeral side conversation: it inherits the parent thread's context, lets you ask a quick tangential question (or even switch its own model with /model, without affecting the parent), and then simply disappears — nothing is saved once you close it, and only a limited command set (/copy, /diff, /mention, /status) is available inside it, by design, so a side question can never accidentally modify your workspace while the main task is still running.

💡 Key warning: because /side is ephemeral, its output is not saved anywhere — if you need to reference what it told you later, copy the answer with /copy before closing it. Also note /side, /plan, /archive, and /copy (which uses the last completed output) are all unavailable while the main session is actively mid-task; queue them with Tab instead of expecting them to run immediately.

🎯 Use this when you want fine-grained, keyboard-first control over an active session instead of quitting and relaunching Codex for every small adjustment — reach for /side specifically for a quick tangent, and /fork when you want a real, separately continuable alternative thread.

9. Configuration & Project Setup — config.toml, AGENTS.md, and MCP Servers

Production example: Codex CLI cheat sheets built for team-wide rollouts consistently point to the same two files as the backbone of a repeatable setup: a personal ~/.codex/config.toml for defaults, and a per-project AGENTS.md for house rules the agent should always follow.

~/.codex/config.toml
  model = "gpt-5.2-codex"
  [mcp_servers.my-db]
  command = "/usr/local/bin/my-mcp-server"

codex mcp add NAME -- COMMAND
codex mcp list
/init

What each piece does: config.toml stores your persistent defaults — default model, default sandbox mode, and named MCP server definitions — so you don't have to pass the same flags on every launch. AGENTS.md, generated with /init or written by hand, is a plain-text file Codex reads automatically at the start of a session in that repository — conventions, forbidden directories, testing requirements, and anything else you'd tell a new human contributor on day one. codex mcp add registers a Model Context Protocol server (a tool integration — a database, a ticketing system, an internal API) so Codex can call it as a tool during a session; codex mcp list confirms what's registered, and the in-session /mcp command (Section 8) shows what's actually active right now.

✅ Worked example: a backend team maintaining a large Rust monorepo keeps an AGENTS.md describing their strict linting rules and preferred error-handling style. A new engineer running codex in that repo for the first time — right after the install and auth steps from Sections 2 and 4 — gets output that already matches house style, with zero extra prompting.

💡 Key warning: a config.toml default model or sandbox setting is a personal-machine convenience, not a security control. For anything CI or compliance-relevant — which sandbox mode, which approval policy — set it explicitly on the command line or in a checked-in profile, since a developer's personal config file isn't guaranteed to match what a pipeline actually uses.

What breaks without this: without a shared AGENTS.md, every engineer re-explains the same project conventions to Codex in every session, and output style drifts across the team in ways a human reviewer then has to catch manually.

🎯 Use this when onboarding a new repository to Codex, standardizing defaults across a team, or wiring Codex into an internal tool via MCP.

10. Enterprise Rollout at Scale

Individual installs are easy. Standardizing Codex CLI across dozens or hundreds of engineers is a governance problem, not an installation problem. OpenAI itself frames this shift explicitly: companies including Virgin Atlantic, Ramp, and Notion are already using Codex across real engineering workflows — test coverage, code review acceleration, and feature delivery, respectively — and Codex usage overall has grown more than 5x year over year among enterprise customers.

  1. Pin a version. Standardize on npm install -g @openai/codex@<version> in onboarding scripts and CI base images rather than always installing "latest," so codex --version returns the same string across the whole org.
  2. Centralize authentication policy. Decide upfront whether engineers sign in with ChatGPT OAuth, device-code auth for remote boxes, or API keys for CI — and set the "Allow device code login" workspace permission deliberately rather than per-engineer.
  3. Template the config. Bake a shared ~/.codex/config.toml (default model, sandbox mode) and a project-level AGENTS.md (conventions, forbidden directories, review expectations) into repo templates so new projects inherit sane defaults automatically.
  4. Enforce approval modes in CI. Use the documented sandbox flags (--sandbox read-only | workspace-write | danger-full-access) to guarantee that automated, unattended codex exec runs in CI never get broader filesystem or network access than a human reviewer explicitly approved.
  5. Track adoption with real metrics. Move past "seats provisioned" to measurable indicators — PRs touched by agent-assisted commits, review turnaround time, and test-coverage delta — the same categories cited in OpenAI's own reporting on customers like Virgin Atlantic.

💡 Governance note: a technology-consulting adopter, Simplex, explicitly frames Codex rollout as "an operating model, not just a tool rollout" — meaning training, a designated primary agent standard, and a center-of-excellence function, not a one-time install email to the whole engineering org.

🎯 Use this when moving from "a few engineers are trying Codex" to "Codex is a standard part of how our engineering org ships code."

11. Common Mistakes (and Why They Happen)

  1. Installing the wrong package name. npm i -g codex instead of npm i -g @openai/codex installs an unrelated 2012 project. This happens because the scope prefix feels optional to newcomers used to unscoped packages — but for OpenAI's Codex, the scope is the package identity.
  2. Assuming --help covers slash commands. Beginners search codex --help output for /model or /permissions and come up empty, because those belong to the in-session TUI layer, not the CLI's launch-time argument parser. The two command surfaces are documented separately for exactly this reason.
  3. Trying device-code auth without enabling it first. codex login --device-auth shows a code and URL even when device-code login is disabled at the account or workspace level — the rejection happens silently on OpenAI's server, so the failure looks identical to a working flow until the code simply never authorizes.
  4. Not pinning versions across a team. Codex CLI ships new releases roughly weekly. Without a pinned version in onboarding scripts, "it works on my machine" becomes a weekly occurrence rather than a rare one, because two engineers a few releases apart can see genuinely different default behavior.
  5. Confusing API-key billing with ChatGPT-subscription billing. API-key authenticated sessions are billed per-token at standard API rates and can lag behind ChatGPT-subscription users on day-one access to new models — teams that default every CI runner to API keys without understanding this trade-off are sometimes surprised by both the cost and the feature gap.
  6. Treating --yolo or danger-full-access as just a faster default. These modes disable sandboxing and approvals entirely rather than just relaxing them, and OpenAI's own reference explicitly warns against using them outside an already-isolated environment. Reaching for them "to save a few clicks" on a normal laptop removes the exact safety net that lets Codex operate autonomously in the first place.
  7. Scripting the interactive TUI instead of using codex exec. Piping input into a plain codex session for automation produces inconsistent results, because the TUI expects a human typing into a composer — codex exec exists specifically as the scriptable, non-interactive alternative.

❓ FAQ

Is @openai/codex the correct npm package name?

Yes. The correct install command is exactly npm install -g @openai/codex. The unscoped codex package on npm is an unrelated, older project with no connection to OpenAI, and installing it silently produces a tool that does nothing useful for Codex workflows.

Why does codex --version matter if the install already succeeded?

Because a successful install doesn't guarantee your shell resolves to the version you think it does, especially with multiple Node version managers installed. codex --version is the fastest way to confirm exactly which build is active before you start debugging anything else.

When should I use codex login --device-auth instead of the default login?

Use it whenever the machine running Codex CLI can't open a local browser to catch an OAuth redirect — remote servers, SSH sessions, and Docker containers are the classic cases. You approve the login from a completely separate device instead.

Can I use /model inside a CI script?

No. /model is a slash command that only works inside the interactive terminal session (the TUI). Non-interactive automation via codex exec uses a single model for the whole run, set instead via the --model/-m flag or your config.toml defaults.

What does codex --help actually list?

It lists the CLI's top-level subcommands (like login and exec) and global launch flags (like --model, --sandbox, and --ask-for-approval) generated directly from the installed binary's own argument parser — so it always matches your exact installed version.

What's the difference between /side and /fork?

/fork clones your whole session into a new, persistent thread that continues to exist afterward and can be resumed later. /side opens a temporary, ephemeral side conversation for a quick tangential question — it inherits the parent's context but disappears entirely once closed, and only a limited command set (/copy, /diff, /mention, /status) works inside it.

🔗 References & Further Reading

All product names, trademarks, and registered trademarks (including OpenAI, Codex, ChatGPT, and npm) are property of their respective owners and are referenced here for identification and educational purposes only. All information above is synthesized and explained in original wording based on the linked public sources — no source text is reproduced verbatim.

📝 Summary

  • Codex CLI is OpenAI's terminal-native coding agent, distributed as the @openai/codex npm package, with four interfaces: the TUI, codex exec, the desktop app, and Codex Cloud.
  • npm install -g @openai/codex installs it (watch the unscoped-package typo) and codex update keeps it current.
  • codex --help, codex <subcommand> --help, and codex doctor are how you discover and debug the CLI's own surface without leaving the terminal.
  • Four login methods cover every environment: codex login (browser), --device-auth (headless), --with-api-key (CI), plus login status and logout for managing sessions.
  • Plain codex launches an interactive session; codex exec is the non-interactive, scriptable path for CI and automation.
  • resume, fork, apply, and cloud manage sessions across time, branches, and remote sandboxes.
  • Inside a session, slash commands like /model, /permissions, /diff, /review, /compact, and the ephemeral /side give keyboard-first control without restarting Codex.
  • config.toml, AGENTS.md, and MCP server registration are how a single install becomes a repeatable, team-wide setup.
  • Enterprise rollout succeeds on governance — pinned versions, centralized auth policy, shared config templates, and real usage metrics — not just individual installs.

That's the complete on-ramp — from a blank terminal to a fully authenticated, configured, team-ready Codex CLI setup, with every major command and slash command covered in one place. Happy shipping! 🚀

Labels:

Comments

Post a Comment