Skip to content

Gateway CLI

Use provon gateway to manage AI Gateway provider keys, model bindings, routing, guardrails, and observability settings. Runtime inference calls (/v1/chat/completions, /v1/responses, /v1/messages) use gateway:invoke; the management commands on this page require gateway:manage.

View as Markdown Open the plain-text version of this page.
Client request Provon Gateway Model policies / auto-router Provider key + model binding Upstream provider API Guardrails: off / monitor / enforce

Prerequisites#

  • Selected project and authenticated credential.
  • Management operations with a credential holding gateway:manage.
  • For providers test, the upstream endpoint reachable from the CLI machine or server runtime.

Status#

Show the Gateway capability matrix and configured providers:

bash
provon gateway status

Providers#

List And Inspect#

bash
provon gateway providers list
provon gateway providers list --provider openai --include-disabled
provon gateway providers get <key-id> --include-disabled

Create A Built-in Provider Key#

bash
provon gateway providers create \
  --provider openai \
  --display-name "OpenAI production" \
  --api-key "$OPENAI_API_KEY" \
  --priority 1

Optional flags: --base-url, --enabled, --priority <n>, --timeout-ms <n>.

Create A Custom Provider#

Add --custom with a project-defined provider id and either an exact endpoint URL or a base URL:

bash
provon gateway providers create \
  --custom \
  --provider internal-kimi \
  --display-name "Internal Kimi" \
  --driver openai-compatible \
  --endpoint-url "https://models.example/custom/chat" \
  --responses-mode bridge-chat-completions \
  --api-key "$KIMI_API_KEY"
  • --endpoint-url is used as-is; --base-url appends the driver's default Chat Completions path.
  • --driver defaults to openai-compatible.
  • --responses-mode accepts disabled (default), native, or bridge-chat-completions. Exact-URL native mode additionally requires --responses-endpoint-url.

Test a candidate connection before saving:

bash
provon gateway providers test \
  --provider internal-kimi \
  --endpoint-url "https://models.example/custom/chat" \
  --model kimi-2.7-code \
  --api-key "$KIMI_API_KEY"

test requires --provider, --endpoint-url, and --model; use --auth-header <name> to send the key in a custom header, or --no-auth for an unauthenticated endpoint.

Update, Enable, Disable, Reorder, Delete#

bash
provon gateway providers update <key-id> --display-name "New name"
provon gateway providers update <key-id> --api-key "$NEW_KEY"
provon gateway providers update <key-id> --enabled
provon gateway providers update <key-id> --disabled
provon gateway providers set-enabled <key-id> true
provon gateway providers set-enabled <key-id> false
provon gateway providers reorder <key-id-1> <key-id-2> <key-id-3>
provon gateway providers delete <key-id>

update requires at least one field; empty input fails with gateway.empty_update.

Model Bindings#

Bind a Gateway model to an upstream model on a provider key:

bash
provon gateway providers bind-model <key-id> \
  --gateway-model-id gpt-4o \
  --upstream-model-id gpt-4o-2024-08-06 \
  --endpoints chat-completions,embeddings \
  --features streaming,tool-calling

Endpoint tokens include chat-completions, responses, messages, embeddings, rerank, and media endpoints; feature tokens include streaming, tool-calling, parallel-tool-calls, json-mode, structured-outputs, reasoning, vision-input, prompt-caching, and more.

Remove a binding:

bash
provon gateway providers unbind-model <key-id> <binding-id>

Model Selection Manifest#

bash
provon gateway model-selection
provon gateway model-selection --endpoint chat-completions --features streaming

Routing#

bash
provon gateway routing get
provon gateway routing model-policies '{"rules":[]}'
provon gateway routing model-policies --file ./model-policies.json
provon gateway routing auto-router '{"enabled":true}'
provon gateway routing auto-router --file ./auto-router.json

Each JSON command accepts inline JSON or --file, not both (gateway.conflicting_input).

Guardrails#

bash
provon gateway guardrails get
provon gateway guardrails set-mode monitor
provon gateway guardrails update '{"mode":"enforce","rules":[]}'
provon gateway guardrails update --file ./guardrails.json

Modes: off, monitor, enforce. set-mode writes the mode with an empty rule set; use update when you need to preserve existing rules.

Observability#

bash
provon gateway observability get
provon gateway observability update '{"logPayloads":false}'
provon gateway observability update --file ./observability.json

Lifecycle And Settings#

bash
provon gateway pause
provon gateway resume
provon gateway settings get
provon gateway settings update '{"modelPolicies":{}}'
provon gateway settings update --file ./settings.json
provon gateway settings delete

Success Check#

bash
provon gateway providers list

Configured keys appear with bindings; after creating a custom provider, providers test returns a successful connection result before traffic depends on it.

Troubleshooting#

Symptom Likely cause Fix
HTTP_403 on management commands Missing gateway:manage Use an administrative credential or key with the capability
gateway.custom_endpoint_required Custom provider without a URL Supply --endpoint-url or --base-url
gateway.responses_endpoint_required Native mode without a responses URL Add --responses-endpoint-url, or use bridge-chat-completions
test fails with auth error Missing or wrong key/header Verify --api-key, or use --auth-header / --no-auth per the upstream
Binding rejected feature name Unknown feature token Use tokens from the feature list above
gateway.conflicting_input Inline JSON and --file together Pass only one form
Traffic routed to the wrong provider Priority or model policy conflict Review routing get, adjust reorder or policies
All calls blocked after pause Gateway intentionally paused provon gateway resume