Files
ProxyPilot/docs/cli.md
T

9.1 KiB

ProxyPilot CLI

proxypilot is the unified command-line interface for the ProxyPilot local AI proxy. It provides both server functionality (running the proxy server) and switch functionality (toggling AI agents between proxy mode and native mode).

Installation

bun install -g proxypilot

Via npm

npm install -g proxypilot

Via Go

go install github.com/Finesssee/ProxyPilot/cmd/server@latest

Manual Download

Download pre-built binaries from GitHub Releases.

Available binaries:

  • proxypilot-darwin-amd64 - macOS Intel
  • proxypilot-darwin-arm64 - macOS Apple Silicon
  • proxypilot-linux-amd64 - Linux x64
  • proxypilot-linux-arm64 - Linux ARM64
  • proxypilot-windows-amd64.exe - Windows x64

Server Mode

Run ProxyPilot as a local proxy server:

proxypilot                           # Start server on default port (8317)
proxypilot -config /path/to/config   # Use custom config file

Server Features

  • Routes AI requests through configured providers
  • Automatic model aliasing and translation
  • OAuth login helpers for various providers
  • Agent configuration management

Login Commands

proxypilot --login                   # Login to Google Account (Gemini)
proxypilot --codex-login             # Login to Codex using OAuth
proxypilot --claude-login            # Login to Claude using OAuth
proxypilot --qwen-login              # Login to Qwen using OAuth
proxypilot --antigravity-login       # Login to Antigravity using OAuth
proxypilot --kiro-login              # Login to Kiro using AWS Builder ID
proxypilot --kiro-aws-login          # Login to Kiro using AWS Builder ID device code
proxypilot --minimax-login           # Add MiniMax API key
proxypilot --zhipu-login             # Add Zhipu AI API key

Kiro Google/GitHub OAuth is not currently supported because AWS Cognito rejects third-party localhost callbacks. Use AWS Builder ID or import a token from the official Kiro IDE instead.

Login Options

--no-browser                         # Don't open browser automatically for OAuth
--incognito                          # Use incognito/private mode (useful for multiple accounts)
--no-incognito                       # Force disable incognito mode

Import Commands

proxypilot --vertex-import <file>    # Import Vertex service account key JSON
proxypilot --kiro-import             # Import Kiro token from Kiro IDE

Agent Configuration

ProxyPilot can automatically configure AI CLI tools to use the proxy.

Detect Installed Agents

proxypilot --detect-agents

Example output:

Detecting installed CLI agents...

  Claude Code:    [+] Installed
                  Binary: /usr/local/bin/claude
                  Config: ~/.claude/settings.json
  Codex CLI:      [+] Installed
                  Binary: /usr/local/bin/codex
                  Config: ~/.codex
  Gemini CLI:     [-] Not found

Setup Commands

proxypilot --setup-all               # Configure all detected agents
proxypilot --setup-claude            # Configure Claude Code
proxypilot --setup-codex             # Configure Codex CLI
proxypilot --setup-droid             # Configure Factory Droid
proxypilot --setup-opencode          # Configure OpenCode
proxypilot --setup-gemini            # Configure Gemini CLI
proxypilot --setup-cursor            # Configure Cursor
proxypilot --setup-kilo              # Configure Kilo Code CLI
proxypilot --setup-roocode           # Configure RooCode (VS Code)

Switch Mode

Switch AI agents between proxy mode (through ProxyPilot) and native mode (direct API access). Think of it like nvm for Node versions, but for AI agent configurations.

Usage

proxypilot --switch <agent>                    # Show status of specific agent
proxypilot --switch <agent> --mode proxy       # Switch agent to proxy mode
proxypilot --switch <agent> --mode native      # Switch agent to native mode
proxypilot --switch <agent> --mode status      # Show current mode (default)

Supported Agents

Agent CLI Tool Config Location
claude Claude Code ~/.claude/settings.json
gemini Gemini CLI ~/.gemini/settings.json
codex Codex CLI ~/.codex/config.toml
opencode OpenCode ~/.opencode/config.json
droid Factory Droid ~/.factory/settings.json
cursor Cursor IDE ~/.cursor/config.json
kilo Kilo Code* VS Code settings
roocode RooCode* VS Code settings

*VS Code extensions require manual configuration - proxypilot will display instructions.

Modes

Mode Description
proxy Route through ProxyPilot (http://127.0.0.1:8317)
native Use direct API access (restore original config)
status Show current mode (default)

Examples

Check single agent status

$ proxypilot --switch claude
Claude Code: proxy
Config: ~/.claude/settings.json

Switch Claude to proxy mode

$ proxypilot --switch claude --mode proxy
Switched Claude Code to proxy mode
Config: ~/.claude/settings.json
Backup: ~/.claude/settings.json.native.json

Switch Gemini back to native mode

$ proxypilot --switch gemini --mode native
Switched Gemini CLI to native mode
Restored from: ~/.gemini/settings.json.native.json

How Switch Works

Switching to proxy mode

  1. Backs up current config to <config>.native.json
  2. Updates config to point to http://127.0.0.1:8317
  3. Preserves all other settings (API keys, preferences, etc.)

Switching to native mode

  1. Restores config from <config>.native.json backup
  2. Removes backup file after successful restore
  3. Original API keys and settings are restored

Config Detection

ProxyPilot automatically detects which mode an agent is in by checking:

  • If config contains 127.0.0.1:8317 -> proxy mode
  • If backup file exists -> was previously in proxy mode
  • Otherwise -> native mode

Agent-Specific Notes

Claude Code

Config location: ~/.claude/settings.json

Proxy mode sets:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317"
  }
}

Codex CLI

Config location: ~/.codex/config.toml

Proxy mode sets:

[openai]
api_base_url = "http://127.0.0.1:8317"

Gemini CLI

Config location: ~/.gemini/settings.json

Proxy mode sets the API endpoint to ProxyPilot.

Kilo Code & RooCode

These are VS Code extensions that require manual configuration:

  1. Open VS Code Settings (Ctrl+,)
  2. Search for the extension settings
  3. Update the API base URL to http://127.0.0.1:8317

ProxyPilot will display these instructions when you run:

proxypilot --setup-kilo
proxypilot --setup-roocode

Backup System

Before modifying any configuration file, ProxyPilot creates a timestamped backup:

~/.claude/.proxypilot-backups/
  settings.json.20251228-221853.bak

~/.codex/.proxypilot-backups/
  config.toml.20251228-221853.bak

Restoring Backups

# List backups
ls ~/.claude/.proxypilot-backups/

# Restore
cp ~/.claude/.proxypilot-backups/settings.json.<timestamp>.bak ~/.claude/settings.json

Troubleshooting

"Config not found"

The agent's config file doesn't exist. Run the agent once to create it, or create the config manually.

"Failed to backup config"

Check file permissions on the config directory.

"Already in proxy/native mode"

The agent is already configured for the requested mode. No changes made.

CLI not detected

If a CLI tool is installed but not detected:

  1. Ensure the binary is in your PATH
  2. Try running the tool directly to verify it's installed
  3. Check if the config directory exists

Configuration not applied

  1. Restart the CLI tool after running setup
  2. Verify ProxyPilot is running on port 8317
  3. Check the backup directory for the original config

Full Usage Reference

proxypilot -h, --help                # Show help
proxypilot -v, --version             # Show version

# Server
proxypilot                           # Start proxy server
proxypilot -config <path>            # Use custom config file

# OAuth Logins
proxypilot --login                   # Google/Gemini login
proxypilot --codex-login             # Codex OAuth
proxypilot --claude-login            # Claude OAuth
proxypilot --qwen-login              # Qwen OAuth
proxypilot --antigravity-login       # Antigravity OAuth
proxypilot --kiro-login              # Kiro AWS Builder ID
proxypilot --kiro-aws-login          # Kiro AWS Builder ID device code

# Agent Detection & Setup
proxypilot --detect-agents           # Detect installed agents
proxypilot --setup-all               # Configure all agents
proxypilot --setup-<agent>           # Configure specific agent

# Agent Switching
proxypilot --switch <agent>          # Show agent status
proxypilot --switch <agent> --mode proxy   # Switch to proxy
proxypilot --switch <agent> --mode native  # Switch to native