Commands

Complete command reference, one section per user-facing binary: the burrowee dispatcher, burrowee-cli (plus its gateways/relays axis sub-helps), burrowee-gateway + burrowee-gateway-cli + burrowee-register, burrowee-edge + burrowee-edge-cli, and the three per-component updaters. Every block below is the verbatim --help output of the binary named in its heading — run it yourself to confirm. The hosted relay is an internal component with no end-user command surface and is intentionally omitted.

• burrowee — the dispatcher
• burrowee-cli
  • burrowee gateways — the gateway axis
  • burrowee relays — the relay axis
• burrowee-gateway, burrowee-gateway-cli & burrowee-register
  • burrowee-gateway — the daemon
  • burrowee-gateway-cli — operator verbs
  • burrowee-register
• burrowee-edge & burrowee-edge-cli
  • burrowee-edge — the daemon
  • burrowee-edge-cli — setup + lifecycle
• Updaters (cli, gateway, edge)
  • burrowee-cli-updater
  • burrowee-gateway-updater
  • burrowee-edge-updater

burrowee — the dispatcher

The bare burrowee command is a near-zero-logic dispatcher: a reserved first word maps to a component binary, which is exec'd in place (a true process replacement — the component's exit code is your exit code). Anything that isn't a reserved word falls through to burrowee-cli untouched, which is why burrowee connect --svc 22 and burrowee cli connect --svc 22 are the same command.

burrowee — the Burrowee command. Dispatches to installed components.

Usage:
  burrowee <component> [args]      run a component
  burrowee <component> cli [args]  run a component's setup cli (e.g. burrowee-edge-cli)
  burrowee <anything-else> [args]  runs burrowee-cli <anything-else> …
  burrowee version, --version      print the dispatcher version
                                   (component versions: burrowee <component> version)

Components:
  cli       client tunnels (connect, ssh, daemon, relays, gateways)
  gateway   the home gateway daemon + local console
  relay     the system relay server
  edge      self-hosted edge relay
  console   the cloud control plane server
  register  register a local service with the gateway

Run 'burrowee <component> --help' for component commands.

For edge and gateway, the dispatcher also splits which binary a verb reaches: a small set of runtime verbs routes to the serving daemon (run/serve/update/version for gateway, run/update/version for edge); every other verb routes to the component's -cli sibling instead. That is the whole mechanism behind lines like "burrowee gateway status ⇔ burrowee-gateway-cli status" elsewhere on this page — status isn't in gateway's runtime set, so the dispatcher sends it straight to burrowee-gateway-cli. You can also force the -cli binary explicitly with the <component> cli infix, e.g. burrowee edge cli --help.

Exit codes:

Code	Meaning
(component's own)	The dispatched component ran; its exit code passes through unchanged
0	A dispatcher intrinsic (--help, -h, help, version, --version) was handled
126	The target binary was found but could not be exec'd
127	The target component is not installed on this machine — stderr lists what is installed here and where to get the missing component

burrowee-cli

The client and local-forwarder bridge: it listens on a local TCP port, opens a carrier to a relay, completes the per-service end-to-end encryption with the gateway, and pipes your local connection through. Everything below dispatches via the bare burrowee command too — burrowee connect --svc 22 ⇔ burrowee-cli connect --svc 22 (no cli infix needed; cli has no runtime/-cli split).

burrowee — the Burrowee client + local-forwarder bridge

Usage:
  burrowee [command] [flags]

Commands:
  bootstrap [--label <name>] [--home <dir>] <blob> <pin>
                               first-time setup: pair with a gateway
  connect --svc <s> [flags]    forward a local TCP port through the relay to a service
  ssh <host>[@<relay>] [args]  connect a named host from ~/.burrowee/cli/ssh_config, then exec ssh
  ssh --svc <s> [ssh args…]    connect then exec ssh against the forwarded port (explicit-flag form)
  ssh list                     list configured hosts from ~/.burrowee/cli/ssh_config
  daemon [--config <path>] [--socket <path>]
                               run the long-running transport daemon (unix only)
  relays <list|use|rm|gateway|pair|probe|ping>
                               manage relays (`burrowee relays --help` for sub-commands)
  gateways <list|use|rm|relays|bridges|resync>
                               manage gateways (`burrowee gateways --help` for sub-commands)
  routes [--json] [--config <path>]
                               print the gateway×relay matrix (--json: stable contract for an extension app; --config: override config.json path)
  update [--dry] [--auto] [--force] [--no-restart] [--version <v>] [--console <url>]
                               update to the latest release (--dry: show only; --auto: no prompt; --force: reinstall even if current; --no-restart: skip service restart; --version: pin/rollback to an exact public version; --console: catalog base URL, used with --version)
  login [--console <url>] [--label <str>]
                               authorize this device with the console (creates ~/.burrowee/cli/identity/device.key, opens browser, polls for approval)
  download-url [--console <url>] <comp> <version> <artifact>
                               resolve a gated cloud-storage presigned download URL (requires prior login; prints the URL to stdout)
  doctor [--fix] [--yes] [--config <path>]
                               run read-only health checks (--fix: thin remediations)
  service <install|status>     install or inspect the managed daemon service
  status                       summarize the service, daemon and version state
  restart                      restart the managed daemon service
  uninstall [--purge]          back up state + clear the socket (--purge deletes all)
  version                      print the version

Connect/ssh flags:
  --svc <name>          service name, e.g. "22" (required)
  --local <addr>        local listen address (default 127.0.0.1:0)
  --relay <url|id>      relay WebSocket URL or matrix relay id; default from config
  --relay-quic <addr>   relay QUIC address (host:port); default from config, empty disables QUIC
  --transport <mode>    transport mode: auto|ws|quic (default auto; ws = WSS-only, no QUIC)
  --isolated            request isolated transport (dedicated conn per local connection); the gateway-advertised mode is authoritative
  --warm <n>            pre-dialed dedicated-conn depth toward the entry edge for an isolated service (0 = default)
  --handshake <dur>     max time for the initial cold connection setup before giving up (default 30s; 0 = no limit)
  --gw <id>             gateway id (matrix gateway); default from config
  --gw-pub <file>       gateway ed25519 public key (hex file); default from config
  --psk <file>          pairing PSK file; default from config
  --config <path>       config.json path (default ~/.burrowee/cli/config.json)

Host aliases (~/.burrowee/cli/ssh_config, OpenSSH format):
  Host <alias> blocks carry burrowee routing in #@ comments:
    #@gateway <name|id>   (default: the Host alias)
    #@service <name>      (default: ssh)
    #@relay   <id|host>   (repeatable; order = priority; override with <alias>@<relay>)
  All other keywords (User, IdentityFile, IdentitiesOnly, …) are read by ssh via -F.

Uninstall flags:
  --purge               delete the cli home and all prior backups (default: back up)
  --home <dir>          cli state dir to uninstall (default ~/.burrowee/cli)
  --config <path>       config.json path; its parent dir is used as the home

Relays/gateways flags:
  --config <path>       config.json path (default ~/.burrowee/cli/config.json)
  --socket <path>       transport IPC socket path (default ~/.burrowee/cli/sockets/transport.sock)

relays use works even when the daemon is down

relays use <id> writes the new default to config.json first, then attempts IPC; if the daemon is down it prints a warning and exits 0 — the preference is still persisted. relays list/gateways list/routes all read config.json directly and need no daemon. Only relays probe and relays ping need a running daemon — everything else (use, rm, pair, resync, …) edits config.json then best-effort pokes the daemon, exiting 0 even if it's down.

Exit codes: 0 success, 1 runtime failure, 2 usage error (unknown command, missing arguments).

burrowee gateways — the gateway axis

The CLI's config is a gateway×relay matrix: one client can be paired with several gateways, each reachable over several relays. gateways manages the gateway axis; relays (below) manages the relay axis. Both dispatch the same way as any other cli verb: burrowee gateways list ⇔ burrowee-cli gateways list.

burrowee gateways — manage gateways (the matrix's gateway axis)

Usage:
  burrowee gateways [list]                          list gateways (id, name, relay count, default relay, default *)
  burrowee gateways use <id>                        set the default gateway
  burrowee gateways rm <id>                         remove a gateway and its edges
  burrowee gateways relays [<gw>]                   list a gateway's relays (omit <gw> → the default gateway)
  burrowee gateways relays [<gw>] default <relay>   set a gateway's default relay (id, host, or wss origin;
                                                    must be an existing edge). Replaces `gateways set-relay`.
  burrowee gateways bridges [<gw>]                  list a gateway's bridges (entry origin, end, cli-path;
                                                    omit <gw> → the default gateway)
  burrowee gateways resync [<gw-id-or-name>]        full-mirror each gateway's relay set from the live gateway
                                                    (omit to resync all; per-gateway failures are non-fatal)
  burrowee gateways rename <id|name> [<new-name>]   set/clear a LOCAL gateway name (never synced to console; omit name to clear)

burrowee relays — the relay axis

burrowee relays — manage relays (the matrix's relay axis)

Usage:
  burrowee relays [list]                            list configured relays (id, name, kind, origin, lan, default *)
  burrowee relays use <id|host>                     set the default relay
  burrowee relays rm <id|host>                      remove a relay and its edges
  burrowee relays gateway [<relay>]                 list a relay's gateways (omit <relay> → the default relay)
  burrowee relays gateway [<relay>] default <gw>    set a relay's default gateway (id or name;
                                                    must be an existing edge). Replaces `relays set-gateway`.
  burrowee relays pair <blob> <pin>                 pair a console-minted relay (adds it to the default gateway)
  burrowee relays probe [--json]                    per-relay connection state
  burrowee relays ping [<relay>|all] [<gw>] [--transport <mode>]
                                                    E2E application-layer ping (--transport: auto|ws|quic, default auto)
  burrowee relays rename <id|host|name> [<new-name>]   set/clear a LOCAL relay name (never synced to console; omit name to clear)

burrowee-gateway, burrowee-gateway-cli & burrowee-register

The home gateway (NAT tunnel endpoint) is three binaries: burrowee-gateway serves the daemon and nothing else; burrowee-gateway-cli carries every operator verb (setup, status, service management, targets); burrowee-register is a small helper that registers one local TCP service with a running gateway. The dispatcher's serving-set for gateway is {run, serve, update, version, --version} — everything else routes to burrowee-gateway-cli automatically, so burrowee gateway status ⇔ burrowee-gateway-cli status, burrowee gateway bootstrap … ⇔ burrowee-gateway-cli bootstrap …, and bare burrowee gateway (no verb) serves the daemon ⇔ burrowee-gateway.

burrowee-gateway — the daemon

burrowee-gateway — the Burrowee home gateway (NAT tunnel endpoint)

Usage:
  burrowee gateway [command] [flags]

Commands:
  (none)                    serve the gateway daemon
  bootstrap <blob> <pin>    first-time setup: persist relays + enroll, then
                            set up + start the service and open the console
  relays list               list this gateway's configured relays
  relays local <id|host:port> on|off
                            mark a relay as on the same host (loopback-first)
  relays pair <blob> <pin>  pair a console-minted relay into this gateway
  console                   open the local console in the browser
  target list|add|remove    manage relay-exposed local services
  target console enable|disable  expose/un-expose the local console via the relay
  status                    show service + live gateway status
  doctor [--fix] [--yes]    diagnose identity/service/relay/console; --fix the service
  service install|status    manage the launchd/systemd unit
  uninstall [--purge]       remove the service; back up (or --purge) config+state
  restart                   restart the managed service
  update [--dry] [--auto] [--force] [--no-restart]
         [--version <stamp>] [--console <url>]
                            update to the latest release; --dry checks only,
                            --auto skips the prompt, --force re-installs even
                            when already up to date, --no-restart skips service restart;
                            --version pins/rolls back to a specific release from the
                            console catalog; --console overrides the console base URL
                            (default https://console.burrowee.com)
  push allow|stop|status    enable or disable cloud push-updates (live, no restart needed)
  version                   print the version

Serve flags:
  --home <dir>   --console off   --no-open

Config:
  <home>/config — console_port=<n>          (loopback console port, default 16518)
              allow_push_update=false   (opt out of console-driven remote push-updates; default true)

Everything except the bare serve form, update, and version above is really implemented in burrowee-gateway-cli — the daemon's help lists every verb for orientation, but the daemon itself rejects a non-runtime verb (unknown command, exit 2); it's the burrowee dispatcher that routes those verbs to burrowee-gateway-cli. See that binary's own help immediately below for the canonical list.

burrowee-gateway-cli — operator verbs

burrowee-gateway-cli — operator subcommands for burrowee-gateway

Usage:
  burrowee-gateway-cli <verb> [args…]

Runtime (served by burrowee-gateway):
  run | serve                  run the gateway daemon (default when no verb given)
  update [--version <stamp>] [--console <url>]
                                self-update from the console catalog

Verbs:
  bootstrap                    first-time setup: persist relays + enroll, start service, open console
  relays list                  list this gateway's configured relays
  relays local <id|h:p> on|off mark a relay as on the same host (loopback-first)
  relays pair <blob> <pin>     ingest a console-minted relay-add blob
  console                      open the local console in the browser
  target list|add|remove       manage relay-exposed local services
  target console enable|disable expose/un-expose the local console via the relay
  status                       show service + live gateway status
  doctor [--fix] [--yes]       diagnose identity/service/relay/console; --fix the service
  service install|status       manage the launchd/systemd unit
  uninstall [--purge]          remove the service; back up (or --purge) config+state
  restart                      restart the managed service
  push allow|stop|status       enable or disable cloud push-updates
  updater [run|update]         run the updater agent / update the updater binary

  help        show this message
  version     print version information

Run 'burrowee-gateway-cli <verb> --help' for verb-specific flags.

burrowee gateway console opens the local console in your browser; the console itself is a separate burrowee-gateway-console process the daemon supervises as a child (the microkernel split — see Config homes & files for its socket). The updater verb wraps the standalone burrowee-gateway-updater agent (see Updaters below): burrowee gateway updater run ⇔ burrowee-gateway-cli updater run ⇔ burrowee-gateway-updater run. updater status and updater doctor pass straight through to the agent too, so burrowee gateway updater doctor renders the same updater-health block as the standalone binary.

burrowee-register

burrowee-register — register a TCP service with the Burrowee gateway

Usage: burrowee register [-sock <register.sock>] -name <svc> -target <host:port>
Flags: -sock  gateway register unix socket path (default ~/.burrowee/gateway/sockets/register.sock)
       -name  service name to register
       -target  TCP address to bridge opened streams to (host:port)

register is its own dispatcher table entry with no daemon/-cli split, so it keeps the dispatcher's plain pass-through: burrowee register -name web -target 127.0.0.1:8080 ⇔ burrowee-register -name web -target 127.0.0.1:8080. Note its flags use a single dash (Go's flag package convention) — unlike every other binary on this page.

Exit codes (gateway + gateway-cli): 0 success, 1 runtime failure, 2 usage error.

burrowee-edge & burrowee-edge-cli

The self-hosted edge relay, hard-bound to the Burrowee console (the console identity is compiled in — there is no override). Like the gateway, it is split: burrowee-edge only serves (run, update, version); every setup/lifecycle verb lives in burrowee-edge-cli. The dispatcher's serving-set for edge is {run, update, version, --version}, so burrowee edge status ⇔ burrowee-edge-cli status, burrowee edge bootstrap <blob> <pin> ⇔ burrowee-edge-cli bootstrap <blob> <pin>, and burrowee edge run ⇔ burrowee-edge run.

burrowee-edge — the daemon

burrowee-edge — self-hosted Burrowee edge relay service

Usage:
  burrowee edge <command> [flags]

Commands:
  run                     serve the relay (foreground)
                          (--tls-listen, --lan-listen, --lan-advertise-port,
                          --quic-addr, --home override config)
  update [--dry] [--auto] [--force] [--no-restart]
         [--version <stamp>] [--console <url>]
                          install the latest release via the official installer,
                          then restart the service only when the binary or unit
                          changed; --dry reports the version gap + changelog only;
                          --force re-installs when up to date; --auto skips the
                          prompt; --no-restart stages without restarting;
                          --version pins/rolls back to a specific release from the
                          console catalog; --console overrides the console base URL
                          (default https://console.burrowee.com)
  version                 print the version

Setup + lifecycle commands (bootstrap, nginx, mode, cert, doctor, service,
restart, status, config, push, bridge, uninstall) live in the companion
burrowee-edge-cli binary.
Run: burrowee edge cli --help

Serve settings (~/.burrowee/edge/config, flags override):
  tls_listen (off = LAN-only)   lan_listen   lan_advertise_port
  lan_allow_ips                 lan_cert     quic_addr

burrowee-edge-cli — setup + lifecycle

burrowee-edge-cli — setup + lifecycle for the burrowee-edge relay

Usage:
  burrowee edge <command> [flags]

Runtime (served by burrowee-edge):
  run                      serve the edge relay
  update                   self-update to the latest release

Lifecycle:
  status                   show enrollment + signed config (tenant, domains, caps)
  restart                  restart the installed edge service
  service install|status|restart
  uninstall [--purge]      remove the service + back up config/state (--purge deletes)
  doctor [--fix] [--yes]   check console + nginx front; --fix brings the front up
  updater status|doctor    cloud-push updater health (forwards to burrowee-edge-updater)

Setup:
  bootstrap <blob> <pin>   enroll this edge, then set up nginx/service
  nginx install|uninstall|apply [--print]|reconcile --mode frontier|lan
  mode <frontier|lan>      switch the edge serve mode (writes serve_mode + reconciles)
  cert [status]            issue a LE host cert via Cloudflare DNS-01 (or print status)
  config get|set           read/upsert config keys in ~/.burrowee/edge/config
                           (incl. buffer_stream/buffer_session/buffer_frame multiplex windows)
  push allow|stop|status   opt in/out of cloud-initiated push updates; allow
                           installs+starts the burrowee-edge-updater daemon,
                           stop disables+stops it (config flag either way)
  bridge key|subscribe|approve|list|remove|raw-port
                           edge-to-edge bridge Links (keypair + authorized_keys);
                           raw-port [<port>|off] sets the nginx-bypass isolated
                           listener port (default off)
  version                  print the version

Common flags:
  --home <dir>   overrides ~/.burrowee; needed under sudo (sudo swaps $HOME)

mode <frontier|lan> is the current way to flip an edge between a public :443 front and a LAN-only front — it replaces an older nginx enable/disable lan toggle from earlier builds; a root/sudo install (see Root-aware installers) renders a disabled updater unit that this binary's service install also manages. burrowee edge updater <sub> forwards to the co-located burrowee-edge-updater binary (status/doctor shown in the help; apply/reinstall/fingerprint/enable/disable/restart/update/run also pass through) — see Updaters.

Exit codes: 0 success, 1 runtime failure, 2 usage error (no command, unknown command).

Updaters (cli, gateway, edge)

Every installable component ships a standalone one-shot or agent binary that applies its own updates out-of-process, so a self-update never has to overwrite its own running binary mid-execution. None of the three below has a dispatcher word of its own (there is no burrowee updater component) — the gateway is the only one reachable through the dispatcher at all, and only via its -cli's updater verb.

burrowee-cli-updater

A one-shot: it applies a pending burrowee-cli update and exits, with no persistent agent form. It backs both the everyday burrowee update path and manual/scripted invocation.

burrowee-cli-updater — apply a burrowee-cli update in a separate process

Usage:
  burrowee-cli-updater update [flags]   apply the update (one-shot)
  burrowee-cli-updater version

Note: the cli updater is a one-shot — there is no `run`/agent form.

Flags:
  --dry          check for a newer version + changelog without installing
  --force        re-install + restart even when already on latest
  --auto         assume-yes: apply without prompting
  --no-restart   install but do not restart the service
  --version <v>  pin/rollback: install this exact public version
  --console <url> console base URL for the release catalog (used with --version)

burrowee-gateway-updater

A persistent agent (installed as its own service unit alongside burrowee-gateway) that dials a local socket and applies console-pushed updates. Reachable through the dispatcher via the gateway-cli wrapper: burrowee gateway updater run ⇔ burrowee-gateway-cli updater run ⇔ burrowee-gateway-updater run.

burrowee-gateway-updater — standalone updater agent for burrowee-gateway

Usage:
  burrowee-gateway-updater [run|daemon]     run the updater agent (default)
  burrowee-gateway-updater status           show updater state + relay uplink probe
  burrowee-gateway-updater doctor [--fix]   check updater health (--fix starts the daemon)
  burrowee-gateway-updater version          print version information
  burrowee-gateway-updater help             show this message

The updater agent dials the kernel's updater.sock and processes apply
requests from the console. It reconnects automatically on disconnect.

status/doctor render the shared updater-health block; the "console uplink"
row reflects the gateway daemon's relay uplink (the updater never dials console).

burrowee-edge-updater

Also a persistent agent, installed as its own service unit by burrowee edge service install. burrowee-edge-cli wraps it with an updater passthrough (burrowee edge updater status|doctor|apply|reinstall|fingerprint|enable|disable|restart|update|run all reach this binary), or run it directly.

burrowee-edge-updater — the standalone edge updater agent

Usage:
  burrowee-edge-updater [daemon|run]   run the console-pushed update agent (default)
  burrowee-edge-updater status         show local updater state + a live console probe
  burrowee-edge-updater doctor [--fix] check updater health (--fix starts the daemon)
  burrowee-edge-updater update         update the updater binary itself
  burrowee-edge-updater apply [--version v]  install (or reinstall) a specific edge version
  burrowee-edge-updater reinstall      re-run the install flow for the current version
  burrowee-edge-updater restart        signal the running updater daemon to restart (SIGHUP)
  burrowee-edge-updater fingerprint    print the edge identity fingerprint
  burrowee-edge-updater enable|disable opt in/out of cloud push-updates (sets
                        allow_push_update + starts/stops this service)
  burrowee-edge-updater version        print the version

Common flags:
  --home <dir>   edge component dir (default ~/.burrowee/edge); needed under sudo

Both agent updaters gate on the same opt-in as their component: push allow|stop|status (see the gateway and edge sections above) controls whether the console may reach them at all; allow_push_update=false in <home>/config refuses a push even if the agent is running.