CLI Reference

This is the quick-lookup cheat-sheet for the leapmux command line. It covers the top-level command list, the commands that every mode shares, 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), Starting and Stopping, 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. --version works at the top level and after a mode command (leapmux hub <command> --version).
• A mode needs a command, and flags follow the command: leapmux solo start -listen .... leapmux solo -listen ... fails, and the error shows the corrected command. LeapMux also rejects an unknown leading -flag such as leapmux -listen ..., 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.

Mode commands

Every mode requires a command. The seven commands below work in every mode, and the worker mode adds three. Start and stop an instance with start and stop; use run only in a container. Starting and Stopping explains the service that start and enable create.

start, restart, enable, and run also take the runtime flags of the mode, which its section below lists. A service saves the runtime flags that you give it. stop, status, and disable take only --data-dir and --config from the mode, plus their own options below.

A lifecycle command that succeeds, and worker register, end with the commands to run next for the same instance, such as stop and disable after start, or start and enable after disable. Each one selects the instance by its configuration file and its data directory, so it works from any directory. run and status --json print no such commands.

Options of the mode commands

status exits with 0 when the instance runs, 3 when it is stopped, and 1 for a failure, an instance that does not answer, or invalid use. A Worker without a Hub connection and a dev instance that waits for /setup both count as running.

status --json

status --json prints one JSON object and nothing else. A value that is not available is null.

The state fields take these values:

• process.state: starting, running, stopping, stopped, failed, or unresponsive. An unresponsive instance holds its lock but does not answer on its control endpoint.
• registration.state: not_applicable, unregistered, pending, registered, or invalid
• connection.state: not_applicable, pending_setup, connecting, connected, or disconnected

solo

Run a Hub and a Worker in one process on loopback. Local IPC needs no credential. A TCP browser sets the first solo password, then every TCP address asks for it. See Running LeapMux and Network access.

leapmux solo start [flags]
# then open the URL that it prints: http://localhost:4327 by default

restart, enable, and run take the same flags.

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 start [flags]

restart, enable, and run take the same 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. Register a Worker once with worker register before you start it. See Managing Workers.

# Once: register, with a key from the Register worker dialog of the Hub.
leapmux worker register --hub https://hub.example.com --registration-key <key>

# Then start it as a background service.
leapmux worker start [flags]

restart, enable, and run take the same flags.

The Worker connects to the Hub URL that its registration saved, so the runtime commands take no --hub and no --registration-key. They refuse both flags.

Worker options

Timeout and limit options

SQLite database options

Common options

worker register

Register the Worker with a Hub, save its credentials in the data directory, and exit. It never starts the Worker.

leapmux worker register --hub <url> --registration-key <key> [flags]

-hub and -registration-key are flags only: no config key or environment variable sets them. When an earlier run stopped before it finished, the same command completes that registration without using another key. A data directory that already holds credentials makes the command fail; see Register a Worker again.

worker deregister

Delete this Worker on its Hub, then remove its credentials from the data directory. Stop the Worker first.

leapmux worker deregister [flags]

The command keeps worker.db. When the Hub cannot confirm the deletion, it keeps the credentials too, so that you can run it again.

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 the data directory of the other Worker commands: 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 start [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_NAME sets name. A service does not inherit these variables from the shell that starts it; see Environment variables.

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.

Files that LeapMux manages in a data directory

Files in the Worker’s data directory says which Worker files to back up. status --json is the interface for scripts; the files above have no stable format.