CLI Reference

Global options

Option	Env var	Description
`-c, --config <PATH\|URL>`	`GATE_CONFIG`	Path or URL to config file (default: `~/.gate/config.toml`)
`--version`		Print version
`--help`		Print help

Use gate exec -- <cmd> to launch a command behind the proxy. A bare gate -- <cmd> is rejected with a hint so accidental shorthand use does not bypass subcommand parsing.

Commands

`gate start`

Start the routing proxy. In foreground mode, the server blocks until Ctrl+C. In detached mode, it spawns a background daemon and exits.

Flag	Description
`-p, --port <PORT>`	Override listen port
`-d, --detach`	Run in background (daemon mode)

gate start              # Start in foreground
gate start -d           # Start in background
gate start -d -p 9000   # Start on a different port

Prints model upgrade hints (e.g., deprecated model names) and missing credential warnings at startup.

`gate stop`

Stop a running instance. Finds the PID via the /health endpoint and sends SIGTERM (Unix) or taskkill (Windows). Cleans up stale PID files.

`gate restart`

Stop any running instance and start a new one.

Flag	Description
`-d, --detach`	Run in background

gate restart -d         # Restart as daemon

`gate status`

Check service status. Displays:

Whether the server is running (with PID)
Bind address and port
Active preset name
Project overlay path (if .gate.toml exists)
Router configuration (default, think, background, websearch models)
GDPR mode and region (if enabled)
All providers with auth status and region tags
All models with provider mappings and strategy labels
Current month spend vs budget

`gate spend`

Show current month's spend breakdown by provider and model, with budget status. Displays:

Total spend vs global budget limit (with percentage)
Per-provider spend with provider-level budgets
Per-model spend with model-level budgets
Remaining global budget
Subscription providers are labeled accordingly

`gate model`

Display configured models and their router assignments (default, think, websearch, background) and enabled providers.

`gate validate`

Test all configured providers with real API calls. Initializes the full provider registry and runs a validation request against each model mapping. Reports success, failure, and latency.

gate validate

`gate doctor`

Run 11 diagnostic checks:

Config file existence
Config version
Provider credentials (count with/without keys)
Model configuration
Service health (/health endpoint)
Port availability (if service not running)
DLP status
Security settings (rate limit, circuit breaker)
Storage backend (atomic files)
Missing environment variables
Podman availability

gate doctor

`gate exec`

Launch a command behind the Gate proxy. Automatically starts Gate if not running, sets environment variables to point at the proxy, runs the command, and stops Gate when it exits.

Alias: gate launch

Flag	Description
`-p, --port <PORT>`	Override listen port
`--no-stop`	Keep Gate running after the command exits

Environment variables set for the child process:

Variable	Value
`ANTHROPIC_BASE_URL`	`http://<host>:<port>`
`OPENAI_BASE_URL`	`http://<host>:<port>/v1`
`ANTHROPIC_URL`	`http://<host>:<port>/v1`
`OPENAI_URL`	`http://<host>:<port>/v1`

gate exec -- claude              # Launch Claude Code
gate exec -- aider               # Launch Aider
gate exec -- opencode            # Launch OpenCode
gate exec --no-stop -- my-tool   # Keep proxy running after exit

`gate run`

Run in container/foreground mode. Binds to :: (all interfaces), outputs JSON logs, no PID file, supports graceful shutdown via SIGTERM/SIGUSR1.

Flag	Env var	Description
`-p, --port <PORT>`	`GATE_PORT`	Listen port
`--host <HOST>`	`GATE_HOST`	Bind address
`--log-level <LEVEL>`	`GATE_LOG_LEVEL`	Log level
`--json-logs`	`GATE_JSON_LOGS`	JSON log format

gate run --port 8080 --json-logs    # Container-friendly invocation

`gate preset`

Manage configuration presets.

Subcommand	Description
`gate preset list`	Show available presets (built-in + installed)
`gate preset info <name>`	Show providers, models, env vars, router config, and requirements
`gate preset apply <name> [-r\|--reload] [--dry-run]`	Apply a preset (backs up current config). With `--reload`, hot-reloads the running server. With `--dry-run`, previews changes without writing to disk.
`gate preset export <name> [--env <ENV>]`	Save current config as a reusable preset (strips `[server]`, replaces API keys with env var references). With `--env`, saves as `{name}.{env}.toml` for per-environment presets.
`gate preset install <source>`	Install presets from a git repo or local path
`gate preset sync`	Sync presets from configured remote

gate preset list
gate preset info perf
gate preset apply eu-pro --reload
gate preset apply eu-pro --dry-run          # Preview without writing
gate preset export my-setup
gate preset export my-setup --env qa        # Saves as my-setup.qa.toml
gate preset install https://github.com/org/presets.git

`gate key`

Manage virtual API keys for multi-tenant deployments.

`gate key create`

Create a new virtual API key.

Flag	Description
`-n, --name <NAME>`	Human-readable key name (required)
`-t, --tenant <TENANT>`	Tenant identifier (required)
`-b, --budget <USD>`	Monthly budget in USD (optional)
`-r, --rate-limit <RPS>`	Rate limit in requests per second (optional)
`-a, --allowed-models <M1,M2>`	Comma-separated allowed model names (optional)
`-e, --expires <DAYS>`	Key expiration in days from now (optional)

gate key create -n "team-alpha" -t "alpha" -b 100.0 -r 10
gate key create -n "ci-bot" -t "ci" -a "claude-haiku-4-5,gpt-4o" -e 30

The full key is shown once at creation and cannot be retrieved afterward.

`gate key list`

List all virtual API keys.

Flag	Description
`--json`	Output in JSON format instead of table

gate key list
gate key list --json

`gate key revoke`

Revoke a virtual API key by UUID or prefix.

gate key revoke <uuid>
gate key revoke gate-ak-xxxx    # Prefix match

`gate bench`

Run a self-contained performance benchmark of the proxy pipeline. Starts a mock backend, builds a minimal proxy with middleware layers, runs scenarios with increasing feature combinations, and reports latency percentiles plus overhead relative to a direct baseline.

Flag	Default	Description
`-n, --requests <N>`	`500`	Number of requests per scenario (sequential mode)
`--with-auth`	off	Include auth overhead (creates a virtual key and authenticates each request)
`--format <FORMAT>`	`table`	Output format (`table` or `json`)
`-c, --concurrency <N>`	`1`	Concurrent requests (`0` = auto = num_cpus, `1` = sequential)
`-p, --payload <SIZE>`	`small`	Payload size: `small` (~300B), `medium` (~80KB), `large` (~150KB), `all`
`--escalate`	off	Run escalation mode: test each feature layer incrementally and show per-feature cost breakdown

gate bench                              # Quick sequential run (500 reqs, small payload)
gate bench -c 0 --payload all           # Concurrent, all payload sizes
gate bench --escalate -c 8              # Feature escalation staircase
gate bench --format json -n 1000        # JSON output for CI
gate bench --with-auth --escalate       # Include virtual-key auth in escalation

`gate rollback`

Restore the previous configuration from backup. Copies config.toml.backup over the active config.toml, then triggers a hot-reload on the running server if reachable. The backup file is created automatically when applying a preset via gate preset apply.

Cannot be used when the config source is a remote URL.

gate rollback

`gate preset push`

Push a local preset to a remote gate instance. Loads the preset, fetches the remote config for a section-level diff, optionally prompts for confirmation, then uploads the config and triggers a reload.

Flag	Description
`<name>`	Preset name to push (positional, required)
`--target <URL>`	Target gate instance URL (e.g., `https://gate-qa.example.com`)
`--yes`	Skip confirmation prompt

gate preset push perf --target https://gate-qa.example.com
gate preset push eu-max --target https://gate-prod.example.com --yes

`gate preset pull`

Pull config from a remote gate instance and save it as a local preset. Fetches the remote /api/config JSON, strips the server section, and saves the result as a TOML preset file.

Flag	Description
`--from <URL>`	Source gate instance URL (e.g., `https://gate-prod.example.com`)
`--save <NAME>`	Name to save the pulled config as

gate preset pull --from https://gate-prod.example.com --save prod-snapshot

`gate watch`

Live traffic inspector TUI. Connects to the running server's SSE endpoint (/api/events) and displays a ratatui dashboard with provider health, live request stream, and DLP alerts.

gate watch

Keyboard: q to quit, p to pause/resume.

`gate env`

Check which environment variables are required by configured providers. Shows whether each variable is set or missing.

gate env

`gate logs`

Decrypt and display encrypted trace entries from ~/.gate/trace.jsonl. Only subcommand today: decrypt.

gate logs decrypt                             # pretty-print to stdout
gate logs decrypt --path <trace.jsonl>        # custom trace file
gate logs decrypt --output <out.jsonl>        # write plaintext to file

`gate secrets`

Manage encrypted upstream provider secrets referenced as secret:<name> in provider config.

Subcommand	Description
`gate secrets add <name>`	Read a secret value from stdin and store it encrypted
`gate secrets list [--json]`	List stored secret names without revealing values
`gate secrets show <name> [--unsafe-show]`	Show a redacted value unless explicitly revealed
`gate secrets rm <name> [--force]`	Remove a secret
`gate secrets test [name] [--json]`	Probe referencing providers' models endpoints

printf '%s\n' "$OPENAI_API_KEY" | gate secrets add openai
gate secrets list
gate secrets test openai

`gate harness` (feature-gated)

Record live traffic to a tape file for later replay. The command is available only when the binary is built with the harness feature.

gate harness record --output <tape.jsonl>
gate harness replay --tape <tape.jsonl>

`gate connect`

Interactive credential setup for providers. Without arguments, checks all providers. With a provider name, sets up that specific provider only.

Flag	Description
`--force-reauth`	Discard existing OAuth tokens and initiate a fresh OAuth flow. Use when `gate connect` reports a revoked token.

gate connect                          # Check all providers
gate connect anthropic                # Set up Anthropic credentials
gate connect anthropic --force-reauth # Re-authenticate after token revocation

`gate init`

Create a per-project .gate.toml file in the current directory. The overlay file can override router models, budget limits, and prompt rules without changing the global config.

gate init

`gate config-diff`

Compare local config against a preset or remote config. Defaults to comparing against the active preset.

gate config-diff                  # Compare against active preset
gate config-diff eu-pro           # Compare against a specific preset

Reports section-level differences for [router], [[providers]], and [[models]].

`gate setup`

Interactive first-run setup wizard (auto-triggered when no config.toml exists). Guides through:

Tool selection (Claude Code, Codex CLI, Forge, Aider, Continue.dev, Cursor)
Provider authentication (OAuth vs API key per provider)
Fallback provider (OpenRouter)
Compliance mode (Standard, DLP only, GDPR, EU AI Act, Enterprise security, Local-only)
Monthly budget cap
Provider status validation

Flag	Description
`--yes`	Accept all defaults without prompting (non-interactive scripted setup)
`--dry-run`	Preview changes without writing to disk
`--edit <SECTION>`	Reconfigure a single section. Valid sections: `providers`, `auth`, `budget`, `compliance`, `fallback`, `endpoints`, `tools`

gate setup                        # Full interactive wizard
gate setup --yes                  # Accept all defaults (scripts/CI)
gate setup --dry-run              # Preview without writing
gate setup --edit budget          # Reconfigure just the budget section

`gate upgrade`

Zero-downtime upgrade using SO_REUSEPORT (Unix). Spawns a new process on the same port, waits for the new process to pass health check, then signals the old process to drain via SIGUSR1.

gate upgrade

On Windows, a brief interruption occurs (stop-then-start) because SO_REUSEPORT is unavailable.

`gate completions`

Generate shell completions for the specified shell.

gate completions zsh > ~/.zfunc/_gate
gate completions bash > /etc/bash_completion.d/gate
gate completions fish > ~/.config/fish/completions/gate.fish

`gate setup-completions`

Automatically install shell completions for the current shell (detects zsh, bash, or fish).

gate setup-completions

`gate harness` (requires `--features harness`)

Record & replay sandwich testing harness.

Subcommand	Description
`gate harness record -o <path>`	Print instructions for recording traffic via `GATE_HARNESS_RECORD` env var
`gate harness replay -t <tape>`	Replay recorded traffic through gate with a mock backend

Replay flags:

Flag	Default	Description
`-t, --tape <PATH>`	(required)	Path to `.tape.jsonl` file
`-u, --target <URL>`	`http://[::1]:13456`	Gate target URL
`-c, --concurrency <N>`	`10`	Maximum concurrent requests
`-q, --qps <N>`	`0` (unlimited)	Target queries per second
`--mock-port <PORT>`	`0` (ephemeral)	Mock backend port
`--mock-latency-ms <MS>`	`50`	Simulated latency
`--error-rate <RATE>`	`0.0`	Fraction of mock errors (0.0-1.0)
`--duration <SECS>`	`0` (no limit)	Maximum replay duration

# Build with harness feature
cargo build --features harness

# Record traffic
GATE_HARNESS_RECORD=traffic.tape.jsonl gate start

# Replay against a running gate instance
gate harness replay -t traffic.tape.jsonl -c 20 --qps 50

Navigation Menu

Repository navigation

cli.md

cli.md

CLI Reference

Global options

Commands

`gate start`

`gate stop`

`gate restart`

`gate status`

`gate spend`

`gate model`

`gate validate`

`gate doctor`

`gate exec`

`gate run`

`gate preset`

`gate key`

`gate key create`

`gate key list`

`gate key revoke`

`gate bench`

`gate rollback`

`gate preset push`

`gate preset pull`

`gate watch`

`gate env`

`gate logs`

`gate secrets`

`gate harness` (feature-gated)

`gate connect`

`gate init`

`gate config-diff`

`gate setup`

`gate upgrade`

`gate completions`

`gate setup-completions`

`gate harness` (requires `--features harness`)

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Global options

Commands

gate start

gate stop

gate restart

gate status

gate spend

gate model

gate validate

gate doctor

gate exec

gate run

gate preset

gate key

gate key create

gate key list

gate key revoke

gate bench

gate rollback

gate preset push

gate preset pull

gate watch

gate env

gate logs

gate secrets

gate harness (feature-gated)

gate connect

gate init

gate config-diff

gate setup

gate upgrade

gate completions

gate setup-completions

gate harness (requires --features harness)

`gate start`

`gate stop`

`gate restart`

`gate status`

`gate spend`

`gate model`

`gate validate`

`gate doctor`

`gate exec`

`gate run`

`gate preset`

`gate key`

`gate key create`

`gate key list`

`gate key revoke`

`gate bench`

`gate rollback`

`gate preset push`

`gate preset pull`

`gate watch`

`gate env`

`gate logs`

`gate secrets`

`gate harness` (feature-gated)

`gate connect`

`gate init`

`gate config-diff`

`gate setup`

`gate upgrade`

`gate completions`

`gate setup-completions`

`gate harness` (requires `--features harness`)