cloud
BitRouter Cloud from the terminal — sign-in, API keys, usage, billing, policies, budgets, presets, and BYOK.
bitrouter cloud login either runs the RFC 8628 Device Authorization Grant or stores an existing BitRouter API key. Both credential types live under $XDG_DATA_HOME/bitrouter/account-credentials.json (mode 0600 on Unix). The API-key form performs no network request, which makes it suitable for CI. Interactive OAuth lets you pick the workspace this session is bound to; tokens refresh automatically within 60 s of expiry.
The default scope set covers inference:invoke, usage:read, keys:read/keys:write, billing:read, policy:read/policy:write, byok:read/byok:write, and namespace:read. Sensitive scopes such as billing:write are opt-in via --scope. After either login form, the bitrouter provider auto-enables in zero-config mode — every model your account is entitled to is routable as bitrouter:<model-id>.
Every leaf accepts --json for raw output; the default is a systemctl-style key:value block for single resources and a small table for lists. When the server returns 403 missing required scope: <s>, OAuth users get a copy-pasteable re-login hint; API-key users are told to mint a key with that scope. See the Cloud API guide for protocol details.
bitrouter cloud
Manage your BitRouter Cloud account — sign in/out, API keys, usage, billing, policies, and BYOK. Start with cloud login
Usage: bitrouter cloud [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud whoami
Print the cloud identity stored on this machine alongside the /v1/* base URL the CLI will target
Usage: bitrouter cloud whoami [OPTIONS]
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud api
Make an authenticated request to a relative BitRouter Cloud API endpoint
Usage: bitrouter cloud api [OPTIONS] <ENDPOINT>
Arguments
| Argument | Description |
|---|---|
<ENDPOINT> | Relative API endpoint, for example /v1/models |
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
-X, --method <METHOD> | HTTP method. Defaults to GET, or POST when fields/input are present |
-H, --header <KEY:VALUE> | Add an HTTP request header. May be repeated |
--human | Render the human-readable view to stdout instead of JSON |
-f, --raw-field <KEY=VALUE> | Add a string field to the JSON body or query string. May be repeated |
-F, --field <KEY=VALUE> | Add a typed field to the JSON body or query string. May be repeated |
--input <FILE> | Read the exact request body from a file, or - for stdin |
-i, --include | Include the response status line and headers in stdout |
--silent | Suppress the response body |
--verbose | Print redacted request and response details to stderr |
Modeled after gh api: injects the stored bearer against the logged-in origin and streams the response. Absolute URLs and redirect following are rejected, so the credential never leaves its login origin.
bitrouter cloud api /v1/models
bitrouter cloud api /v1/chat/completions --input request.json
bitrouter cloud api /v1/responses -f model=openai/gpt-5 -F stream=truebitrouter cloud login
Sign in to BitRouter Cloud from this terminal.
Prints a verification URL — open it, approve, and this CLI stores an access token it refreshes automatically. This is the same credential the built-in bitrouter provider uses for inference, so providers login bitrouter is an alias for this command.
Usage: bitrouter cloud login [OPTIONS]
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--oauth-as <URL> | Authorization server URL. Defaults to <https://api.bitrouter.ai>; override only for a self-hosted deployment (env: BITROUTER_OAUTH_AS) |
--client-id <ID> | OAuth client id. Defaults to bitrouter-cli; override only for a self-hosted deployment (env: BITROUTER_OAUTH_CLIENT_ID) |
--human | Render the human-readable view to stdout instead of JSON |
--scope <SCOPE> | Permissions to request, as a space-delimited list. Defaults to a broad "developer" set; pass a narrower or wider list to override (env: BITROUTER_OAUTH_SCOPE) |
--api-key <BRK_API_KEY> | Authenticate with a BitRouter API key instead of OAuth. Intended for CI and other non-interactive environments |
bitrouter cloud login # device flow, pick a workspace
bitrouter cloud login --api-key "$BITROUTER_API_KEY" # CI: no network, no browserbitrouter cloud logout
Sign out: revoke the stored token at the server (best-effort) and delete the local credentials file
Usage: bitrouter cloud logout [OPTIONS]
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--oauth-as <URL> | Override the authorization server URL recorded in the credentials file for the revocation call |
--client-id <ID> | Override the recorded OAuth client id for the revocation call |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud namespace
Inspect the namespaces you own and the one this CLI is bound to
Usage: bitrouter cloud namespace [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud namespace list
List the namespaces you own. The one this CLI is signed in to is marked (active). Switching namespaces is a re-login: bitrouter cloud login and pick a different namespace in the browser
Usage: bitrouter cloud namespace list [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud namespace current
Print the namespace this CLI's credential is bound to. Offline — reads the local credential, no network call
Usage: bitrouter cloud namespace current [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud keys
Manage brk_ API keys in your namespace
Usage: bitrouter cloud keys [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud keys list
List API keys on your account
Usage: bitrouter cloud keys list [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud keys mint
Mint a new API key. The plaintext is printed once
Usage: bitrouter cloud keys mint [OPTIONS] --name <NAME>
Options
| Flag | Description |
|---|---|
--name <NAME> | Operator-supplied display name |
--human | Render the human-readable view to stdout instead of JSON |
--scope <SCOPE> | Wire-format scope tokens (repeat the flag, or pass a single space-delimited list). Must be a subset of your effective scopes |
--expires-at <EXPIRES_AT> | Optional expiry (RFC 3339, e.g. 2026-12-31T00:00:00Z) |
--json | Print the response as raw JSON instead of the human-readable summary |
Returns the plaintext brk_… token exactly once — the server keeps only the SHA-256 hash. Requested scopes must be a subset of your effective scopes.
bitrouter cloud keys mint --name ci --scope "policy:read usage:read"bitrouter cloud keys revoke
Revoke a key by id
Usage: bitrouter cloud keys revoke [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The key id (e.g. k_…) |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud usage
Read aggregate spend / token counts for your account
Usage: bitrouter cloud usage [OPTIONS]
Options
| Flag | Description |
|---|---|
--from <FROM> | Lower bound (RFC 3339). Defaults to to - 30 days |
--human | Render the human-readable view to stdout instead of JSON |
--to <TO> | Upper bound (RFC 3339). Defaults to now |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud requests
Page through recent inference requests
Usage: bitrouter cloud requests [OPTIONS]
Options
| Flag | Description |
|---|---|
--limit <LIMIT> | Page size (server clamps to [1, 100]) |
--human | Render the human-readable view to stdout instead of JSON |
--offset <OFFSET> | Offset into the result set |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud billing
Credit balance and Stripe checkout
Usage: bitrouter cloud billing [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud billing balance
Show the account's credit balance
Usage: bitrouter cloud billing balance [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud billing checkout
Start a Stripe checkout session for a credit top-up. Requires the billing:write scope
Usage: bitrouter cloud billing checkout [OPTIONS] --amount-cents <AMOUNT_CENTS>
Options
| Flag | Description |
|---|---|
--amount-cents <AMOUNT_CENTS> | Amount in USD cents |
--human | Render the human-readable view to stdout instead of JSON |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy
Generic CRUD over the typed policy registry
Usage: bitrouter cloud policy [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
--spec reads a JSON file (or - for stdin) holding the flat inner spec body — e.g. {"window": "day", "limit_micro_usd": 5000000} for a budget. effective and for-principal answer "what would happen to a request from this principal" without making an inference call. budget and preset are typed sugar over the same rows.
bitrouter cloud policy list
List policies on your account
Usage: bitrouter cloud policy list [OPTIONS]
Options
| Flag | Description |
|---|---|
--kind <KIND> | Narrow the list to one kind [possible values: budget, rate-limit, guardrail, preset] |
--human | Render the human-readable view to stdout instead of JSON |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy get
Fetch one policy
Usage: bitrouter cloud policy get [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy create
Create a policy. Spec body is read from --spec <file\|->
Usage: bitrouter cloud policy create [OPTIONS] --name <NAME> --kind <KIND> --spec <SPEC>
Options
| Flag | Description |
|---|---|
--name <NAME> | Operator-supplied display name |
--human | Render the human-readable view to stdout instead of JSON |
--kind <KIND> | Kind discriminator — selects which shape --spec must take [possible values: budget, rate-limit, guardrail, preset] |
--spec <SPEC> | Path to a JSON file containing the flat inner spec body, or - to read from stdin |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy update
Update a policy's name and / or spec
Usage: bitrouter cloud policy update [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The policy id |
Options
| Flag | Description |
|---|---|
--name <NAME> | New name. Omit to leave unchanged |
--human | Render the human-readable view to stdout instead of JSON |
--spec <SPEC> | New spec. Path to a JSON file or - for stdin. Omit to leave unchanged |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy delete
Delete a policy
Usage: bitrouter cloud policy delete [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy bind
Attach a policy to a principal
Usage: bitrouter cloud policy bind [OPTIONS] --principal-type <PRINCIPAL_TYPE> --principal-id <PRINCIPAL_ID> <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The policy id |
Options
| Flag | Description |
|---|---|
--principal-type <PRINCIPAL_TYPE> | Principal kind (namespace, api_key, oauth_token, oauth_client) |
--human | Render the human-readable view to stdout instead of JSON |
--principal-id <PRINCIPAL_ID> | Principal id — interpretation depends on --principal-type |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy unbind
Detach one binding from a policy
Usage: bitrouter cloud policy unbind [OPTIONS] <ID> <BINDING_ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The policy id |
<BINDING_ID> | The binding id (from cloud policy bindings <id>) |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy disable
Park a policy — the engine skips it at request time
Usage: bitrouter cloud policy disable [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy enable
Re-enable a previously disabled policy
Usage: bitrouter cloud policy enable [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy bindings
List the bindings of one policy
Usage: bitrouter cloud policy bindings [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud policy effective
Preview the effective policy for a principal
Usage: bitrouter cloud policy effective [OPTIONS] --principal-type <PRINCIPAL_TYPE> --principal-id <PRINCIPAL_ID>
Options
| Flag | Description |
|---|---|
--principal-type <PRINCIPAL_TYPE> | Principal kind (namespace, api_key, oauth_token, oauth_client) |
--human | Render the human-readable view to stdout instead of JSON |
--principal-id <PRINCIPAL_ID> | Principal id |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud policy for-principal
List every policy bound to a principal
Usage: bitrouter cloud policy for-principal [OPTIONS] <PRINCIPAL_TYPE> <PRINCIPAL_ID>
Arguments
| Argument | Description |
|---|---|
<PRINCIPAL_TYPE> | Principal kind |
<PRINCIPAL_ID> | Principal id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud budget
Typed wrapper over budget-kind policies
Usage: bitrouter cloud budget [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud budget list
List every budget on the account
Usage: bitrouter cloud budget list [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud budget get
Fetch one budget
Usage: bitrouter cloud budget get [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud budget create
Create a budget
Usage: bitrouter cloud budget create [OPTIONS] --name <NAME> --window <WINDOW> --limit-micro-usd <LIMIT_MICRO_USD>
Options
| Flag | Description |
|---|---|
--name <NAME> | Display name |
--human | Render the human-readable view to stdout instead of JSON |
--window <WINDOW> | Rolling-spend window [possible values: day, month, total] |
--limit-micro-usd <LIMIT_MICRO_USD> | Spend cap in micro-USD (must be strictly positive) |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud budget update
Patch a budget's fields
Usage: bitrouter cloud budget update [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The budget id |
Options
| Flag | Description |
|---|---|
--name <NAME> | New name |
--human | Render the human-readable view to stdout instead of JSON |
--window <WINDOW> | New window [possible values: day, month, total] |
--limit-micro-usd <LIMIT_MICRO_USD> | New cap (must be strictly positive when supplied) |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud budget delete
Remove a budget
Usage: bitrouter cloud budget delete [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud preset
Typed wrapper over preset-kind policies
Usage: bitrouter cloud preset [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud preset list
List every preset on the account
Usage: bitrouter cloud preset list [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud preset get
Fetch one preset
Usage: bitrouter cloud preset get [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud preset create
Create a preset. Each clause is supplied as a JSON file (or - for stdin)
Usage: bitrouter cloud preset create [OPTIONS] --name <NAME>
Options
| Flag | Description |
|---|---|
--name <NAME> | Display name |
--guardrail <GUARDRAIL> | Optional guardrail clause (JSON file or -) |
--human | Render the human-readable view to stdout instead of JSON |
--budget <BUDGET> | Optional budget clause |
--rate-limit <RATE_LIMIT> | Optional rate-limit clause |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud preset update
Patch a preset's clauses. Use --clear-* to drop a clause
Usage: bitrouter cloud preset update [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The preset id |
Options
| Flag | Description |
|---|---|
--name <NAME> | New name |
--guardrail <GUARDRAIL> | Replace the guardrail clause (JSON file or -) |
--human | Render the human-readable view to stdout instead of JSON |
--budget <BUDGET> | Replace the budget clause |
--rate-limit <RATE_LIMIT> | Replace the rate-limit clause |
--clear-guardrail | Drop the guardrail clause |
--clear-budget | Drop the budget clause |
--clear-rate-limit | Drop the rate-limit clause |
--json | Print the response as raw JSON instead of the human-readable summary |
bitrouter cloud preset delete
Remove a preset
Usage: bitrouter cloud preset delete [OPTIONS] <ID>
Arguments
| Argument | Description |
|---|---|
<ID> | The resource id |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud byok
Bring-your-own-key provider keys
Usage: bitrouter cloud byok [OPTIONS] <COMMAND>
Options
| Flag | Description |
|---|---|
-j, --json | Force JSON output (the default; agent-native). Conflicts with --human |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud byok list
List every BYOK row on the account
Usage: bitrouter cloud byok list [OPTIONS]
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
bitrouter cloud byok set
Upsert a BYOK row. Ciphertext must be sealed by the caller against the cloud's current X25519 public key
Usage: bitrouter cloud byok set [OPTIONS] --provider <PROVIDER> --ciphertext-b64 <CIPHERTEXT_B64> --kek-id <KEK_ID> --key-prefix <KEY_PREFIX>
Options
| Flag | Description |
|---|---|
--provider <PROVIDER> | Upstream provider id (e.g. anthropic) |
--ciphertext-b64 <CIPHERTEXT_B64> | Base64-encoded sealed-box ciphertext |
--human | Render the human-readable view to stdout instead of JSON |
--kek-id <KEK_ID> | KEK id used to seal --ciphertext-b64. Must match the cloud's current primary_kek_id |
--key-prefix <KEY_PREFIX> | Operator-visible prefix of the underlying plaintext |
--api-base <API_BASE> | Override API base for the provider |
--json | Print the response as raw JSON instead of the human-readable summary |
Ciphertext must be sealed against the cloud's current X25519 public key before submission — the server only stores already-encrypted bytes. Fetch the current key from GET /v1/byok/encryption-pubkey first.
bitrouter cloud byok delete
Remove a BYOK row by provider id
Usage: bitrouter cloud byok delete [OPTIONS] <PROVIDER>
Arguments
| Argument | Description |
|---|---|
<PROVIDER> | Provider id (the row's provider_name) |
Options
| Flag | Description |
|---|---|
--json | Print the response as raw JSON instead of the human-readable summary |
--human | Render the human-readable view to stdout instead of JSON |
How is this guide?