CLI reference

rb is the razorBridge command-line client. It is a standalone Python package (rb-cli) that talks to the REST API; anything the CLI can do you can also do with an HTTP call.

Install and update

pipx install rb-cli          # recommended
pipx upgrade rb-cli

pip install rb-cli works too. Python 3.11 or newer is required.

Global options

These belong to rb itself, so they go before the subcommand (rb --json credits, not rb credits --json).

Option	Effect
--version, -V	Print the client version and exit
--json	Emit one clean JSON document instead of a table, for the commands that return data
--verbose, -v	Log the underlying HTTP requests — the first thing to try when a command misbehaves
--help	Show help. Also works on any subcommand
--install-completion	Install tab completion for your shell (bash, zsh, fish, PowerShell)
--show-completion	Print the completion script instead of installing it

--json is honoured by rb status, rb doctor, rb auth status, rb event list, rb blade list, rb credits, rb gate keys list, rb gate usage and rb gate models. Interactive commands (ssh, run, scp, config, gate test, quickstart) always print for humans.

Configuration

What	Where
Credentials	~/.config/rb/token, JSON, created with 0600 permissions
Optional settings	~/.config/rb/config.json, with an api_url key
API address override	The RB_API_URL environment variable, which wins over both files

export RB_API_URL=https://api.razorbridge.eu/v1

Caution

Set RB_API_URL as shown. The default compiled into the current release points at an API path that no longer exists, so without it every command fails to connect.

The CLI warns, in the manner of ssh, if the token file is readable by anyone else; fix it with chmod 600 ~/.config/rb/token.

Access tokens last one hour and are refreshed automatically for up to 30 days. When a refresh fails, the stored credentials are cleared and you are told to run rb auth login again.

Command summary

Command	Purpose
rb status	Overview of blades, events and balance
rb doctor	Check local setup and API connectivity
rb quickstart	Guided first-run walkthrough
rb auth login	Sign in through the browser
rb auth logout	Sign out and revoke sessions
rb auth status	Who you are, which account, what balance
rb event list	Events you participate in or organize
rb event join	Join an event with its code
rb event info	Event detail, including your blade
rb blade list	Your blades
rb blade status	One blade in detail, with time remaining
rb blade ssh	Open a shell on a blade
rb run	Run one command on a blade
rb blade config	Print an SSH config block
rb blade scp	Copy files to or from a blade
rb credits	Balance and transaction history
rb gate keys list	Inference gate keys
rb gate keys create	Create a gate key
rb gate keys revoke	Revoke a gate key
rb gate test	Send one inference request
rb gate usage	Inference usage history
rb gate models	Available model ids

Commands exit 0 on success and 1 on error. rb blade ssh and rb run exit with the remote command’s own exit code.

Everything except rb doctor requires a signed-in session; without one you get Not logged in. Run: rb auth login.

---

Overview and diagnostics

rb status

rb status

Prints your email, account name and balance, then a table of running blades (id, GPU, IP, event) and a table of events whose status is upcoming, active or running. Says so plainly when either list is empty.

rb doctor

rb doctor

Reports the client version, the API address in use, the credentials path, whether you are signed in, and whether the API answered — then exits 1 if it could not be reached. It does not need authentication and never touches your stored tokens, so it is safe to run when things are broken. Any HTTP response, including a 401, counts as reachable.

rb quickstart

rb quickstart

Walks a new user through signing in, optionally joining an event by code, and connecting to a blade, then prints a short list of what to try next. Everything it does is available as an individual command.

---

Authentication

rb auth login

rb auth login

Starts the browser-based device flow: prints a verification URL and an eight-character code, opens your browser, and polls until you approve. Type the code on the page that opens.

The code is valid for 15 minutes; the CLI gives up after 5 and tells you to try again. On success it stores the tokens and prints the signed-in email.

rb auth logout

rb auth logout

Revokes your sessions server-side and deletes the local token file. Revocation applies to all of your CLI sessions, on every machine. Local credentials are removed even if the server call fails.

rb auth status

rb auth status

Prints email, name, account and balance. Add --json for the same data as an object.

---

Events

rb event list

rb event list

One table combining events you participate in and events you organize, with columns for slug, name, status, your role, start time and join code. The join code is only present for events you organize.

rb event join

rb event join CODE

Registers you for the event with that join code — four letters, a hyphen, four digits, not case-sensitive. Joining does not create a blade; the event’s schedule does that shortly before its start time.

Fails if the code is unknown (Event not found), if registration has closed (Registration closed), if the participant cap is full (Event is full), or if you have already joined (Already registered).

rb event info

rb event info SLUG

Prints the event’s name, slug, status, GPU type, start and end times, join code, and — once one exists — your blade’s id, GPU, status, IP and time remaining.

Note

Despite the help text, this takes the event slug (as shown by rb event list), not the join code. A join code returns Event not found.

---

Blades

Every blade command takes an optional blade id and defaults to your most recent running blade when you omit it. With no running blade, the CLI says so and, if you have one coming, names your next event.

rb blade list

rb blade list

Table of every blade assigned to you: id, GPU, status, IP and event. Statuses are explained in GPU blades and sessions.

rb blade status

rb blade status [BLADE_ID]

Detail for one blade — GPU, status, IP, region, time remaining (for event blades, derived from the event’s end time) and the event name.

rb blade ssh

rb blade ssh [BLADE_ID]

Opens an interactive SSH session. Host-key checking is disabled, because blades are ephemeral. If sshpass is on your PATH the password is supplied for you; otherwise it is printed for you to paste. Exits with ssh’s exit code.

Fails with Credentials not yet assigned if the blade is not ready, and Blade has no IP address if it has not been given one yet.

rb run

rb run COMMAND [--blade BLADE_ID]

Runs one command on the blade over SSH, streams the output, and exits with the command’s exit code. Quote anything containing spaces.

rb run nvidia-smi
rb run "python train.py --epochs 10"

Option	Effect
--blade, -b	Target a specific blade instead of the most recent running one

rb blade config

rb blade config [BLADE_ID]

Prints an SSH Host block for ~/.ssh/config, using the alias rb- plus the first eight characters of the blade id, and then the password. It prints only — copy it in yourself. With the block in place, ssh rb-abc12345, VS Code Remote-SSH, JetBrains Gateway, scp and rsync all work; each will ask for the password, since blade access is password-based.

rb blade scp

rb blade scp SRC [DST] [--blade BLADE_ID]

Copies files with scp. A source containing : that does not begin with / is treated as a path on the blade; otherwise the copy goes to the blade. Omitting DST uploads to your home directory on the blade, or downloads into the current directory.

rb blade scp ./train.py                        # → ~/train.py on the blade
rb blade scp ./train.py ~/work/train.py        # → an explicit path on the blade
rb blade scp blade:~/results/metrics.json ./   # ← download one file

sshpass, if installed, avoids the password prompt. Requires scp on your PATH.

Note

This copies files, not directories — no recursive flag is passed through. For a whole directory, add an SSH config block with rb blade config and then use scp -r or rsync -avP against the rb-… alias.

---

Credits

rb credits

rb credits
rb --json credits

Prints the balance, then the most recent ledger entries with date, type, description, source, amount and balance after. Amounts are formatted in European style (€1.234,56). Sources are explained in Credits and billing.

---

Inference gates

rb gate keys list

rb gate keys list

Active keys with id, name, visible prefix, creation date and last use. Full key values are never retrievable.

rb gate keys create

rb gate keys create NAME

Creates a key and prints it once. Store it immediately. Model restrictions and budget caps are not settable here — see Inference gates.

rb gate keys revoke

rb gate keys revoke KEY_ID

Deactivates the key immediately. Use the id from rb gate keys list, not the key itself.

rb gate test

rb gate test [MESSAGE] [--model MODEL]

Sends a single chat completion using your CLI session rather than a gate key, and prints the model, token counts and the reply. Defaults to "Hello, GPU!" and the klusai/fast model.

Option	Effect
--model, -m	Model id to use

It is billed like any other inference call, and returns HTTP 402 if your balance is empty.

rb gate usage

rb gate usage

Recent inference calls with date, model, prompt and completion tokens, and cost in euros.

rb gate models

rb gate models

Intended to list available model ids.

Caution

This currently fails with Invalid API key: the models endpoint expects an inference gate key, while the CLI sends your login session. Use the curl form until the client is fixed.

Related pages

• Quickstart — the commands in the order you first need them.
• API reference — the endpoints behind each command.
• Troubleshooting — errors and their causes.