Skip to main content

​
Syntax

codex login [OPTIONS]
codex login status

​
Description

The login command authenticates Codex with OpenAI. You can sign in with your ChatGPT account (recommended) or provide an API key.
We recommend signing in with ChatGPT to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about ChatGPT plans.

​
Usage

codex login
This opens your browser to sign in with your ChatGPT account.

​
Sign In with Device Code

If you can’t open a browser, use device code authentication: 
codex login --device-auth
You’ll receive a code to enter at a URL.

​
Sign In with API Key

API keys require additional setup and are billed separately from ChatGPT plans.
Provide an API key from stdin: 
printenv OPENAI_API_KEY | codex login --with-api-key
echo "sk-..." | codex login --with-api-key

​
Check Login Status

View your current authentication status: 
codex login status

​
Options

​
--device-auth
boolean
Use device code authentication instead of browser-based login. Shows a code to enter at a URL.
​
--with-api-key
boolean
Read an API key from stdin instead of using ChatGPT authentication.

​
Advanced OAuth Options

​
--experimental_issuer
string
Custom OAuth issuer base URL. Advanced use only.
This is an experimental flag for custom deployments.
​
--experimental_client-id
string
Custom OAuth client ID. Advanced use only.
This is an experimental flag for custom deployments.

​
Examples

​
Standard Login Flow

# Sign in with ChatGPT (opens browser)
codex login

# Check your authentication status
codex login status

​
Device Code Flow

# Start device code authentication
codex login --device-auth

# Output:
# Visit https://chatgpt.com/activate
# Enter code: ABCD-1234
# Waiting for authentication...

​
API Key from Environment

# From environment variable
printenv OPENAI_API_KEY | codex login --with-api-key

# From file
cat api-key.txt | codex login --with-api-key

# Inline (avoid for security)
echo "sk-proj-..." | codex login --with-api-key

​
Verify Authentication

# Check login status
codex login status

# Sample output:
# Authenticated: Yes
# Method: ChatGPT OAuth
# Account: [email protected]

​
CI/CD Authentication

For automation, use API keys: 
# GitHub Actions
- name: Login to Codex
  run: |
    echo "${{ secrets.OPENAI_API_KEY }}" | codex login --with-api-key

# GitLab CI
script:
  - echo "$OPENAI_API_KEY" | codex login --with-api-key
  - codex exec "run tests"

​
Authentication Methods

Pros:
  • Uses your existing ChatGPT subscription
  • No additional billing
  • Includes plan features (Plus, Pro, Team, etc.)
How it works:
  1. Run codex login
  2. Browser opens to ChatGPT
  3. Sign in and authorize
  4. Credentials stored securely

​
Device Code

When to use:
  • Remote servers without browser access
  • Terminal-only environments
  • Restricted network access
How it works:
  1. Run codex login --device-auth
  2. Get a device code
  3. Visit URL in any browser
  4. Enter code
  5. Credentials stored

​
API Key

When to use:
  • CI/CD pipelines
  • Automation scripts
  • Separate billing requirements
How it works:
  1. Get API key from OpenAI Platform
  2. Pipe to codex login --with-api-key
  3. Key stored securely
API keys are billed separately on the OpenAI Platform. ChatGPT subscriptions don’t include API credits.

​
Credential Storage

Codex stores credentials securely using your system’s keychain:
  • macOS: Keychain Access
  • Linux: Secret Service API (gnome-keyring, KWallet)
  • Windows: Windows Credential Manager
You can configure storage with the cli_auth_credentials_store setting in config.toml.

​
Troubleshooting

​
Browser Doesn’t Open

Use device code authentication instead: 
codex login --device-auth

​
“Invalid API Key” Error

Ensure your API key:
  • Starts with sk-proj- or sk-
  • Has not expired
  • Has correct permissions
  • Is from OpenAI Platform

​
Credentials Not Persisting

Check credential storage configuration: 
codex login status
Configure in ~/.codex/config.toml: 
[cli_auth]
credentials_store = "keychain"  # or "file"