CLI Reference

Global options

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

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

Commands

`grob 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)
`--adopt-from-system`	Adopt and refresh compatible OAuth tokens from co-installed CLIs for this invocation. A later restart uses the configuration's setting.

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

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

`grob stop`

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

`grob restart`

Stop any running instance and start a new one.

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

grob restart -d         # Restart as daemon

`grob status`

Check service status. Displays:

Whether the server is running (with PID)
Bind address and port
Active preset name
Project overlay path (if .grob.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

`grob 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

`grob model`

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

`grob 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.

grob validate

`grob 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

grob doctor

`grob exec`

Launch a command behind the Grob proxy. Starts Grob if needed, sets base-URL environment variables, and runs the command. When the command exits, it stops an instance it started; an existing instance stays running. It does not supply an inbound Grob credential to the child process.

Alias: grob launch

Flag	Description
`-p, --port <PORT>`	Override listen port
`--no-stop`	Keep Grob running after the command exits
`--adopt-from-system`	Enable OAuth token adoption for a proxy started by this command. Does not change an already-running instance.

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`

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

`grob run`

Run in container/foreground mode. Binds to :: (all interfaces) by default, uses no PID file, and supports graceful shutdown via SIGTERM/SIGUSR1 on Unix. Logs are human-readable unless --json-logs or GROB_JSON_LOGS=true is set.

Flag	Env var	Description
`-p, --port <PORT>`	`GROB_PORT`	Listen port
`--host <HOST>`	`GROB_HOST`	Bind address
`--log-level <LEVEL>`	`GROB_LOG_LEVEL`	Log level
`--json-logs`	`GROB_JSON_LOGS`	JSON log format
`--adopt-from-system`	`GROB_ADOPT_FROM_SYSTEM`	Adopt and refresh compatible OAuth tokens from co-installed CLIs

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

`grob preset`

Manage configuration presets.

Subcommand	Description
`grob preset list`	Show available presets (built-in + installed)
`grob preset info <name>`	Show providers, models, env vars, router config, and requirements
`grob 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.
`grob 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.
`grob preset install <source>`	Install presets from a git repo or local path
`grob preset sync`	Sync presets from configured remote

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

`grob key`

Manage virtual API keys for multi-tenant deployments.

`grob 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)
`--allowed-providers <P1,P2>`	Comma-separated configured provider names (optional; omitted means any provider)
`-e, --expires <DAYS>`	Key expiration in days from now (optional)

grob key create -n "team-alpha" -t "alpha" -b 100.0 -r 10
grob 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.

`grob key list`

List all virtual API keys.

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

grob key list
grob key list --json

`grob key revoke`

Revoke a virtual API key by UUID or prefix.

grob key revoke <uuid>
grob key revoke grob_a1b2      # Replace with a unique prefix from grob key list

`grob 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

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

`grob 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 grob preset apply.

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

grob rollback

`grob preset push`

Push a local preset to a remote grob 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 grob instance URL (e.g., `https://grob-qa.example.com`)
`--yes`	Skip confirmation prompt

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

`grob preset pull`

Pull config from a remote grob 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 grob instance URL (e.g., `https://grob-prod.example.com`)
`--save <NAME>`	Name to save the pulled config as

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

`grob 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.

grob watch

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

`grob env`

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

grob env

`grob logs`

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

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

`grob secrets`

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

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

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

`grob credentials`

Manage credentials for a configured HTTP service binding. These commands operate on the local encrypted store; run them with the daemon's configuration, GROB_HOME and encryption-key source. They do not change the agent's identity.

Subcommand	Behavior
`grob credentials local <service> [--expires-at <unix-seconds>]`	Read a complete token or Basic-auth JSON bundle from stdin; publish local authority. Without a new deadline, preserve the existing bound.
`grob credentials vault <service>`	Select configured Vault authority and clear an override or revocation. The next dispatch must verify Vault.
`grob credentials status <service>`	Show source, generation and effective credential expiry, without values.
`grob credentials check <service>`	Check local readiness and emit warnings; exit unsuccessfully if not ready. Does not probe remote authorization.
`grob credentials revoke <service>`	Deny local and remote dispatch until explicit publication.

See service credential routing for bundle shapes, setup, expiry semantics and upgrades. Provider secret:<name> references use the separate secrets commands above.

`grob 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 `grob connect` reports a revoked token.
`--from-system`	Adopt an existing compatible OAuth token from Codex CLI or Claude Code instead of opening a browser. Requires a provider argument.

grob connect                          # Check all providers
grob connect anthropic                # Set up Anthropic credentials
grob connect anthropic --force-reauth # Re-authenticate after token revocation
grob connect anthropic --from-system # Adopt an existing Claude Code login

The provider argument accepts either its configured name or oauth_provider identifier. Token adoption supports Codex CLI's auth file and Claude Code's macOS Keychain credential. See OAuth Setup for requirements and the ongoing adopt_from_system setting.

`grob init`

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

grob init

`grob config-diff`

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

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

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

`grob 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`

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

`grob 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.

grob upgrade

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

`grob completions`

With no argument, detects the current shell (zsh, bash, or fish) and installs completions for it:

grob completions

setup-completions remains as a hidden alias of this command.

Name a shell to write the script to stdout instead, for packaging or a custom install path:

grob completions zsh > ~/.zfunc/_grob
grob completions bash > /etc/bash_completion.d/grob
grob completions fish > ~/.config/fish/completions/grob.fish

`grob harness` (requires `--features harness`)

Record & replay sandwich testing harness.

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

Replay flags:

Flag	Default	Description
`-t, --tape <PATH>`	(required)	Path to `.tape.jsonl` file
`-u, --target <URL>`	`http://[::1]:13456`	Grob 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
GROB_HARNESS_RECORD=traffic.tape.jsonl grob start

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

Navigation Menu

Repository navigation

CLI Reference

Global options

Commands

`grob start`

`grob stop`

`grob restart`

`grob status`

`grob spend`

`grob model`

`grob validate`

`grob doctor`

`grob exec`

`grob run`

`grob preset`

`grob key`

`grob key create`

`grob key list`

`grob key revoke`

`grob bench`

`grob rollback`

`grob preset push`

`grob preset pull`

`grob watch`

`grob env`

`grob logs`

`grob secrets`

`grob credentials`

`grob connect`

`grob init`

`grob config-diff`

`grob setup`

`grob upgrade`

`grob completions`

`grob harness` (requires `--features harness`)

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Global options

Commands

grob start

grob stop

grob restart

grob status

grob spend

grob model

grob validate

grob doctor

grob exec

grob run

grob preset

grob key

grob key create

grob key list

grob key revoke

grob bench

grob rollback

grob preset push

grob preset pull

grob watch

grob env

grob logs

grob secrets

grob credentials

grob connect

grob init

grob config-diff

grob setup

grob upgrade

grob completions

grob harness (requires --features harness)

`grob start`

`grob stop`

`grob restart`

`grob status`

`grob spend`

`grob model`

`grob validate`

`grob doctor`

`grob exec`

`grob run`

`grob preset`

`grob key`

`grob key create`

`grob key list`

`grob key revoke`

`grob bench`

`grob rollback`

`grob preset push`

`grob preset pull`

`grob watch`

`grob env`

`grob logs`

`grob secrets`

`grob credentials`

`grob connect`

`grob init`

`grob config-diff`

`grob setup`

`grob upgrade`

`grob completions`

`grob harness` (requires `--features harness`)