Authentication, Plans & Usage

You've installed the CLI. The first time you run codex, it stops and asks one question that shapes everything downstream: how do you want to sign in? There are exactly two doors, and they bill in completely different ways.

• Sign in with ChatGPT — the default and recommended path. Codex opens your browser for an OAuth flow; the browser hands back an access token that Codex caches. Your usage then draws from your ChatGPT plan's included Codex allowance first, and from purchased credits once you exceed it. This is what most people want.
• Sign in with an API key — uses your OpenAI Platform account at standard, usage-based API token prices. There's no included allowance and no subscription buffer; every call is billed. The docs note that with an API key "some functionality might not be available." It's the right choice for CI/CD and shared automation, where you don't want a personal subscription in the loop.

The mental model: ChatGPT sign-in is a subscription with an allowance; an API key is a metered utility bill. One is tied to your plan, the other to your API org's pricing, retention, and data-sharing settings.

On first run, codex walks you through sign-in interactively. But you can also drive auth explicitly — essential for headless boxes and automation. Here is the toolkit:

Notice the stdin-based variants — they exist so a key never has to appear in your shell history or a process list. Pipe it in instead:

# API key from an environment variable, non-interactively
printenv OPENAI_API_KEY | codex login --with-api-key

# enterprise access token for trusted automation
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

There's no "switch account" command. To move between the two doors you log out and log back in with the method you want: codex logout, then codex login (ChatGPT) or codex login --with-api-key (API). When no valid session exists, Sign in with ChatGPT is the default.

Codex keeps all of its state under one home directory, and it's worth knowing exactly where — both to back it up and to keep it out of places it shouldn't be.

• Config directory: ~/.codex/ — the root for config, auth, logs, sessions, and skills.
• Config file: ~/.codex/config.toml (covered in depth in a later lesson).
• Credentials (file mode): ~/.codex/auth.json — a plaintext file containing access tokens. Treat it exactly like a password: never commit it, paste it into a ticket, or share it.
• Relocate everything by setting the CODEX_HOME environment variable. Point it elsewhere and config, auth, logs, and sessions all move with it.

Because auth.json is plaintext by default, Codex lets you choose a safer backend with the config key cli_auth_credentials_store:

# in ~/.codex/config.toml
cli_auth_credentials_store = "keyring"   # file | keyring | auto

A few auth-relevant environment variables round this out: CODEX_HOME (the state root), CODEX_API_KEY (provides a key for a single non-interactive run — and is honored only by codex exec), and CODEX_ACCESS_TOKEN (an access token for trusted automation). One subtlety worth flagging: whether a plain OPENAI_API_KEY auto-authenticates the interactive CLI — and how it would rank against a stored auth.json — is not confirmed in the env-var docs. Don't rely on it; sign in explicitly.

Codex is bundled into the ChatGPT subscription you already have. As of June 2026 it's included in Free, Go, Plus, Pro, Business, Edu, and Enterprise plans, plus the separate API-key path for shared/CI environments.

Three things newcomers get wrong:

1. Free does include Codex. Some older marketing copy omitted it, but the current pricing page lists Free explicitly — at $0/month it's limited (quick exploration), but it's real.
2. There is no separate "Team" plan. "Team" was the prior name for the business tier; the current business-tier name is Business. If a guide tells you to pick "Team," it's out of date.
3. Higher plans buy more usage, not different features. Plus and Pro who hit their limits can buy additional credits without upgrading; Business/Edu/Enterprise on flexible pricing can buy workspace credits.

The exact plan roster and what each tier includes is volatile — confirm the live list and inclusions at the pricing page before quoting it to anyone.

Here's the part that confuses people, so let's make it concrete. Under ChatGPT sign-in, your usage is governed by time windows, not a per-message counter.

• One rolling 5-hour window. Critically, local messages (CLI/IDE on your machine) and cloud tasks share the same five-hour window — there's no separate local-only allowance. Burn through it in the terminal and your cloud tasks feel it too. The official wording: "The usage limits for local messages and cloud tasks share a five-hour window. Additional weekly limits may apply."
• Weekly limits sit on top. The pricing page only says "additional weekly limits may apply" and publishes no weekly numbers. In practice, users report the weekly cap is the real bottleneck — the thing you hit before the 5-hour window after several heavy sessions.
• Credits when you hit the cap. Since April 2, 2026, Codex bills on token-based pricing — credits per 1M input / cached-input / output tokens — rather than per-message. Codex, ChatGPT for Excel, and Workspace Agents all draw from one shared agentic usage limit pool. The credit-to-dollar anchor is stable enough to state: 1 credit = $0.04 (so 2,500 credits = $100).
• What happens at the cap. Plus/Pro get an add-credits prompt and continue without upgrading (or enable Auto top-up at Codex Settings → Usage); Free/Go are prompted to upgrade to Plus. Purchased credits are valid 12 months and don't roll over.

Notice what's stable here versus what rots. The structure — shared 5-hour window, weekly caps on top, credits at the cap, $0.04/credit, 12-month expiry — is durable. The exact numbers — per-plan 5-hour limits, the weekly caps, the per-model credit rate card — are volatile and will be wrong next month. Teach yourself the structure; look up the numbers live.

Because the numbers move, the skill that actually matters is knowing where to look for your current state:

• /status in the CLI — type it mid-session for a quick read of your active model and remaining usage. It's intentionally minimal; a 2026 snapshot looks like gpt-5.4 high · 100% left · ~. A richer progress-bar view (separate 5-hour and weekly bars with reset times) has been proposed but isn't the default — treat fancy examples from blog posts as aspirational.
• The web usage page — the authoritative live view of your 5-hour and weekly limits, plus credits and Auto top-up, lives at https://chatgpt.com/codex/settings/usage (Codex Settings → Usage). Buy credits at Codex Settings → Usage → Credits.
• Enterprise/admin analytics — workspace admins can query the Analytics API at https://api.chatgpt.com/v1/analytics/codex (endpoints like /usage, /code_reviews) with a Platform API key.

For the canonical, current numbers — the per-plan 5-hour limits, the credit rate card (credits per 1M tokens by model), and the API USD token prices — the live sources are https://developers.openai.com/codex/pricing, the help-center rate card, and https://developers.openai.com/api/docs/pricing. Bookmark those three; they're the ground truth.