Appearance
Commands
Complete command reference, one section per user-facing binary: the burrowee dispatcher, burrowee-cli (plus its gateways/relays axis sub-helps), burrowee-gateway-cli + burrowee-gateway + burrowee-register, burrowee-edge-cli + burrowee-edge, and the three per-component updaters. Every block below is the verbatim help page of the command named in its heading — run it with --help to confirm. The hosted relay is an internal component with no end-user command surface and is intentionally omitted.
As of v0.2.1 every binary follows one shared help model, and each one has a docs verb that prints its entire command reference as markdown (burrowee docs, burrowee gateway docs, burrowee edge docs, …) — the blocks on this page are extracted verbatim from those generated references. Every level of every command tree answers --help/-h with its own page, so anything this page doesn't drill into is one --help away.
Help and exit codes
All binaries on this page share one help and exit-code contract:
| Invocation | Result |
|---|---|
Explicit help (--help, -h) at any level | that level's own page on stdout, exit 0 |
A bare parent verb (e.g. burrowee service, burrowee edge push) | its page on stdout, exit 0 — except bare relays/gateways, which run list (real commands, not fallbacks) |
| Malformed invocation — unknown verb or sub-verb, bad flag, wrong arity, stray positional | the page for the level above the mistake on stderr, exit 2 |
| A command that ran and failed | exit 1 |
Documented exceptions:
burrowee edge doctorexits3when any health row is ✗ (0all-green;statusis the read-only alias and always exits 0, on the edge and everywhere else).burrowee relays probealso uses2for a daemon that refused the probe (unknown relay) — a shipped contract predating this model; a shelling consumer controls its own argv, so the collision is theirs to avoid.- The
burroweedispatcher adds two codes of its own (126/127) — see its table below.
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. New in v0.2.1, agent is a reserved word too: burrowee agent <verb> ⇔ burrowee-agent <verb>, a plain pass-through with no verb splitting.
burrowee — the Burrowee command. Dispatches to installed components.
Usage:
burrowee <component> [args] run a component
burrowee <edge|relay|gateway> cli [args]
run that component's setup cli (e.g. burrowee-edge-cli)
burrowee <anything-else> [args] runs burrowee-cli <anything-else> …
burrowee help <verb> [sub] that verb's own help, from the binary that owns it
burrowee version, --version print the dispatcher version
(component versions: burrowee <component> version)
Flags always follow the verb — 'burrowee <component> <verb> [flags]'. The
dispatcher routes on the verb word alone and parses nothing, so a flag placed
BEFORE the verb ('burrowee gateway --config /x run') is rejected here rather
than sent to the wrong binary.
'burrowee help <verb>' — and the flag spellings, 'burrowee --help <verb>' and
'burrowee -h <verb>' — forward the verb as '<verb> --help', so the binary that
owns it scopes its own help instead of printing its top-level page; the same
rewrite 'burrowee <component> help <verb>' makes one level down. What that
prints, and the exit status, are the component's — the dispatcher execs and is
gone. A tail that STARTS with a flag ('burrowee help --json') names no verb —
the dispatcher parses none — so it keeps this page, at exit 0.
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
agent the AI-agent identity client
Run 'burrowee <component> --help' for component commands.
This page lists components, not cli verbs: a bare 'burrowee' prints the cli's
own page — the full list of the verbs a bare 'burrowee <anything-else>' runs —
and 'burrowee <verb> --help' scopes that to one verb.For edge, relay, and gateway — the components that ship a -cli sibling — the dispatcher also splits which binary a verb reaches. A small set of runtime verbs routes to the serving daemon (run/serve/version/--version for gateway, run/version/--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 serving set, so the dispatcher sends it straight to burrowee-gateway-cli. Note that update is no longer a daemon verb: burrowee gateway update and burrowee edge update land on the component cli, whose update verb is the shorthand for updater update — an update always runs through the component's standalone updater (see Updaters). You can also force the -cli binary explicitly with the <component> cli infix, e.g. burrowee edge cli --help; the infix exists only for these three components (burrowee agent cli reaches burrowee-agent's own cli verb untouched).
Help forwarding. burrowee help <verb> — and the flag spellings burrowee --help <verb> and burrowee -h <verb> — forward the verb as <verb> --help, so the binary that owns it prints its own scoped page. The same rewrite works one level down: burrowee <component> help <verb> becomes the component-cli's <verb> --help. A tail that starts with a flag (burrowee help --json) names no verb and keeps the dispatcher's page at exit 0, and help version / help help are answered by the dispatcher itself — those are its own intrinsics.
Binary resolution. Discovery is per component, and neither rule falls back to the other's location. gateway, edge, relay, and register are root-owned system components: the dispatcher resolves their binaries at the exec root /usr/local/burrowee/bin only, by absolute path — PATH, per-user bindirs and /usr/local/bin are never consulted for them, so a stale copy elsewhere can't shadow the system install, and burrowee gateway … works whether or not the exec root is on your PATH. The per-user components — cli, agent, console, and the cli fall-through — are found on PATH only; well-known bin dirs are no longer probed after a PATH miss. A missing component gets a truthful report: which rule applied and where it looked, what is installed here, and the real way to obtain what isn't.
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 |
2 | Unroutable argv: a flag placed before the verb on a serving component (burrowee gateway --config /x run) — the dispatcher routes on the verb word and parses nothing |
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 how 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:
connect forward a local TCP port through the relay to a
service
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--gw <id>] gateway id or name; default from config
[--gw-pub <file>] gateway ed25519 public-key hex file; default from
config
[--handshake <timeout>] per-attempt cold-setup timeout; 0 = no limit
[--isolated] request a dedicated conn per local connection (the
gateway's advertised mode wins)
[--local <address>] local listen address
[--psk <file>] pairing PSK file; default from config
[--relay <id>] relay id, host, URL, or wss://<lan-address>@<short-id>;
default from config
[--relay-quic <address>] relay QUIC address (host:port); default from config,
empty disables QUIC
[--svc <name>] service name, e.g. "22" (required)
[--transport <mode>] transport mode: auto|ws|quic (default auto; empty =
config)
[--warm <depth>] pre-dialed dedicated-conn depth for an isolated
service; 0 disables pre-warming
open forward a local port to a host named in the
{svc}_config alias file
<host>[@<relay>]
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--gw <id>] gateway id or name; default from config
[--local <address>] local listen address
[--relay <id>] relay id, host, URL, or wss://<lan-address>@<short-id>;
default from config
[--svc <name>] service name; also selects the
~/.burrowee/cli/<svc>_config alias file (required)
ssh forward a host's ssh service, then exec the system
ssh against it
list list the aliases configured in
~/.burrowee/cli/ssh_config
<host>[@<relay>] [ssh args…] resolve <host> from ssh_config; everything after it
passes through to ssh
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--gw <id>] gateway id or name; default from config
[--gw-pub <file>] gateway ed25519 public-key hex file; default from
config
[--handshake <timeout>] per-attempt cold-setup timeout; 0 = no limit
[--isolated] request a dedicated conn per local connection (the
gateway's advertised mode wins)
[--local <address>] local listen address
[--psk <file>] pairing PSK file; default from config
[--relay <id>] relay id, host, URL, or wss://<lan-address>@<short-id>;
default from config
[--relay-quic <address>] relay QUIC address (host:port); default from config,
empty disables QUIC
[--svc <name>] service name, e.g. "22" (required)
[--transport <mode>] transport mode: auto|ws|quic (default auto; empty =
config)
[--warm <depth>] pre-dialed dedicated-conn depth for an isolated
service; 0 disables pre-warming
daemon run the long-running transport daemon (what the
managed service runs)
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--socket <path>] transport IPC socket path (default
~/.burrowee/cli/sockets/transport.sock)
relays manage the matrix's relay axis (bare `relays` runs
list)
list print every relay with its LAN pick tokens (default
*, local name *)
use set the default gateway's default edge (its system
relay is refused — that is the fallback)
<id|host>
rm remove a relay and its memberships
<id|host>
gateway list a relay's gateways, or set its default gateway
[<relay>] list that relay's gateways (omit it → the default
relay)
[<relay>] default <gw> set the relay's default gateway (must be an existing
edge)
pair pair a console-minted relay into the default gateway
<blob> <pin>
probe report per-relay connection state (omit <relay> →
every relay)
[<relay>]
[--json] emit the daemon's raw ProbeInfo payload
ping E2E application-layer ping through a relay
[<relay>|all] [<gw>]
[--transport <mode>] transport mode: auto|ws|quic (default auto)
rename set or clear a LOCAL relay name (omit the name to
clear)
<id|host|name> [<new-name>]
reset retire every cached carrier for this relay across
all gateways
<id|host|name>
gateways manage the matrix's gateway axis (bare `gateways`
runs list)
list print the configured gateways (id, name, relay
count, default relay, default *)
use set the default gateway
<id>
rm remove a gateway and its memberships
<id>
relays list a gateway's relays, or set its default edge or
system path
[<gw>] list that gateway's relays (omit it → the default
gateway)
[<gw>] default <relay> set the gateway's default path (must be one of its
edges)
[<gw>] system <relay> override the gateway's system path (must be a system
relay)
bridges list a gateway's bridges (entry origin, end,
cli-path)
[<gw>]
resync full-mirror each gateway's relay set from the live
gateway
[<gw>]
rename set or clear a LOCAL gateway name (omit the name to
clear)
<id|name> [<new-name>]
routes print the whole gateway×relay matrix
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--json] emit the stable JSON matrix export instead of the
adjacency print
fingerprint inspect and control the browser TLS/HTTP disguise
config
path print the fingerprints.json path
list print the valid presets and the effective config
validate check the shape of fingerprints.json (or the given
file)
[<file>]
enable turn the disguise on, optionally setting the default
browser
[<browser>]
disable turn the disguise off (stock TLS)
doctor unified health report; --fix applies the thin
remediations
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--fix] apply the thin remediations (bootstrap guidance;
restart a down daemon)
[--yes] assume yes for any --fix prompt
bootstrap first-time setup: pair this client with a gateway
[<blob>] [<pin>]
[--blob-file <file>] read the blob from this file instead of argv
[--home <dir>] component dir to write config under (default
~/.burrowee/cli)
[--label <label>] a label for this client, shown to the gateway
operator
[--pin-file <file>] read the pin from this file instead of argv
uninstall remove the managed service and back up (or purge)
the cli state
[--config <path>] config.json path (default
~/.burrowee/cli/config.json)
[--home <dir>] cli state dir to uninstall (default ~/.burrowee/cli)
[--purge] delete every file instead of backing the state up
service install or inspect the managed daemon service
install write and load the SYSTEM unit for the current
binary (via sudo)
[--force-service-override] take over a system unit another user installed
status print the unit's state plus the supervisor's own
dump
status read-only alias of doctor (no --fix)
stats show the carrier pool's smux/byte snapshot
[--json] emit the raw daemon payload
[--socket <path>] transport IPC socket path (default
~/.burrowee/cli/sockets/transport.sock)
restart restart the managed daemon service
updater forward straight to the co-located
burrowee-cli-updater
update update the cli component to the latest release
[--auto] assume-yes: apply without prompting
[--console <url>] catalog base url, used with --version
[--dry] show what would happen, install nothing
[--force] reinstall even when already current
[--no-restart] skip the managed service restart
[--version <version>] pin or roll back to an exact public version
upgrade upgrade the updater binary itself
[--auto] assume-yes: apply without prompting
[--console <url>] catalog base url, used with --version
[--dry] show what would happen, install nothing
[--force] reinstall even when already current
[--no-restart] skip the managed service restart
[--version <version>] pin or roll back to an exact public version
reinstall reinstall the current version (repair-to-current)
[--auto] accepted for symmetry with update; the repair never
prompts
[--dry] show what would happen, install nothing
[--no-restart] skip the managed service restart
status report the installed versus available version
doctor diagnose the update path
version print the updater's own version
update shortcut for `updater update` (applied without
prompting)
[--auto] assume-yes: apply without prompting
[--console <url>] catalog base url, used with --version
[--dry] show what would happen, install nothing
[--force] reinstall even when already current
[--no-restart] skip the managed service restart
[--version <version>] pin or roll back to an exact public version
reinstall shortcut for `updater reinstall` (repair-to-current)
[--auto] accepted for symmetry with update; the repair never
prompts
[--dry] show what would happen, install nothing
[--no-restart] skip the managed service restart
login authorize this device with the console
[--console <url>] console base url
[--label <label>] device label shown in the console (default:
hostname)
download-url print a gated presigned download URL (requires a
prior login)
<comp> <version> <artifact>
[--console <url>] console base url for the release gate
version print the versions block
docs print the full CLI reference as markdown (docs
sites, AI agents)
Service aliases (~/.burrowee/cli/<svc>_config, OpenSSH ssh_config format):
`ssh` reads ssh_config; `open --svc <s>` reads <s>_config (e.g. vnc_config) —
the same standard {svc}_config structure. Host <alias> blocks carry burrowee
routing in #@ comments:
#@gateway <name|id> (default: the Host alias)
#@service <name> (default: ssh for ssh_config, else the --svc value)
#@relay <id|host> (repeatable; order = priority; override with <alias>@<relay>)
All other keywords (User, IdentityFile, IdentitiesOnly, …) are read by ssh via -F.
Shell helpers: shell/burrowee.{bash,zsh,fish} are EXAMPLE functions over
`burrowee open`/`ssh` + the {svc}_config aliases — copy and adapt them.
Run 'burrowee <command> --help' for that command's own page ('burrowee docs'
prints the full reference as markdown).relays use works even when the daemon is down
relays use <id> writes the default gateway's new default edge 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/relays ping/gateways list/routes all read config.json directly and need no daemon — ping dials the relay itself. Only relays probe needs 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: the shared contract — 0 success, 1 runtime failure, 2 usage error; relays probe's daemon-refusal 2 is the one exception.
burrowee gateways — the gateway axis
The CLI's config is a relay matrix: one client can be paired with several gateways, and each gateway carries its own relay membership — a system path, a set of edges, and optionally a default chosen from those edges (see 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 the matrix's gateway axis (bare `gateways` runs list)
Usage:
burrowee gateways <command> [flags]
Commands:
list print the configured gateways (id, name, relay count, default
relay, default *)
use set the default gateway
<id>
rm remove a gateway and its memberships
<id>
relays list a gateway's relays, or set its default edge or system path
[<gw>] list that gateway's relays (omit it → the default gateway)
[<gw>] default <relay> set the gateway's default path (must be one of its edges)
[<gw>] system <relay> override the gateway's system path (must be a system relay)
bridges list a gateway's bridges (entry origin, end, cli-path)
[<gw>]
resync full-mirror each gateway's relay set from the live gateway
[<gw>]
rename set or clear a LOCAL gateway name (omit the name to clear)
<id|name> [<new-name>]
Flags:
gateways
[--config <path>] config.json path (default ~/.burrowee/cli/config.json)
[--socket <path>] transport IPC socket path (default
~/.burrowee/cli/sockets/transport.sock)burrowee relays — the relay axis
burrowee relays — manage the matrix's relay axis (bare `relays` runs list)
Usage:
burrowee relays <command> [flags]
Commands:
list print every relay with its LAN pick tokens (default *,
local name *)
use set the default gateway's default edge (its system relay
is refused — that is the fallback)
<id|host>
rm remove a relay and its memberships
<id|host>
gateway list a relay's gateways, or set its default gateway
[<relay>] list that relay's gateways (omit it → the default relay)
[<relay>] default <gw> set the relay's default gateway (must be an existing edge)
pair pair a console-minted relay into the default gateway
<blob> <pin>
probe report per-relay connection state (omit <relay> → every
relay)
[<relay>]
[--json] emit the daemon's raw ProbeInfo payload
ping E2E application-layer ping through a relay
[<relay>|all] [<gw>]
[--transport <mode>] transport mode: auto|ws|quic (default auto)
rename set or clear a LOCAL relay name (omit the name to clear)
<id|host|name> [<new-name>]
reset retire every cached carrier for this relay across all
gateways
<id|host|name>
Flags:
relays
[--config <path>] config.json path (default ~/.burrowee/cli/config.json)
[--socket <path>] transport IPC socket path (default
~/.burrowee/cli/sockets/transport.sock)burrowee-gateway-cli, burrowee-gateway & burrowee-register
The home gateway (NAT tunnel endpoint) is three binaries: burrowee-gateway-cli carries every operator verb (setup, migration, status, targets, the local console, service management, updates); burrowee-gateway serves the daemon and nothing else; 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, version, --version — everything else routes to burrowee-gateway-cli automatically, so burrowee gateway status ⇔ burrowee-gateway-cli status and burrowee gateway bootstrap … ⇔ burrowee-gateway-cli bootstrap …, while bare burrowee gateway (no verb) serves the daemon ⇔ burrowee-gateway. Since 0.2.0 the gateway is a system service, and since 0.3 its whole footprint is one machine-owned tree: binaries in the root-owned exec root /usr/local/burrowee/bin (not on PATH — see Put the exec root on PATH), config under /usr/local/burrowee/etc/gateway, data under /usr/local/burrowee/var/gateway (the --config-dir/--data-dir flags below; --home survives only as a deprecated alias, and a pre-0.2.0 per-user tree is adopted via migrate).
burrowee-gateway-cli — operator verbs
burrowee gateway — operator subcommands for the gateway daemon
Usage:
burrowee gateway <command> [flags]
Commands:
bootstrap first-time setup: persist the relays, enroll,
start the service, open the console
<blob> <pin> the console-minted setup blob and its pin, as
argv
(none) read both from --blob-file/--pin-file instead
[--accept-new-identity] mint a new identity even though an unmigrated
legacy tree was found elsewhere
[--blob-file <path>] read the blob from this path instead of an
argv positional
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir (default
/usr/local/burrowee/var/gateway as root)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
[--migrate-from <dir>] legacy ~/.burrowee/gateway dir to migrate
identity/config/db from first
[--pin-file <path>] read the pin from this path instead of an argv
positional
migrate adopt a pre-split 0.1.x tree into the 0.2.x
config/data roots, then retire it
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir (default
/usr/local/burrowee/var/gateway as root)
[--from <dir>] legacy ~/.burrowee/gateway dir to migrate
identity/config/db from (required)
relays this gateway's configured relays
list print the relay table: kind, local-machine,
carrier state, LAN origins
local mark a relay as on this host, so it is dialed
over loopback first
<id|host:port> on|off
pair ingest a console-minted relay-add blob into
this enrolled gateway
[<blob>] [<pin>]
[--accept-new-identity] mint a new identity even though an unmigrated
legacy tree was found elsewhere
[--blob-file <path>] read the blob from this path instead of an
argv positional
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir (default
/usr/local/burrowee/var/gateway as root)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
[--migrate-from <dir>] legacy ~/.burrowee/gateway dir to migrate
identity/config/db from first
[--pin-file <path>] read the pin from this path instead of an argv
positional
resync re-check relay addresses with the console
[<ws_url>]
console the loopback console served beside the daemon
open check the console is up and open it in the
browser
password set or change the console password
(interactive and no-echo by default)
<newpassword> the new password as argv — warns: shell
history and /proc/<pid>/cmdline
(none) prompt for it, or read it from stdin with
--stdin
[--stdin] read the password(s) from stdin instead of
prompting (for provisioning scripts)
console-url print the console URL carrying its bearer
token, without opening a browser
console-rotate-token mint a new console bearer token, signing out
every existing session
target the local services this gateway exposes
through the relay
list print the configured targets
add expose a local service under a name
<svc> <host:port>
[--type <web|raw>] handler type web|raw (or legacy
auto|http|https)
remove delete a target
<svc>
address re-point an existing target at another address
<svc> <host:port>
mode set a target's transport mode, and the warm
pool for isolated
<svc> <isolated|multiplex>
[--pool-max <n>] isolated mode: maximum warm pool size n (0 =
default ceiling)
[--pool-min <n>] isolated mode: minimum warm pool size n
console expose or un-expose the local console itself
<enable|disable>
register the register socket diagnostic
info print the resolved socket, whether it dials,
and the declared targets
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir (default
/usr/local/burrowee/var/gateway as root)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
[--json] print machine-readable JSON
fingerprint the opt-in uTLS browser disguise on the relay
dial
path print where fingerprints.json lives
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir, accepted for symmetry (unused
here)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
list print the configured presets and the active
default
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir, accepted for symmetry (unused
here)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
validate check the file for preset names nothing
resolves
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir, accepted for symmetry (unused
here)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
enable turn the disguise on, optionally setting that
browser as the default
<preset> chrome|firefox|safari|edge|randomized — also
made the default
(none) keep the existing default (chrome when unset)
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir, accepted for symmetry (unused
here)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
disable turn the disguise off — back to stock TLS,
keeping the presets
[--config-dir <dir>] config root dir (default
/usr/local/burrowee/etc/gateway as root)
[--data-dir <dir>] data root dir, accepted for symmetry (unused
here)
[--home <dir>] DEPRECATED alias setting both roots to dir;
use --config-dir/--data-dir
status diagnose identity, service, relay and console;
never remediates
doctor the same diagnostic, plus --fix for the checks
that have a repair
[--fix] remediate fixable checks (service not running)
[--yes] assume yes to all remediation prompts
service the system launchd/systemd units for the
daemon and its updater
install write and load both units, then start them
[--force-service-override] take over a legacy per-user unit owned by
another user
status print what the supervisor says about both
units
uninstall remove the units, then back up (or --purge)
the config and state roots
[--purge] delete the data root instead of backing it up
restart restart the managed gateway service
push whether the cloud console may push an update
to this gateway
allow let the console push updates here
stop refuse pushed updates from now on
status report what the config file says
updater the self-update lifecycle for this component
and its updater
run run the updater agent in the foreground
update install the gateway component at
console-current, or a pinned version
[--auto] assume-yes, and restart the freshly-placed
binary into service
[--dry] resolve + print the version gap without
installing
[--force] install even when already current
[--version <stamp>] pin/rollback to an exact console-catalog stamp
instead of console-current
upgrade replace the updater binary itself
reinstall re-run install.sh pinned to the running
version — repair, not upgrade
restart restart this component's updater daemon
status show updater state + relay uplink probe
doctor check updater health (--fix installs + starts
the updater daemon)
version print updater version information
update shorthand for 'updater update'
[--auto] assume-yes, and restart the freshly-placed
binary into service
[--dry] resolve + print the version gap without
installing
[--force] install even when already current
[--version <stamp>] pin/rollback to an exact console-catalog stamp
instead of console-current
reinstall shorthand for 'updater reinstall'
version print this cli's version block (also
--version)
docs print the whole surface as markdown, for docs
sites and AI agents
Run 'burrowee gateway <command> --help' for that command's help
('burrowee gateway docs' prints the full reference as markdown).
Runtime (served by burrowee-gateway): run | serve — see 'burrowee gateway run --help'.
The dispatcher sends run, serve, version and --version to that daemon, so the `version`
row above is reached as 'burrowee gateway cli version'.burrowee gateway console open opens the local console in your browser (console-url prints its token-bearing URL without opening one); 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 subtree wraps the standalone burrowee-gateway-updater agent (see Updaters below): burrowee gateway updater run ⇔ burrowee-gateway-updater run, and the top-level update/reinstall verbs are shorthands for updater update/updater reinstall.
burrowee-gateway — the daemon
burrowee gateway — the Burrowee home gateway daemon (NAT tunnel endpoint)
Usage:
burrowee gateway [command] [flags]
Commands:
run | serve run the gateway daemon in the foreground
[--accept-new-identity] allow a freshly minted identity even though an unmigrated
legacy tree was found
[--config-dir <dir>] config root dir (config, identity/, fingerprints.json,
console.token)
[--console <on|off>] run the local console: on|off
[--data-dir <dir>] data root dir (gateway.db, sockets/, logs/)
[--home <dir>] DEPRECATED alias setting both roots to one dir; use
--config-dir/--data-dir
[--migrate-from <dir>] legacy ~/.burrowee/gateway dir to copy identity, config
and gateway.db from
[--no-open] do not open the local console in a browser
version print the gateway version (also --version)
Run 'burrowee gateway <command> --help' for that command's help.
Config file — <config-dir>/config, one key=value per line:
console_port=16518 loopback port the local console listens on
allow_push_update=true whether the cloud console may push an update here
Operator verbs (bootstrap, status, doctor, service, updater, …) live in the gateway
cli: run 'burrowee gateway --help' for that list.burrowee-register
burrowee register — register a TCP service with the Burrowee gateway
Usage:
burrowee register [command] [flags]
Commands:
(none) register --name with the gateway and bridge every opened stream
to --target
[--name <name>] service name to register
[--sock <path>] gateway register unix socket path (default
~/.burrowee/gateway/sockets/register.sock)
[--target <host:port>] TCP address to bridge opened streams to, as host:port
version print the burrowee-register version (also --version)
Run 'burrowee register <command> --help' for that command's help.
The registrar is the gateway-side adapter for a service that does not speak the
Burrowee register protocol itself: it holds the register socket open and bridges
every stream the gateway opens for <name> to <target>.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. Its flags are now rendered GNU-style (--name, --sock, --target) like every other binary on this page, and — because it ships inside the gateway payload — the dispatcher resolves it at /usr/local/burrowee/bin only. burrowee gateway register info [--json] (a gateway-cli verb, above) is the matching diagnostic: the resolved socket path, whether it dials, and the declared targets.
burrowee-edge-cli & burrowee-edge
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: every setup/lifecycle verb lives in burrowee-edge-cli; burrowee-edge only serves. The dispatcher's serving set for edge is run, 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. The daemon's former update verb is gone — burrowee edge update now reaches the cli's update, which forwards to the standalone updater (see Updaters).
burrowee-edge-cli — setup + lifecycle
burrowee edge — setup + lifecycle for the burrowee-edge relay
Usage:
burrowee edge <command>
Commands:
bootstrap enroll this edge with the console, then set up nginx
+ the service
<blob> <pin> the enrollment blob and PIN, inline
(none) read both from --blob-file/--pin-file, keeping them
off the process table
[--blob-file <path>] read the blob from this path instead of a positional
arg
[--home <dir>] component CONFIG root dir (the data root follows)
[--mode <frontier|lan>] serve mode: frontier|lan (default frontier)
[--pin-file <path>] read the PIN from this path instead of a positional
arg
migrate adopt a pre-0.2.0 per-user edge tree into this
install (copies, never moves)
[--force] OVERWRITE the destination from --from, including
identity/, bridge/ and console.json. Snapshots both
destination roots first and names every file it
replaced. For a tree adopted from the WRONG source,
which the never-overwrite copy can never repair
[--from <dir>] the per-user edge tree to adopt FROM — the full dir,
e.g. /home/ubuntu/.burrowee/edge (required)
[--home <dir>] component CONFIG root dir (the data root follows)
nginx the nginx stream front this edge serves behind
(self-elevates via sudo)
install install nginx if needed and wire the top-level
stream{} include
[--conf-dir <dir>] nginx conf dir
[--home <dir>] component CONFIG root dir (the data root follows)
[--internal-port <port>] edge TLS listen port on loopback
uninstall remove a stream front (--lan removes the LAN one,
not the frontier one)
[--conf-dir <dir>] nginx conf dir
[--home <dir>] component CONFIG root dir (the data root follows)
[--lan] remove the LAN stream front (default: the frontier
stream front)
apply render + load the passthrough front (--print
previews, writing nothing)
[--conf-dir <dir>] nginx conf dir
[--home <dir>] component CONFIG root dir (the data root follows)
[--listen-lan <port>] external LAN TLS port nginx listens on
[--listen-tls <port>] external TLS port nginx listens on
[--print] preview the config to stdout; no writes or cert
generation
reconcile re-render the front for --mode frontier|lan and
reload nginx
[--conf-dir <dir>] nginx conf dir
[--home <dir>] component CONFIG root dir (the data root follows)
[--mode <frontier|lan>] serve mode: frontier|lan
mode switch the serve mode: writes serve_mode, reconciles
the front, restarts
frontier public TLS front, nginx-fronted
lan raw-forward-only LAN edge
[--home <dir>] component CONFIG root dir (the data root follows)
proxy-protocol the frontier PROXY-protocol flag: config key + nginx
reconcile + restart
on send the PROXY header from the nginx front
[--home <dir>] component CONFIG root dir (the data root follows)
off stop sending it
[--home <dir>] component CONFIG root dir (the data root follows)
status print the effective value and where it came from
[--home <dir>] component CONFIG root dir (the data root follows)
lan-listen the loopback dial-in face a co-located gateway dials
directly
on enable it (default: the current address, else
127.0.0.1:9448); restarts
[<addr>]
[--home <dir>] component CONFIG root dir (the data root follows)
off disable it and restart the service
[--home <dir>] component CONFIG root dir (the data root follows)
status print the configured address and whether it is in
effect
[--home <dir>] component CONFIG root dir (the data root follows)
cert the host HTTPS cert, issued from Let's Encrypt over
Cloudflare DNS-01
status report the stored cert's expiry, and whether it
needs renewing
[--home <dir>] component CONFIG root dir (the data root follows)
issue issue or renew it (--manual prints the TXT record
instead of using a token)
[--cf-token <token>] Cloudflare DNS API token (or @<file> to read from
file)
[--home <dir>] component CONFIG root dir (the data root follows)
[--hostname <fqdn>] host fqdn (default: host_fqdn from config, then
os.Hostname())
[--manual] manual DNS-01: print the _acme-challenge TXT and
wait (no Cloudflare token needed)
[--staging] use Let's Encrypt staging (for testing)
doctor the full diagnostic; --fix repairs the nginx front +
host cert
[--fix] remediate the nginx front (install → apply → start)
and issue/renew the host cert
[--home <dir>] component CONFIG root dir (the data root follows)
[--no-external] skip the through-Cloudflare reachability probe of
host_fqdn
[--yes] assume yes for all remediation prompts (unattended)
restart restart the installed edge service (the alias of
`service restart`)
[--home <dir>] component CONFIG root dir (the data root follows)
service the system-level units for the edge and its updater
(sudo)
install lay down both units (--force-service-override takes
over another user's)
[--force-service-override] consent to replacing a system unit installed by a
DIFFERENT user
[--home <dir>] component CONFIG root dir (the data root follows)
status report both units' states, legacy per-user ones
included
[--home <dir>] component CONFIG root dir (the data root follows)
restart restart the serve unit through the full
legacy→system chain
[--home <dir>] component CONFIG root dir (the data root follows)
status the read-only alias of doctor — the same report,
always exit 0
[--home <dir>] component CONFIG root dir (the data root follows)
config read or upsert keys in the edge config file
get print one key, or the whole file when none is named
[<key>]
[--home <dir>] component CONFIG root dir (the data root follows)
set upsert one key (incl. the buffer_* multiplex
windows)
<key> <value>
[--home <dir>] component CONFIG root dir (the data root follows)
push opt in or out of cloud-initiated push updates
allow set allow_push_update, then install + start the
updater agent
[--home <dir>] component CONFIG root dir (the data root follows)
stop unset it, then disable + stop the agent (the unit
file stays)
[--home <dir>] component CONFIG root dir (the data root follows)
status print the current setting and the agent's state (the
bare default)
[--home <dir>] component CONFIG root dir (the data root follows)
updater forward a command to the co-located
burrowee-edge-updater
<command>
update update the edge component to the current released
version
reinstall reinstall the current version: every binary re-laid,
config kept
bridge edge-to-edge bridge Links: the keypair and the
authorized_keys it trusts
key print this edge's bridge fingerprint (the value a
peer approves)
[--home <dir>] component CONFIG root dir (the data root follows)
subscribe stage an outbound Link to a downstream edge
[--addr <address>] downstream edge address: wss://host:port (domain) or
ip:port (with --cert-fp or --plain)
[--cert-fp <fingerprint>] pinned TLS leaf fingerprint for an ip wss-pinned
dial
[--home <dir>] component CONFIG root dir (the data root follows)
[--peer-fp <fingerprint>] the downstream edge's Ed25519 fingerprint to pin
(trust anchor)
[--plain] plain ws:// (no TLS) — LAN only
approve trust an inbound peer by fingerprint
<fingerprint>
[--home <dir>] component CONFIG root dir (the data root follows)
[--yes] skip the local fingerprint confirmation
(unattended/console-driven)
list print the trusted inbound peers and the staged
outbound Links
[--home <dir>] component CONFIG root dir (the data root follows)
remove drop an inbound peer, or --link a staged outbound
Link
[<fingerprint>]
[--home <dir>] component CONFIG root dir (the data root follows)
[--link <linkID>] remove a staged outbound Link by linkID (instead of
an inbound authorized_keys fingerprint)
raw-port the nginx-bypass isolated listener port (default
off)
[<port>|off]
[--home <dir>] component CONFIG root dir (the data root follows)
uninstall remove the service and back up config + state
(--purge deletes instead)
[--conf-dir <dir>] nginx conf dir
[--home <dir>] component CONFIG root dir (the data root follows)
[--purge] delete the edge config/state instead of backing it
up
version print the version block for this install (also
--version)
docs print the full CLI reference as markdown (docs
sites, AI agents)
Runtime (served by burrowee-edge): run — see 'burrowee edge run --help'.
Every level answers --help: `burrowee edge <command> --help`.
--home <dir> overrides the CONFIG root — default /usr/local/burrowee/etc, or
~/.burrowee with no system install. The DATA root is derived from it, never
named separately, so one --home always means exactly one tree.burrowee-edge — the daemon
burrowee edge — the self-hosted Burrowee edge relay, as served by this daemon
Usage:
burrowee edge <command>
Commands:
run serve the edge in the foreground (the form the service
unit runs)
[--home <dir>] component CONFIG root dir (the data root follows)
[--lan-advertise-port <port>] LAN port to advertise in self-reports (overrides config
lan_advertise_port)
[--lan-listen <addr>] LAN plain-WS listen addr (overrides config lan_listen)
[--quic-addr <addr>] QUIC listen addr (overrides config quic_addr)
[--tls-listen <addr>] TLS listen addr, or "off" for LAN-only (overrides config
tls_listen)
version print the installed binary and running daemon versions
(also --version)
Run 'burrowee edge <command> --help' for that command's help.
Bare 'burrowee-edge' prints this page; the service unit runs `run`.
Setup + lifecycle (bootstrap, migrate, nginx, mode, cert, doctor, service, status,
config, push, bridge, uninstall) live in the companion burrowee-edge-cli, and
update/upgrade/reinstall in burrowee-edge-updater ('burrowee edge updater <command>').Updaters (cli, gateway, edge)
Every installable component ships a standalone updater binary that applies its own updates out-of-process, so a self-update never has to overwrite its own running binary mid-execution. In v0.2.1 each component cli grew a first-class updater subtree that forwards to it — burrowee updater …, burrowee gateway updater …, burrowee edge updater … — plus top-level update/reinstall shorthands, so none of the three needs a dispatcher word of its own. The verbs are uniform across all three: update updates the component (with --dry/--force and --version pin-and-rollback), upgrade advances the updater binary itself (which update deliberately never touches), and reinstall is an offline repair-to-current that downloads nothing.
burrowee-cli-updater
A one-shot: it applies a pending burrowee-cli update and exits, with no persistent agent form. burrowee update is the everyday shortcut for burrowee updater update — and, unlike the raw verb, it applies without prompting.
burrowee updater — apply a burrowee-cli update in a separate process
Usage:
burrowee updater <command> [flags]
Commands:
update update the cli component to the latest released version
[--auto] assume-yes: apply without prompting
[--console <url>] console base url for the release catalog (used with --version)
[--dry] report the version gap and the changelog, install nothing
[--force] re-install and restart even when already on the latest version
[--no-restart] install but do not restart the managed service
[--version <version>] pin or roll back to this exact public version from the console
catalog
upgrade advance this updater binary itself (the updater-only swap)
[--auto] assume-yes: apply without prompting
[--console <url>] console base url for the release catalog (used with --version)
[--dry] report the version gap and the changelog, install nothing
[--force] re-install and restart even when already on the latest version
[--no-restart] install but do not restart the managed service
[--version <version>] pin or roll back to this exact public version from the console
catalog
reinstall repair the current install (offline, units only)
[--auto] accepted for symmetry with update; the repair never prompts
[--dry] show the repair plan without running it
[--no-restart] repair but do not restart the managed service
status print the installed · running · available version picture
doctor the status report plus a one-line verdict
version print this updater binary's own version
status and doctor are VERSION-FOCUSED: the cli has no push-updater daemon, so
they report installed · running · available versions rather than daemon health
rows, and neither ever fails on a verdict.
The BARE form — `burrowee-cli-updater --auto`, no sub-verb — is the cli daemon's
internal update trigger, not an operator surface. It is spelled with the binary
name because nothing types it: the daemon spawns the binary directly, and it
takes `update`'s flags with no auto-default. One exception: a LEADING `--version`
is read as the version alias, so only a `--version` after another flag pins.
Run 'burrowee updater <command> --help' for that command's own page.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. Reached as burrowee gateway updater <command> ⇔ burrowee-gateway-updater <command>.
burrowee gateway updater — the burrowee-gateway updater: apply component updates, and report on the
agent
Usage:
burrowee gateway updater <command> [flags]
Commands:
update install the gateway component at console-current (or a pinned
version)
[--auto] assume-yes, and restart the freshly-placed binary into service
[--dry] resolve + print the version gap without installing
[--force] install even when already current
[--version <stamp>] pin/rollback to an exact console-catalog stamp instead of
console-current
upgrade self-update this updater binary
reinstall full install.sh reinstall pinned to the running version
restart restart this component's updater daemon
status show updater state + relay uplink probe
[--home <dir>] gateway component dir (default ~/.burrowee/gateway)
doctor check updater health (--fix installs + starts the updater
daemon)
[--fix] install + start the updater daemon when push is enabled but it
is not running
[--home <dir>] gateway component dir (default ~/.burrowee/gateway)
version print updater version information (also --version)
Run 'burrowee gateway updater <command> --help' for that command's help.
The updater AGENT — 'burrowee-gateway-updater run' (also 'daemon', also a bare or
flags-only invocation) — dials the kernel's updater.sock and processes apply requests
from the console, reconnecting on disconnect. That is the form the service units run,
not a verb anyone types, which is why it is named here rather than listed above. A help
spelling anywhere in it prints this page instead of starting the agent.
status and doctor render the same updater-health block; the "console uplink" row
reflects the gateway daemon's relay uplink (the updater never dials console). A row
whose input this user cannot read (the config file, gateway.db) reports "cannot
determine" rather than a state, and both verbs offer to re-read as root on a terminal.burrowee-edge-updater
Also a persistent agent, installed as its own service unit by burrowee edge service install. burrowee edge updater <command> forwards any command to it.
burrowee edge updater — the edge's update agent: the console pushes here, and so does the operator
Usage:
burrowee edge updater <command>
Commands:
update install the edge version the console currently serves
[--auto] apply and restart immediately (default: stage only)
[--dry] resolve + print the version gap without installing
[--force] full reinstall via the public installer, even when already
current
[--home <dir>] edge component CONFIG root dir (the data root follows)
[--version <version>] pin/rollback to this exact version (default: current from
console)
upgrade update THIS agent's own binary, which `update` deliberately
never touches
[--home <dir>] edge component CONFIG root dir (the data root follows)
[--version <version>] updater version to fetch (default: the installed serve-track
version)
status the local updater snapshot plus a live console-connectivity
probe
[--home <dir>] edge component CONFIG root dir (the data root follows)
doctor the same report, plus --fix to start the daemon when it is
down
[--fix] attempt to start the updater daemon when it is not running
[--home <dir>] edge component CONFIG root dir (the data root follows)
reinstall offline units-only repair: re-run the on-disk install.sh, no
download
[--home <dir>] edge component CONFIG root dir (the data root follows)
restart signal the running updater daemon to restart (SIGHUP)
[--home <dir>] edge component CONFIG root dir (the data root follows)
fingerprint print this edge's identity fingerprint
[--home <dir>] edge component CONFIG root dir (the data root follows)
enable opt in to cloud push-updates: set allow_push_update, start
this agent
[--home <dir>] edge component CONFIG root dir (the data root follows)
disable opt back out: unset it, then stop the agent (its unit file
stays)
[--home <dir>] edge component CONFIG root dir (the data root follows)
version print this agent's installed and running versions (also
--version)
Run 'burrowee edge updater <command> --help' for that command's help.
Reached through burrowee-edge-cli's forward, which is why every page names the
command the way it is typed rather than the binary on disk.
--home names the edge component CONFIG root — default /usr/local/burrowee/etc/edge,
or ~/.burrowee/edge with no system install. The data root follows it, so one
--home always means exactly one tree.Both agent updaters gate on the same opt-in as their component: push allow|stop|status (see the gateway and edge sections above) — or the equivalent updater enable|disable on the edge — controls whether the console may reach them at all; allow_push_update=false in the component's config refuses a push even if the agent is running.