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

Install CLI Proxy API

Choose your preferred installation method:

# 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

# Download the latest release for your platform
# Visit: https://github.com/router-for-me/CLIProxyAPI/releases

# Example for Linux AMD64
wget https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api_linux_amd64.tar.gz
tar -xzf cli-proxy-api_linux_amd64.tar.gz
chmod +x cli-proxy-api

# Move to your preferred location
sudo mv cli-proxy-api /usr/local/bin/

# Requires Go 1.26 or later
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI

# Build the binary
go build -o cli-proxy-api ./cmd/server/

# Run directly
./cli-proxy-api

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

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.

Start the Server

Launch CLI Proxy API with your configuration:

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

# Start with default config.yaml in current directory
./cli-proxy-api

# Or specify a config file path
./cli-proxy-api -config /path/to/config.yaml

# Create docker-compose.yml
services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    restart: unless-stopped

# Start the service
docker-compose up -d

You should see output like:

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

Authenticate with a Provider

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

Gemini (Google)
Claude Code
OpenAI Codex
Qwen Code

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

# For binary installation
./cli-proxy-api -login

This will:

Open your browser automatically
Prompt you to sign in with your Google account
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.

# 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.

# 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.

./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.

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 logs cli-proxy-api

# Logs output to stdout by default
# To enable file logging, add to config.yaml:
logging-to-file: true

# View logs
tail -f logs/app.log

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.

Get Started

Core Concepts

Configuration

OAuth Authentication

Integrations

Deployment

Quick Start

Quick Start Guide

What You’ll Build

Verify Your Setup

1. List Available Models

2. Check Server Health

3. Review Logs

Common Issues

Next Steps

Add More Accounts

Configure Model Mappings

Integrate with Your Tools

Deploy to Production

Alternative: Quick Docker Setup

​Quick Start Guide

​What You’ll Build

​Verify Your Setup

​1. List Available Models

​2. Check Server Health

​3. Review Logs

​Common Issues

​Next Steps

Add More Accounts

Configure Model Mappings

Integrate with Your Tools

Deploy to Production

​Alternative: Quick Docker Setup

Quick Start Guide

What You’ll Build

Verify Your Setup

1. List Available Models

2. Check Server Health

3. Review Logs

Common Issues

Next Steps

Alternative: Quick Docker Setup