CLI Reference

This is the quick-lookup cheat-sheet for the leapmux command line. It covers the top-level command list, a synopsis and flag table for each daemon mode (solo, hub, worker, dev), the version command, the environment variables LeapMux reads, and outlines of the three large command groups — recover (offline break-glass), control (user-facing scripting), and control admin (hub administration) — which have their own dedicated chapters.

For task-oriented walkthroughs rather than reference tables, see Running LeapMux (run modes, ports, data dirs, Docker), Configuration (full config-key reference and storage backends), Recovery, and Control CLI.

Top-level usage

leapmux is a single binary with seven commands:

Usage: leapmux <command> [flags]

Commands:
  solo      Run Hub + Worker locally for single-user use
  hub       Run the Hub service
  worker    Run a Worker connected to a Hub
  dev       Run Hub + Worker for development
  recover   Offline break-glass recovery (opens the database directly)
  control   Remotely control LeapMux from a script or another LeapMux agent
  version   Print version and exit

Common options:
  -h, --help     Print help and exit
  -version       Print version and exit
  --version      Print version and exit

Any command name can be shortened as far as it stays unambiguous.

Notes on dispatch:

• The default TCP port for every mode is 4327.
• -h, -help, and --help are recognized at every level (help prints to stdout, exit 0). The bare help token works only at the top level.
• -version, --version, and the version command all print the same version string.
• Daemon flags must follow the command keyword — leapmux solo -listen ..., not leapmux -listen ... solo. LeapMux rejects an unknown leading -flag because it is not a top-level flag.
• LeapMux rejects an unexpected positional argument and points you at --help.

Durations. Every flag whose default is shown as a duration (1h, 5m, …) takes a unit suffix — ns, us, ms, s, m, h, d, w — and combines parts. A bare number is a count of seconds. See Duration values.

solo

Run a Hub and a Worker in one process on loopback, with no login (every request is auto-authenticated as the admin). See Running LeapMux for details.

leapmux solo [flags]
# then open http://127.0.0.1:4327

hub

Run only the Hub: authentication, workspace management, Worker registration, and the encrypted relay. Binds all interfaces by default and requires a real login. See Running LeapMux and Configuration for the complete key reference.

leapmux hub [flags]

This table lists the most common flags. The full set — including all PostgreSQL/MySQL/CockroachDB/YugabyteDB/TiDB pool-tuning flags — is in Configuration.

Server options

Behavioral settings. Auth policy (sign-up, verification, sessions), SMTP, timeouts, and per-user limits are not flags: they are instance settings in the Hub’s database, managed by leapmux control admin settings (see Configuration and the control admin section).

Storage options

The Postgres family (-storage-postgres-*, -storage-cockroachdb-*, -storage-yugabytedb-*) and the MySQL family (-storage-mysql-*, -storage-tidb-*) share pool defaults:

CockroachDB/YugabyteDB use the Postgres driver; TiDB uses the MySQL driver. See Configuration for every storage flag and DSN format.

Common options

worker

Run a Worker that connects out to a Hub. Workers do not serve an inbound HTTP port; they register with the Hub using a key minted in the Hub UI. See Managing Workers.

# First run — register with a key from the hub UI:
leapmux worker -hub https://hub.example.com -registration-key <key>

# Subsequent runs — credentials are saved, no key needed:
leapmux worker -hub https://hub.example.com

Worker options

Timeout and limit options

SQLite database options

Common options

worker cross-worker-pins

A local-only utility for inspecting the Worker’s TOFU pin store. It runs entirely against local files — no Worker process starts. See Security & Threat Model for what these pins protect.

leapmux worker cross-worker-pins list|show|remove [--target-worker-id=<id>] [--data-dir=<dir>]

When --data-dir is omitted, the data directory is resolved through the standard Worker config loader, so it matches what leapmux worker would use: default ~/.config/leapmux/worker, overridable with LEAPMUX_WORKER_DATA_DIR (or a data_dir entry in worker.yaml).

dev

Run a Hub and a Worker in one process with real password authentication — the same program as solo but with login enabled, binding all interfaces, and the first admin bootstrapped through the /setup flow. See Running LeapMux.

leapmux dev [flags]

Dev mode uses the same flag set as solo.

The other differences from solo: dev enables signup_enabled=true by default, and the bundled Worker’s auto-registration is deferred until the first admin completes /setup. The runtime knobs (session_duration_seconds, limits, timeouts, …) are leapmux control admin settings keys. The default -listen is :4327 (all interfaces), and the config/data location is ~/.config/leapmux/dev/.

version

Print the build version and exit. The output is a single line with fields joined by ·:

$ leapmux version
0.0.1-dev · 9c81b87 · feature/foo · Thu, 4/23/2026, 11:45:00 PM KST

Fields are conditional: the version value is always present (falls back to dev), the commit hash and build time appear when set, and the branch is shown only when it is not main. The top-level -version / --version flags print the same string.

recover (command-group outline)

leapmux recover is the offline break-glass tree: it manages the Hub’s database and encryption key file directly, with the hub stopped — no network call, no login. It is deliberately tiny. For full per-command flags and behavior, see Recovery.

leapmux recover <group> <command> [flags]

Recover commands accept --data-dir to locate the data directory. The commands that open the database also accept --config, which loads the Hub’s storage settings; pass it whenever the Hub runs on Postgres or MySQL. Three leaves need no database connection and take no --config: db path, encryption-key rotate, and encryption-key rotate-pepper (which also takes --yes).

Commands that take --password prompt interactively when you omit the flag. Every other administration task is online — see Admin CLI, and Recovery for the full per-command reference.

control (command-group outline)

leapmux control drives a running Hub over RPC — it does not touch the database. It is used both by external scripts (which authorize with leapmux control auth login) and by agents/terminals that LeapMux spawns (which inherit LEAPMUX_CONTROL_* env vars). Every command emits a JSON envelope — {"data": ...} on success, {"error": {"code", "message"}} on failure (both on stdout) — with a non-zero exit on failure. For full per-command flags, entity-ID resolution, and output shapes, see Control CLI.

leapmux control <group> <command> [flags]
leapmux control auth login --hub https://hub.example.com   # authorize first

Environment variables

LeapMux reads configuration and credentials from these environment variables.

Daemon configuration (hub / solo / dev and worker)

Hub-family modes (hub, solo, dev) read variables prefixed LEAPMUX_HUB_; the Worker reads LEAPMUX_WORKER_. The variable name after the prefix is lowercased to form the config key — for example LEAPMUX_HUB_LISTEN sets listen, LEAPMUX_WORKER_HUB sets hub.

The Worker reads:

The prefix strip lowercases the remainder but does not translate _ into ., so nested storage keys such as storage.type and storage.postgres.dsn cannot be set cleanly via env vars — use the YAML config file or the dedicated -storage-* flags instead. See Configuration for the full list and precedence rules (defaults < config file < env vars < explicitly-set CLI flags).

Remote CLI (leapmux control)

The LEAPMUX_CONTROL_* variables other than _CONFIG_DIR are injected automatically by the Worker into the agents and terminals it spawns; you do not set them by hand. See Control CLI for how they drive entity-ID resolution.

Config and data locations

Each mode reads an optional YAML config file named after the mode. Each mode stores data under its own directory. LeapMux skips a missing config file without a message.

In solo and dev, the data directory is split into <data-dir>/hub and <data-dir>/worker subdirectories. See Running LeapMux and Configuration for the full layout and resolution rules.