CLI Reference

Complete reference for the relayplane command-line interface. Every command, flag, and subcommand documented.

Basic Usage

1npx @relayplane/proxy [command] [options]
2relayplane [command] [options]

Global Options

These flags apply when starting the proxy server (the default command).

Flag	Default	Description
`--port <number>`	`4100`	Port to listen on (1–65535)
`--host <string>`	`127.0.0.1`	Host/IP to bind to. Default `127.0.0.1` keeps admin endpoints local; only use `0.0.0.0` behind firewall/reverse proxy/auth.
`--offline`	`false`	Disable all network calls except LLM API endpoints. No telemetry, no cloud sync, no update checks.
`--audit`	`false`	Print telemetry payloads to stdout before they are sent. Useful for verifying what data is collected.
`-v, --verbose`	`false`	Enable verbose logging (routing decisions, cache hits, config reloads).
`-h, --help`	,	Print help text and exit.
`--version`	,	Print version number and exit.

--host 0.0.0.0 exposes admin and control endpoints to your network. Prefer localhost by default:

1# Recommended (local-only)
2relayplane --host 127.0.0.1 --port 4100
3
4# If you must bind all interfaces, put it behind firewall + reverse proxy + auth
5relayplane --host 0.0.0.0 --port 4100

Commands

(default) / start

Start the proxy server. This is the default action when no command is specified. The proxy listens for incoming LLM API requests and routes them according to config.

1# Start on default port 4100 (localhost-only, safest)
2relayplane
3
4# Explicit start command (equivalent)
5relayplane start
6
7# Localhost-first custom binding
8relayplane --port 3002 --host 127.0.0.1
9
10# Network-exposed binding (only behind firewall/reverse proxy/auth)
11relayplane --port 3002 --host 0.0.0.0
12
13# Audit mode, see telemetry before it's sent
14relayplane --audit
15
16# Offline mode, no telemetry, no cloud sync
17relayplane --offline
18
19# Verbose logging
20relayplane -v

Starts with or without provider keys. With none set it runs in passthrough for Claude Code (Max plan OAuth); with ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY or others it routes to those providers. Override any provider endpoint with RELAYPLANE_<PROVIDER>_BASE_URL.

--host 0.0.0.0 should be treated as an internet/LAN exposure mode. Protect sensitive admin routes such as /control/*, /v1/config, and /dashboard/config with firewall + reverse proxy + auth.

init

Initialize the RelayPlane config file at ~/.relayplane/config.json. Creates default config if it doesn't exist.

1relayplane init

Example output:

1✅ RelayPlane initialized
2   Config: /home/user/.relayplane/config.json
3
4Next steps:
5  1. Start the proxy:
6     relayplane start
7  2. Point your agent at the proxy:
8     export ANTHROPIC_BASE_URL=http://localhost:4100
9     export OPENAI_BASE_URL=http://localhost:4100
10  3. Check your costs:
11     relayplane stats

login

Log in to RelayPlane cloud using a device OAuth flow. Opens a browser for approval. Credentials are stored at ~/.relayplane/credentials.json.

1relayplane login

Example output:

1  🔐 Logging in to RelayPlane...
2
3  Your one-time code:
4
5    📋 ABCD-1234
6
7  ✅ Browser opened to: https://relayplane.com/device
8     Paste the code above and approve.
9
10  Waiting for approval (expires in 15 minutes)...
11
12  ✅ Login successful!
13     Team: My Team
14     Plan: pro
15
16  ☁️  Cloud sync will activate on next proxy start.

logout

Clear stored credentials. Cloud sync stops on next proxy restart.

1relayplane logout

status

Show proxy status, login state, plan info, and cloud sync status. Checks if the proxy process is reachable on the default port.

1relayplane status

Example output:

1  📊 RelayPlane Status
2  ════════════════════
3
4  Proxy:       🟢 Running
5  Account:     ❌ Not logged in
6  Plan:        free (local only)
7  Cloud sync:  ❌ Disabled

upgrade

Opens relayplane.com/pricing in your browser. It does not install updates; use npm install -g @relayplane/proxy@latest for that.

1relayplane upgrade

enable / disable

Enable or disable RelayPlane routing in ~/.relayplane/config.json (hot-reloaded). When disabled, the proxy enters passthrough mode: requests are forwarded unmodified to the original provider, so traffic still flows and still costs money. This is not a kill switch; for that use relayplane kill below.

1relayplane enable
2relayplane disable

kill / resume

The global kill switch. While active, every /v1/messages and /v1/chat/completions request gets 503 kill_switch_active and nothing is forwarded to any provider. Persisted in ~/.relayplane/config.json, so it survives a restart until you resume. Same switch as the dashboard KILL button and POST /control/kill {"all":true} / POST /control/resume.

1relayplane kill --reason "runaway loop"
2relayplane resume

telemetry [on|off|status]

Manage anonymous telemetry collection. Telemetry is on by default. Use telemetry off to disable.

1relayplane telemetry status   # Check current setting
2relayplane telemetry on       # Enable telemetry
3relayplane telemetry off      # Disable telemetry

Example output for telemetry status:

1📊 Telemetry Status
2───────────────────
3   Enabled: ✅ Yes
4   Data file: /home/user/.relayplane/telemetry.json
5
6   To enable:  relayplane telemetry on
7   To disable: relayplane telemetry off
8   To audit:   relayplane --audit

stats

Show usage statistics: total requests, actual cost, baseline cost (what you would have spent using Opus for everything), savings percentage, and per-model/task-type breakdowns.

1relayplane stats

Example output:

1📊 Usage Statistics
2═══════════════════
3
4  Total requests: 142
5  Actual cost:    $1.2340
6  Without RP:     $8.5600
7  💰 You saved:   $7.3260 (85.6%)
8  Success rate:   99.3%
9
10  By Model:
11    claude-sonnet-4-6: 120 requests, $0.8200 (saved $6.1800 vs Opus)
12    claude-haiku-4-5: 22 requests, $0.4140 (saved $1.1460 vs Opus)
13
14  By Task Type:
15    code_generation: 89 requests, $0.7800
16    question_answering: 53 requests, $0.4540

config [show|set-key <key>]

View current configuration or set the RelayPlane API key for Pro features.

1relayplane config             # Show current config
2relayplane config set-key rp_sk_abc123  # Set API key

Example output for config:

1⚙️  Configuration
2═════════════════
3
4  Config file: /home/user/.relayplane/config.json
5  Device ID:   anon_a1b2c3d4e5f6g7h8
6  Telemetry:   ✅ Enabled
7  API Key:     ••••bc23
8  Created:     2025-01-15T10:30:00.000Z
9
10  To set API key: relayplane config set-key <your-key>

budget [status|set|reset]

Manage spend budgets. The budget system tracks daily and hourly spend windows and can block, warn, or downgrade requests when limits are exceeded.

1# Show current budget status
2relayplane budget status
3
4# Set budget limits
5relayplane budget set --daily 25 --hourly 5 --per-request 1
6
7# Reset spend counters for current window
8relayplane budget reset

Example output for budget status:

1💰 Budget Status
2   Enabled:     ✅
3   Daily:       $12.3400 / $50 (24.7%)
4   Hourly:      $3.1200 / $10 (31.2%)
5   Per-request: max $2
6   On breach:   downgrade

Flag	Description
`--daily <usd>`	Set daily spend limit in USD
`--hourly <usd>`	Set hourly spend limit in USD
`--per-request <usd>`	Set per-request spend limit in USD

run [flags] -- <command...>

Wrap any command as one attributed run, with no code changes. Everything before the bare -- is a flag for the wrapper, everything after is your command. The separator is mandatory. Sets ANTHROPIC_CUSTOM_HEADERS, RELAYPLANE_RUN_ID and RELAYPLANE_RUN_HEADERS in the child environment, and ANTHROPIC_BASE_URL only if you have not set one. stdout belongs to your command; the wrapper writes to stderr. The exit code is your command's exit code. Full reference: Runs and attribution.

1relayplane run --label nightly-backfill -- ./orchestrate.sh
2
3# Flags (all before the --)
4#   --label X      human name for the run, bands key off this
5#   --tag k:v      repeatable, up to 10 pairs
6#   --cap USD      per-run hard cap
7#   --id X         use this run id instead of minting one ("parent/child" nests)
8#   --parent X     explicit parent run id
9#   --agent X      agent label for the whole command
10#   --proxy URL    talk to a proxy other than the local default
11#   --json         machine readable rollup on stdout instead of stderr
12relayplane run --label nightly-backfill --tag repo:api --cap 12 -- ./orchestrate.sh

Example output. Costs are notional list price for the traffic, not an invoice:

1Run nightly-backfill-20260905-a1b2c3 (nightly-backfill)  completed  18m 42s
2  cost $6.41 notional (all-opus baseline $19.02)   requests 214   retries $1.10 (17%)   band in [4.00, 9.00]
3  429s 0   model drift 3
4  agents: coder $3.88 (121 req, claude-sonnet-4-6 x118) | architect $1.94 (34 req, claude-opus-4-6 x34)
5  dashboard http://localhost:4100/dashboard#run=nightly-backfill-20260905-a1b2c3

runs [list|show|export|band|alerts]

Read the local run ledger. list is the default subcommand. Every subcommand also takes --json and --proxy URL.

1relayplane runs list [--active] [--days N] [--label X] [--status X] [--json]
2relayplane runs show <run-id> [--json]
3relayplane runs export <run-id> | --days N [--format csv|json|jsonl] [--out FILE]
4relayplane runs band <label> [--apply] [--json]
5relayplane runs alerts [--since 1h] [--json]

Notes: --active ignores --days, --label and --status, and adds a 429-wave column when one is firing. runs band <label> --apply writes the observed p25 to p75 range into attribution.bands.<label>, and only after five completed runs with that label. Export defaults to csv.

1RUN                             STATUS     SOURCE  STARTED  DURATION  REQ  COST   RETRIES  BAND  AGENTS
2nightly-backfill-20260905-a1b2  completed  header  02:00    18m 42s   214  $6.41  $1.10    in    coder, architect
3cc-9f2c1a04-...                 running    cc      09:41    12m 03s    58  $1.92  $0.00    none  unknown
4
5Costs are notional (list price for the traffic), not an invoice.

alerts [list|counts]

View cost alerts, anomaly detections, and budget breach history.

1# List recent alerts (default: last 20)
2relayplane alerts list
3relayplane alerts list 50     # Last 50 alerts
4
5# Show alert counts by type
6relayplane alerts counts

Example output for alerts list:

1🔔 Recent Alerts
2═════════════════
3  🟡 [2025-02-25T18:30:00] threshold: Daily spend reached 80% ($40.00/$50.00)
4  🔴 [2025-02-25T19:00:00] breach: Hourly limit breached ($10.50/$10.00)

Example output for alerts counts:

1🔔 Alert Counts
2   Threshold: 3
3   Anomaly:   1
4   Breach:    0

cache [on|off|status|clear|stats]

Manage the response cache. The cache stores LLM responses locally to avoid duplicate API calls. By default only caches deterministic requests (temperature=0).

1relayplane cache status   # Show cache status
2relayplane cache on       # Enable cache
3relayplane cache off      # Disable cache
4relayplane cache clear    # Delete all cached responses
5relayplane cache stats    # Detailed cache statistics

Example output for cache status:

1📦 Response Cache Status
2   Enabled:    ✅
3   Entries:    234
4   Size:       12.5 MB
5   Hit rate:   34.2%
6   Saved:      $8.45

Example output for cache stats:

1📊 Cache Statistics
2   Total entries:  234
3   Total size:     12.50 MB
4   Hit rate:       34.2%
5   Hits: 80  Misses: 154  Bypasses: 12
6   Saved:          $8.4500 across 80 requests
7
8   By Model:
9     claude-sonnet-4-6: 180 entries, 60 hits, $6.2000 saved
10     claude-haiku-4-5: 54 entries, 20 hits, $2.2500 saved

service [install|uninstall|status]

Manage RelayPlane as a system service. Supports Linux (systemd) and macOS (launchd). The service auto-starts on boot and restarts on crash.

1# Check service status
2relayplane service status
3
4# Install as system service (Linux: requires sudo)
5sudo relayplane service install
6
7# Preview what would be installed (dry run)
8sudo relayplane service install --dry-run
9
10# Remove system service
11sudo relayplane service uninstall

On Linux, installs a systemd unit at /etc/systemd/system/relayplane-proxy.service with watchdog support and automatic restart. On macOS, installs a launchd plist at ~/Library/LaunchAgents/com.relayplane.proxy.plist. Current environment API keys are baked into the service file.

autostart [on|off|status]

Legacy command for managing autostart on Linux with systemd. Prefer service install for new setups.

1relayplane autostart status
2sudo relayplane autostart on
3sudo relayplane autostart off

mesh [status|on|off|sync|contribute]

Manage the mesh learning layer (Osmosis). The mesh captures routing data locally and optionally syncs anonymized patterns to improve routing for all users.

1# Show mesh status (queries running proxy if available)
2relayplane mesh status
3
4# Enable/disable mesh
5relayplane mesh on
6relayplane mesh off
7
8# Force a sync now
9relayplane mesh sync
10
11# Manage contribution (sharing anonymized data)
12relayplane mesh contribute status
13relayplane mesh contribute on
14relayplane mesh contribute off

Example output for mesh status (proxy running):

1🧠 Mesh Learning Layer
2══════════════════════
3  Enabled:       ✅
4  Atoms (local): 1420
5  Atoms (synced): 890
6  Last sync:     2025-02-25T18:00:00.000Z
7  Endpoint:      https://osmosis-mesh-dev.fly.dev

Port Note

The CLI default port is 4100. When using the proxy programmatically via the startProxy() function (without the CLI), the default port is 4801. The CLI always passes the port explicitly, so when running via relayplane, port 4100 is used unless overridden with --port.

Security notes

Keep the proxy on 127.0.0.1 unless you explicitly need remote access. When binding to 0.0.0.0, assume /control/*, /v1/config, and /dashboard/configare sensitive admin surfaces and protect them with network and auth controls.

Quick Start Examples

1# 1. Start the proxy
2export ANTHROPIC_API_KEY=sk-ant-api-...
3relayplane
4
5# 2. Point your agent at it
6export ANTHROPIC_BASE_URL=http://localhost:4100
7export OPENAI_BASE_URL=http://localhost:4100
8
9# 3. Run your agent as usual, RelayPlane routes automatically
10claude  # or cursor, aider, etc.
11
12# 4. Check savings
13relayplane stats

Claim-URL Nudge

At the 100th proxied request the CLI prints a one-time claim URL to stdout, letting you attach your anonymous local proxy data to a RelayPlane account. The nudge fires once per install, is non-blocking, and never affects request routing. Opening the URL is optional, your proxy keeps running locally either way.

1[relayplane] You have proxied 100 requests. Claim your data:
2[relayplane]   https://relayplane.com/claim/<one-time-token>

Credential Quarantine

When a pooled credential returns two consecutive 401 auth failures, the proxy quarantines it for 1 hour and routes requests through the remaining credentials. This keeps a single revoked or rate-limited key from breaking the pool. A quarantined credential is restored automatically once the window expires, so a transient auth failure never requires manual intervention.