> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.
# CLIProxy Control API
> REST API endpoints for managing CLIProxyAPI service, models, and configurations
# 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](http://localhost:3000)). No authentication required.
## Service Control
### GET /api/cliproxy/proxy-status
Get detailed proxy process status including PID, port, and session count.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/proxy-status
```
```json Response (Running) theme={null}
{
"running": true,
"port": 8317,
"pid": 12345,
"sessionCount": 3,
"startedAt": 1704460000000
}
```
```json Response (Not Running) theme={null}
{
"running": false
}
```
**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.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/cliproxy/proxy-start
```
```json Response (Started) theme={null}
{
"started": true,
"alreadyRunning": false,
"port": 8317
}
```
```json Response (Already Running) theme={null}
{
"started": false,
"alreadyRunning": true,
"port": 8317
}
```
***
### POST /api/cliproxy/proxy-stop
Stop the CLIProxy service.
```bash Request theme={null}
curl -X POST http://localhost:3000/api/cliproxy/proxy-stop
```
```json Response theme={null}
{
"stopped": true,
"pid": 12345,
"sessionCount": 3
}
```
***
### GET /api/cliproxy/update-check
Check for CLIProxyAPI binary updates.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/update-check
```
```json Response (Update Available) theme={null}
{
"hasUpdate": true,
"currentVersion": "1.5.0",
"latestVersion": "1.6.0",
"fromCache": false
}
```
```json Response (Up to Date) theme={null}
{
"hasUpdate": false,
"currentVersion": "1.6.0",
"latestVersion": "1.6.0",
"fromCache": true
}
```
## 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.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/models
```
```json Response theme={null}
{
"models": [
{
"id": "claude-sonnet-4",
"object": "model",
"created": 1704460000,
"owned_by": "anthropic"
},
{
"id": "gemini-3-flash-preview",
"object": "model",
"created": 1704460000,
"owned_by": "google"
}
],
"byCategory": {
"anthropic": [...],
"google": [...]
},
"totalCount": 42
}
```
```json Error (Service Down) theme={null}
{
"error": "CLIProxy Plus not running",
"message": "Start a CLIProxy session (gemini, codex, agy) to fetch available models"
}
```
## Error Logs
### GET /api/cliproxy/error-logs
List error log files with metadata extraction (status code, model).
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/error-logs
```
```json Response theme={null}
{
"files": [
{
"name": "error-2026-01-05T14-30-00.log",
"size": 4096,
"mtime": 1704467400000,
"absolutePath": "/home/user/.ccs/cliproxy/logs/error-2026-01-05T14-30-00.log",
"statusCode": 429,
"model": "gemini-3-flash-preview"
}
]
}
```
**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.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/error-logs/error-2026-01-05T14-30-00.log
```
```text Response theme={null}
=== Request ===
POST /v1/messages HTTP/1.1
Content-Type: application/json
{"model":"gemini-3-flash-preview","messages":[...]}
=== Response ===
Status: 429
{"error":{"type":"rate_limit_error","message":"Rate limit exceeded"}}
```
## Configuration
### GET /api/cliproxy/config.yaml
Get CLIProxy YAML configuration content.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/config.yaml
```
```yaml Response theme={null}
server:
port: 8317
host: 127.0.0.1
auth:
api_key: "your-api-key"
management_secret: "your-secret"
providers:
gemini:
enabled: true
oauth_port: 8318
codex:
enabled: true
oauth_port: 8319
```
***
### PUT /api/cliproxy/config.yaml
Save CLIProxy YAML configuration with atomic write (temp file + rename).
```bash Request theme={null}
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"}'
```
```json Response theme={null}
{
"success": true,
"path": "/home/user/.ccs/cliproxy/config.yaml"
}
```
## Auth Files
### GET /api/cliproxy/auth-files
List auth files in `~/.ccs/cliproxy/auth/` directory.
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/auth-files
```
```json Response theme={null}
{
"files": [
{
"name": "user@gmail.com-project123.json",
"size": 2048,
"mtime": 1704467400000
},
{
"name": "codex-user@email.com.json",
"size": 1536,
"mtime": 1704467300000
}
],
"directory": "/home/user/.ccs/cliproxy/auth"
}
```
***
### 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`)
```bash Request theme={null}
curl "http://localhost:3000/api/cliproxy/auth-files/download?name=user@gmail.com-project123.json" \
-o auth-file.json
```
```json Response theme={null}
{
"access_token": "ya29...",
"refresh_token": "1//...",
"scope": "https://www.googleapis.com/auth/cloud-platform",
"token_type": "Bearer",
"expiry_date": 1704471000000
}
```
## Provider Quota
### GET /api/cliproxy/quota/:provider/:accountId
Get quota information for a specific provider account.
**Path Parameters:**
* `provider`: Provider name (agy, gemini, codex, iflow, kiro, ghcp)
* `accountId`: Account identifier
```bash Request theme={null}
curl http://localhost:3000/api/cliproxy/quota/gemini/user@gmail.com-project123
```
```json Response theme={null}
{
"provider": "gemini",
"accountId": "user@gmail.com-project123",
"quotas": [
{
"model": "gemini-3-flash-preview",
"limit": 1000000,
"used": 450000,
"remaining": 550000,
"resetAt": 1704510000000
},
{
"model": "gemini-3-pro-preview",
"limit": 500000,
"used": 200000,
"remaining": 300000,
"resetAt": 1704510000000
}
]
}
```
```json Error (Invalid Provider) theme={null}
{
"error": "Invalid provider",
"message": "Provider must be one of: agy, gemini, codex, iflow, kiro, ghcp"
}
```
## Error Responses
```json 400 Bad Request theme={null}
{
"error": "Missing required field: content"
}
```
```json 404 Not Found theme={null}
{
"error": "Config file not found"
}
```
```json 500 Server Error theme={null}
{
"error": "Failed to write config file",
"message": "Detailed error message"
}
```
```json 503 Service Unavailable theme={null}
{
"error": "CLIProxy Plus not running",
"message": "Start a CLIProxy session to access this endpoint"
}
```
## 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