CLI reference

Every meshhold subcommand and flag.

The meshhold binary is both the node daemon and a thin client for its REST surface. The same binary ships on every platform — Linux package, Windows installer, macOS tarball — and every subcommand documented here is available on all of them.

meshhold [--version] <command> [args] [flags]

A bare meshhold (or meshhold --help) prints the top-level subcommand list. meshhold <command> --help always works and is the authoritative source if anything below drifts from the binary.

The commands split into three families by how they reach the daemon:

The header of every subcommand section below states which family it belongs to. The "direct" family inherits the same constraint already documented on set-password — they take an exclusive lock on the metadata store, so they only work when the node daemon isn't holding it.

Global flags

These apply to every API-using subcommand (the --api family — auth, vault, file, node, profile, s3-key, s3-perm, forwards, agent, status, replicate-now, settings, chat, vpn, audit, logs, bug-report, send / recv / transfers, plus the online networks invite / networks add / networks add-peer):

How a credential is chosen. When neither --password nor $MESHHOLD_PASSWORD is set, the CLI uses a saved token from auth login (~/.meshhold/cli.json), and only then falls back to the daemon's local admin token (<metadata_dir>/cli-admin.token, readable by root / the daemon user — and on a Windows service install, by administrators only). Running auth login once is what lets a non-root, non-administrator user drive these commands without read access to the daemon's config.yaml and admin-token files.

Several commands are auto: they prefer the running daemon's REST API and fall back to opening the metadata store directly only when the daemon is stopped, so they work in both states without a flag. These are set-password, 2fa, mgmt-keys (self keys), networks list / networks set-swarm-key, and blocks gc. They accept --config / -c for the offline fallback path. (telemetry is local: it only rewrites config.yaml and never touches a running daemon.)

daemon

Family: local — this is the daemon.

Runs the node. Reads ~/.meshhold/config.yaml (Linux) or %LOCALAPPDATA%\MeshHold\config.yaml (Windows) and brings up the libp2p host, REST listener, replication scheduler, and any optional surfaces (S3, push, port-forwards, agent).

meshhold daemon --log-level=debug --log-format=json

keygen

Family: local. No daemon, no config.

Generates a fresh 32-byte swarm key in the libp2p PSK (/key/swarm/psk/1.0.0/) format. Every node that wants to join the same network must share this key — treat it as sensitive.

meshhold keygen -o ~/.meshhold/swarm.key

keygen-reality

Family: local.

Vestigial. The reality transport authenticates with a marker derived from the swarm key, not an X25519 server key, and nothing in the daemon loads the private half this command writes. You do not need to run it to use REALITY, and losing the file costs you nothing. It is kept for now because removing a shipped command breaks scripts; meshhold config lint flags node.obfs.reality.private_key_file if you set it.

Generates an X25519 keypair. The private half is written to disk; the public half goes to stdout in base64url form.

The command refuses to clobber an existing file unless --force is given.

check-reality-dest

Family: local.

Probes a candidate REALITY destination (<host:port>) for the four properties the transport relies on: TCP reachability, TLS 1.3 negotiation, X25519 key share, and an ALPN response. Designed to run before you flip node.obfs.reality.enabled = true.

meshhold check-reality-dest www.microsoft.com:443

Exits non-zero when the destination is not REALITY-compatible, so you can wire it into a first-run script.

Sample output:

TCP        www.microsoft.com:443 OK
TLS 1.3    OK
X25519     OK
ALPN       "h2"
ServerCert CN=www.microsoft.com (issuer: CN=Microsoft RSA TLS CA 02)

set-password

Family: auto — talks to the daemon over loopback when one is running, falls back to direct BadgerDB writes when it isn't. There is no --offline flag; the CLI picks the right path automatically.

Sets the Argon2id hash the Web UI / REST API check against. Reads the new password from, in order:

1. $MESHHOLD_PASSWORD env var
2. piped stdin (single line, non-interactive)
3. interactive TTY prompt with confirmation

MESHHOLD_PASSWORD='swordfish' meshhold set-password

A node upgraded from a build that hashed the password with bcrypt cannot check its old hash at all, so its login answers 409 until this command has been run once. See Login brute-force protection for what that looks like from the browser.

auth

Family: API. Controls how the CLI authenticates to a local (or tunnelled) daemon. Run auth login once and every other --api subcommand authenticates with the saved token — no password on the command line, and no read access to the daemon's root-owned config.yaml / cli-admin.token required. This is the supported way to drive the CLI as a non-root user.

The token is a long-lived bearer (mhk_…) held in BadgerDB on the daemon and saved to ~/.meshhold/cli.json (mode 0600) on the client, encrypted under your own account's keystore — DPAPI on Windows, Secret Service or a key file in your home directory on Linux. Copied to another machine or another account the file is inert; where the platform offers no keystore it stays plaintext, as before. An older plaintext cli.json keeps working and is rewritten encrypted on your next auth login. It survives daemon restarts and upgrades, is independent of the Web UI password (changing the password does not revoke it — same model as S3 tokens), and has no expiry: revoke it explicitly with auth logout or auth revoke. The daemon stores only the token's SHA-256, so a database leak yields no usable credential.

auth login reads the password from $MESHHOLD_PASSWORD, piped stdin, or an interactive prompt. If 2FA is enabled, pass --totp <code> or enter it when prompted.

# Log in once on a server, as an ordinary (non-root) user:
meshhold auth login

# From then on every --api command authenticates with the saved token,
# e.g. `meshhold node …`, `meshhold vault …`, `meshhold mgmt-keys …`.

# Revoke a lost device's token from any logged-in machine:
meshhold auth list
meshhold auth revoke fe774279

vault

Family: API.

meshhold vault list
meshhold vault get       <vault_id>
meshhold vault keyid     [<key>]                 # also: --key-file <path>
meshhold vault create
meshhold vault s3-alias  <vault_id> <alias>      # pass "" to clear
meshhold vault share     <vault_id>
meshhold vault link new  <vault_id> <path>       # flags below
meshhold vault link ls   <vault_id>              # --all
meshhold vault link rm   <vault_id> <link_id>
meshhold vault join      <invite-or-key>         # flags below
meshhold vault rename    <vault_id> <new-name>
meshhold vault ignore    <vault_id>              # view; --set <glob> (repeat) / --clear
meshhold vault sync      <vault_id>              # --wait --node <id> / --replicas N
meshhold vault rm        <vault_id>              # --force to confirm

vault link flags (on new):

vault link new says on stderr whether the link needs this node awake: either how much is being sent to the gateway, or why nothing is — a gateway with no room, or none configured. It is invisible until the day it matters, which is why it is said at the moment the link is made.

The URL is printed once, because it exists once: the daemon keeps the token's hash and the link's key wrapped under the vault key, so nothing can reproduce it afterwards. The part after the # is that key — it never reaches the server, which is what stops the serving node reading what it serves, and it is what some chat clients strip.

Needs node.share.enabled and node.share.base_url in the daemon's config before a link can actually be answered; new says so on stderr when they are missing.

keyid accepts the key as a positional arg, --key-file <path> (use - for stdin), or piped stdin.

join flags (used mainly on the bare-key path; invite values are filled in automatically and overridden by any flag you pass):

# Onboard a vault key shared with you out-of-band:
meshhold vault keyid --key-file ./shared.key
# 5e3b...c4

# Generate one from scratch:
meshhold vault create
# key:      4c1e...f0
# vault_id: 9a44...20

# Share a vault, then join it from another headless node:
meshhold vault share 9a44...20
# meshhold://join?swarm_key=…&bootstrap=…&vault_key=…
meshhold vault join 'meshhold://join?swarm_key=…&vault_key=…' --storage-path /srv/vault

file

Family: API.

meshhold file ls        <vault_id>
meshhold file get       <vault_id> <path>
meshhold file upload    <vault_id> <path> <local_file>   # local_file '-' = stdin
meshhold file download  <vault_id> <path> <local_file>   # local_file '-' = stdout
meshhold file rm        <vault_id> <path>
meshhold file mv        <vault_id> <old_path> <new_path>
meshhold file mkdir     <vault_id> <path>
meshhold file rmdir     <vault_id> <path>

A vault's folders are otherwise implied by the paths of the files in them, so mkdir is the only way to make one before there is anything to put in it. The folder is a catalog entry like any other: it replicates to peers, survives being empty, and shows up on every mount and in the Android picker.

Both upload and download accept - as the local-file argument for stdin / stdout. Combined, they pipe across vaults:

meshhold file download v1 docs/spec.md - \
  | meshhold file upload   v2 docs/spec.md -

node

Family: API.

meshhold node list
meshhold node self
meshhold node share   [node_id]
meshhold node connect <invite>          # --network <id>

# On node A — share yourself:
meshhold node share
# meshhold://join?peer_id=12D3KooW…&host=…&plain_port=…

# On node B (already on the same network) — start talking to A directly:
meshhold node connect 'meshhold://join?peer_id=12D3KooW…&host=…&plain_port=…'

profile

Family: API.

Reads and edits this node's user profile — the values the daemon persists in its metadata store and advertises to peers over the hello / topology beat. There is no offline path: a profile change has to flow through the running daemon so peers pick it up, so the daemon must be running.

meshhold profile show                       [--json]
meshhold profile set-name        <display-name>
meshhold profile set-country     <code>
meshhold profile set-allow-calls <true|false>

allow_calls defaults are platform-dependent until you set them explicitly: true on Android / Windows / macOS (devices with a human at the keyboard), false on Linux and other headless runtimes. That's why calls to a Linux node are off by default — set-allow-calls true is the way to turn them on from the command line (the Profile page in the Web UI has the same toggle). An explicit value sticks across upgrades.

# Allow calls to this Linux node (e.g. a desktop with a mic + camera):
meshhold profile set-allow-calls true
# allow_calls set to true

meshhold profile show
# node_id:      12D3KooW…
# display_name: garage-pi
# country_code: RS
# allow_calls:  true

Note that this flag only governs whether peers offer the call button and whether this node accepts incoming calls. Actually answering still needs working audio/video I/O — on a truly headless server with no mic, camera, or speakers the button will appear but there's nothing to answer with.

s3-key

Family: API.

meshhold s3-key add [--label <text>]
meshhold s3-key list
meshhold s3-key delete <access_key_id>

s3-perm

Family: API.

meshhold s3-perm grant  <access_key_id> <vault_id> <perms>
meshhold s3-perm revoke <access_key_id> <vault_id>
meshhold s3-perm list   [--key <id>] [--vault <id>]

<perms> accepts read, write, read+write, plus the shorthands r, w, rw, read,write. To remove a grant entirely use revoke, not grant <... > none.

mgmt-keys

Family: auto — the self-key subcommands talk to the running daemon over REST and fall back to the metadata store when it's stopped (the peer subcommands are REST-only — see below).

Manages this node's self management keys — named credentials another device presents when it wants to invoke a capability on this node (currently tunnel and camera). See the mesh-VPN scenario for how these get consumed.

Keys are filed under a saved network: the Web UI's Network → Keys tab shows only the active network's keys (plus untagged keys, which appear everywhere). A new key is filed under the active network by default; pass --network <id> to file it elsewhere. The tag also scopes verification: this node only honours a self key while it is connected to that key's network — a key filed under network A won't authorise a tunnel / mesh / camera request while the node is on network B. Untagged (global) keys are honoured on every network. The swarm key is still the outer gate; the network scope is defence-in-depth for a node that serves several networks. To make a key work everywhere, file it under All networks (global) (Web UI) or --network "".

meshhold mgmt-keys list   [--json]
meshhold mgmt-keys add    --name <text> [--caps <list>] [--expires-in <dur> | --never-expires]
                          [--allow <proto:port> ...] [--key <secret>] [--network <id>]
meshhold mgmt-keys show   <id>          [--json]
meshhold mgmt-keys share  <id>          [--node-id <peer>]
meshhold mgmt-keys rm     <id>

share prints the unified meshhold://join?mgmt_key=… invite (the form another device's scanner recognises as a management key). Because the command runs offline it can't discover this node's own peer ID — pass --node-id <peer> to embed it so the receiver can auto-bind the key to the right node. Without it the invite still works; the receiver picks the node manually.

<id> accepts any unambiguous prefix of the full key ID — paste the short 8-char form list prints.

meshhold mgmt-keys add --name="My phone"   --caps=tunnel,camera --expires-in=30d
meshhold mgmt-keys add --name="Friend exit" --caps=tunnel       --never-expires
# Stand up a mesh-LAN network (see the Flat Mesh LAN scenario):
meshhold mgmt-keys add --name="Home net" --caps=meshlan --never-expires \
    --allow tcp:22 --allow tcp:445
# …then JOIN it on another node with the printed secret:
meshhold mgmt-keys add --name="Home net" --caps=meshlan --never-expires \
    --key <secret>

mgmt-keys peer

Family: API (daemon must be running).

The subcommands above manage self keys — the credentials this node hands out. mgmt-keys peer manages the mirror image: the credentials other nodes have granted us, which forwards add --peer-key and vpn up --key reference by ID. Storing one from the CLI is what makes a fully headless port-forward / VPN setup possible.

meshhold mgmt-keys peer list                       [--json]
meshhold mgmt-keys peer add  <invite-or-key> --name <text> [--node-id <peer>] [--network <id>]
meshhold mgmt-keys peer rename <id> <new-name>
meshhold mgmt-keys peer rm     <id>

--network <id> files the stored credential under a saved network for the Web UI's per-network Keys filter (defaults to the active network).

add accepts either the full meshhold://join?mgmt_key=… invite the other node's mgmt-keys share (or its Web UI) produced — it parses the issuing node_id and any password-gate parameters out of the URL — or a bare key, in which case pass --node-id to bind it to the issuer. <id> accepts any unambiguous prefix of the ID shown by peer list.

# On node A (the exit), mint and share a tunnel key:
meshhold mgmt-keys add --name="for my laptop" --caps=tunnel --never-expires
meshhold mgmt-keys share <id>
# meshhold://join?mgmt_key=…&node_id=12D3KooW…

# On node B (the client), store it, then use it in a forward:
meshhold mgmt-keys peer add 'meshhold://join?mgmt_key=…&node_id=12D3KooW…' --name "A exit"
meshhold mgmt-keys peer list      # copy the short id

networks

Family: mixed. list / set-swarm-key are auto — they prefer the running daemon's /api/v1/networks and fall back to opening networks.json (and the metadata Badger) directly when it's stopped, so they work in either state. invite / add / add-peer are API (daemon must be running). Each per-command --help states which.

Manages the saved-networks roster the daemon persists at <metadata_dir>/networks.json.

meshhold networks list                       [--json]      # direct
meshhold networks set-swarm-key <id>         (--key <psk> | --regenerate)   # direct
meshhold networks invite        <network_id> [--source own|upstream]        # API
meshhold networks add           <invite>                                    # API
meshhold networks add-peer      <network_id> <invite>                       # API
meshhold networks connect       <network_id>                                # API
meshhold networks disconnect                                                # API
meshhold networks rm            <network_id>                                # API

key-receive

Family: API (daemon must be running).

Show a QR code that an already-configured device (the phone app) scans to push a key to this node — the headless counterpart to the web UI's "receive a key" button. Handy when bringing a node up over SSH, where you can't paste a swarm key. On the other device you open the Scan tab, scan the code, and pick which key to send; it's delivered over the network, encrypted to a one-time key embedded in the QR. On a LAN nothing leaves the local network, and only the key you pick is ever sent.

meshhold key-receive [--type network|vault|chat|mgmt|contact]
                     [--port <n>] [--host <addr>]… [--apply] [--qr]

On the same LAN the defaults just work. For a VPS, open a port and pass --port (and --host <public-ip> behind NAT). To pin the port for the web UI's button too, set node.key_relay_port in the config.

# On the VPS console (over SSH): receive a swarm key by scanning with your phone.
# Open TCP 39000 in the firewall first.
meshhold key-receive --type network --port 39000
# …scan the QR, pick the network on your phone, and this node joins it.

forwards

Family: API.

Manages TCP/UDP port forwards that ride the libp2p tunnel mesh (inherits multi-hop routing + libp2p Circuit Relay v2). Direction mirrors ssh -L / ssh -R.

meshhold forwards list                          [--json]
meshhold forwards add  --name <n> (--forward | --reverse) --proto <tcp|udp> \
                       --listen <addr> --remote <host:port> \
                       --peer-node <peer_id> --peer-key <key_id> \
                       [--id <stable-id>] [--no-autostart]
meshhold forwards rm    <id>
meshhold forwards start <id>
meshhold forwards stop  <id>

Exactly one of --forward / --reverse must be set.

Two canonical shapes:

# Expose a local Project Zomboid server through a public VPS:
meshhold forwards add \
  --name pz-via-vps --reverse --proto udp \
  --peer-node 12D3KooW…VPS  --peer-key vps-key-id \
  --listen :16261 --remote 192.168.1.50:16261

# Connect through a domestic peer to a remote OpenVPN:
meshhold forwards add \
  --name openvpn --forward --proto udp \
  --peer-node 12D3KooW…HOME --peer-key home-key-id \
  --listen 127.0.0.1:1194 --remote 10.0.0.5:1194

agent

Family: API.

Drives the local daemon's universal-AI-agent surface — list / create / delete agent instances, share them with other devices, manage Code-mode workspaces, and trigger the OAuth sign-in.

meshhold agent list                                 [--json]
meshhold agent show       <id>                      [--json]
meshhold agent create     [--name <text>] [--type claude|opencode|gemini]
meshhold agent delete     <id>
meshhold agent share      <id>
meshhold agent join       <invite>
meshhold agent reset-key  <id>     --force
meshhold agent login      <id>
meshhold agent workspace  add      <instance-id> <path> [--name <text>]
meshhold agent workspace  remove   <instance-id> <path>

status

Family: API.

One-shot health summary of the running daemon — the first command to reach for on a headless box. Folds /system/status, /system/nat, and /version into a single round-trip: version, node ID, network state, enabled surfaces (S3 / media / enrich), TLS, at-rest encryption, public IP, and listen addresses. --json for the raw objects.

meshhold status
# version:     0.7.208
# node_id:     12D3KooW…
# running:     true
# network:     connected (home)
# surfaces:    s3=false media=true enrich=true
# tls:         on (self-signed)
# at_rest:     on (linux-secret-service)

replicate-now

Family: API.

Forces one immediate replication cycle instead of waiting for the periodic tick — handy right after joining a vault or adding a peer. The daemon pulls any missing blocks and re-announces what it holds. Requires the P2P stack to be up; an offline node returns an error.

meshhold replicate-now
# replication cycle complete

settings

Family: API.

Reads and edits the runtime toggles the Web UI's Features panel owns — these live in the metadata store, not config.yaml, so this is the only headless way to flip them. With no flags it prints the current state; each flag actually passed is sent as a partial update (the rest are left untouched).

meshhold settings                              # show
meshhold settings --enrich=true                # start the metadata enricher
meshhold settings --node-reliable=false        # mark this node unreliable
meshhold settings --tmdb-key=<key>             # "" clears it
meshhold settings --blocks-quota=53687091200   # 50 GiB cap; 0 = uncapped

chat

Family: API (daemon must be running and connected to a network).

Use chat rooms from the terminal. A room is addressed by its full id, an unambiguous id prefix, or its display name. Rooms are vaults of type chat — create / join one with vault join … --type chat and share one with vault share.

meshhold chat list
meshhold chat read <room>   [--limit <n>] [--mark-read]
meshhold chat send <room> <text>

read renders media / location messages as compact placeholders and can --mark-read up to the newest line shown.

meshhold chat list
meshhold chat send "Family" "running late, back by 7"
meshhold chat read Family --mark-read

vpn

Family: API.

Bring the system VPN up from the command line. With no exit it's the master toggle — the mesh overlay plus whatever exits are configured, on one interface (the way to turn a mesh-only overlay on from a headless box). With --exit/--key it routes the default through that exit, authorised with a peer mgmt key this node holds (add one with mgmt-keys peer add).

meshhold vpn up                                          # mesh + configured exits
meshhold vpn up   --exit <peer_id> --key <peer_key_id> [--name <label>]
meshhold vpn down
meshhold vpn status

status always works (reports not-running / not-supported cleanly); down is idempotent. The system VPN needs a daemon-owned TUN, so up works on Windows (via the helper service) and Linux; on Android the fd arrives from the platform VpnService, so up returns a clear error there.

Exit routing — vpn routes, vpn config, vpn policy

The full split-tunnel / multi-exit model (see Exit routing) is scriptable headlessly. All three talk to the daemon and persist to the vpn: config block.

Kept-local routes — destinations that stay off the exit (LAN, exceptions):

meshhold vpn routes list
meshhold vpn routes add <cidr> [--note <label>]
meshhold vpn routes rm  <id>

list shows system (read-only), auto-detected host subnets, and custom routes; config-managed rows are tagged [config] and can't be removed here.

Exit selection, fail behaviour, default route — config show prints the current block; config set changes only the flags you pass:

meshhold vpn config show
meshhold vpn config set [--enabled] [--exit <peer_id>] [--key <peer_key_id>]
                        [--name <label>] [--fail-mode drop|direct]
                        [--default-route exit|direct|drop]
                        [--auto-local-subnets]

--fail-mode direct is fail-open (send tunneled traffic out the host when the exit is down; Windows/Android, else drops). --default-route direct makes a selective VPN (only policy destinations are tunnelled). --enabled arms boot auto-start.

Exits (multi-exit policy) — route destination prefixes through exit nodes. A 0.0.0.0/0 rule is a full tunnel. For a destination the daemon tries the matching exits highest-priority first and fails over to the next live one (prefix length only breaks ties at equal priority), so two 0.0.0.0/0 rules at different priorities are a hot-standby pair:

meshhold vpn policy list
meshhold vpn policy add <cidr> [<cidr>…] --exit <peer_id> --key <peer_key_id> \
    [--priority <n>] [--name <label>] [--note <text>]
meshhold vpn policy state <id> <permanent|temporary|off> [--priority <n>]
meshhold vpn policy rm  <id>

Egress / download QoS — prioritise and rate-shape tunnel traffic so a bulk transfer can't starve interactive flows. Rates are in kilobits/s; priority only takes effect once a rate is set (the shaper must be the bottleneck, not your ISP). See QoS:

meshhold vpn qos show                  # policy + live per-class telemetry
meshhold vpn qos preset [name]         # list built-in presets, or apply one
meshhold vpn qos set --enabled --uplink-kbits <n> --downlink-kbits <n>
meshhold vpn qos set --from-file <policy.json>   # full classes + rules

adblock

Family: API.

Manage the ad blocker — the domain blocklists merged into one filter and applied to the in-app tunnel browser and/or the system VPN. On the VPN the in-mesh resolver (the system DNS while the VPN is up) NXDOMAINs blocked names for every app on the device. Mirrors the Settings → Ad blocker panel; edits persist as a runtime override and the daemon rebuilds the filter live.

meshhold adblock                       # status: config + per-source domain counts
meshhold adblock status [--json]
meshhold adblock js <on|off>           # in-page JS cosmetic hiding (browser only)
meshhold adblock apply browser <on|off>
meshhold adblock apply tunnels <on|off>
meshhold adblock sources               # list sources with their index
meshhold adblock add <url> [--name <label>] [--disabled]
meshhold adblock enable  <index>       # index from `adblock sources`
meshhold adblock disable <index>
meshhold adblock remove  <index>
meshhold adblock refresh               # re-download every enabled source now

Sources are hosts-format URLs (0.0.0.0 host or one domain per line); the built-in offline list shows as a non-removable row. Only enabled sources are downloaded and applied — disabled ones cost nothing. status shows each enabled source's live state (downloading / ok / error) and parsed domain count.

meshlan

Family: API.

Inspect the mesh-LAN overlay — the routable virtual network where every member reaches another member's local services by a stable virtual IP.

meshhold meshlan status [--json]

Shows this node's virtual IPs and the peers reachable by IP, or reports that this node holds no meshlan key, or that the overlay is idle (the TUN couldn't come up). Membership and which local ports are open are controlled by Mesh LAN (meshlan) management keys, not this command — see mgmt-keys.

audit

Family: API.

Reads the daemon's security / activity audit log — logins, vault unlocks, key changes, swarm-key rotations, peers appearing / leaving.

meshhold audit list   [--limit <n>] [--severity info|warn|critical] [--json]
meshhold audit export [file]        # full JSON-Lines dump ('-' or omit = stdout)

logs

Family: API.

A snapshot of the daemon's in-memory log ring (not a live tail). Since the CLI logs to stderr with no file to tail, this is how you see what a running daemon has been doing on a headless install.

meshhold logs                     # last 1000 lines
meshhold logs --level=warn        # warnings and errors only
meshhold logs --limit=200
meshhold logs --export node.log   # dump the whole ring to a file ('-' = stdout)

bug-report

Family: API.

Builds a diagnostics bundle (daemon status, network snapshot, redacted config, audit tail, log ring) and optionally uploads it — the headless counterpart of the Profile-page "Report a problem" button.

meshhold bug-report send  [--description <text>]   # build + upload in one shot
meshhold bug-report build [--description <text>]   # build on disk only
meshhold bug-report list                           # bundles saved on the host

send needs the operator to have configured a submit URL (node.diagnostics.submit_url); otherwise use build and hand the file over out-of-band.

2fa

Family: auto — prefers the running daemon's admin-token endpoint (no restart needed) and falls back to BadgerDB when it's stopped.

Enable / disable / inspect the optional TOTP second factor for the Web UI login. Compatible with Google Authenticator, Aegis, FreeOTP, etc.

meshhold 2fa setup     # print the enrolment QR + recovery codes
meshhold 2fa disable
meshhold 2fa status

send / recv / transfers

Family: API.

Direct node-to-node file transfer — files stream peer-to-peer over libp2p and are never stored in a vault or chat.

meshhold send <file> [<file>...] [--to <node_id>]   # interactive picker if --to omitted
meshhold recv                       [--once]         # accept inbound transfers from a TTY
meshhold transfers                                   # list recent + in-flight transfers
meshhold receive-policy [ask|accept-trusted|accept-from|off]   # show or set consent policy
meshhold incoming-folder [path]                      # show or set where received files land

send reads the file paths on the daemon's host (the common case: CLI and daemon co-located). recv is the headless answer to "the receive policy is ask but there's no Web UI open to click Accept".

blocks

Family: auto (REST when the daemon is running, direct BadgerDB walk when it's stopped).

Ciphertext-store maintenance.

meshhold blocks gc [--dry-run]

gc deletes orphan blocks (no catalog entry references them) and redundant blocks (regenerable on demand from a file-mode source), then reports the bytes freed. --dry-run reports without touching disk.

telemetry

Family: local — rewrites config.yaml only; takes effect at the next daemon start.

Inspect or toggle the once-a-day anonymous usage beat.

meshhold telemetry status
meshhold telemetry disable
meshhold telemetry enable

See privacy and telemetry for the exact fields the beat carries.

config

Family: local — reads config.yaml and nothing else.

meshhold config lint [--strict]

Reports three kinds of finding:

The warnings matter because config loading is deliberately permissive about keys it does not recognise — failing on one would break every node carrying a key from a different build. So blocks_max_byte: 12345 parses, applies nothing, and says nothing. This is how you find it.

  WARNING  node.blocks_max_byte
           unknown key — it parses, and then nothing reads it.
  WARNING  swarm_key
           secret written into config.yaml … Use MESHHOLD_SWARM_KEY or
           swarm_key_file instead

Exits non-zero when there is an error, so it can gate a deploy. --strict fails on warnings too.

at-rest

Family: local — edits config.yaml and the on-disk state directly. The daemon must be stopped.

Inspect or change at-rest encryption of the metadata store, the libp2p identity (node.key), and the saved networks (networks.json — this is where the swarm key lives).

meshhold at-rest status
meshhold at-rest enable
meshhold at-rest disable --yes

status reports what config.yaml asks for and what the disk actually holds, separately, plus which key provider is in play:

at-rest encryption: enabled (config: /etc/meshhold/config.yaml)
  metadata_dir:     /var/lib/meshhold/meta
  database:         encrypted
  node.key:         encrypted
  networks.json:    encrypted
  key provider:     linux-host-file
  host binding:     machine-id

Those two disagreeing is worth knowing about: a node whose disk is encrypted while config says it is not will refuse to start, rather than write plaintext over encrypted state. status names that case and both ways out.

enable sets at_rest_encryption.enabled: true after checking that a key source actually exists on this host. The migration itself runs at the next daemon start.

disable decrypts everything back to plaintext and clears the flag. It requires --yes because it lowers the protection on the node. Nothing is deleted until the plaintext state has been reopened and verified to hold what the encrypted state held.

Reach for disable when the keystore is gone or changing — a reinstalled OS, a wiped keyring, a re-imaged VM, or a move to passphrase_file — and the alternative is a node that will not start. It needs the master key to work, so it cannot rescue a node whose key is genuinely lost; see at_rest_encryption.

Hidden subcommands

_mcp-approve is reserved for the daemon's own use — it spawns this process under claude --permission-prompt-tool to bridge MCP approvals back over loopback REST. The leading underscore is the convention for internal commands hidden from --help; you should never need to invoke it directly.

Environment variables

A small set of env vars are read by the CLI. The secret-carrying ones take precedence over both the *_file and inline forms in config.yaml — see keeping secrets out of this file.

Exit codes

All commands follow the standard cobra convention: