Command reference

Run beacon --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

Opens your browser to sign in via Clerk and pick an org, then saves the resulting token to ~/.config/roboflare/credentials.toml. The CLI binds an ephemeral port on 127.0.0.1 to receive the one-time authorization code.

Flag	Default	Notes
`--token <token>`	(browser flow)	Skip the browser. Also reads `BEACON_TOKEN`.
`--base-url <url>`	`https://beacon-api.canlearn.workers.dev`	Persisted alongside the token.
`--portal-url <url>`	Same as `--base-url`	Override when dashboard and API differ.
`--no-browser`	off	Print the authorization URL instead of opening.

`beacon logout`

Deletes the local credentials file. Does not revoke the token server-side.

`beacon agent`

Runs this machine as a Beacon robot agent — useful for demos and dev loops without shipping a separate agent binary.

Subcommand	Notes
`run [--enrollment-key …] [--name …] [--fresh] [--heartbeat-seconds N]`	Calls `POST /agent/enroll` (first run only), then opens `WS /agent/ws` and sends heartbeats until Ctrl-C. Identity is cached at `~/.config/roboflare/agent.toml`. `--fresh` forces re-enrollment. Heartbeat default `10`.
`forget`	Removes the cached robot identity on this machine.

--enrollment-key also reads BEACON_ENROLLMENT_KEY. --backend-url overrides the URL stored at login. Auto-reconnects with exponential backoff (1s → 30s) when the connection drops.

`beacon 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)

`beacon 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`.

`beacon deploy`

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

`beacon 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.

`beacon sites`

Subcommand	API call
`list`	`GET /api/sites`
`create <name>`	`POST /api/sites`

`beacon fleets`

Subcommand	API call
`list`	`GET /api/fleets`
`create <name> --site <id>`	`POST /api/fleets`
`logs <id>`	`GET /api/fleets/<id>/logs`

`beacon 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 --json to capture the API response body.

Configuration files

~/.config/roboflare/credentials.toml — written by beacon login:

token    = "rf_user_..."
base_url = "https://beacon-api.canlearn.workers.dev"

~/.config/roboflare/agent.toml — written by beacon agent run on first enrollment, reused by subsequent runs:

backend_url  = "https://beacon-api.canlearn.workers.dev"
robot_id     = "..."
robot_token  = "rf_robot_..."
robot_name   = "warehouse-bot-01"
org_id       = "..."
site_id      = "..."
fleet_id     = "..."

Edit by hand to switch environments (staging, self-hosted), or just beacon login again with the new backend.

Command reference

On this page