How to check Codex login status

Checking the Codex login status before opening a session, running codex exec, or handing a shell to automation prevents false starts caused by missing cached credentials or by a terminal that points at a different CODEX_HOME.

The codex login status subcommand reads the cached authentication state for the current CLI environment and prints the active sign-in mode. Codex local surfaces support ChatGPT sign-in and API-key sign-in, and the CLI and IDE extension reuse the same cached login details. A one-off CODEX_API_KEY for codex exec does not become a cached login.

Credential storage can use the operating system credential store or a file-based auth.json under CODEX_HOME, which defaults to /~/.codex. If CODEX_HOME is set, the directory must already exist, and it points Codex at a separate config and credential cache. The status command does not create or remove credentials, so it is a safe preflight before login, logout, CI setup, or troubleshooting access differences between terminals.

Related: How to log out of Codex

Steps to check Codex login status:

  1. Run the status check in the same terminal environment that will run Codex. 
    $ codex login status
Not logged in

    A profile with no cached credentials prints Not logged in. A cached ChatGPT login reports Logged in using ChatGPT, and a cached API-key login reports a masked API-key line.

  2. Print the exit code immediately when automation needs a shell gate. 
    $ echo $?
1

    The unauthenticated check exits with status 1. Authenticated profiles exit successfully, so scripts can stop before starting a Codex run that would need login.

  3. Check the active CODEX_HOME when the same machine shows different login states in different shells. 
    $ printenv CODEX_HOME
/home/ops/.codex-ci

    An unset CODEX_HOME uses /~/.codex. If CODEX_HOME is set, the directory must already exist and can point Codex at a separate config and credential cache.

  4. Keep one-off API keys separate from persisted login status.

    CODEX_API_KEY is supported for a single non-interactive codex exec run. It does not make codex login status report a cached login; use codex login --with-api-key when the environment needs a persistent API-key login.

  5. Start the matching login flow only if this environment needs credentials. 
    $ codex login

    Plain codex login starts the default ChatGPT browser flow.
    Related: How to log in to Codex with device authentication
    Related: How to log in to Codex with an API key

  6. Re-run the status check after signing in, logging out, or changing CODEX_HOME. 
    $ codex login status
Logged in using ChatGPT

    Run the check from the same shell, container, or automation account that will start the later Codex session.