CLI

rp is the Routeplane command-line interface — chat, embeddings, model catalog, logs, FinOps, prompts, cache, and the Control-Plane admin surface (virtual keys and tenants), all from your terminal. It is a thin shell over the TypeScript SDK's core client, so the same connection resolution and output shapes apply.

bashinstall

npm i -g @routeplane/cli     # installs the `rp` binary
# or run without installing:
npx @routeplane/cli status

Set up a profile

rp init walks you through saving a connection profile to ~/.routeplane/config.json (created 0700, the file 0600). After that, every command reuses it.

bashfirst run

rp init                      # save base URL + gateway key as a profile
rp status                    # verify the gateway is reachable
rp chat "Hello in one word"  # stream a completion

Command reference

Data-plane commands talk to the gateway with your virtual key. The Control-Plane commands (login, keys, tenants) talk to the admin API and authenticate over Entra ID.

Command	What it does
`rp init`	Interactive setup — save a connection profile.
`rp login`	Authenticate with the Control Plane (OAuth device-code flow).
`rp chat [message]`	Stream a chat completion; reads stdin when no message is given.
`rp embed [text]`	Generate an embedding; reads stdin when no text is given.
`rp status`	Show gateway health and per-provider circuit state.
`rp models list`	List available models, optionally filtered by provider.
`rp logs`	Show recent request logs.
`rp usage`	FinOps usage summary over a date range.
`rp prompts`	Prompt templates: `list`, `get <ref>`, `render <ref>`.
`rp providers list`	List registered custom OpenAI-compatible providers.
`rp cache purge`	Purge the response cache for your tenant.
`rp feedback`	Attach a quality score to a request by its id.
`rp residency`	Sovereign-routing summary.
`rp keys`	Virtual-key admin (CP): `list`, `create`, `rotate`, `revoke`.
`rp tenants`	Tenant admin (CP): `list`, `get <id>`, `create`.

Chat and embeddings

bashrp chat

# Stream a completion with a fallback chain and a routing strategy
rp chat "Summarize this" \
  --model gpt-4o \
  --provider anthropic,openai \
  --strategy cost \
  --residency IN \
  --system "You are concise."

# Pipe stdin in, get raw JSON out
echo "Translate to French: hello" | rp chat --json

# Embeddings
rp embed "text to embed" --model text-embedding-3-small

Observability and FinOps

bashlogs / usage

rp logs --limit 100                 # recent request logs
rp usage --from 2026-07-01 --to 2026-07-31
rp status --output json             # machine-readable health

Prompts

bashrp prompts

rp prompts list
rp prompts get welcome-v2
rp prompts render welcome-v2 --var name=Rohit --var plan=pilot

Admin — keys and tenants (Control Plane)

These commands hit the Control-Plane admin API, so run rp login first. keys create shows the full key value once; keys rotate issues a new value with a 30-day grace period on the old one; keys revoke takes effect immediately.

bashrp keys / tenants

rp login                                     # OAuth device-code flow
rp tenants list
rp tenants create --name "Acme" --tier standard
rp keys list --tenant-id tid_123
rp keys create --tenant-id tid_123 --name "prod-backend"
rp keys rotate --key-id key_456
rp keys revoke --key-id key_456 --force

Global flags

These apply to every command:

Flag	Effect
`--profile <name>`	Config profile to use (default `default`).
`--base-url <url>`	Override the gateway base URL.
`--api-key <key>`	Override the API key.
`--output <format>`	`table` (default) or `json`. Most commands also accept `--json`.

Config profiles

Profiles live in ~/.routeplane/config.json. Each is a named connection; default points at the one used when --profile is omitted. This lets you keep, say, a prod and a staging gateway side by side and switch with a flag.

json~/.routeplane/config.json

{
  "default": "cloud",
  "profiles": {
    "cloud":   { "base_url": "https://api.routeplane.ai", "api_key": "rp_live_..." },
    "staging": { "base_url": "https://staging.example.com", "api_key": "rp_test_..." }
  }
}

bashswitch profiles

rp status --profile staging

Environment variables

Handy for CI, where you would rather not write a config file. Resolution order is flag → environment → profile (and base_url falls back to the built-in default).

Variable	Effect
`ROUTEPLANE_API_KEY`	Your gateway virtual key (`rp_...`).
`ROUTEPLANE_BASE_URL`	Gateway base URL (default `https://api.routeplane.ai`).
`ROUTEPLANE_PROFILE`	Profile name to select.

bashCI usage

export ROUTEPLANE_API_KEY=rp_live_...
rp usage --from 2026-07-01 --output json