Codex CLI — Full Tutorial

A complete walkthrough for Codex CLI: from a clean install to real project work, paired with Tokensmart for cost control.

If you just need the config reference, go to Codex CLI config. This page is the long-form tutorial.

What Codex CLI is

Codex CLI is OpenAI's official terminal-based coding assistant (open source, the @openai/codex npm package). Inside your terminal it can:

• Read your code and answer questions: codex "why does this function return undefined" — it opens the file, reads it, then answers
• Write code and create files: codex "write hello.js that prints the current time" — generates a diff, asks for confirmation, then writes
• Run terminal commands: codex "compress every png in this folder to half size" — proposes the command, runs after you approve
• Refactor or port code: codex "convert this file from Python 2 to Python 3 with type hints"

Compared to Cursor or Claude Code, Codex is the purest CLI agent — no IDE, no GUI, everything in the terminal. Great for Vim / Neovim users, servers, automation scripts.

Prerequisites

You need:

• Node.js 18+ (check with node -v)
• A Tokensmart account — sign up free if you don't have one
• A Tokensmart API key — create one dedicated to Codex on the API Keys page

💡 Why a dedicated key: Codex writes the key in plaintext to disk at ~/.codex/auth.json. A dedicated key + daily limit (e.g. $10/day) = bounded blast radius if the file gets rsynced or committed by accident, and a one-click revoke.

Step 1: Install

npm install -g @openai/codex
codex --version

A version number means you're good.

Step 2: Point Codex at Tokensmart

Create the dir and two files:

~/.codex/config.toml

model_provider = "OpenAI"
model = "gpt-5.4-mini"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.tokensmart.ai/v1"
wire_api = "responses"
requires_openai_auth = true

~/.codex/auth.json

{
  "OPENAI_API_KEY": "pk_live_xxxxxxxxxxxxxxxx"
}

On Windows swap ~ for %USERPROFILE%. If .codex doesn't exist: mkdir -p ~/.codex first.

Step 3: Hello World

Open an empty directory and run:

mkdir codex-hello && cd codex-hello
codex "write a Node.js program hello.js that prints the current time, no extra explanation"

Codex will:

1. Print what it plans to do ("I'll create hello.js...")
2. Show the file content as a diff
3. Ask "Apply this change? [y/N]"
4. Press y → file lands on disk

Then:

node hello.js

You should see a timestamp. Congrats — your first Codex task is done.

Step 4: Real project work

Say you have a Python project and want Codex to add logging to a function:

cd your-project
codex "in src/api.py, add info-level logging to login() that records email and IP"

Codex will:

1. Open src/api.py on its own
2. Locate login()
3. Produce a diff
4. Apply after your approval

Don't want to approve step by step? Switch mode (see below).

Three approval modes

Codex defaults to the safest setting (afraid to break your code), but you can loosen:

Example:

codex -a auto-edit "replace every console.log with logger.info across src/"

Picking a model

Codex uses whatever config.toml says by default, but you can override per-invocation:

codex -m gpt-5.4-mini "simple rename task"

Recommended:

Tokensmart-specific wins

• Transparent 24% pricing: GPT models on Tokensmart are billed at 24% of official list — daily Codex spend drops significantly vs direct-to-OpenAI.
• Daily-limit safety net: set daily_limit on the Codex key in API Keys. Even a runaway full-auto run stops when it hits the cap.
• Model allowlist lock: restrict the Codex key to cheaper models like gpt-5.4-mini / gpt-5.4 and leave the flagship gpt-5.5 off. Codex occasionally suggests "let me retry with a stronger model" — the allowlist stops that before you get a surprise bill.
• Automatic failover: Tokensmart has built-in redundancy. A 429 is automatically retried on backups transparently.
• Per-task accounting: filter API Logs by time range to see every turn of a Codex session — tokens and dollars — perfect for tightening your prompts.

Handy shortcuts

• Read-only — answer without editing anything: codex -q "explain what scripts/build.sh does" (-q = quiet)
• Pipe context from stdin: cat error.log | codex "what causes this error"
• Scope to a subdirectory: codex -C path/to/subdir "..."
• Exit the REPL: press Ctrl+C twice or type /exit

Common pitfalls

• "auth.json not found": ~/.codex does not exist. mkdir -p ~/.codex and retry.
• 401 Invalid API Key: JSON key name must be OPENAI_API_KEY (not api_key), value starts with pk_live_, no extra whitespace.
• "invalid wire_api": config.toml's wire_api must be "responses" — that's the only protocol Tokensmart exposes to Codex.
• Command seems stuck: default suggest mode is waiting for y. Add -a full-auto for automation.
• Committed auth.json by accident: treat the key as leaked immediately. Go to API Keys, revoke it, create a new one. Git history is forever — rotation is the only real fix.

Next steps

• Want to manage Codex + Claude Code provider configs in one place? See CC-Switch.
• Prefer the same workflow inside an IDE? See Cursor or Cline (VS Code).
• Every Codex call shows up in API Logs — full cost transparency down to the penny.