Using Codex CLI on macOS (Apple Silicon)#

Codex CLI is the terminal interface for OpenAI Codex.

Codex supports two authentication methods:

ChatGPT account
- Uses ChatGPT plan limits (Free, Plus, Pro)
- No API key required
OpenAI API key
- Uses OpenAI Platform API billing
- Requires an API key
- Usage is charged against API credits

You can switch between both methods.

1. Installation#

Install Codex CLI via Homebrew Cask:

brew install --cask codex

Verify:

which codex
codex --version

2. Configuration#

Codex stores configuration in:

~/.codex/

Important files:

File	Purpose
`config.toml`	Main configuration
`auth.json`	Authentication state
`logs_*.sqlite`	Conversation logs
`state_*.sqlite`	Internal state

Edit configuration:

nano ~/.codex/config.toml

3. MCP Server Configuration#

MCP servers are managed through the centralized Git-backed pipeline documented in:

AI - MCP Configuration Guide

Check MCP and system configuration:

codex doctor

4. Authentication#

Uses your ChatGPT account limits.

codex login

Check status:

codex login status

Example:

Logged in using ChatGPT

Check Codex usage:

/status

Online usage page:

https://chatgpt.com/codex/settings/usage

Uses OpenAI API billing.

Create an API key:

https://platform.openai.com/api-keys

Store the key in 1Password.

Add it to your shell environment:

nano ~/.zshrc

Add to ~/.zshrc:

alias codexa='printf "%s" "$OPENAI_API_KEY SEE 1Passoed" | codex login --with-api-key'

Then switch to API authentication:

codexa

5. Switching Authentication Methods#

Check current login:

codex login status

Switch to ChatGPT account:

codex login

Switch to API key:

codexa

6. Checking Usage#

Inside Codex:

/status

ChatGPT usage:

https://chatgpt.com/codex/settings/usage

API usage:

https://platform.openai.com/usage

7. Diagnostics#

Run:

codex doctor

Check configuration:

cat ~/.codex/config.toml

8. Quick Reference#

Command	Description
`codex`	Start Codex CLI
`codex --version`	Show version
`codex login`	Login with ChatGPT account
`codex login status`	Show authentication mode
`codex-api`	Switch to API key authentication
`codex doctor`	Diagnose installation
`/status`	Show current session information

Notes#

Codex CLI uses the same installation for both authentication methods.

Authentication	Billing source
ChatGPT login	ChatGPT plan limits
API key	OpenAI Platform API credits

Use:

ChatGPT login when you want to use included Codex access.
API key login when you want API billing and usage tracking.