Skip to content

Codex CLI: the whole development loop in one terminal

The four install paths, first run and sign-in, the commands worth learning early (resume, --image, --search, cloud, mcp, /permissions), and when the CLI is the right surface rather than the desktop app.

CurrentLast verified

Platforms

  • macOS
  • Linux
  • Windows

What the official documentation says

  • Codex CLI is for inspecting code, making changes, running commands and automating repeatable work without leaving your terminal.

    Codex CLI

  • The macOS/Linux standalone installer is: curl -fsSL https://chatgpt.com/codex/install.sh | sh, and the same command updates it.

    Codex CLI

  • The Windows standalone installer is: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex", and the same command updates it.

    Codex CLI

  • It can also be installed with npm install -g @openai/codex or brew install --cask codex.

    Codex CLI

  • You open a project directory and run codex; the first time, choose Sign in with ChatGPT or another available sign-in method.

    Codex CLI

  • The documented advice is to create Git checkpoints before and after a task so you can revert changes.

    Codex CLI

  • codex resume reopens a recent chat from the current repository, or searches across local chats when you need older work.

    Codex CLI

  • codex --image passes an error screenshot, architecture diagram or design reference with the first prompt, and images can also be pasted into the interactive composer.

    Codex CLI

  • codex --search switches a run to live web search when a task depends on current releases, documentation or external behaviour, and search activity stays visible in the transcript.

    Codex CLI

  • codex cloud browses active and completed chats, submits work to a configured environment, and applies the result to your local repository from the terminal.

    Codex CLI

  • codex mcp adds local or remote MCP servers, authenticates when needed, and inspects the tools available to the current session before Codex uses them.

    Codex CLI

  • /permissions chooses when Codex can edit files or run commands without asking, and inspects the active sandbox and writable roots before you continue.

    Codex CLI

  • The local code review runs against uncommitted changes, a commit, or a base branch, and reports prioritized findings without modifying your working tree.

    Codex CLI

  • The OpenAI developer documentation index lists Codex developer tools as its own documentation set, covering the Codex CLI, IDE, cloud, config.toml, authentication, customization, automation and security.

    OpenAI developer documentation index (llms.txt)

What it is

The documented positioning: inspect code, make changes, run commands, and automate repeatable work without leaving your terminal.

The three stated reasons are direct:

  • Work against your local repository — let Codex inspect files, make edits, and run the tools already installed on your machine.
  • Stay in control — choose the model, reasoning effort, permissions and commands that fit the task.
  • Compose with scripts and CI — use Codex interactively, or call codex exec from repeatable workflows and pipelines.

The third is the CLI's real advantage over every other surface: it can be called from a script.

Installing: four paths

macOS / Linux standalone

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

The same command updates it.

Windows standalone

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

Also the same command to update.

npm

npm install -g @openai/codex

Homebrew

brew install --cask codex

Updated with brew upgrade --cask codex.

First run

Open a project directory and run codex. The first time, choose Sign in with ChatGPT or another available sign-in method.

Then describe what you want. The example first prompt in the documentation is deliberately modest:

Tell me about this project

That is a good habit in itself — landing in an unfamiliar repository and asking for an explanation surfaces your own misconceptions faster than jumping straight to a change request.

One more piece of quickstart advice worth adopting on day one: create Git checkpoints before and after a task so you can revert changes.

The commands worth learning early

The command surface is large; these are the ones that show up in most real workflows.

codex resume — return to a saved chat. Reopen a recent chat from the current repository, or search across local chats when you need to return to older work.

codex --image — bring visual context into the prompt. Pass an error screenshot, architecture diagram or design reference with the first prompt, or paste an image into the interactive composer.

codex --search — when the answer depends on now. Switch a run to live web search when a task depends on current releases, documentation or external behaviour. Search activity stays visible in the transcript — which matters, because you can see what it actually looked at.

codex cloud — move work to the cloud. Browse active and completed chats, submit work to a configured environment, and apply the result to your local repository from the terminal.

codex mcp — connect external tools. Add local or remote MCP servers, authenticate when needed, and inspect the tools available to the current session before Codex uses them. That last clause is the good habit: look at what is on the table before letting it act.

/permissions — set the boundaries for each run. Choose when Codex can edit files or run commands without asking, and inspect the active sandbox and writable roots before you continue.

subagents — split up a larger investigation. Ask Codex to delegate focused work to specialized agents, then bring their findings back into the main terminal session.

codex completion — fit Codex to your terminal. Generate completions for your shell, choose a syntax theme, and open longer prompts in the editor configured by VISUAL or EDITOR.

Three terminal workflows

The documentation groups CLI usage into three shapes worth comparing against your own habits.

Keep the coding loop in your terminal. Start Codex in a repository to explore unfamiliar code, plan a change, edit files and run your local development tools. Steer the active turn, inspect commands and diffs as they appear, and keep follow-up work in the same session.

Use skills and plugins. Package repeatable instructions as skills, then add plugins to connect Codex to your team's tools and data without leaving the CLI.

Review changes before they ship. Run a dedicated review against uncommitted changes, a commit, or a base branch. Codex reports prioritized findings without modifying your working tree, so you can address risks before you commit or open a pull request.

That last guarantee is worth underlining: the review is read-only. Running one never leaves you with unexplained changes to sort out.

When to reach for the CLI

The four documented cases:

  • You work from the terminal — explore, edit and run a repository in one focused loop.
  • You need scripting or CI — run a non-interactive command (codex exec) in a repeatable workflow.
  • You want a local code review — inspect changes before you commit or open a pull request.
  • You want to hand work to the cloud — launch a cloud chat and return to the terminal later.

Conversely, if you need the built-in browser, annotations or file previews, those live in the desktop app; the CLI does not have them.

How to do it

  1. Pick an install path — the macOS/Linux standalone script, the Windows standalone script, npm, or Homebrew.
  2. Open a project directory and run codex.
  3. The first time, choose Sign in with ChatGPT or another available sign-in method.
  4. Describe what you want — ask it to explain the project, make a focused change, or help debug an issue.
  5. Create Git checkpoints before and after a task so you can revert.
  6. Use /permissions to set the boundaries for the run and inspect the active sandbox and writable roots.

On Windows

  1. Windows standalone install: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
  2. The same command updates it.
  3. npm install -g @openai/codex also works.
  4. If you also run the Windows ChatGPT desktop app, note the Codex home directory and config sharing behaviour covered in the Windows tutorial.

On mobile

N/ACodex CLI is a terminal tool and the official CLI page does not describe mobile. Driving Codex on a computer from a phone is Remote's territory — see the Codex Remote tutorial.

Use cases

  • Landing in an unfamiliar repository and asking Codex to explain the project first.
  • Running a local review against uncommitted changes before committing or opening a pull request.
  • Running a repeatable flow non-interactively from a script or CI.
  • Handing a larger piece of work to the cloud and collecting the result from the terminal later.

Common mistakes

  • Letting Codex change files without a Git checkpoint. The quickstart names checkpoints before and after a task as explicit advice.
  • Starting a file-modifying task without checking the boundaries. /permissions inspects the active sandbox and writable roots before you continue.
  • Not using --search for tasks that depend on current releases or external behaviour, then acting on a stale answer.
  • Looking for a graphical plugin browser in the CLI. It has one via /plugins, but it is a TUI, not a GUI.

FAQ

What are the install options?
Four are documented. macOS/Linux standalone: curl -fsSL https://chatgpt.com/codex/install.sh | sh. Windows standalone: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". npm: npm install -g @openai/codex. Homebrew: brew install --cask codex, updated with brew upgrade --cask codex. For the first three, the update command is the same as the install command.
How do I get back to an earlier chat?
Use codex resume. It reopens a recent chat from the current repository, or searches across local chats when you need to return to older work.
Can I show it a screenshot?
Yes. codex --image passes an error screenshot, architecture diagram or design reference with the first prompt, and you can also paste an image into the interactive composer.
When is the CLI the right surface?
Four documented cases: you work from the terminal and want to explore, edit and run a repository in one focused loop; you need scripting or CI and want a non-interactive command in a repeatable workflow; you want a local code review before committing or opening a pull request; or you want to hand work to the cloud and return to the terminal later.
Does the local review modify my code?
No. The documentation states it runs against uncommitted changes, a commit or a base branch and reports prioritized findings **without modifying your working tree**, so you can address risks before you commit or open a pull request.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status