CLI reference

Commands at a glance#

• up
  First-run setup plus serve, advertised on your Wi-Fi with code pairing.
• init
  Create state with an explicit address, listener and certificate names.
• serve
  Run the bridge from existing state.
• pair
  Make a one-time pairing invitation, optionally as a QR code.
• devices
  List paired devices.
• revoke
  Unpair a device at once.
• console
  Print a one-time link to the local web console.
• certificate
  Show the certificate, or renew it early.
• relay join | status | leave
  Connect this bridge to a relay, or stop.
• relay serve | profile | rotate
  Run a relay, make its profile, replace its secrets.

herdr-remote up#

herdr-remote up [--port 8443] [--name NAME] [--no-discovery] [--backend herdr|orca|plain]

The one-step command for a computer on your Wi-Fi. On first run it creates TLS material for this computer’s .local name and private addresses, listening on all interfaces; then it serves, advertises the computer to phones nearby, and opens the console. Pairing needs the code that pops up on this computer.

• --port 8443
  Port for phones, used when creating state.
• --name NAME
  Name shown on the phone.
• --no-discovery
  Don’t advertise this computer or accept nearby code pairing.
• --backend herdr|orca|plain
  Which terminals to serve; saved for next time.
• --folder DIR
  Plain backend: open this folder as a workspace (repeatable).
• --herdr PATH
  Path to the herdr program.
• --no-console
  Don’t start the local web console.
• --no-local-route
  With a relay: don’t also accept phones on this network.

herdr-remote init#

herdr-remote init --url https://host.example:8443 [--listen 127.0.0.1] [--port 8443] [--san localhost,127.0.0.1]

Creates the private state directory with a one-year self-signed certificate. It never overwrites an existing certificate or paired devices.

• --url URL
  The HTTPS address phones dial. Its host is always in the certificate.
• --listen ADDRESS
  Interface to listen on: 127.0.0.1 for this computer only, 0.0.0.0 for the network.
• --port PORT
  Listening port.
• --san NAMES
  Extra comma-separated names or addresses for the certificate.
• --name, --backend, --herdr, --session, --orca-connection
  As for up and serve.

herdr-remote serve#

herdr-remote serve [--backend herdr|orca|plain] [--herdr /path/to/herdr] [--session NAME] [--discoverable]

Runs the bridge from existing state, keeping a relay connection open if it has joined one. Command-line options win over the saved config for this run; settings saved in the console replace them. The bridge checks its certificate every few hours and renews it 30 days before expiry.

• --backend herdr|orca|plain
  Terminal backend for this run.
• --herdr PATH
  Path to the herdr program.
• --session NAME
  Herdr session to serve (default: the main one).
• --orca-connection FILE
  Orca: private file with the local runtime link.
• --folder DIR
  Plain backend: a folder to open as a workspace (repeatable).
• --discoverable
  Advertise on the network and accept nearby code pairing.
• --listen, --port
  Override the saved listener for this run.
• --no-console
  Don’t start the web console.
• --no-local-route
  With a relay: stay on loopback, relay only.

herdr-remote pair#

herdr-remote pair [--scope read|control] [--ttl 300] [--qr] [--json] [--connection PRIVATE_PROFILE.json] [--no-relay]

Prints a herdr-remote://pair?data=… link containing a short-lived, single-use secret. Show it only to the device’s owner.

• --scope read|control
  Access for the new device. Default: read.
• --ttl SECONDS
  How long the invitation is valid, 1 to 3600. Default: 300.
• --qr
  Also draw a QR code in the terminal.
• --json
  Print the invitation as JSON for pasting into the app.
• --connection FILE
  Add a private route (secure gateway or app-only WireGuard).
• --no-relay
  Leave out the relay route.

herdr-remote devices#

herdr-remote devices

Lists paired devices with their id, name, access, and when they were paired or revoked.

herdr-remote revoke#

herdr-remote revoke --device UUID

Revokes a device at once, closing its sockets and releasing any control it holds.

herdr-remote console#

herdr-remote console

Prints a one-time link (valid two minutes) to the running bridge’s local web console. up and serve open it themselves in a desktop terminal; turn it off with --no-console or "console": false. See Web console.

herdr-remote certificate#

herdr-remote certificate [renew [--days N]]

Without arguments, shows the current fingerprint and expiry. Paired phones pick up a renewed certificate automatically.

{"pin":"c7944b5aa4a875bf7b22264dce1d701feee50abad52483bf24e32aed9265c3a1","expiresAt":"2027-10-31T07:53:31.000Z"}

• renew --days N
  Create a successor now and switch to it after N days (default 14, at the latest a day before expiry).

herdr-remote relay#

herdr-remote relay join PRIVATE_RELAY.jsonherdr-remote relay statusherdr-remote relay leave

join saves a relay profile privately in the state directory; restart serve or up to connect, and new invitations carry the relay route. status shows the joined relay, leave removes it. See Reverse relay.

herdr-remote relay serve#

herdr-remote relay serve [--listen 127.0.0.1] [--port 8788] [--state DIR] [--personal-only]herdr-remote relay profile --public-url wss://relay.example.com > PRIVATE_RELAY.jsonherdr-remote relay rotate --public-url wss://relay.example.com

Run on the relay server. profile prints the private profile the bridge joins with; rotate issues new relay secrets, after which bridges join again.

• --listen, --port
  Where the relay listens; put HTTPS/WSS in front of it.
• --state DIR
  Relay secrets folder. Default: ~/.local/share/herdr-remote-relay.
• --personal-only
  Admit only the per-device credentials the bridge lists; revoked phones are refused.
• --public-url URL
  The relay’s public root wss:// address, written into the profile.

Files#

• ~/.local/share/herdr-remote/config.json
  Settings, certificate and its private key (mode 600).
• ~/.local/share/herdr-remote/
  Device database, relay profile (relay.json), plain-terminal folders.
• ~/.local/share/herdr-remote-relay/
  A relay server’s secrets.