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).

FlagDefaultDescription
--port <number>4100Port to listen on (1–65535)
--host <string>127.0.0.1Host/IP to bind to. Default 127.0.0.1 keeps admin endpoints local; only use 0.0.0.0 behind firewall/reverse proxy/auth.
--offlinefalseDisable all network calls except LLM API endpoints. No telemetry, no cloud sync, no update checks.
--auditfalsePrint telemetry payloads to stdout before they are sent. Useful for verifying what data is collected.
-v, --verbosefalseEnable 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

Requires at least one provider API key set as an environment variable (e.g. ANTHROPIC_API_KEY). The proxy checks for updates on startup (non-blocking).

--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  Autostart:   ✅ Enabled
6  Account:     ✅ Logged in (user@example.com)
7  Plan:        pro
8  API Key:     ••••abcd
9  Cloud sync:  ☁️  Active

upgrade

Check for proxy updates and install the latest version.

1relayplane upgrade

enable / disable

Enable or disable RelayPlane proxy routing. When disabled, the proxy enters passthrough mode: requests are forwarded unmodified to the original provider. Updates ~/.openclaw/openclaw.json.

1relayplane enable
2relayplane disable

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
FlagDescription
--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

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