CLIProxyAPI: A Free, Unified Proxy for Gemini, Claude, Codex, and More

OpenAI, Google’s Gemini, Anthropic’s Claude, and Baidu’s Qwen all ship with their own APIs, SDKs, and authentication models. For developers building a single‑click CLI or web tool, juggling key prefixes, OAuth flows, and JSON dialects can feel more like a full‑stack project than a simple "call an API" exercise.

Enter CLIProxyAPI – a lightweight Go server that wraps all those APIs into one OpenAI‑compatible endpoint. It runs locally, exposes a standard OpenAI‑compatible interface, and optionally forwards calls to a chosen provider. The result? One curl command, one SDK, one authentication flow, and no hard‑coded keys.

Why CLIProxyAPI? The Pain Points it Solves

Quick Start

1. Installation

You can run CLIProxyAPI either as a pre‑built binary or via Docker.

From Homebrew (macOS/Linux)

brew install router-for-me/cli/cli-proxy-api
cli-proxy-api --help

From Docker

docker pull ghcr.io/router-for-me/cliproxyapi:latest

docker run \
  --rm -it \
  -p 8080:8080 \
  -e CONFIG_PATH=/etc/cliproxyapi/config.yaml \
  -v $(pwd)/config.yaml:/etc/cliproxyapi/config.yaml \
  ghcr.io/router-for-me/cliproxyapi:latest

From Source

go install github.com/router-for-me/CLIProxyAPI/cmd/server@latest
# or
go run main.go

Tip – The repository ships a Dockerfile and a Docker‑compose example that sets up the proxy and a front‑end client.

2. Configuring the Proxy

Create config.yaml (found in the repo’s example folder). Minimal example:

# config.yaml
# List of providers you want to expose
providers:
  - name: gemini          # Google Gemini
    type: gemini
    key: <YOUR_GEMINI_KEY>
  - name: claude          # Anthropic Claude
    type: claude
    key: <YOUR_CLAUDE_KEY>
  - name: codex           # OpenAI Codex
    type: codex
    key: <YOUR_OPENAI_KEY>
    oauth: true

# Optional: routing fallback chain
fallback:
  - gemini
  - claude
  - codex

# Optional: HTTPS (self‑signed or certs via cert-manager or Let's Encrypt)
# https:
#   cert: /path/to/cert.pem
#   key: /path/to/key.pem

Run the proxy and it will expose these endpoints:

GET  /v1/models
POST /v1/chat/completions
GET  /v1/models/<model>/functions

All requests go to /v1/* just like an OpenAI client.

3. Using the Proxy

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
       "model": "gemini-2.5-pro",
       "messages": [{"role":"user", "content":"Hello"}]
     }'

The model field can be any of the provider names (gemini-2.5-pro, claude-3-opus-20240229, codex-gpt-35-turbo), or a proxy‑defined alias such as gemini-pro. The server does the translation.

4. SDK Integration

A lightweight Go SDK is included under the sdk/ folder. Using it is as simple as:

import "github.com/router-for-me/CLIProxyAPI/sdk"

client, err := sdk.NewClient("http://localhost:8080", &sdk.Config{BearerToken: "<TOKEN>"})
if err != nil { log.Fatal(err) }

resp, _ := client.ChatCompletion(context.Background(), &sdk.ChatRequest{
    Model: "gemini-2.5-pro",
    Messages: []sdk.Message{{Role: "user", Content: "Hi!"}},
})
fmt.Println(resp.Choices[0].Message.Content)

The SDK handles HTTP, streaming and function calling under the hood. Check docs/sdk-usage.md for full details.

Advanced Features

Multi‑Account Load Balancing

If you have several Gemini or Claude accounts, add them all in the config with unique names. Set the round_robin flag on the provider to enable rotation:

providers:
  - name: gemini-acc1
    type: gemini
    key: <KEY1>
    round_robin: true
  - name: gemini-acc2
    type: gemini
    key: <KEY2>
    round_robin: true

Requests to gemini will pick alternately from gemini-acc1 and gemini-acc2.

Automatic Model Fallback

If a provider doesn’t support a particular model, set a fallback chain in the config. For example, if Claude‑Opus is unavailable, fall back to claude-sonnet:

fallback:
  - 'claude-sonnet-2'
  - 'claude-3-haiku-20240307'

The proxy intercepts a 404 from its target and retries with the next model until success or exhaustion.

Function Calling and Streaming

All OpenAI‑style function calls work out of the box. Just request them via the proxy; the server adds the necessary tools and tool_choice fields in the translated request.

Streaming is handled through the /v1/chat/completions endpoint with stream=true. The response is chunked in the OpenAI event‑stream format and forwarded to the client.

Community and Ecosystem

CLIProxyAPI is the hub for a growing ecosystem of tools: - vibemacro – macOS menu bar app that turns your subscription into a CLI‑ready proxy. - ProxyPal – GUI for managing proxies. - ProxyPilot – Windows native TUI. - Claude Proxy VSCode – extension to switch models with a proxy backend.

Check the projects section of the repo for a full list and contribute by adding your own.

The repo encourages contributions. Issues for bugs or feature requests are welcome, and the community actively maintains documentation and examples.

FAQs

Q: Do I need to pay for each target provider?

A: The proxy itself is free and MIT‑licensed. You only pay for the underlying provider’s usage. For free tiers, Gemini 2.5 Pro, GPT‑5, and Claude‑sonnet are available at no cost.

Q: Can I expose the proxy through a reverse‑proxy like Nginx?

A: Absolutely. Run CLIProxyAPI behind HTTPS, use a CORS‑friendly reverse‑proxy, and even add basic auth if you wish.

Q: What other providers are supported?

A: Currently Gemini, Claude, Codex (OpenAI), Qwen, iFlow, and any OpenRouter‑compatible API via a custom provider.

Get Started

Visit the official repo at https://github.com/router-for-me/CLIProxyAPI for code, examples, and the community.

# Clone and run
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
make run

Now you’re one step closer to an effortlessly unified AI CLI experience. Happy coding!

Further Reading

• Managing Multiple AI Providers in Go – An in‑depth technical post on provider routing.
• OAuth in CLI Tools – How CLIProxyAPI implements secure token stores.
• Function Calling with OpenAI APIs – A quick guide.

If you have feedback or a feature request, open an issue or submit a pull request – the project thrives on community involvement.