### Install CLI Proxy SDK (Go)

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

Installs the CLI Proxy API SDK using the go get command. Ensure you use the correct module path including the version.

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

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

### Minimal CLI Proxy Service Embedding (Go)

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

Demonstrates the minimal setup to embed and run the CLI Proxy service using its Go SDK. It loads configuration, builds the service, and runs it within a context, handling graceful shutdown via context cancellation.

```go
cfg, err := config.LoadConfig("config.yaml")
if err != nil { panic(err) }

svc, err := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml"). // absolute or working-dir relative
    Build()
if err != nil { panic(err) }

ctx, cancel := context.WithCancel(context.Background())
deferr cancel()

if err := svc.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
    panic(err)
}
```

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

### Start Cliproxyapi Server

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Command to start the cliproxyapi server with a specified configuration file.

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

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

### Configure Service Lifecycle Hooks (Go)

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

Shows how to attach lifecycle hooks to the embedded CLI Proxy service, allowing observation and custom actions before starting (`OnBeforeStart`) and after starting (`OnAfterStart`).

```go
hooks := cliproxy.Hooks{
  OnBeforeStart: func(cfg *config.Config) { log.Infof("starting on :%d", cfg.Port) },
  OnAfterStart:  func(s *cliproxy.Service) { log.Info("ready") },
}
svc, _ := cliproxy.NewBuilder().WithConfig(cfg).WithConfigPath("config.yaml").WithHooks(hooks).Build()
```

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

### Implement SDK Lifecycle Hooks in Go

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Shows how to observe service startup and shutdown events using lifecycle hooks. This is useful for logging or performing initialization tasks like registering custom models after the service starts.

```go
package main

import (
    "context"
    "log"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
)

func main() {
    cfg, _ := config.LoadConfig("config.yaml")

    hooks := cliproxy.Hooks{
        OnBeforeStart: func(cfg *config.Config) {
            log.Printf("Starting server on port %d", cfg.Port)
        },
        OnAfterStart: func(s *cliproxy.Service) {
            log.Println("Server is ready to accept requests")
            models := []*cliproxy.ModelInfo{
                {ID: "custom-model-1", Object: "model", Type: "custom", DisplayName: "Custom Model 1"},
            }
            cliproxy.GlobalModelRegistry().RegisterClient("auth-id", "custom", models)
        },
    }

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

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    svc.Run(ctx)
}
```

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

### Provide Custom Client Token Source (Go)

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

Illustrates how to replace the default token client loaders with a custom implementation, such as loading credentials from memory. This is achieved by implementing the `Load` method and providing it via `WithTokenClientProvider`.

```go
type memoryTokenProvider struct{}
func (p *memoryTokenProvider) Load(ctx context.Context, cfg *config.Config) (*cliproxy.TokenClientResult, error) {
    // Populate from memory/remote store and return counts
    return &cliproxy.TokenClientResult{}, nil
}

svc, _ := cliproxy.NewBuilder().
  WithConfig(cfg).
  WithConfigPath("config.yaml").
  WithTokenClientProvider(&memoryTokenProvider{}).
  WithAPIKeyClientProvider(cliproxy.NewAPIKeyClientProvider()).
  Build()
```

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

### Start Cliproxyapi with TUI Interface

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Commands to start the cliproxyapi server with the Text User Interface (TUI) management interface, including a standalone mode with an embedded server.

```bash
# Start with TUI management interface
./cliproxyapi -tui

# TUI with embedded server (standalone mode)
./cliproxyapi -tui -standalone
```

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

### Execute Auth Manager Requests (Go)

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

Demonstrates how to programmatically execute requests using the core authentication manager, both for non-streaming and streaming responses. This is useful when using the manager standalone without the full service.

```go
// Non‑streaming
resp, err := core.Execute(ctx, []string{"gemini"}, req, opts)

// Streaming
chunks, err := core.ExecuteStream(ctx, []string{"gemini"}, req, opts)
for ch := range chunks { /* ... */ }
```

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

### Configuring API Key Providers

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Example YAML configuration for defining API keys used by the built-in provider.

```yaml
api-keys:
  - sk-test-123
  - sk-prod-456
```

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

### Configure CLI Proxy Server Options (Go)

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

Shows how to configure advanced server options for the embedded CLI Proxy service, including global middleware, gin engine customization, custom routes, and request loggers. These options allow fine-tuning the proxy's behavior.

```go
svc, _ := cliproxy.NewBuilder().
  WithConfig(cfg).
  WithConfigPath("config.yaml").
  WithServerOptions(
    // Add global middleware
    cliproxy.WithMiddleware(func(c *gin.Context) { c.Header("X-Embed", "1"); c.Next() }),
    // Tweak gin engine early (CORS, trusted proxies, etc.)
    cliproxy.WithEngineConfigurator(func(e *gin.Engine) { e.ForwardedByClientIP = true }),
    // Add your own routes after defaults
    cliproxy.WithRouterConfigurator(func(e *gin.Engine, _ *handlers.BaseAPIHandler, _ *config.Config) {
      e.GET("/healthz", func(c *gin.Context) { c.String(200, "ok") })
    }),
    // Override request log writer/dir
    cliproxy.WithRequestLoggerFactory(func(cfg *config.Config, cfgPath string) logging.RequestLogger {
      return logging.NewFileRequestLogger(true, "logs", filepath.Dir(cfgPath))
    }),
  ).
  Build()
```

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

### Embed CLIProxyAPI as a Go Library

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Integrate the proxy service into a Go application. This snippet demonstrates the minimal setup required to initialize the service, manage configuration, and handle the server lifecycle.

```go
package main

import (
    "context"
    "errors"
    "time"

    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
)

func main() {
    cfg, err := config.LoadConfig("config.yaml")
    if err != nil {
        panic(err)
    }

    svc, err := cliproxy.NewBuilder().
        WithConfig(cfg).
        WithConfigPath("config.yaml").
        Build()
    if err != nil {
        panic(err)
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    if err := svc.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
        panic(err)
    }
}
```

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

### Implement Custom HTTP Transport for Auth (Go)

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

Provides an example implementation of a custom `http.RoundTripper` for the core authentication manager. This custom transport can be used to configure specific proxy settings for different authentication methods.

```go
type myRTProvider struct{}
func (myRTProvider) RoundTripperFor(a *coreauth.Auth) http.RoundTripper {
    if a == nil || a.ProxyURL == "" { return nil }
    u, _ := url.Parse(a.ProxyURL)
    return &http.Transport{ Proxy: http.ProxyURL(u) }
}
```

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

### Manually Shut Down CLI Proxy Service (Go)

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

Demonstrates how to manually initiate a graceful shutdown of the embedded CLI Proxy service using the `Shutdown` method with a context. This is an alternative to relying solely on parent context cancellation.

```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
deferr cancel()
_ = svc.Shutdown(ctx)
```

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

### Import CLI Proxy SDK Packages (Go)

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

Imports necessary packages from the CLI Proxy API SDK and related internal modules for use in a Go program. Note the specific module path '/v6'.

```go
import (
    "context"
    "errors"
    "time"

    "github.com/router-for-me/CLIProxyAPI/v6/internal/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
)
```

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

### GET /v0/management/usage

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Retrieve usage statistics for the proxy service.

```APIDOC
## GET /v0/management/usage

### Description
Fetches usage statistics across all configured providers.

### Method
GET

### Endpoint
/v0/management/usage

### Response
#### Success Response (200)
- **usage_data** (object) - JSON object containing usage metrics
```

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

### Set Auth Update Queue in WatcherWrapper

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-watcher.md

Shows how to wire the SDK service's auth update queue into the WatcherWrapper. This must be performed before the watcher starts to ensure all events are captured.

```go
func (w *WatcherWrapper) SetAuthUpdateQueue(queue chan<- watcher.AuthUpdate) {
	w.mu.Lock()
	defer w.mu.Unlock()
	w.authUpdateQueue = queue
}
```

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

### Embed Custom Core Auth Manager (Go)

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

Explains how to provide a custom core authentication manager to the embedded CLI Proxy service. This allows customization of transports and hooks for authentication processes, including setting a custom RoundTripperProvider.

```go
core := coreauth.NewManager(coreauth.NewFileStore(cfg.AuthDir), nil, nil)
core.SetRoundTripperProvider(myRTProvider) // per‑auth *http.Transport

svc, _ := cliproxy.NewBuilder().
    WithConfig(cfg).
    WithConfigPath("config.yaml").
    WithCoreAuthManager(core).
    Build()
```

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

### Managing Access Providers

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Demonstrates how to initialize the access manager and populate it with registered providers.

```go
manager := sdkaccess.NewManager()
manager.SetProviders(sdkaccess.RegisteredProviders())
```

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

### Initialize cliproxy Service with Access Manager

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Demonstrates how to instantiate a cliproxy service using the builder pattern, incorporating configuration files and a custom access manager instance.

```go
coreCfg, _ := config.LoadConfig("config.yaml")
accessManager := sdkaccess.NewManager()

svc, _ := cliproxy.NewBuilder().
  WithConfig(coreCfg).
  WithConfigPath("config.yaml").
  WithRequestAccessManager(accessManager).
  Build()
```

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

### Importing the Access SDK

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Shows the standard import path for the CLIProxyAPI access package.

```go
import (
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

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

### Manage Auth Files via Management API

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Endpoints for managing authentication files, including listing, getting models, downloading, uploading, and deleting. Requires a management secret for authorization. Upload uses multipart/form-data.

```bash
# List auth files
curl http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer your-management-secret"

# Get models from auth files
curl http://localhost:8317/v0/management/auth-files/models \
  -H "Authorization: Bearer your-management-secret"

# Download auth file
curl "http://localhost:8317/v0/management/auth-files/download?filename=gemini-cli.json" \
  -H "Authorization: Bearer your-management-secret"

# Upload auth file
curl -X POST http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer your-management-secret" \
  -F "file=@gemini-cli.json"

# Delete auth file
curl -X DELETE http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer your-management-secret" \
  -H "Content-Type: application/json" \
  -d '{"filename": "old-auth.json"}'
```

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

### POST /v1beta/models/*

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Provides Gemini-native API endpoints for direct interaction with Gemini models.

```APIDOC
## POST /v1beta/models/{model}:generateContent

### Description
Direct Gemini API endpoint for generating content.

### Method
POST

### Endpoint
/v1beta/models/{model}:generateContent

### Parameters
#### Path Parameters
- **model** (string) - Required - The Gemini model name.

### Request Body
- **contents** (array) - Required - Input content parts.
- **generationConfig** (object) - Optional - Configuration for generation parameters.

### Response
#### Success Response (200)
- **candidates** (array) - Generated response candidates.
```

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

### Configure Auth Update Queue in Go

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-watcher.md

Demonstrates the implementation of the auth update queue using a buffered channel and a consumer goroutine. This pattern ensures that credential changes are processed efficiently without blocking the main watcher loop.

```go
func (s *Service) ensureAuthUpdateQueue() {
	s.authQueue = make(chan watcher.AuthUpdate, 256)
	go s.consumeAuthUpdates()
}

func (s *Service) consumeAuthUpdates() {
	for update := range s.authQueue {
		s.handleAuthUpdate(update)
	}
}
```

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

### Registering External Providers

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Shows how to import external modules to trigger provider registration via side effects.

```go
import (
    _ "github.com/acme/xplatform/sdk/access/providers/partner"
    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
)
```

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

### Configure Custom Access Control in Go

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Demonstrates how to implement a custom authentication provider by satisfying the access provider interface and registering it with the CLIProxyAPI access manager. This allows for token-based request validation before service execution.

```go
package main

import (
    "context"
    "net/http"

    sdkaccess "github.com/router-for-me/CLIProxyAPI/v6/sdk/access"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
)

type customProvider struct{}

func (p *customProvider) Identifier() string { return "my-provider" }

func (p *customProvider) Authenticate(ctx context.Context, r *http.Request) (*sdkaccess.Result, *sdkaccess.AuthError) {
    token := r.Header.Get("X-Custom-Token")
    if token == "" {
        return nil, sdkaccess.NewNotHandledError()
    }
    if token != "expected-token" {
        return nil, sdkaccess.NewInvalidCredentialError()
    }
    return &sdkaccess.Result{
        Provider:  p.Identifier(),
        Principal: "service-user",
        Metadata:  map[string]string{"source": "x-custom-token"},
    }, nil
}

func init() {
    sdkaccess.RegisterProvider("custom", &customProvider{})
}

func main() {
    cfg, _ := config.LoadConfig("config.yaml")
    accessManager := sdkaccess.NewManager()
    accessManager.SetProviders(sdkaccess.RegisteredProviders())

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

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    svc.Run(ctx)
}
```

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

### Manage API Keys via REST API

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Demonstrates how to list, replace, add, or delete client API keys at runtime using the management API endpoints.

```bash
curl http://localhost:8317/v0/management/api-keys -H "Authorization: Bearer your-management-secret"
curl -X PUT http://localhost:8317/v0/management/api-keys -H "Authorization: Bearer your-management-secret" -H "Content-Type: application/json" -d '["sk-new-key-1", "sk-new-key-2"]'
curl -X PATCH http://localhost:8317/v0/management/api-keys -H "Authorization: Bearer your-management-secret" -H "Content-Type: application/json" -d '{"add": ["sk-new-key-3"]}'
curl -X DELETE http://localhost:8317/v0/management/api-keys -H "Authorization: Bearer your-management-secret" -H "Content-Type: application/json" -d '{"keys": ["sk-old-key"]}'
```

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

### SDK Server Options

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Customize the embedded server with middleware, routes, engine configuration, and request logging.

```APIDOC
## Go SDK - Server Options

### Description
Customize the embedded CLIProxyAPI server with middleware, custom routes, Gin engine configuration, and request logging.

### Method
N/A (This is an SDK usage example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```go
package main

import (
    "context"
    "path/filepath"

    "github.com/gin-gonic/gin"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/api/handlers"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/logging"
)

func main() {
    cfg, _ := config.LoadConfig("config.yaml")

    svc, _ := cliproxy.NewBuilder().
        WithConfig(cfg).
        WithConfigPath("config.yaml").
        WithServerOptions(
            // Add global middleware
            cliproxy.WithMiddleware(func(c *gin.Context) {
                c.Header("X-Embed", "1")
                c.Next()
            }),
            // Configure gin engine (CORS, trusted proxies, etc.)
            cliproxy.WithEngineConfigurator(func(e *gin.Engine) {
                e.ForwardedByClientIP = true
            }),
            // Add custom routes after defaults
            cliproxy.WithRouterConfigurator(func(e *gin.Engine, _ *handlers.BaseAPIHandler, _ *config.Config) {
                e.GET("/healthz", func(c *gin.Context) {
                    c.String(200, "ok")
                })
                e.GET("/ready", func(c *gin.Context) {
                    c.JSON(200, gin.H{"status": "ready"})
                })
            }),
            // Custom request logger factory
            cliproxy.WithRequestLoggerFactory(func(cfg *config.Config, cfgPath string) logging.RequestLogger {
                return logging.NewFileRequestLogger(true, "logs", filepath.Dir(cfgPath))
            }),
        ).
        Build()

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    svc.Run(ctx)
}
```

### Response
N/A (This is a Go program execution)
```

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

### Implementing Custom Providers

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Provides a template for creating a custom authentication provider by implementing the required interface and registering it.

```go
type customProvider struct{}

func (p *customProvider) Identifier() string { return "my-provider" }

func (p *customProvider) Authenticate(ctx context.Context, r *http.Request) (*sdkaccess.Result, *sdkaccess.AuthError) {
    token := r.Header.Get("X-Custom")
    if token == "" {
        return nil, sdkaccess.NewNotHandledError()
    }
    if token != "expected" {
        return nil, sdkaccess.NewInvalidCredentialError()
    }
    return &sdkaccess.Result{
        Provider:  p.Identifier(),
        Principal: "service-user",
        Metadata:  map[string]string{"source": "x-custom"},
    }, nil
}

func init() {
    sdkaccess.RegisterProvider("custom", &customProvider{})
}
```

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

### Import Vertex Service Account with Cliproxyapi CLI

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Command to import a Vertex service account JSON file for authentication.

```bash
# Import Vertex service account
./cliproxyapi -vertex-import /path/to/service-account.json
```

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

### SDK Lifecycle Hooks

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Observe service lifecycle events without patching internals. Hooks provide callbacks for startup and shutdown events.

```APIDOC
## SDK Lifecycle Hooks

Observe service lifecycle events without patching internals. Hooks provide callbacks for startup and shutdown events.

### Lifecycle Hooks Example

This Go code demonstrates how to use lifecycle hooks to perform actions before and after the service starts, and how to register custom models.

```go
package main

import (
    "context"
    "log"

    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
)

func main() {
    cfg, _ := config.LoadConfig("config.yaml")

    hooks := cliproxy.Hooks{
        OnBeforeStart: func(cfg *config.Config) {
            log.Printf("Starting server on port %d", cfg.Port)
        },
        OnAfterStart: func(s *cliproxy.Service) {
            log.Println("Server is ready to accept requests")

            // Register custom models after startup
            models := []*cliproxy.ModelInfo{
                {ID: "custom-model-1", Object: "model", Type: "custom", DisplayName: "Custom Model 1"},
            }
            cliproxy.GlobalModelRegistry().RegisterClient("auth-id", "custom", models)
        },
    }

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

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    svc.Run(ctx)
}
```
```

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

### POST /v0/management/auth-files

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Upload authentication files for OAuth providers.

```APIDOC
## POST /v0/management/auth-files

### Description
Uploads an authentication file to the server.

### Method
POST

### Endpoint
/v0/management/auth-files

### Parameters
#### Request Body
- **file** (binary) - Required - The authentication file to upload (multipart/form-data)

### Response
#### Success Response (200)
- **status** (string) - Confirmation message
```

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

### Customize Embedded Server Options

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Configure the embedded proxy server with custom middleware, Gin engine settings, additional API routes, and custom request logging factories.

```go
package main

import (
    "context"
    "path/filepath"

    "github.com/gin-gonic/gin"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/api/handlers"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/logging"
)

func main() {
    cfg, _ := config.LoadConfig("config.yaml")

    svc, _ := cliproxy.NewBuilder().
        WithConfig(cfg).
        WithConfigPath("config.yaml").
        WithServerOptions(
            cliproxy.WithMiddleware(func(c *gin.Context) {
                c.Header("X-Embed", "1")
                c.Next()
            }),
            cliproxy.WithEngineConfigurator(func(e *gin.Engine) {
                e.ForwardedByClientIP = true
            }),
            cliproxy.WithRouterConfigurator(func(e *gin.Engine, _ *handlers.BaseAPIHandler, _ *config.Config) {
                e.GET("/healthz", func(c *gin.Context) {
                    c.String(200, "ok")
                })
                e.GET("/ready", func(c *gin.Context) {
                    c.JSON(200, gin.H{"status": "ready"})
                })
            }),
            cliproxy.WithRequestLoggerFactory(func(cfg *config.Config, cfgPath string) logging.RequestLogger {
                return logging.NewFileRequestLogger(true, "logs", filepath.Dir(cfgPath))
            }),
        ).
        Build()

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    svc.Run(ctx)
}
```

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

### Authenticating Requests

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Illustrates how to use the manager to authenticate an HTTP request and handle various authentication outcomes.

```go
result, authErr := manager.Authenticate(ctx, req)
switch {
case authErr == nil:
    // Authentication succeeded
case sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeNoCredentials):
    // No credentials supplied
case sdkaccess.IsAuthErrorCode(authErr, sdkaccess.AuthErrorCodeInvalidCredential):
    // Invalid credentials
default:
    // Internal failure
}
```

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

### Management API - API Keys

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Manage API keys for client authentication at runtime.

```APIDOC
## Management API - API Keys

Manage API keys for client authentication at runtime.

### List API Keys

Retrieves a list of all currently active API keys.

*   **Method:** GET
*   **Endpoint:** `/v0/management/api-keys`
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`

### Replace All API Keys

Replaces the entire list of API keys with a new set.

*   **Method:** PUT
*   **Endpoint:** `/v0/management/api-keys`
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** An array of API key strings.
    ```json
    ["sk-new-key-1", "sk-new-key-2"]
    ```

### Add API Keys

Adds new API keys to the existing list.

*   **Method:** PATCH
*   **Endpoint:** `/v0/management/api-keys`
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** An object containing an `add` field with an array of API key strings to add.
    ```json
    {"add": ["sk-new-key-3"]}
    ```

### Delete API Keys

Deletes specific API keys from the list.

*   **Method:** DELETE
*   **Endpoint:** `/v0/management/api-keys`
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** An object containing a `keys` field with an array of API key strings to delete.
    ```json
    {"keys": ["sk-old-key"]}
    ```
```

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

### SDK Embed - Minimal Server

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Embed the proxy as a Go library with minimal configuration. The SDK manages config/auth watching, background token refresh, and graceful shutdown.

```APIDOC
## Go SDK - Minimal Server

### Description
Embed the CLIProxyAPI as a Go library with minimal configuration. The SDK handles configuration and authentication watching, background token refresh, and graceful shutdown.

### Method
N/A (This is an SDK usage example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```go
package main

import (
    "context"
    "errors"
    "time"

    "github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
    "github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
)

func main() {
    cfg, err := config.LoadConfig("config.yaml")
    if err != nil {
        panic(err)
    }

    svc, err := cliproxy.NewBuilder().
        WithConfig(cfg).
        WithConfigPath("config.yaml").
        Build()
    if err != nil {
        panic(err)
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    if err := svc.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
        panic(err)
    }
}
```

### Response
N/A (This is a Go program execution)
```

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

### Build Cliproxyapi Docker Image

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Command to build the Docker image for the cliproxyapi application.

```bash
# Build Docker image
docker build -t cliproxyapi .
```

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

### List Available Models via API

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Retrieve a list of available AI models from configured providers. The response format is dynamically adjusted based on the User-Agent header to support OpenAI, Claude, and Gemini-style clients.

```bash
# OpenAI-style models list
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

# Claude-style models list (auto-detected via User-Agent)
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "User-Agent: claude-cli/2.1.44"

# Gemini-style models list
curl "http://localhost:8317/v1beta/models" \
  -H "X-Goog-Api-Key: sk-your-api-key"
```

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

### Perform OAuth Login with Cliproxyapi CLI

Source: https://context7.com/luispater/cliproxyapi/llms.txt

CLI commands to initiate OAuth login flows for various AI providers like Google/Gemini, Claude, Codex, Qwen, iFlow, Antigravity, and Kimi. Authentication tokens are stored in the configured auth directory.

```bash
# Google/Gemini OAuth login
./cliproxyapi -login -project_id my-project-id

# Claude OAuth login
./cliproxyapi -claude-login

# OpenAI Codex OAuth login
./cliproxyapi -codex-login

# OpenAI Codex device code flow
./cliproxyapi -codex-device-login

# Qwen OAuth login
./cliproxyapi -qwen-login

# iFlow OAuth login
./cliproxyapi -iflow-login

# iFlow cookie-based authentication
./cliproxyapi -iflow-cookie

# Antigravity OAuth login
./cliproxyapi -antigravity-login

# Kimi OAuth login
./cliproxyapi -kimi-login
```

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

### Run Cliproxyapi Docker Container

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Commands to run the cliproxyapi Docker container, with options for default configuration, environment variables, and Docker Compose.

```bash
# Run with default configuration
docker run -d -p 8317:8317 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/auths:/app/auths \
  cliproxyapi

# Run with environment variables
docker run -d -p 8317:8317 \
  -e MANAGEMENT_PASSWORD=your-secret \
  -v $(pwd)/config.yaml:/app/config.yaml \
  cliproxyapi

# Docker Compose
docker-compose up -d

# docker-compose.yml example:
# version: '3.8'
# services:
#   cliproxyapi:
#     build: .

```

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

### Register Request/Response Translators in Go

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Demonstrates how to register custom translators to convert data schemas between different API formats. It includes logic for both request transformation and response handling for streaming and non-streaming scenarios.

```go
package main

import (
	"context"
	"fmt"

	"github.com/router-for-me/CLIProxyAPI/v6/sdk/translator"
	_ "github.com/router-for-me/CLIProxyAPI/v6/sdk/translator/builtin"
)

const (
	fOpenAI = translator.Format("openai.chat")
	fMyProv = translator.Format("myprov.chat")
)

func init() {
	translator.Register(fOpenAI, fMyProv,
		func(model string, raw []byte, stream bool) []byte {
			return raw
		},
		translator.ResponseTransform{
			Stream: func(ctx context.Context, model string, originalReq, translatedReq, raw []byte, param *any) []string {
				return []string{string(raw)}
			},
			NonStream: func(ctx context.Context, model string, originalReq, translatedReq, raw []byte, param *any) string {
				return string(raw)
			},
		},
	)
}

func main() {
	rawRequest := []byte(`{"messages":[{"content":[{"text":"Hello!","type":"text"}],"role":"user"}],"model":"gemini-2.5-pro","stream":false}`)

	translatedRequest := translator.TranslateRequestByFormatName(
		translator.FormatOpenAI,
		translator.FormatGemini,
		"gemini-2.5-pro",
		rawRequest,
		false,
	)
	fmt.Printf("Translated request:\n%s\n", translatedRequest)

	geminiResponse := []byte(`{"candidates":[{"content":{"role":"model","parts":[{"text":"Hello! How can I help?"}]}}]}`)

	openaiResponse := translator.TranslateNonStreamByFormatName(
		context.Background(),
		translator.FormatGemini,
		translator.FormatOpenAI,
		"gemini-2.5-pro",
		rawRequest,
		translatedRequest,
		geminiResponse,
		nil,
	)
	fmt.Printf("Converted response:\n%s\n", openaiResponse)
}
```

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

### List Models API

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Retrieve available models from all configured providers. The response format adapts based on the User-Agent header.

```APIDOC
## GET /v1/models

### Description
Retrieve available models from all configured providers. The response format adapts based on the User-Agent header.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# OpenAI-style models list
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

# Claude-style models list (auto-detected via User-Agent)
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "User-Agent: claude-cli/2.1.44"
```

### Response
#### Success Response (200)
- **object** (string) - Type of the response object, typically "list".
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier for the model.
  - **object** (string) - The type of the object, typically "model".
  - **owned_by** (string) - The provider or entity that owns the model.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {"id": "gemini-2.5-pro", "object": "model", "owned_by": "google"},
    {"id": "claude-sonnet-4-20250514", "object": "model", "owned_by": "anthropic"},
    {"id": "gpt-5-codex", "object": "model", "owned_by": "openai"}
  ]
}
```

## GET /v1beta/models

### Description
Retrieve available models from all configured providers, specifically for Gemini-style requests.

### Method
GET

### Endpoint
/v1beta/models

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl "http://localhost:8317/v1beta/models" \
  -H "X-Goog-Api-Key: sk-your-api-key"
```

### Response
#### Success Response (200)
(Response structure is similar to /v1/models, but tailored for Gemini)

#### Response Example
(Example response would be specific to Gemini model listing)
```

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

### Hot Reloading Access Providers

Source: https://github.com/luispater/cliproxyapi/blob/main/docs/sdk-access.md

Shows how to update the access manager's provider chain at runtime by registering new configurations and refreshing the provider list.

```go
// configaccess is github.com/router-for-me/CLIProxyAPI/v6/internal/access/config_access
configaccess.Register(&newCfg.SDKConfig)
accessManager.SetProviders(sdkaccess.RegisteredProviders())
```

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

### Configure OpenAI-Compatible Providers

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Sets up upstream providers like OpenRouter with support for multiple API keys and model pool mapping. Allows mapping multiple upstream models to a single alias for fallback strategies.

```yaml
openai-compatibility:
  - name: "openrouter"
    prefix: "router"
    base-url: "https://openrouter.ai/api/v1"
    headers:
      X-Custom-Header: "custom-value"
    api-key-entries:
      - api-key: "sk-or-v1-XXXXXXXXXXXXXX"
        proxy-url: "socks5://proxy.example.com:1080"
      - api-key: "sk-or-v1-YYYYYYYYYYYYYY"
    models:
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"
      - name: "qwen3.5-plus"
        alias: "claude-opus-fallback"
      - name: "glm-5"
        alias: "claude-opus-fallback"
      - name: "kimi-k2.5"
        alias: "claude-opus-fallback"
```

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

### Management API - Provider Keys

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Manage provider-specific API keys (Gemini, Claude, Codex) at runtime.

```APIDOC
## Management API - Provider Keys

Manage provider-specific API keys (Gemini, Claude, Codex) at runtime.

*(Note: Specific endpoints and request/response formats for provider keys are not detailed in the provided text. This section serves as a placeholder based on the title.)*

### List Provider Keys

Retrieves a list of provider-specific API keys.

*   **Method:** GET
*   **Endpoint:** `/v0/management/providers/{provider_name}/keys` (Example endpoint)
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`

### Update Provider Keys

Updates or replaces provider-specific API keys.

*   **Method:** PUT
*   **Endpoint:** `/v0/management/providers/{provider_name}/keys` (Example endpoint)
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** (Structure depends on provider)

### Add Provider Keys

Adds new provider-specific API keys.

*   **Method:** PATCH
*   **Endpoint:** `/v0/management/providers/{provider_name}/keys` (Example endpoint)
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** (Structure depends on provider)

### Delete Provider Keys

Deletes specific provider-specific API keys.

*   **Method:** DELETE
*   **Endpoint:** `/v0/management/providers/{provider_name}/keys` (Example endpoint)
*   **Headers:**
    *   `Authorization: Bearer your-management-secret`
    *   `Content-Type: application/json`
*   **Request Body:** (Structure depends on provider)
```

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

### GET/PUT /v0/management/gemini-api-key

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Retrieve or update the Gemini API key configuration.

```APIDOC
## GET /v0/management/gemini-api-key

### Description
Retrieves the currently configured Gemini API keys.

### Method
GET

### Endpoint
/v0/management/gemini-api-key

### Response
#### Success Response (200)
- **api-key** (string) - The API key
- **prefix** (string) - The key prefix/identifier
```

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

### PUT /v0/management/usage-statistics-enabled

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Toggle the collection of usage statistics.

```APIDOC
## PUT /v0/management/usage-statistics-enabled

### Description
Enables or disables the collection of usage statistics.

### Method
PUT

### Endpoint
/v0/management/usage-statistics-enabled

### Parameters
#### Request Body
- **enabled** (boolean) - Required - Set to true to enable, false to disable

### Response
#### Success Response (200)
- **status** (string) - Updated status
```

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

### Function Calling / Tools API

Source: https://context7.com/luispater/cliproxyapi/llms.txt

The proxy supports function calling with automatic translation between OpenAI and provider-native formats.

```APIDOC
## POST /v1/chat/completions

### Description
Enables function calling with automatic translation between OpenAI and provider-native formats.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The model to use for the chat completion.
- **messages** (array) - Required - The conversation history.
  - **role** (string) - Required - The role of the message sender (e.g., "user", "assistant").
  - **content** (string) - Required - The content of the message.
- **tools** (array) - Optional - A list of tools the model may call.
  - **type** (string) - Required - The type of tool, e.g., "function".
  - **function** (object) - Required - The function definition.
    - **name** (string) - Required - The name of the function.
    - **description** (string) - Optional - A description of the function.
    - **parameters** (object) - Required - The parameters the function accepts.
      - **type** (string) - Required - The type of the parameters, typically "object".
      - **properties** (object) - Optional - Definitions of the parameters.
      - **required** (array) - Optional - List of required parameter names.
- **tool_choice** (string) - Optional - Controls how the model selects a tool, e.g., "auto".

### Request Example
```bash
curl -X POST http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{ "model": "gemini-2.5-pro", "messages": [ {"role": "user", "content": "What is the weather in Tokyo?"} ], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "Get the current weather in a location", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location"] } } }], "tool_choice": "auto" }'
```

### Response
#### Success Response (200)
- **choices** (array) - A list of completion choices.
  - **message** (object) - The message from the assistant.
    - **role** (string) - The role of the assistant, typically "assistant".
    - **tool_calls** (array) - A list of tool calls made by the assistant.
      - **id** (string) - The ID of the tool call.
      - **type** (string) - The type of tool call, typically "function".
      - **function** (object) - The details of the function call.
        - **name** (string) - The name of the function to call.
        - **arguments** (string) - The arguments for the function call, as a JSON string.

#### Response Example
```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "tool_calls": [{
        "id": "call_xxx",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\": \"Tokyo\", \"unit\": \"celsius\"}"
        }
      }]
    }
  }]
}
```
```

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

### Perform Gemini Native API Request

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Sends requests to the Gemini-native /v1beta/models/* endpoints. Supports both standard content generation and streaming via SSE.

```bash
# Generate Content
curl -X POST "http://localhost:8317/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: sk-your-api-key" \
  -d '{
    "contents": [{"parts": [{"text": "Explain machine learning briefly."}]}],
    "generationConfig": {"temperature": 0.7, "maxOutputTokens": 1024}
  }'

# Stream Generate Content
curl -X POST "http://localhost:8317/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: sk-your-api-key" \
  -d '{
    "contents": [{"parts": [{"text": "Write a short story about robots."}]}]
  }'
```

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

### POST /v1/chat/completions

Source: https://context7.com/luispater/cliproxyapi/llms.txt

Provides an OpenAI-compatible chat completions endpoint that routes requests to configured upstream providers.

```APIDOC
## POST /v1/chat/completions

### Description
Translates and routes OpenAI-compatible chat completion requests to configured upstream LLM providers.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The model ID to use.
- **messages** (array) - Required - A list of message objects with 'role' and 'content'.
- **stream** (boolean) - Optional - If true, enables server-sent events for streaming responses.
- **temperature** (number) - Optional - Sampling temperature.
- **max_tokens** (integer) - Optional - Maximum tokens to generate.

### Request Example
{
  "model": "gemini-2.5-pro",
  "messages": [{"role": "user", "content": "Explain quantum computing."}]
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **choices** (array) - List of completion choices.
- **usage** (object) - Token usage statistics.

#### Response Example
{
  "id": "chatcmpl-xxxxx",
  "object": "chat.completion",
  "choices": [{"message": {"role": "assistant", "content": "..."}}]
}
```