# 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 ### Via bun (recommended) ```bash bun install -g proxypilot ``` ### Via npm ```bash npm install -g proxypilot ``` ### Via Go ```bash go install github.com/Finesssee/ProxyPilot/cmd/server@latest ``` ### Manual Download Download pre-built binaries from [GitHub Releases](https://github.com/Finesssee/ProxyPilot/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: ```bash 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 ```bash 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 ```bash --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 ```bash proxypilot --vertex-import # 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 ```bash 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 ```bash 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 ```bash proxypilot --switch # Show status of specific agent proxypilot --switch --mode proxy # Switch agent to proxy mode proxypilot --switch --mode native # Switch agent to native mode proxypilot --switch --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 ```bash $ proxypilot --switch claude Claude Code: proxy Config: ~/.claude/settings.json ``` #### Switch Claude to proxy mode ```bash $ 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 ```bash $ 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 `.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 `.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: ```json { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317" } } ``` ### Codex CLI Config location: `~/.codex/config.toml` Proxy mode sets: ```toml [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: ```bash 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 ```bash # List backups ls ~/.claude/.proxypilot-backups/ # Restore cp ~/.claude/.proxypilot-backups/settings.json..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 ```bash proxypilot -h, --help # Show help proxypilot -v, --version # Show version # Server proxypilot # Start proxy server proxypilot -config # 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- # Configure specific agent # Agent Switching proxypilot --switch # Show agent status proxypilot --switch --mode proxy # Switch to proxy proxypilot --switch --mode native # Switch to native ``` ## Links - [npm package](https://www.npmjs.com/package/proxypilot) - [GitHub Releases](https://github.com/Finesssee/ProxyPilot/releases) - [Source Code](https://github.com/Finesssee/ProxyPilot)