Quick Start

Get up and running with CLI Proxy API in 5 minutes

Quick Start Guide

Get CLI Proxy API running in under 5 minutes. This guide will walk you through installation, configuration, OAuth authentication, and making your first API call.

What You’ll Build

By the end of this guide, you’ll have:

• A running CLI Proxy API server
• OAuth authentication configured for at least one provider
• Successfully made an API call using your CLI subscription

1. Install CLI Proxy API

   Choose your preferred installation method:

   Docker (Recommended)

   # Pull the latest image
   docker pull eceasy/cli-proxy-api:latest
   
   # Create directories for config and auth
   mkdir -p ~/cli-proxy/{config,auths,logs}
   
   # Download example config
   curl -o ~/cli-proxy/config/config.yaml \
     https://raw.githubusercontent.com/router-for-me/CLIProxyAPI/main/config.example.yaml
   

   The Docker method is recommended for production deployments as it includes automatic updates and easier management.

2. Configure the Server

   Create a config.yaml file with your basic settings:

   config.yaml

   # Server Configuration
   host: ""  # Empty = bind to all interfaces
   port: 8317
   
   # Authentication directory (OAuth tokens stored here)
   auth-dir: "~/.cli-proxy-api"
   
   # API keys for client authentication
   api-keys:
     - "your-secure-api-key-here"
     - "another-key-for-different-client"
   
   # Enable debug logging (optional)
   debug: false
   
   # Routing strategy for multi-account load balancing
   routing:
     strategy: "round-robin"  # Options: round-robin, fill-first
   
   # Retry configuration
   request-retry: 3
   max-retry-credentials: 0  # 0 = try all available credentials
   

   Generate secure API keys using: openssl rand -hex 32

   Key Configuration Options:

   Option	Description	Default
   host	Network interface to bind (empty = all)	""
   port	HTTP server port	8317
   auth-dir	Directory for OAuth tokens	~/.cli-proxy-api
   api-keys	Client authentication keys	[]
   debug	Enable verbose logging	false

   For advanced configuration options, see the Server Configuration guide.

3. Start the Server

   Launch CLI Proxy API with your configuration:

   Docker

   docker run -d \
     --name cli-proxy-api \
     -p 8317:8317 \
     -v ~/cli-proxy/config/config.yaml:/CLIProxyAPI/config.yaml \
     -v ~/cli-proxy/auths:/root/.cli-proxy-api \
     -v ~/cli-proxy/logs:/CLIProxyAPI/logs \
     eceasy/cli-proxy-api:latest
   
   # View logs
   docker logs -f cli-proxy-api
   

   You should see output like:

   CLIProxyAPI Version: v6.x.x, Commit: abc123, BuiltAt: 2026-03-10
   INFO[0000] Server starting on :8317
   
4. Authenticate with a Provider

   Authenticate with at least one OAuth provider. We’ll use Google Gemini as an example:

   Gemini (Google)

   # For Docker
   docker exec -it cli-proxy-api ./CLIProxyAPI -login
   
   # For binary installation
   ./cli-proxy-api -login
   

   This will:

   1. Open your browser automatically
   2. Prompt you to sign in with your Google account
   3. Save OAuth tokens to ~/.cli-proxy-api/gemini_*.json

   Use the -no-browser flag if you’re on a headless server. You’ll get a URL to open manually.

   For multiple accounts:

   # Add a second Gemini account
   ./cli-proxy-api -login
   
   # Add a third Gemini account
   ./cli-proxy-api -login
   

   Each login creates a new credential file, enabling automatic load balancing.

   Claude Code

   # For Docker
   docker exec -it cli-proxy-api ./CLIProxyAPI -claude-login
   
   # For binary installation  
   ./cli-proxy-api -claude-login
   

   The CLI will open your browser to authenticate with Claude Code OAuth.

   OpenAI Codex

   # Standard OAuth flow
   ./cli-proxy-api -codex-login
   
   # Device code flow (for headless servers)
   ./cli-proxy-api -codex-device-login
   

   For device code flow, you’ll receive a code to enter at the provided URL.

   Qwen Code

   ./cli-proxy-api -qwen-login
   

   Authenticates with Alibaba’s Qwen Code service via OAuth.

   OAuth tokens are stored in auth-dir (default: ~/.cli-proxy-api/). Keep these files secure and never commit them to version control.

5. Make Your First API Call

   Test your setup with a simple API request:

   cURL

   curl http://localhost:8317/v1/chat/completions \
     -H "Authorization: Bearer your-secure-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "gemini-2.5-pro",
       "messages": [
         {"role": "user", "content": "Hello! Can you help me test CLI Proxy API?"}
       ]
     }'
   

   Expected Response:

   {
     "id": "chatcmpl-123456",
     "object": "chat.completion",
     "created": 1709251200,
     "model": "gemini-2.5-pro",
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": "Hello! I'm working perfectly through CLI Proxy API. How can I assist you today?"
         },
         "finish_reason": "stop"
       }
     ],
     "usage": {
       "prompt_tokens": 15,
       "completion_tokens": 20,
       "total_tokens": 35
     }
   }
   

   Replace your-secure-api-key-here with one of the API keys you defined in config.yaml.

   Test with Python:

   python

   import openai
   
   # Configure OpenAI client to use CLI Proxy API
   client = openai.OpenAI(
       api_key="your-secure-api-key-here",
       base_url="http://localhost:8317/v1"
   )
   
   # Make a request
   response = client.chat.completions.create(
       model="gemini-2.5-pro",
       messages=[
           {"role": "user", "content": "Hello from Python!"}
       ]
   )
   
   print(response.choices[0].message.content)
   

   Test with Streaming:

   python (streaming)

   import openai
   
   client = openai.OpenAI(
       api_key="your-secure-api-key-here",
       base_url="http://localhost:8317/v1"
   )
   
   stream = client.chat.completions.create(
       model="gemini-2.5-pro",
       messages=[{"role": "user", "content": "Count to 5 slowly"}],
       stream=True
   )
   
   for chunk in stream:
       if chunk.choices[0].delta.content:
           print(chunk.choices[0].delta.content, end="")
   

Verify Your Setup

Check that everything is working correctly:

1. List Available Models

curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer your-secure-api-key-here"

You should see all models from your authenticated providers.

2. Check Server Health

curl http://localhost:8317/health

3. Review Logs

Docker

docker logs cli-proxy-api

Common Issues

OAuth browser doesn't open

Solution: Use the -no-browser flag:

./cli-proxy-api -login -no-browser

Copy the URL shown and open it in your browser manually.

Port 8317 already in use

Solution: Change the port in config.yaml:

port: 8318  # Use a different port

Then update your client requests to use the new port.

API returns 401 Unauthorized

Causes:

• Incorrect API key in Authorization header
• API key not defined in config.yaml

Solution: Verify your API key:

config.yaml

api-keys:
  - "your-secure-api-key-here"  # Must match exactly

No models available after OAuth

Solution: Verify OAuth tokens were saved:

ls -la ~/.cli-proxy-api/

You should see files like gemini_account1.json, claude_account1.json, etc.

If missing, re-run the login command:

./cli-proxy-api -login

Next Steps

Now that you have CLI Proxy API running:

Add More Accounts

Set up multiple accounts for load balancing across providers

Configure Model Mappings

Create custom model aliases and route unavailable models

Integrate with Your Tools

Connect Cursor, Cline, or other AI coding tools

Deploy to Production

Learn best practices for production deployments

Alternative: Quick Docker Setup

If you prefer a fully automated Docker setup:

# Clone the repository
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI

# Copy example config
cp config.example.yaml config.yaml

# Edit config.yaml with your API keys
vim config.yaml

# Start with docker-compose
docker-compose up -d

# Perform OAuth login
docker exec -it cli-proxy-api ./CLIProxyAPI -login

# View logs
docker-compose logs -f

This gives you a complete setup with persistent storage for configs, auth tokens, and logs.

For production deployments with high availability, see our Cloud Deployment guide.