CLI overview

beacon is a single-binary Rust CLI that wraps the Beacon control plane. Every dashboard mutation has a CLI equivalent, and every CLI call is a plain HTTP request you could make yourself.

Install

See Install the CLI. The short version: build from source with cargo build --release and copy the binary into /usr/local/bin/.

Command groups

beacon login                                Browser sign-in (or --token for CI)
beacon logout                               Clear local credentials
beacon sites    list|create                 Sites
beacon fleets   list|create|logs            Fleets and aggregated fleet logs
beacon keys     list|new|revoke             Enrollment keys
beacon robots   list|inspect|logs|timeline  Read-only robot operations
beacon releases list|push                   Release artifacts
beacon deploy   <release> --robot|--fleet   Ship a release to a robot or fleet
beacon configs  list|set|deployments|events Config blobs and rollouts
beacon agent    run|forget                  Run this machine as a robot agent

Every command supports --json for machine-readable output, which makes beacon safe to pipe into jq, GitHub Actions, or your own automation.

Authentication

beacon reads credentials from ~/.config/roboflare/credentials.toml. The file is created by beacon login and contains the token plus base URL:

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

beacon login opens your browser to sign in via Clerk and pick an org; pass --token (or set BEACON_TOKEN) for non-interactive flows. Edit the file directly to point at a self-hosted control plane.

Scripting patterns

Wait until a robot is online before deploying:

while ! beacon robots list --json | jq -e '.[] | select(.id == "'"$ROBOT"'") | .last_seen_at'; do
  sleep 2
done
beacon deploy "$RELEASE" --fleet "$FLEET"

Drive a CI rollout:

beacon releases push ./robot-app.tar --tag "$GITHUB_SHA"
release_id=$(beacon releases list --json | jq -r '.[0].id')
beacon deploy "$release_id" --fleet canary

Snapshot fleet state into a build log:

beacon robots list --json | jq '.[] | {id, name, last_seen_at, fleet_id}' > fleet.json

Limits in v0

beacon is intentionally narrow. A few flows still need the dashboard or direct API calls:

• Inviting org users — use the dashboard's user management page or POST /api/org-users.
• Shell and camera streams — the WebSocket endpoints exist (/api/robots/<id>/shell/ws, /api/robots/<id>/camera/ws) but the CLI doesn't wrap them yet; use the dashboard.

See the command reference for the full surface.