CLI
Command reference
Every rf command, its flags, and the API path it calls.
Run rf --help or any command with --help for clap-generated output.
This page is the curated reference with the underlying API endpoint for
each command.
Global flags
| Flag | Effect |
|---|---|
--json | Emit raw JSON instead of human-formatted output |
--base-url <URL> | Override the configured API base URL for this call |
--help | Print usage for the current command |
rf login
Saves a portal token to ~/.config/roboflare/credentials.toml.
| Flag | Default | Notes |
|---|---|---|
--token <token> | (interactive prompt) | Pass non-interactively for scripts/CI |
--base-url <url> | https://api.roboflare.com | Persisted alongside the token |
rf logout
Deletes the local credentials file. Does not revoke the token server-side.
rf robots
| Subcommand | API call | Notes |
|---|---|---|
list | GET /api/robots | All robots in your org |
inspect <id> | GET /api/robots/<id>/health | Latest health snapshot |
logs <id> [--follow] | GET /api/robots/<id>/logs or WS /api/robots/<id>/logs/ws | Without --follow returns the latest batch. With --follow opens the live WebSocket stream until Ctrl-C; prints agent offline if the robot isn't connected. |
timeline <id> | GET /api/robots/<id>/timeline | Audit timeline (connects, deploys, configs) |
rf releases
| Subcommand | API call | Notes |
|---|---|---|
list | GET /api/releases | |
push <path> [--tag] [--notes] [--kind] | POST /api/releases | Reads the file to compute artifact_sha256 and artifact_size. --tag defaults to the filename stem, --kind defaults to container_image. |
rf deploy
rf deploy <release> (--robot <id> | --fleet <id>) [--watch] [--scheduled-at <ts>] [--idempotency-key <uuid>]| Flag | Notes |
|---|---|
--robot <id> / --fleet <id> | Required, mutually exclusive. Picks target_kind. |
--watch | After creating, polls /api/deployments/<id>/events every 2s until terminal status (applied, failed, rolled_back, cancelled). |
--scheduled-at <rfc3339> | Defers dispatch until the timestamp. |
--idempotency-key <uuid> | Pass the same value to safely retry. Defaults to a fresh UUIDv4. |
Calls POST /api/deployments with the required Idempotency-Key header.
rf configs
| Subcommand | API call |
|---|---|
list | GET /api/configs |
set <key> <value> [--namespace] [--fleet <id> | --robot <id>] | POST /api/configs and (if --fleet/--robot) POST /api/configs/deployments with an autogenerated idempotency key |
deployments | GET /api/configs/deployments |
events <id> | GET /api/configs/deployments/<id>/events |
set parses <value> as JSON; if parsing fails it treats it as a string.
rf sites
| Subcommand | API call |
|---|---|
list | GET /api/sites |
create <name> | POST /api/sites |
rf fleets
| Subcommand | API call |
|---|---|
list | GET /api/fleets |
create <name> --site <id> | POST /api/fleets |
logs <id> | GET /api/fleets/<id>/logs |
rf keys
| Subcommand | API call |
|---|---|
list | GET /api/enrollment-keys |
new --site <id> --fleet <id> [--label] [--max-uses] [--expires-in-hours] | POST /api/enrollment-keys. Response includes the raw rf_enroll_<hex> value — shown once. |
revoke <id> | POST /api/enrollment-keys/<id>/revoke |
--expires-in-hours 0 sets the key to never expire.
Exit codes
0— success- non-zero — any error. The CLI prints a human message on stderr; pair
with
--jsonto capture the API response body.
Configuration file
~/.config/roboflare/credentials.toml:
token = "rf_org_..."
base_url = "https://api.roboflare.com"Edit by hand to switch environments (staging, self-hosted), or just
rf login again with the new token.