Providers & Auth

The epi CLI supports five AI providers out of the box: Anthropic, OpenAI, OpenAI Codex, Google, and GitHub Copilot. Authentication is handled through API keys, environment variables, or OAuth.

Supported Providers

Provider	Flag	Default Model	Environment Variable
Anthropic	`--provider anthropic`	`claude-opus-4-6`	`ANTHROPIC_API_KEY`
OpenAI	`--provider openai`	`gpt-5.3`	`OPENAI_API_KEY`
OpenAI Codex	`--provider openai-codex`	`gpt-5.3-codex`	`OPENAI_API_KEY`
Google	`--provider google`	`gemini-3-flash`	`GEMINI_API_KEY`
GitHub Copilot	`--provider github-copilot`	`claude-sonnet-4.5`	`GITHUB_TOKEN`

Provider Selection

The CLI determines which provider to use in this order:

Explicit flag — --provider anthropic
Stored credentials — From auth.json (see below)
Environment variables — First available key wins

If no provider can be determined, the CLI exits with an error.

API Key Setup

Environment Variables

The simplest way to authenticate:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-api03-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google
export GEMINI_API_KEY=...

Command-Line Override

Pass an API key directly (overrides all other sources):

epi --provider anthropic --api-key sk-ant-api03-...

OAuth (Anthropic)

The CLI supports OAuth 2.0 with PKCE for Anthropic. This provides token-based authentication with automatic refresh.

Login

# In interactive mode:
/login

# This opens a browser for OAuth authorization via claude.ai

Logout

# In interactive mode:
/logout

OAuth Token via Environment

You can also provide an OAuth token directly:

export ANTHROPIC_OAUTH_TOKEN=...

Note: The ANTHROPIC_OAUTH_TOKEN environment variable takes precedence over ANTHROPIC_API_KEY.

OAuth (OpenAI Codex)

The CLI supports ChatGPT OAuth device flow for openai-codex:

# In interactive mode:
/login

# Select "OpenAI (ChatGPT Plus/Pro)"

Credential Storage

Credentials are stored in ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json).

Credential Types

API Key:

{
  "type": "api_key",
  "key": "sk-ant-api03-..."
}

OAuth:

{
  "type": "oauth",
  "access": "<access_token>",
  "refresh": "<refresh_token>",
  "expires": 1705123456
}

Resolution Priority

When resolving credentials for a provider, the CLI checks in this order:

Runtime override (--api-key flag)
Stored API key in auth.json
OAuth token with automatic refresh
Environment variable

Choosing a Model

Each provider has a default model. Override it with --model:

# Anthropic models
epi --provider anthropic --model claude-sonnet-4-20250514
epi --provider anthropic --model claude-opus-4-20250514

# OpenAI models
epi --provider openai --model gpt-5.3
epi --provider openai --model gpt-5.2-codex

# OpenAI Codex models
epi --provider openai-codex --model gpt-5.3-codex

# Google models
epi --provider google --model gemini-3-flash
epi --provider google --model gemini-3-pro-preview

# GitHub Copilot models
epi --provider github-copilot --model claude-sonnet-4.5

Configuration Directory

By default, the CLI stores configuration in ~/.pi/agent/. Override with the PI_CODING_AGENT_DIR environment variable:

export PI_CODING_AGENT_DIR=/path/to/custom/config
epi

This directory contains:

~/.pi/agent/
├── auth.json      # Stored credentials
├── sessions/      # Session files (organized by project)
└── skills/        # User-defined skills