CLI

The Burrowee CLI is the client you connect from. It is a small binary (burrowee-cli) with two jobs: it pairs your machine with a gateway, and it acts as a local forwarder — it listens on a local TCP port, opens an encrypted carrier to a relay, completes the per-service end-to-end handshake with the gateway, and pipes your local connection through. Ordinary tools like ssh, curl, or your browser just talk plain TCP to localhost; the CLI owns the transport and the crypto.

You normally reach it as burrowee …: the bare burrowee command is the universal dispatcher, which forwards anything it doesn't recognize to burrowee-cli. Everything on these pages works the same whether you type burrowee connect or burrowee-cli connect.

Commands at a glance

Command	What it does
bootstrap [<blob>] [<pin>]	First-time setup: pair with a gateway (secrets on argv or via --blob-file/--pin-file)
connect --svc <s> [flags]	Forward a local TCP port through a relay to a service
open --svc <s> <host>[@<relay>]	Forward to a host named in the <svc>_config alias file
ssh --svc <s> [ssh args…]	Connect, then exec ssh against the forwarded port
daemon [--config <path>] [--socket <path>]	Run the long-running transport daemon (unix only)
relays <list|use|rm|gateway|pair|probe|ping|rename|reset>	Manage the relay axis of the matrix
gateways <list|use|rm|relays|bridges|resync|rename>	Manage the gateway axis of the matrix
routes [--json] [--config <path>]	Print the whole matrix (--json is the schema-2 export)
fingerprint <path|list|validate|enable|disable>	Inspect and control the opt-in browser TLS/HTTP disguise
doctor [--fix] [--yes]	Unified health report (--fix: thin remediations, incl. starting a down daemon)
service <install|status>	Install or inspect the managed daemon service (system unit)
status	Read-only alias of doctor (no --fix; always exits 0)
stats [--json]	Show the daemon's carrier-pool snapshot
restart	Restart the managed daemon service
update [flags]	Update to the latest release (applies without prompting)
updater <update|upgrade|reinstall|status|doctor|version>	The update system — forwards to the co-located updater binary
reinstall	Offline repair-to-current (shortcut for updater reinstall)
login [--console <url>] [--label <str>]	Authorize this device with the console
download-url [--console <url>] <comp> <version> <artifact>	Resolve a gated release-download URL
uninstall [--purge]	Remove the managed service and back up (--purge: delete) the state
version	Print the versions block
docs	Print the full CLI reference as markdown

Run burrowee --help to see this list plus every flag in your terminal, or burrowee docs to print the complete reference (every command's own page) as markdown — handy for grepping or feeding to an AI agent.

Help works the same at every level: a bare parent verb (burrowee service, burrowee updater, burrowee fingerprint) prints its own help page and exits 0 — except relays and gateways, where the bare form runs list. burrowee help <verb> is forwarded as <verb> --help. A malformed invocation — unknown verb, bad flag, stray argument — never runs anything else silently: it exits 2 with the help page for the level above the mistake on stderr.

Signing in (login and download-url)

Almost everything above never talks to the cloud console — connect/ssh/relays/gateways reach your gateway only through a relay. Two verbs are the exception, and both exist to support gated release downloads (an install script fetching one specific artifact):

burrowee login [--console <url>] [--label <str>]

login creates (or reuses) a device identity key at ~/.burrowee/cli/identity/device.key, opens the console's device-authorization page in your browser (and prints the URL, for headless machines), then polls for up to about 3 minutes waiting for you to approve the device. --label sets the name shown next to the pending device in the console (default: your hostname); --console points at a non-default console (default https://console.burrowee.com).

burrowee download-url [--console <url>] <component> <version> <artifact>

Once you're logged in, download-url signs a request with your device key and prints a presigned, time-limited download URL for the named release artifact to stdout. This is what an installer calls under the hood via $(...) when a release is gated — you won't normally run it by hand. Without a prior login, it fails with a pointer back to it.

Where the CLI keeps its state

Everything lives in one directory, ~/.burrowee/cli/, seeded by bootstrap. There are no environment variables to set.

File	Contents
config.json	The relay matrix (schema v4): every paired gateway with its own relay membership — a system path, a set of edges, and optionally a default edge — plus the shared relay catalog and the global default gateway. Everything a pairing needs is stored inline here — there are no sidecar files.
client.key	Your client's own identity key, generated on first use and shared across every paired gateway
identity/device.key	Only present after login: this device's identity key, used to authorize gated release downloads
ssh_config, <svc>_config	Optional, yours to edit: OpenSSH-format host aliases read by ssh and open (e.g. vnc_config for open --svc vnc)
fingerprints.json	Optional: the opt-in browser TLS/HTTP disguise config (burrowee fingerprint path prints the path; enable/disable flip it)
sockets/, logs/	The daemon's transport socket and its log files (daemon.err.log lines are timestamped)

You rarely need to touch the state by hand: connect and ssh read config.json automatically, and the relays/gateways verbs rewrite it for you. uninstall backs the whole directory up when you want it gone.

Where to next

1. Bootstrap — pair with your gateway.
2. Connect & SSH — open your first session.
3. Daemon & service — keep a warm connection running in the background.
4. Relays — manage multiple gateways and relays, and read the route matrix.
5. Updates — keep the CLI itself current.