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 a pointer to the two large command groups — admin and remote — 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), Admin CLI, and Remote 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
  admin     Manage LeapMux resources
  remote    Drive LeapMux remotely (CLI / spawned agent)
  version   Print version and exit

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

Notes on dispatch:

• The default TCP port for every mode is 4327.
• -h, -help, --help, and help are all recognized as help tokens (help prints to stdout, exit 0).
• -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. An unknown leading -flag errors with <flag> is not a top-level flag.
• Help tokens are recognized at every level; unexpected positional args are rejected with unexpected argument: "<arg>" (use --help for usage).

Tip: Flags accept both single- and double-hyphen forms (-listen and --listen are equivalent). This chapter uses the single-hyphen form, matching the binary’s help output.

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

Note: -public-url is not available in solo mode; public_url set by any means is rejected with public_url is not supported in solo mode. Binding solo to a non-loopback address logs a warning because every request is auto-authenticated as the admin — use hub or dev for network-exposed deployments.

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

Auth options

SMTP options

Timeout and limit options

Storage options

The Postgres family (-storage-postgres-*, -storage-cockroachdb-*, -storage-yugabytedb-*) defaults to max-conns 25, min-conns 5, conn-max-lifetime-seconds 3600, max-conn-idle-time-seconds 300, health-check-period-seconds 30. The MySQL family (-storage-mysql-*, -storage-tidb-*) defaults to max-conns 25, max-idle-conns 5, conn-max-lifetime-seconds 3600, conn-max-idle-time-seconds 300. CockroachDB/YugabyteDB use the Postgres driver; TiDB uses the MySQL driver. See Configuration for every storage flag and DSN format.

Common options

Note: Two hub config keys have no CLI flag and are set only via YAML or env var: secure_cookies (LEAPMUX_HUB_SECURE_COOKIES) and encryption_key_path (LEAPMUX_HUB_ENCRYPTION_KEY_PATH, default <data-dir>/encryption.key). See Configuration and Encryption & Data.

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

Note: An unregistered Worker with no saved credentials errors with worker is unregistered: pass --registration-key <key> from the hub UI. Passing -registration-key again to an already-registered Worker errors with worker is already registered; remove --registration-key or wipe local state to re-register, which protects you from burning a one-time key.

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).

Note: The binary’s own help text for this flag mentions LEAPMUX_DATA_DIR, but that variable is not read by the leapmux binary itself (only by the Docker entrypoint script), so it has no effect on this subcommand’s data-dir resolution. Use LEAPMUX_WORKER_DATA_DIR (or --data-dir) here.

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, with one addition:

The other differences from solo: the default -listen is :4327 (all interfaces), the config/data location is ~/.config/leapmux/dev/, and the bundled Worker’s auto-registration is deferred until the first admin completes /setup.

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.

admin (command-group outline)

leapmux admin manages a Hub’s persistent data directly against its database and on-disk encryption key — no running Hub or network call required. It is a tree of command groups. For full per-command flags and behavior, see Admin CLI.

leapmux admin <group> <command> [flags]

Most admin commands accept --data-dir and --config to locate the database and encryption key; output is indented JSON or a tabular listing. Commands that take --password prompt interactively when the flag is omitted (and require --password when stdin is not a terminal). See Admin CLI, Authentication Providers, and Encryption & Data.

remote (command-group outline)

leapmux remote drives a running Hub over RPC — it does not touch the database. It is used both by external scripts (which authorize with leapmux remote auth login) and by agents/terminals that LeapMux spawns (which inherit LEAPMUX_REMOTE_* 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 Remote Control CLI.

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

Note: Agents are opened, closed, listed, and renamed through the tab group (tab open --type agent, tab close, …) — there is no agent open/agent close/agent list. The agent group is for agent-specific operations only.

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 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 remote)

The LEAPMUX_REMOTE_* variables (the _SOCK / _TOKEN / _*_ID / _TAB_* family) are injected automatically by the Worker into the agents and terminals it spawns; you do not set them by hand. See Remote Control CLI for how they drive entity-ID resolution.

Config and data locations

Each mode reads an optional YAML config named after the mode, and stores data, under its own directory. A missing config file is silently skipped.

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.