DOCSEARCHbyAlgolia
Submit Docs

CLIProxyAPI

repository·main·Indexed 10 days ago

https://github.com/router-for-me/cliproxyapi

A proxy server that translates AI provider APIs (Kimi, OpenAI, Claude, Gemini, Grok) into standardized OpenAI, Gemini, or Claude-compatible interfaces for CLI tools and SDKs. It supports a plugin system for request normalization, custom authentication, and specialized routing, such as the claude-web-search-router for intercepting and routing Claude Code web search requests.

Tokens
34.6K
Snippets
96
Records
143
Agent score
98%

What's inside CLIProxyAPI

  1. Overview of CLIProxyAPI

    main

    CLIProxyAPI is a proxy server that provides OpenAI, Gemini, Claude, Codex, and Grok compatible API interfaces for Command Line Interfaces (CLI).

    It allows you to access various AI providers using any client or SDK that is compatible with OpenAI (including Responses), Gemini (including Interactions), or Claude protocols. You can access these providers either locally or via multiple CLI accounts.

    Supported Providers:

    • Kimi: Kimi series models (e.g., Kimi K3, K2.7 Code). Supports access via OAuth or compatible APIs.
    • OpenAI: GPT series models (e.g., GPT 5.6, GPT 5.5).
    • Anthropic: Claude series models (e.g., Claude Fable, Claude Opus, Claude Sonnet).
    • Google Gemini: Gemini series models (e.g., Gemini 3.5 Flash, Gemini 3.1 Pro).
    • xAI Grok: Grok series models (e.g., Grok 4.5, Grok Composer 2.5 Fast).

  2. Overview of CLI Proxy API features

    main

    CLI Proxy API provides OpenAI/Gemini/Claude/Grok compatible API endpoints specifically designed for CLI models. Key capabilities include:

    • Multi-Model Support: Compatible endpoints for OpenAI, Gemini, Claude, and Grok.
    • Authentication: Supports OAuth login for OpenAI Codex (GPT models), Claude Code, and Grok Build, as well as simple CLI authentication flows.
    • Advanced Features: Supports streaming, non-streaming, and WebSocket responses (where supported), function calling/tools, and multimodal inputs (text and images).
    • Load Balancing: Implements round-robin load balancing across multiple accounts for Gemini, OpenAI, Claude, and Grok (including AI Studio, Claude Code, OpenAI Codex, and Grok Build).
    • Extensibility: Supports Generative Language API keys and allows configuring OpenAI-compatible upstream providers (e.g., OpenRouter).
    • Integration: Provides a reusable Go SDK for embedding the proxy.

  3. Overview of CLIProxyAPI features

    main

    CLIProxyAPI provides OpenAI, Gemini, Claude, and Grok compatible API endpoints designed for use with CLI models. It allows developers to leverage existing subscriptions (like Claude Code, OpenAI Codex, or Grok Build) via OAuth login instead of traditional API keys.

    Key capabilities include:

    • Protocol Support: Streaming, non-streaming, and WebSocket responses.
    • Model Features: Function calling/tools and multimodal input (text and images).
    • Load Balancing: Round-robin load balancing across multiple accounts for Gemini, OpenAI, Claude, and Grok.
    • Upstream Providers: Support for OpenAI-compatible upstream providers (e.g., OpenRouter) via configuration.
    • Extensibility: A reusable Go SDK is available for embedding the proxy directly into your own applications.

  4. Explore CLIProxyAPI C ABI plugin examples

    main

    The examples/plugin directory contains standard dynamic library plugin examples for the CLIProxyAPI C ABI. Most standard capability examples include implementations in go/, c/, and rust/ subdirectories. Specialized examples may only provide a single implementation language.

    Available Plugin Examples by Capability

    CapabilityExample Directory
    Full Skeletonsimple/
    Modelmodel/
    Authentication Providerauth/
    Frontend Authentication Providerfrontend-auth/
    Exclusive Frontend Authfrontend-auth-exclusive/
    Executorexecutor/
    Protocol Formatprotocol-format/ (uses minimal executor)
    Request Translationrequest-translator/
    Request Normalizationrequest-normalizer/
    Codex Service Tiercodex-service-tier/ (Go implementation)
    Request Lifecyclerequest-lifecycle/ (Go implementation)
    Schedulerscheduler/ (Go implementation)
    Response Translationresponse-translator/
    Response Normalizationresponse-normalizer/
    Thinkingthinking/
    Usage Observationusage/
    CLI Extensioncli/
    Management API & Resource Extensionmanagement-api/
    Host Callbackshost-callback/ (uses minimal plugin resource)
    Host Auth Files Callbackhost-callback-auth-files/ (Go implementation)
    Host Model Callbackhost-model-callback/ (Go implementation)

  5. Explore CLIProxyAPI inspired projects and alternatives

    main

    If you are looking for implementations, ports, or tools inspired by CLIProxyAPI, the following projects are available:

    • 9Router: A Next.js implementation featuring format conversion (OpenAI/Claude/Gemini/Ollama), automatic fallback combo systems, multi-account management with exponential backoff, a Web dashboard, and support for CLI tools like Cursor, Claude Code, Cline, and RooCode. It requires no API keys.
    • OmniRoute: An AI gateway for multi-provider LLMs providing an OpenAI-compatible endpoint with smart routing, load balancing, retries, and fallbacks. It includes policies, rate limiting, caching, and observability.
    • Playful Proxy API Panel (PPAP): A public CLIProxyAPI-compatible fork and management panel. It includes usage statistics, cache hit rates, time-to-first-byte (TTFB) recording, TPS tracking, and self-hosting instructions for Docker.
    • Codex Switch: A desktop tool built with Tauri 2 and Vue 3 for managing multiple OpenAI Codex accounts. It allows switching between authentication profiles, monitoring real-time quota usage (5-hour and weekly), verifying token status, and importing/saving auth.json files.
    • Alex: A local Rust-based LLM proxy with an optional UI. It routes coding agents across multiple providers and supports local tracing, scriptable middleware, multi-subscription integration, failover, and re-authentication via Instant Messenger.

  6. Core Features of CLIProxyAPI

    main

    CLIProxyAPI provides compatible API endpoints for various CLI-based models. Key capabilities include:

    • Model Compatibility: Provides OpenAI, Gemini, Claude, Codex, and Grok compatible endpoints.
    • Protocol Support: Supports streaming, non-streaming, and WebSocket responses where applicable.
    • Advanced AI Features: Supports function calling/tool use and multimodal inputs (text and images).
    • Account Management:
      • Multi-account support with round-robin load balancing for Gemini, OpenAI, Claude, and Grok.
      • Simple CLI authentication flows for Gemini, OpenAI, Claude, and Grok.
      • Support for Gemini AIStudio API keys and AI Studio Build multi-account polling.
      • Support for Claude Code, OpenAI Codex, and Grok Build multi-account polling.
    • Extensibility: Allows connecting to upstream OpenAI-compatible providers (e.g., OpenRouter) via configuration.
    • Developer Tools: Provides a reusable Go SDK.

  7. Explore related projects built on CLIProxyAPI

    main

    CLIProxyAPI serves as a foundation for a wide ecosystem of tools designed to manage AI subscriptions (Claude, ChatGPT, Gemini, etc.) without requiring API keys. These projects include:

    Desktop & Menu Bar Apps

    • vibeproxy: macOS native menu bar app for using Claude Code and ChatGPT in AI coding tools.
    • Quotio / Quotio Desktop: macOS/Cross-platform apps for real-time quota tracking and smart failover.
    • ZeroLimit: Windows Tauri/React app for monitoring AI coding assistant quotas.
    • ProxyPal: Cross-platform native GUI for managing multiple providers and usage analytics.
    • AIUsage: macOS SwiftUI dashboard for managing CLIProxyAPI releases and OAuth accounts.
    • 霖君 (LinJun): Cross-platform desktop app for managing multi-account quotas.

    Developer Tools & IDE Extensions

    • Claude Proxy VSCode: VSCode extension to quickly switch Claude Code models.
    • Universal Chat Provider: VSCode extension that integrates subscriptions into GitHub Copilot Chat.
    • CCS (Claude Code Switch): CLI wrapper for switching between Claude accounts and alternative models.
    • Panopticon: Multi-agent orchestration tool that uses CLIProxyAPI as a local sidecar.
    • Claude Dialects: macOS tool that provides multiple Claude Code command interfaces powered by different models.

    Management & Monitoring

    • CPA-XXX Panel: Lightweight web management panel for health checks, logs, and statistics.
    • CLIProxyAPI Dashboard: Modern Next.js/React web dashboard for structured configuration and usage analysis.
    • CLIProxy API Quota Inspector: Cross-platform tool for viewing account-specific quotas (e.g., Codex 5h/7d).
    • CLIProxy Pool Watch: macOS SwiftUI app for monitoring account availability and capacity.
    • All API Hub: Browser extension for managing New API compatible relay sites and syncing with CLIProxyAPI.

    Specialized Utilities

    • Subtitle Translator: Cross-platform app for translating/validating SRT subtitles using existing LLM subscriptions.
    • Grok Search MCP: MCP server providing real-time web/X search via CLIProxyAPI.
    • Shadow AI: Stealth-mode AI assistant tool for restricted environments.
    • Tunnel Agent: Windows UI for managing CLIProxyAPI and Perplexity WebUI Scraper.

  8. Explore Standard Dynamic Library Plugin Examples

    main

    The examples/plugin directory contains various implementations of the CLIProxyAPI C ABI using standard dynamic libraries. These examples demonstrate different plugin capabilities, including model providers, authentication, executors, and request manipulation. Most standard capability examples provide implementations in go/, c/, and rust/ subdirectories.

    Available Capability Examples

    • simple/: Full provider-native skeleton declaring all supported capabilities.
    • model/: Model capability only.
    • auth/: Auth provider capability only.
    • frontend-auth/: Frontend auth provider capability only.
    • frontend-auth-exclusive/: Frontend auth provider that becomes the only request authentication provider when selected.
    • executor/: Executor capability only.
    • protocol-format/: Minimal executor focused on input/output format declarations.
    • request-translator/: Request translation capability only.
    • request-normalizer/: Request normalization capability only.
    • codex-service-tier/: Go-only request normalizer for Codex gpt-5.5 priority.
    • request-lifecycle/: Go-only request admission with concurrency control and HTTP termination.
    • scheduler/: Go-only scheduler for auth selection or delegation.
    • claude-web-search-router/: ModelRouter + executor for Claude Code web_search.
    • response-translator/: Response translation capability only.
    • response-normalizer/: Response normalization capability only.
    • thinking/: Thinking applier capability only.
    • usage/: Usage observer capability only.
    • cli/: Command-line capability only.
    • management-api/: Management API and resource capability only.
    • host-callback/: Minimal plugin resource demonstrating host callbacks.
    • host-callback-auth-files/: Go-only plugin resource calling host auth file callbacks.
    • host-model-callback/: Go-only plugin resource calling host model execution callbacks.

  9. Use JSON Envelopes for Plugin Communication

    main

    All data exchanged between the host and the plugin via the call methods must be formatted as JSON envelopes. Raw byte fields within these JSON objects must be encoded as base64.

    Successful Response Format

    {
  "ok": true,
  "result": {}
}

    Error Response Format

    {
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "request is invalid"
  }
}
    {
  "ok": true,
  "result": {}
}

  10. How the Provider Registry and Manager work together

    main

    The @sdk/access package uses a two-step process for managing authentication providers:

    1. Global Registration: Providers are registered globally using RegisterProvider(type, provider). The order in which types are first registered determines their priority.
    2. Manager Snapshot: A Manager is created and then populated with a snapshot of the currently registered providers using SetProviders(sdkaccess.RegisteredProviders()).

    Key Lifecycle Methods:

    • sdkaccess.NewManager(): Creates an empty manager.
    • sdkaccess.RegisteredProviders(): Returns the list of all registered providers in their registration order.
    • manager.SetProviders(providers): Replaces the manager's provider list with a defensive copy of the provided slice.
    • manager.Providers(): Returns a snapshot of the providers suitable for concurrent reading.

    If the manager is nil or has no providers configured, authentication calls will return nil, nil, effectively disabling access control.

    manager := sdkaccess.NewManager()
manager.SetProviders(sdkaccess.RegisteredProviders())

  11. Understand Stream Close Semantics in Plugins

    main

    When implementing streaming in a plugin, you have two options for closing the host-owned stream:

    1. Explicit Close (Recommended): Use host.model.stream_close (e.g., via a deferred call). This is the preferred pattern as it releases stream resources immediately after the plugin finishes reading.
    2. Implicit Close: Set the query parameter implicit_close=true. The plugin forwards the host_callback_id to host.model.execute_stream, allowing the host to close the stream automatically when the management.handle RPC callback scope returns. This is primarily used for demonstrating host cleanup behavior.

  12. Understand the Request Lifecycle Plugin behavior

    main

    The Request Lifecycle Plugin is a Go dynamic-library plugin designed for request admission, active termination, and exactly-once terminal lifecycle handling. It is intended for hosts supporting plugin RPC schema version 2 or newer.

    Core Capabilities

    • request_interceptor: Acquires a concurrency slot during the request.intercept_before phase. It can terminate a request before it reaches an upstream executor.
    • request_lifecycle_plugin: Releases the concurrency slot during the request.complete event for successful, failed, rejected, or canceled requests.

    Key Behaviors

    • Concurrency Control: Limits in-flight requests to a defined max_concurrency. When the limit is reached, it returns a 429 JSON response with a Retry-After: 1 header.
    • Keyword Rejection: If the raw request body contains the configured reject_keyword, the plugin returns a 403 JSON response.
    • Upstream Protection: Terminated requests are not forwarded to upstream models.
    • Slot Safety: The plugin only releases RequestIDs that were previously admitted, preventing counter underflow from rejected requests or duplicate terminal events.