Management

CrabLLM supports dynamic management of providers and API keys at runtime — no restart required. You can use the crabctl CLI or call the admin API directly.

Install

cargo install crabllm crabctl

Both binaries are installed from the same workspace. crabctl talks to a running gateway over HTTP.

Admin token

All management operations require a bearer token. Configure it in your TOML:

admin_token = "${CRABLLM_ADMIN_TOKEN}"

Pass it to crabctl via --token or the CRABCTL_TOKEN environment variable.

Crabctl CLI

Global flags

Key management

crabctl keys list
crabctl keys create my-key --models gpt-4o,claude-sonnet-4-20250514 --rpm 60 --tpm 100000
crabctl keys get my-key
crabctl keys update my-key --rpm 120
crabctl keys delete my-key

Keys created via the API are "dynamic" — they're stored in the configured storage backend and persist across restarts (with SQLite or Redis). Keys defined in TOML cannot be modified or deleted via the API.

Provider management

crabctl providers list
crabctl providers create my-openai \
  --kind openai \
  --api-key "$OPENAI_API_KEY" \
  --models gpt-4o,gpt-4o-mini \
  --weight 2
crabctl providers get my-openai
crabctl providers update my-openai --weight 5
crabctl providers delete my-openai

When you create a provider with --kind openai, --kind ollama, or --kind custom and omit --models, CrabLLM auto-fetches the model list from the provider's /models endpoint.

Dynamic providers are hot-loaded — the routing registry rebuilds immediately. No restart.

Operational queries

crabctl usage                          # all usage
crabctl usage --key my-key             # usage for one key
crabctl usage --model gpt-4o           # usage for one model

crabctl budget                         # budget status per key

crabctl logs                           # recent audit logs
crabctl logs --key my-key --limit 50   # filtered logs
crabctl logs --since 1713200000000     # logs after epoch ms

crabctl cache clear                    # clear response cache

Admin API

All endpoints require Authorization: Bearer {admin_token}.

Keys

Create request body:

{
  "name": "team-a",
  "models": ["gpt-4o", "claude-sonnet-4-20250514"],
  "rate_limit": { "rpm": 60, "tpm": 100000 }
}

The response includes the generated secret key (sk-...). Store it — it's only shown once.

Providers

Create request body:

{
  "name": "openai-backup",
  "kind": "openai",
  "api_key": "sk-...",
  "models": ["gpt-4o"],
  "weight": 1,
  "max_retries": 3,
  "timeout": 30
}

Operational

TOML vs dynamic

Resources defined in TOML take precedence. They appear in list responses (with source: "config") but cannot be updated or deleted via the API. Dynamic resources (created via API or crabctl) have source: "dynamic" and persist in the configured storage backend.

OpenAPI / Scalar docs

CrabLLM serves interactive API documentation out of the box:

• /docs — Scalar UI for browsing and testing all endpoints
• /openapi.json — raw OpenAPI 3.1 spec

Enabled by default. Disable with:

openapi = false

You can also export the spec from the CLI:

crabllm openapi --format json > openapi.json
crabllm openapi --format html > docs.html