Codex works in the browser, but the CLI fails: check authentication before changing your plan

A working ChatGPT tab is not evidence that a terminal process is using the same account, workspace, or billing path. When a Codex CLI task fails, my first question is not "Should I upgrade?" It is "What did this process actually use?"

This is a short diagnostic workflow, not a claim that every failure has an authentication cause. It does not make a model request, spend credits, or ask anyone to share a credential.

1. Identify the client you are checking

Run these locally, in the same terminal where the failing task runs:

codex --version
codex login status

The official CLI command reference documents login status as the active-authentication check. Its successful exit is not a successful model request, a remaining-credit measurement, or proof that a particular model is enabled. Check the installed version's help if its interface differs.

Record the authentication method, not a screenshot of an entire terminal session. If the output contains a key fragment or another identifier, redact it before sharing.

2. Keep subscription access and API access separate

OpenAI's authentication documentation distinguishes ChatGPT sign-in from API-key sign-in. API-key usage follows Platform billing rather than included ChatGPT-plan credits. Workspace controls also matter.

That gives two different questions:

• ChatGPT sign-in: is the expected account and workspace active, and does its usage view show the relevant entitlement?
• API-key sign-in: does the expected Platform project have access and available budget?

A successful browser session answers neither question for a separate terminal process. Do not purchase another plan merely because the terminal printed an error.

3. Check environment presence without printing secrets

For a shareable first pass, I use a presence-only check. Save this as auth_presence.py:

import os

GROUPS = {
    "platform_key_present": ("OPENAI_API_KEY",),
    "codex_access_token_present": ("CODEX_ACCESS_TOKEN",),
    "custom_codex_home_present": ("CODEX_HOME",),
}


def presence(env):
    return {
        label: any(bool(env.get(name, "").strip()) for name in names)
        for label, names in GROUPS.items()
    }


if __name__ == "__main__":
    for label, present in presence(os.environ).items():
        print(f"{label}={str(present).lower()}")

Run:

python3 auth_presence.py

Example from a synthetic environment containing only an API-key placeholder:

platform_key_present=true
codex_access_token_present=false
custom_codex_home_present=false

These flags describe process inputs, not the selected authentication method. They cannot validate a key, infer ownership, establish billing, or detect workload identity and every custom provider. A custom-home flag means only that a nonblank CODEX_HOME input exists, not that its contents are valid. Use the CLI status and your organization's configuration to interpret it.

Never replace the check with env, printenv OPENAI_API_KEY, or a dump of the authentication cache for a public support request. The official authentication guide treats that cache as a secret. Keep custom gateway values and private paths out of screenshots too.

4. Sort the failure by evidence

Write down four non-sensitive observations: client version, active authentication method, the operation that failed, and the redacted error category. Then investigate that category:

• A connection failure calls for a connection check.
• A permission or model-access error calls for an access check.
• A usage-limit message calls for the relevant usage or billing view.
• A login failure calls for the official login flow in that client.

These are triage branches, not interchangeable fixes. They deliberately do not promise that signing in again will repair a network failure or reset usage.

I tested the presence checker with eight synthetic cases, including empty values, individual credential inputs, custom-home inputs, and mixed inputs. No real account, API request, customer record, or payment was used. This checks the helper's redaction boundary; it is not an end-to-end Codex authentication test.

Further reading and disclosure

I maintain AIXiamo's Chinese tutorials. Our Plus/Pro/Codex guide repository: membership versus API provides the broader account-and-billing decision context. AIXiamo also operates a subscription service; this post contains no purchase instruction or affiliate link.

AI assisted drafting and test preparation. The commands were checked against the official documentation on October 12, 2026; the Python helper was tested locally with synthetic inputs. This article is not an official OpenAI support document.