Skip to main content

​
CLIProxy Control API

Control the CLIProxyAPI service lifecycle, manage OAuth accounts, and access provider-specific features. CLIProxy enables OAuth authentication for Gemini, Codex, Antigravity, and other AI providers.

​
Overview

CLIProxy endpoints provide:
  • Service start/stop control
  • Proxy health status monitoring
  • Model listing and configuration
  • Error log access
  • Config file management
  • Auth file downloads
  • Provider quota queries

​
Authentication

All endpoints are available on localhost only (http://localhost:3000). No authentication required.

​
Service Control

​
GET /api/cliproxy/proxy-status

Get detailed proxy process status including PID, port, and session count. 
curl http://localhost:3000/api/cliproxy/proxy-status
Response Fields:
  • running: Service status (boolean)
  • port: Local proxy port (default: 8317)
  • pid: Process ID
  • sessionCount: Active CLIProxy sessions
  • startedAt: Timestamp when service started

​
POST /api/cliproxy/proxy-start

Start the CLIProxy service in background. 
curl -X POST http://localhost:3000/api/cliproxy/proxy-start

​
POST /api/cliproxy/proxy-stop

Stop the CLIProxy service. 
curl -X POST http://localhost:3000/api/cliproxy/proxy-stop

​
GET /api/cliproxy/update-check

Check for CLIProxyAPI binary updates. 
curl http://localhost:3000/api/cliproxy/update-check

​
Model Management

​
GET /api/cliproxy/models

Get available models from CLIProxyAPI /v1/models endpoint.
Requires CLIProxy service to be running. Returns 503 if service is down.
curl http://localhost:3000/api/cliproxy/models

​
Error Logs

​
GET /api/cliproxy/error-logs

List error log files with metadata extraction (status code, model). 
curl http://localhost:3000/api/cliproxy/error-logs
Metadata Fields:
  • statusCode: Extracted from response section (e.g., 429, 500)
  • model: Extracted from request body (e.g., “gemini-3-flash-preview”)

​
GET /api/cliproxy/error-logs/:name

Get full content of a specific error log. Path Parameters:
  • name: Error log filename (e.g., error-2026-01-05T14-30-00.log)
Filename must match pattern error-*.log and cannot contain path traversal characters.
curl http://localhost:3000/api/cliproxy/error-logs/error-2026-01-05T14-30-00.log

​
Configuration

​
GET /api/cliproxy/config.yaml

Get CLIProxy YAML configuration content. 
curl http://localhost:3000/api/cliproxy/config.yaml

​
PUT /api/cliproxy/config.yaml

Save CLIProxy YAML configuration with atomic write (temp file + rename). 
curl -X PUT http://localhost:3000/api/cliproxy/config.yaml \
  -H "Content-Type: application/json" \
  -d '{"content":"server:\n  port: 8317\n  host: 127.0.0.1"}'

​
Auth Files

​
GET /api/cliproxy/auth-files

List auth files in ~/.ccs/cliproxy/auth/ directory. 
curl http://localhost:3000/api/cliproxy/auth-files

​
GET /api/cliproxy/auth-files/download

Download auth file content as octet-stream. Query Parameters:
  • name: Auth filename (e.g., user@gmail.com-project123.json)
curl "http://localhost:3000/api/cliproxy/auth-files/download?name=user@gmail.com-project123.json" \
  -o auth-file.json

​
Provider Quota

​
GET /api/cliproxy/quota/:provider/:accountId

Get quota information for a specific provider account. Path Parameters:
  • provider: Provider name (agy, gemini, codex, qwen, iflow, kiro, ghcp)
  • accountId: Account identifier
curl http://localhost:3000/api/cliproxy/quota/gemini/user@gmail.com-project123

​
Error Responses

{
  "error": "Missing required field: content"
}

​
Security Notes

  • Path Traversal Protection: All file operations validate filenames to prevent ../ attacks
  • Atomic Writes: Config updates use temp file + rename for crash safety
  • Localhost Only: API only accessible on 127.0.0.1
  • No External Access: CLIProxy management API requires local network access