Issue 00 · Autumn 2026日本語 · RSS
AgentKoji

Getting Started with Codex CLI

Codex CLI works with a ChatGPT Plus or higher plan, or with an API key. This guide covers install, sign-in, your first question, and your first small code change.

TL;DR

  • Using Codex CLI with a ChatGPT plan requires Plus or higher; you can also use an API key, billed at standard API rates.
  • Codex CLI runs on macOS, Linux and Windows; credentials are stored under ~/.codex and shared with the IDE extension.
  • Start with a question that doesn't touch code; inside a session, /status shows the current state and /model the model in use.

Codex CLI runs OpenAI’s Codex coding agent from your terminal. This guide goes from install to handing Codex its first small change. It is not a comparison. If you are still choosing a tool, read Choosing a Coding Agent first.

Before you start

To use the CLI with a ChatGPT plan, you need Plus or higher (Plus, Pro, Business, Edu, or Enterprise). On Free and Go, Codex is limited to the desktop app. You can also use the CLI with an API key instead of a ChatGPT plan. Check the official pricing page for per-plan features and usage limits. We do not list numbers here (source: https://learn.chatgpt.com/docs/pricing, checked 2026-10-18).

Codex CLI runs on macOS, Linux, and Windows. GitHub Releases ships binaries for macOS (Apple Silicon and x86_64) and Linux (x86_64 and arm64). Windows has an install script, and the official docs also cover WSL (source: https://github.com/openai/codex, checked 2026-10-18).

Install

These are the official install methods:

# macOS / Linux (official installer)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

On Windows, in PowerShell:

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

These are copied from the official docs. We did not run them locally (source: https://github.com/openai/codex, checked 2026-10-18).

In our test environment, we checked the version with npx instead of a global install. We ran it in a temporary directory:

npx -y @openai/codex@latest --version
codex-cli 0.163.0

--help lists the subcommands. Here is the start of the output:

Usage: codex [OPTIONS] [PROMPT]
       codex [OPTIONS] <COMMAND> [ARGS]

Commands:
  agents            Browse all agent sessions on the shared local app-server daemon
  exec              Run Codex non-interactively [aliases: e]
  review            Run a code review non-interactively
  login             Manage login
  logout            Remove stored authentication credentials

Sign in

There are two ways to sign in: with your ChatGPT account, or with an API key. A ChatGPT sign-in counts usage against your plan. An API key bills at standard API rates. Codex cloud requires a ChatGPT sign-in.

# Sign in through the browser
codex login

# Pass an API key on stdin
printenv OPENAI_API_KEY | codex login --with-api-key

# Check which auth method is active
codex login status

Credentials are stored under ~/.codex by default, and the CLI and the IDE extension share them. We did not sign in or call a model (source: https://learn.chatgpt.com/docs/auth, checked 2026-10-18).

Your first question

Run codex in your project directory. On first run, it asks you to pick a sign-in method. After you sign in, start with a question that does not touch the code. The official example:

cd your-project
codex
Tell me about this project

Inside a session, /status shows the current state and /model shows which model is in use (source: https://learn.chatgpt.com/docs/codex/cli, checked 2026-10-18).

Your first change

Before Codex edits files, decide how much it may do without asking. In the CLI, /permissions opens the permissions picker. The docs list four modes:

The docs recommend starting with Ask for approval for most work. Each mode combines a sandbox with an approval policy. There are three sandbox modes: read-only, workspace-write, and danger-full-access. macOS uses the built-in Seatbelt framework. Linux uses bubblewrap (sources: https://learn.chatgpt.com/docs/permission-modes and https://learn.chatgpt.com/docs/sandboxing, checked 2026-10-18).

Start with something small, like renaming a function or adding a test. The docs suggest making Git checkpoints before and after a task so you can roll back. Use /review to check the diff. It does not modify your working tree. We cover the permission side in more depth in Permission Design for AI Agents.

Where AGENTS.md goes

Codex reads instructions from AGENTS.md. It looks in two places:

Global files load first. Project files follow, from the root down, joined together. Files closer to your current directory come later, so they take precedence. In each directory, AGENTS.override.md is checked before AGENTS.md. The combined size limit defaults to 32 KiB (source: https://learn.chatgpt.com/docs/agent-configuration/agents-md, checked 2026-10-18).

Running on a VPS or always-on server

A headless server cannot do the browser sign-in. The docs recommend device code auth instead. It is in beta, and you need to enable it in your ChatGPT security settings first.

codex login --device-auth

Open the printed link in a browser on your own machine and enter the one-time code. If device code auth is not available, the docs list two fallbacks. You can copy ~/.codex/auth.json from a machine that has a browser. Or you can forward port 1455 over SSH and then run codex login. Treat auth.json like a password. For automation, the docs recommend API keys (source: https://learn.chatgpt.com/docs/auth, checked 2026-10-18).

ssh -L 1455:localhost:1455 user@remote

For the server setup itself, see Run an AI Agent 24/7 on a VPS.

Summary