Skip to main content
ChatCLI supports authentication via OAuth 2.0 with PKCE and Device Flow (RFC 8628) for providers that offer these options. This allows you to use your existing plan (such as ChatGPT Plus, Codex, Claude Pro, or GitHub Copilot) directly in the terminal, without needing to generate or paste API keys.

​
Authentication Methods

MethodDescriptionWhen to Use
API KeyEnvironment variable in .env (e.g., OPENAI_API_KEY)Programmatic access, CI/CD, platform API keys
OAuth (interactive login)/auth login command in the terminalChatGPT Plus/Codex plans, Claude Pro, no key management
Both methods can coexist. ChatCLI prioritizes OAuth credentials when both are available.

​
/auth Commands

All authentication commands have auto-completion — just type /auth and press Tab.

​
View Status

/auth status
Displays the authentication status of all configured providers, including credential type (API Key vs OAuth), token validity, and source.

​
Login via OAuth

/auth login openai-codex
/auth login anthropic
/auth login github-copilot
1

Browser opens automatically

The browser opens to the provider’s login page.
2

Authorize access

OpenAI: a local HTTP server captures the callback automatically (port 1455).Anthropic: after authorizing, copy the code displayed on the page and paste it in the terminal.GitHub Copilot: enter the device code displayed in the terminal on the GitHub page.
3

Provider available immediately

The provider appears immediately in /switch — no app restart needed.

​
Supported Providers

ProviderCommandCompatible Plans
OpenAI/auth login openai-codexChatGPT Plus, Codex, Team, Enterprise
Anthropic/auth login anthropicClaude Pro, Team
GitHub Copilot/auth login github-copilotCopilot Individual, Business, Enterprise

​
Logout

/auth logout openai-codex
/auth logout anthropic
/auth logout github-copilot
Removes the stored OAuth credentials for the specified provider.

​
Complete Flow: From Zero to First Prompt

If you are starting without any configured credentials, follow these steps:
1

Start ChatCLI

Works even without configured credentials.
chatcli
2

Log in via OAuth

/auth login openai-codex
3

Authorize in the browser

The browser opens automatically to the provider’s login page.
4

Switch to the provider

/switch
5

Send your first prompt

Hello, how are you?

​
Automatic Endpoint Routing (OpenAI)

ChatCLI automatically detects the credential type and routes requests to the correct endpoint:
CredentialEndpointAPI Format
OPENAI_API_KEYapi.openai.com/v1/responsesResponses API (default)
OPENAI_API_KEYapi.openai.com/v1/chat/completionsChat Completions (legacy models)
OAuth (/auth login)chatgpt.com/backend-api/codex/responsesResponses API (streaming SSE)
You don’t need to configure anything — routing is automatic based on the token type.

​
Credential Storage

OAuth credentials are saved with AES-256-GCM encryption at: 
~/.chatcli/auth-profiles.json
The encryption key is automatically generated and stored at ~/.chatcli/.auth-key (permission 0600). Unencrypted data from previous versions is transparently migrated on first read. The file contains access tokens, refresh tokens, and metadata for each provider. Tokens are automatically renewed when they expire. To customize the storage directory, set the environment variable: 
export CHATCLI_AUTH_DIR="~/.config/chatcli/auth"

​
Advanced Configuration

VariableDescription
CHATCLI_OPENAI_CLIENT_IDAllows overriding the OpenAI OAuth client ID
CHATCLI_COPILOT_CLIENT_IDAllows overriding the GitHub Copilot Device Flow client ID (default: Ov23lifEydOk2Non90tJ)
COPILOT_API_BASE_URLCopilot API base URL for enterprise environments (default: https://api.githubcopilot.com)

​
Troubleshooting

The Anthropic flow redirects to the console page that displays the authorization code. Copy the displayed code and paste it in the terminal when prompted.
Run /auth status to verify that the token was saved correctly. If needed, try /auth logout <provider> followed by /auth login <provider>.
Make sure your GitHub account has an active Copilot subscription (Individual, Business, or Enterprise). Check at https://github.com/settings/copilot if Copilot is enabled.
OAuth tokens are automatically renewed using the refresh token. If the refresh fails, log in again with /auth login.GitHub Copilot tokens (Device Flow) do not expire and do not have a refresh token — they are persistent until manually revoked.

​
Next Steps

Command Reference

Complete list of all available commands.

Configuration (.env)

All available environment variables.

Basic Usage

Learn the fundamentals of ChatCLI.