### Setup Directories and Config

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/guides/quick-start/ARM64_DOCKER_PROVIDER_QUICKSTART.html

Creates necessary directories for authentication and logs, and copies the example configuration file.

```bash
mkdir -p auths logs
cp config.example.yaml config.yaml
```

--------------------------------

### Install the SDK

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/features/architecture/USER.md

Use 'go get' to install the cliproxy SDK for embedding.

```bash
go get github.com/KooshaPari/cliproxyapi-plusplus/sdk/cliproxy
```

--------------------------------

### Install CLI Proxy SDK

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms-full.txt

Install the SDK using go get. Note the /v6 module path.

```bash
go get github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy
```

--------------------------------

### Develop Documentation Locally

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/README.md

Navigate to the docs directory, install dependencies using npm, and start the development server or build the documentation.

```bash
cd docs
npm install
npm run docs:dev
npm run docs:build
```

--------------------------------

### Install cliproxy SDK

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/sdk-usage.md

Install the cliproxy SDK using go get. Note the /v6 module path.

```bash
go get github.com/kooshapari/cliproxyapi-plusplus/v6/sdk/cliproxy
```

--------------------------------

### Install phenotype-go-auth

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/third_party/phenotype-go-auth/README.md

Install the shared Go module using go get.

```bash
go get github.com/KooshaPari/phenotype-go-auth
```

--------------------------------

### Setup and Deploy cliproxyapi++ with Docker Compose

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms.txt

Use this command to set up the configuration, create the Docker Compose file, and start cliproxyapi++ in detached mode. Ensure Docker and Docker Compose are installed.

```bash
mkdir -p ~/cliproxy && cd ~/cliproxy
curl -o config.yaml https://raw.githubusercontent.com/KooshaPari/cliproxyapi-plusplus/main/config.example.yaml
cat > docker-compose.yml << 'EOF'
services:
cliproxy:
image: KooshaPari/cliproxyapi-plusplus:latest
container_name: cliproxyapi++
ports: ["8317:8317"]
volumes:
- ./config.yaml:/CLIProxyAPI/config.yaml
- ./auths:/root/.cli-proxy-api
- ./logs:/CLIProxyAPI/logs
restart: unless-stopped
EOF
docker compose up -d
```

--------------------------------

### Build All Plugin Examples

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/examples/plugin/README.md

Builds all plugin examples located in the 'examples/plugin' directory. Artifacts are generated in 'examples/plugin/bin'.

```bash
make -C examples/plugin list
make -C examples/plugin build
```

--------------------------------

### Environment Variable Setup Example

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/CLAUDE.md

Illustrates how to set environment variables for API keys, database URLs, and JWT secrets. These variables are crucial for configuring applications securely.

```bash
# Use environment variables
export API_KEY="your-key"
export DATABASE_URL="postgresql://..."
export JWT_SECRET="your-secret"
```

--------------------------------

### Gemini 3 Flash Quickstart with includeThoughts

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/provider-quickstarts.md

Example request to Gemini 3 Flash enabling high reasoning effort and disabling streaming for detailed thought process inclusion.

```bash
curl -sS -X POST http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer demo-client-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gemini/flash",
    "messages":[{"role":"user","content":"ping"}],
    "reasoning_effort":"high",
    "stream":false
  }' | jq
```

--------------------------------

### List Auth Files URL Example

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/examples/plugin/host-callback-auth-files/README.md

Example URL to list all available authentication files managed by the host.

```text
http://localhost:8080/v0/resource/plugins/host-callback-auth-files/status?op=list
```

--------------------------------

### Start Service with Binary

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms-full.txt

Command to start the CliproxyAPI++ service using the downloaded binary, specifying the configuration file path.

```bash
./cliproxyapi++ --config config.yaml
```

--------------------------------

### Search for Codex load-balancing quickstart in provider-quickstarts.md

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/planning/reports/issue-wave-cpb-0176-0245-lane-7.md

Use ripgrep to search for specific phrases related to Codex Responses load-balancing quickstart within the provider quickstart documentation. This helps verify documentation updates.

```bash
rg -n "Codex Responses load-balancing quickstart|Question: Does load balancing work with 2 Codex accounts" docs/provider-quickstarts.md
```

--------------------------------

### Quick Start: Initialize and Use Auth Module

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/third_party/phenotype-go-auth/README.md

Demonstrates initializing token storage, generating PKCE codes, starting an OAuth callback server, and waiting for a callback. Ensure necessary imports are included.

```go
import "github.com/KooshaPari/phenotype-go-auth"

// Create token storage
storage := auth.NewBaseTokenStorage("/path/to/token.json")

// Load from file
if err := storage.Load(); err != nil {
    log.Fatal(err)
}

// Generate PKCE codes for OAuth
codes, err := auth.GeneratePKCECodes()
if err != nil {
    log.Fatal(err)
}

// Start OAuth callback server
server := auth.NewOAuthServer(8080)
if err := server.Start(); err != nil {
    log.Fatal(err)
}

// Wait for callback
result, err := server.WaitForCallback(5 * time.Minute)
```

--------------------------------

### Build All Plugin Examples

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/examples/plugin/simple/README.md

Use this command to build all plugin examples, including the three 'simple' variants (Go, C, Rust). Artifacts are placed in `examples/plugin/bin`.

```bash
make -C examples/plugin build
```

--------------------------------

### Initialize and Run Go SDK

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms-full.txt

Demonstrates how to initialize the Go SDK with configuration and run the service. Ensure the configuration is properly set up before building the service instance.

```go
import "github.com/KooshaPari/cliproxyapi-plusplus/sdk/cliproxy"

svc, err := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml").
    Build()

ctx := context.Background()
svc.Run(ctx)
```

--------------------------------

### Environment Setup and CLI Usage

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/CLAUDE.md

Demonstrates the essential steps for setting up the development environment and using the project's CLI for various operations.

```bash
# Environment setup (always first)
source .venv/bin/activate

# ✅ REQUIRED: Use project CLI for all operations
python cli.py test run --scope unit              # Run unit tests
python cli.py test run --scope integration       # Run integration tests
python cli.py test run --coverage                # Run with coverage
python cli.py lint check                         # Check code quality
python cli.py lint fix                           # Auto-fix linting issues
python cli.py format                             # Format code (black + ruff)
python cli.py db migrate                         # Run database migrations
python cli.py server start                       # Start MCP server
python cli.py tools list                         # List available MCP tools

# ❌ AVOID: Direct tool invocation (only for debugging CLI itself)
uv run pytest -q                                 # Don't use directly
uv run ruff check                                # Don't use directly
uv run black .                                   # Don't use directly
```

--------------------------------

### Prepare Working Directory

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/getting-started.md

Sets up the necessary directory structure and downloads the example configuration file. Ensure the 'auths' directory has restricted permissions.

```bash
mkdir -p ~/cliproxy && cd ~/cliproxy
curl -fsSL -o config.yaml \
  https://raw.githubusercontent.com/kooshapari/cliproxyapi-plusplus/main/config.example.yaml
mkdir -p auths logs
chmod 700 auths
```

--------------------------------

### Install and Manage Windows Service

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/install.html

Use these PowerShell commands to install, start, and check the status of the cliproxyapi-plusplus service on Windows. Ensure you run these commands as an administrator.

```powershell
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action install -BinaryPath "C:\Program Files\cliproxyapi-plusplus\cliproxyapi++.exe" -ConfigPath "C:\ProgramData\cliproxyapi-plusplus\config.yaml"
```

```powershell
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action start
```

```powershell
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action status
```

--------------------------------

### Install Go SDK Package

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Get the cliproxyapi-plusplus Go SDK package using the go get command. This is the first step to embedding the proxy functionality within your Go applications.

```bash
go get github.com/kooshapari/cliproxyapi-plusplus/sdk/cliproxy
```

--------------------------------

### Install and Run macOS Service with launchd

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Use these commands to install the cliproxyapi-plusplus service on macOS using Homebrew and launchd. Ensure the plist file is correctly placed and then bootstrap and start the service.

```bash
mkdir -p ~/Library/LaunchAgents
cp examples/launchd/com.router-for-me.cliproxyapi-plusplus.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.router-for-me.cliproxyapi-plusplus.plist
launchctl kickstart -k gui/$(id -u)/com.router-for-me.cliproxyapi-plusplus
```

--------------------------------

### Build and Run from Source

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Clone the repository, build the binary using Go, and run it with a configuration file. Ensure you have Go installed.

```bash
git clone https://github.com/kooshapari/cliproxyapi-plusplus.git
cd cliproxyapi-plusplus
go build ./cmd/cliproxyapi
./cliproxyapi --config ./config.example.yaml
```

--------------------------------

### Setup and Management Checks

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/provider-quickstarts.md

Demonstrates how to set up the cliproxyctl, perform manual callbacks, and check Hugging Face provider status in management logs and usage.

```bash
cliproxyctl setup --help | rg -n "cursor|antigravity|manual|callback"
```

```bash
cliproxyctl login --provider openai --manual-callback
```

```bash
curl -sS http://localhost:8317/v0/management/logs -H "X-Management-Secret: ${MANAGEMENT_SECRET}" | jq '.entries[]? | select((.provider // "")=="huggingface" or (.message // "" | test("huggingface"; "i")))'
```

```bash
curl -sS http://localhost:8317/v0/management/usage -H "X-Management-Secret: ${MANAGEMENT_SECRET}" | jq '.providers.huggingface // .'
```

--------------------------------

### Install and Manage Windows Service with PowerShell

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Use this PowerShell script to install, start, and check the status of the cliproxyapi-plusplus service on Windows. Run PowerShell as Administrator and provide the correct binary and config paths.

```powershell
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action install -BinaryPath "C:\Program Files\cliproxyapi-plusplus\cliproxyapi-plusplus.exe" -ConfigPath "C:\ProgramData\cliproxyapi-plusplus\config.yaml"
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action start
.\examples\windows\cliproxyapi-plusplus-service.ps1 -Action status
```

--------------------------------

### Run Docker Compose

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms-full.txt

Starts the cliproxyapi++ service using Docker Compose in detached mode. Ensure Docker Compose is installed and configured.

```yaml
docker:run:
    desc: "Run proxy via Docker"
    cmds:
      - docker compose up -d
```

--------------------------------

### Build and Verify Plugin Examples

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/examples/plugin/simple/README.md

Run these commands to build, list, and clean the plugin examples. The `find` command counts the number of executable files in the bin directory.

```bash
make -C examples/plugin list
make -C examples/plugin build
find examples/plugin/bin -maxdepth 1 -type f | wc -l
make -C examples/plugin clean
```

--------------------------------

### Query All Security Events

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/llms.txt

Example PromQL query to get the total number of security events recorded. Provides an overview of security-related activities.

```prometheus
# Get all security events
sum(cliproxy_security_events_total)
```

--------------------------------

### Gemini Chat Completions Quickstart

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/provider-quickstarts.html

Validate the Gemini chat completions endpoint by sending a POST request. This example demonstrates basic usage and expected response.

```APIDOC
## POST /v1/chat/completions (Gemini)

### Description
Validates the Gemini chat completions endpoint by sending a POST request with a user message.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be application/json.

### Request Body
- **model** (string) - Required - The Gemini model alias (e.g., "gemini/flash").
- **messages** (array) - Required - An array of message objects, each with a role and content.
  - **role** (string) - The role of the message sender (e.g., "user").
  - **content** (string) - The message content.

### Request Example
```json
{
  "model": "gemini/flash",
  "messages": [
    {
      "role": "user",
      "content": "ping"
    }
  ]
}
```

### Response
#### Success Response (200)
- The response will be a JSON object containing the chat completion details.

#### Response Example
```json
{
  "id": "...",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gemini/flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "model",
        "content": "pong"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "candidates_tokens": 5,
    "total_tokens": 15
  }
}
```
```

--------------------------------

### Make Binary Executable and Run

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/install.html

After downloading the standalone binary, make it executable and run it with a configuration file.

```bash
chmod +x cliproxyapi++
./cliproxyapi++ --config ./config.yaml
```

--------------------------------

### Gemini 3 Aspect Ratio Quickstart

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/provider-quickstarts.md

Proves the config is sane and the ratio is passed through the translator for Gemini 3 image generation.

```bash
curl -sS -X POST http://localhost:8317/v1/images/generate \
  -H "Authorization: Bearer demo-client-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gemini/flash",
    "prompt":"Futuristic rooftop skyline at sunset",
    "imageConfig":{
      "aspect_ratio":"16:9",
      "width":1024,
      "height":576
    }
  }' | jq
```

--------------------------------

### Basic FastMCP Server Setup

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/CLAUDE.md

Initialize a FastMCP server with a name, version, and description. Define tools, resources, and prompts that the server will expose.

```python
from fastmcp import FastMCP

mcp = FastMCP(
    name="my-mcp-server",
    version="1.0.0",
    description="My MCP Server"
)

@mcp.tool
async def my_tool(param: str) -> dict:
    """Tool description."""
    return {"result": param}

@mcp.resource("resource://{id}")
async def get_resource(id: str) -> str:
    """Get resource by ID."""
    return f"Resource {id}"

@mcp.prompt
async def my_prompt(context: str) -> str:
    """Generate a prompt."""
    return f"Context: {context}"
```

--------------------------------

### Install Linux Systemd Service

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Copy and adjust systemd service and environment files, create necessary directories, set ownership, and reload the systemd daemon to enable and start the service.

```bash
sudo cp examples/systemd/cliproxyapi-plusplus.service /etc/systemd/system/cliproxyapi-plusplus.service
sudo cp examples/systemd/cliproxyapi-plusplus.env /etc/default/cliproxyapi
sudo mkdir -p /var/lib/cliproxyapi /etc/cliproxyapi
sudo touch /etc/cliproxyapi/config.yaml  # replace with your real config
sudo useradd --system --no-create-home --shell /usr/sbin/nologin cliproxyapi || true
sudo chown -R cliproxyapi:cliproxyapi /var/lib/cliproxyapi /etc/cliproxyapi
sudo systemctl daemon-reload
sudo systemctl enable --now cliproxyapi-plusplus
```

--------------------------------

### Embeddings Quickstart (OpenAI-compatible)

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/provider-quickstarts.md

Validate the /v1/embeddings endpoint for embedding-enabled providers. This example sends a POST request with a model alias and input text, then checks the response structure and data count.

```bash
curl -sS -X POST http://localhost:8317/v1/embeddings \
  -H "Authorization: Bearer demo-client-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"embedding probe"}' | jq '{object,model,data_count:(.data|length)}'
```

--------------------------------

### Register a New Provider

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/features/providers/SPEC.md

Example of how to register a newly defined provider with the system's registry during initialization.

```go
func init() {
    registry.Register(NewMyProvider(&ProviderConfig{
        Name:    "myprovider",
        Type:    "direct",
        Enabled: false,
    }))
}
```

--------------------------------

### Search Documentation Files

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/planning/reports/issue-wave-cpb-0176-0245-lane-4.md

Use ripgrep to search for specific keywords or phrases within documentation files. This command is useful for finding relevant sections in provider quickstarts and troubleshooting guides.

```bash
rg -n "Opus 4.6 quickstart sanity check|claude-opus-4-6|streaming parity check" docs/provider-quickstarts.md docs/troubleshooting.md
```

--------------------------------

### Cross-Platform Service Management Script

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/install.md

Use this script for cross-platform service management operations like install, start, stop, status, restart, and remove. On Linux, it writes to systemd and requires root.

```bash
./scripts/service install
./scripts/service start
./scripts/service status
./scripts/service restart
./scripts/service stop
./scripts/service remove
```

--------------------------------

### Add Provider Configuration Example

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/USER_JOURNEYS.md

Provides an example of how to configure the newly added provider in a YAML configuration file. This shows the expected structure for API key settings.

```yaml
config.example.yaml: providers.myprovider.api_key
```

--------------------------------

### Search for iFlow OAuth documentation

Source: https://github.com/kooshapari/cliproxyapi-plusplus/blob/main/docs/planning/reports/issue-wave-cpb-0176-0245-lane-1.md

Use ripgrep to search for specific terms related to iFlow OAuth, non-CLI subsets, and '^iflow' across documentation files. This helps verify the implementation of quickstart and troubleshooting guides.

```bash
rg -n "iFlow OAuth|non-CLI subset|\^iflow/" docs/provider-quickstarts.md docs/troubleshooting.md docs/provider-operations.md
```