CLI Reference

bmux

Server-backed terminal multiplexer CLI
Usage: bmux [OPTIONS]
Options:
FlagDescriptionValuesDefault
--configMerge an additional config file (highest precedence layer)
--targetExecute command against a configured target (local or remote)
--runtimeSelect named runtime instance (default: default)
-v, --verboseEnable verbose loggingtrue, false
--log-levelSet log level for file loggingerror, warn, info, debug, trace
Subcommands:
  • setup — First-run setup wizard for hosted mode (p2p default)
  • host — Start hosted mode (p2p default, control-plane opt-in)
  • join — Join a hosted link/target quickly
  • hosts — List known hosts/targets (recent first)
  • auth — Authentication commands
  • access — SSH-key access controls for iroh hosting
  • kiosk — SSH kiosk profiles and token management
  • share — Share helpers for hosted links
  • unshare — Remove a named shared link
  • connect — Connect to a target and attach to a session
  • new-session — Create a new session
  • list-sessions — List active sessions
  • list-clients — List connected clients
  • kill-session — Kill a session by name or UUID
  • kill-all-sessions — Kill all sessions
  • attach — Attach to a session by name or UUID
  • detach — Detach from the current session
  • follow — Follow another client’s active target
  • unfollow — Stop following a client
  • session — Session management commands
  • remote — Remote target utilities
  • server — Server lifecycle and status tools
  • logs — Logging diagnostics and utilities
  • diagnostics — Structured diagnostics event viewer
  • config — Configuration management and inspection
  • perf — Runtime performance telemetry controls
  • doctor — Run system-wide health checks
  • keymap — Keymap tools and diagnostics
  • terminal — Terminal capability tools and diagnostics
  • playbook — Headless playbook execution and testing
  • sandbox — Run bmux in an isolated ephemeral sandbox environment
  • slot — Manage bmux slots (multi-version installs)
  • env — Alias for bmux slot ... (same subcommand tree; useful alongside the standalone bmux-env binary for symmetry)
  • device-seal-broker — Internal sshenv device-seal broker used by panes

bmux setup

First-run setup wizard for hosted mode (p2p default)
Usage: bmux setup [OPTIONS]
Options:
FlagDescriptionValuesDefault
--checkCheck hosted readiness without starting or changing runtime statetrue, false
--modeHosted operation mode (p2p is infra-light default)p2p, control-plane

bmux host

Start hosted mode (p2p default, control-plane opt-in)
Usage: bmux host [OPTIONS]
Options:
FlagDescriptionValuesDefault
--listenOptional listen address for local gateway bridge127.0.0.1:7443
--nameOptional friendly name hint
--copyCopy the resulting join link to clipboardtrue, false
--daemonRun host runtime in the backgroundtrue, false
--statusShow hosted-mode runtime statustrue, false
--stopStop hosted-mode runtime if runningtrue, false
--restartRestart hosted-mode runtime in backgroundtrue, false
--modeHosted operation mode (p2p is infra-light default)p2p, control-plane

bmux join

Join a hosted link/target quickly
Usage: bmux join [LINK] [SESSION]
Arguments:
NameDescriptionRequired
linkLink or target name (bmux://, iroh://, https://, or configured target)no
sessionSession name or UUIDno

bmux hosts

List known hosts/targets (recent first)
Usage: bmux hosts [OPTIONS]
Options:
FlagDescriptionValuesDefault
--verboseInclude detailed target mappings and diagnosticstrue, false

bmux auth

Authentication commands
Subcommands:
  • login — Login and register this device for hosted mode
  • status — Show current authentication state
  • logout — Clear locally stored authentication state

bmux auth login

Login and register this device for hosted mode
Usage: bmux auth login [OPTIONS]
Options:
FlagDescriptionValuesDefault
--no-browserDo not try to open a browser automaticallytrue, false

bmux auth status

Show current authentication state

bmux auth logout

Clear locally stored authentication state

bmux access

SSH-key access controls for iroh hosting
Subcommands:
  • status — Show iroh SSH access status
  • init — Initialize iroh SSH access and enable it immediately
  • add — Add SSH keys to iroh allowlist
  • list — List currently authorized SSH keys
  • remove — Remove an SSH key from the allowlist
  • enable — Enable iroh SSH access enforcement
  • disable — Disable iroh SSH access enforcement

bmux access status

Show iroh SSH access status

bmux access init

Initialize iroh SSH access and enable it immediately
Usage: bmux access init [OPTIONS]
Options:
FlagDescriptionValuesDefault
--agentAdd all currently loaded SSH agent keystrue, false
--key-fileAdd a public key from file (repeatable)repeatable
--public-keyAdd a public key line directly (repeatable)repeatable
--github-userImport public keys from a GitHub username (repeatable)repeatable
--yesSkip interactive confirmation promptstrue, false

bmux access add

Add SSH keys to iroh allowlist
Usage: bmux access add [OPTIONS]
Options:
FlagDescriptionValuesDefault
--agentAdd all currently loaded SSH agent keystrue, false
--key-fileAdd a public key from file (repeatable)repeatable
--public-keyAdd a public key line directly (repeatable)repeatable
--github-userImport public keys from a GitHub username (repeatable)repeatable

bmux access list

List currently authorized SSH keys
Usage: bmux access list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux access remove

Remove an SSH key from the allowlist
Usage: bmux access remove <FINGERPRINT> [OPTIONS]
Arguments:
NameDescriptionRequired
fingerprintKey fingerprint to removeyes
Options:
FlagDescriptionValuesDefault
--yesSkip interactive confirmation promptstrue, false

bmux access enable

Enable iroh SSH access enforcement

bmux access disable

Disable iroh SSH access enforcement

bmux kiosk

SSH kiosk profiles and token management
Subcommands:
  • status — Show kiosk profile status and effective defaults
  • init — Initialize/update kiosk bootstrap files from config
  • issue-token — Issue a kiosk token scoped to a profile
  • revoke-token — Revoke one issued kiosk token by id
  • attach — Attach using a kiosk token (intended for forced SSH command)
  • ssh-print-config — Print generated sshd include text without writing files

bmux kiosk status

Show kiosk profile status and effective defaults
Usage: bmux kiosk status [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux kiosk init

Initialize/update kiosk bootstrap files from config
Usage: bmux kiosk init [OPTIONS]
Options:
FlagDescriptionValuesDefault
--profileKiosk profile to reconcile (repeatable)repeatable
--all-profilesReconcile all configured profilestrue, false
--dry-runPreview actions without writing filestrue, false
--yesSkip confirmation promptstrue, false

bmux kiosk issue-token

Issue a kiosk token scoped to a profile
Usage: bmux kiosk issue-token <PROFILE> [OPTIONS]
Arguments:
NameDescriptionRequired
profileKiosk profile nameyes
Options:
FlagDescriptionValuesDefault
--sessionOptional session override stored in token
--ttl-secsOptional token TTL in seconds (defaults to profile/default TTL)
--one-shotMark token as one-shot (defaults to profile/default one_shot)true, false
--multi-useMark token as reusable until expirytrue, false

bmux kiosk revoke-token

Revoke one issued kiosk token by id
Usage: bmux kiosk revoke-token <TOKEN_ID>
Arguments:
NameDescriptionRequired
token_idToken id to revokeyes

bmux kiosk attach

Attach using a kiosk token (intended for forced SSH command)
Usage: bmux kiosk attach <PROFILE> [OPTIONS]
Arguments:
NameDescriptionRequired
profileKiosk profile nameyes
Options:
FlagDescriptionValuesDefault
--tokenRaw kiosk token

bmux kiosk ssh-print-config

Print generated sshd include text without writing files
Usage: bmux kiosk ssh-print-config [OPTIONS]
Options:
FlagDescriptionValuesDefault
--profileKiosk profile to print (repeatable)repeatable
--all-profilesPrint all configured profilestrue, false

bmux share

Share helpers for hosted links
Usage: bmux share [TARGET] [SECONDARY] [OPTIONS]
Arguments:
NameDescriptionRequired
targetTarget/link to shareno
secondaryOptional second positional argument (used by bmux share revoke <name>)no
Options:
FlagDescriptionValuesDefault
--nameOptional stable share name
--roleOptional access role hintcontrol
--ttlOptional invite TTL (example: 24h, 30m)
--one-timeMark the share as one-time usetrue, false
--copyCopy resulting share link to clipboardtrue, false
--qrRender a terminal QR code for the share linktrue, false

bmux unshare

Remove a named shared link
Usage: bmux unshare <NAME>
Arguments:
NameDescriptionRequired
nameShare name/slug to removeyes

bmux connect

Connect to a target and attach to a session
Usage: bmux connect [TARGET] [SESSION] [OPTIONS]
Arguments:
NameDescriptionRequired
targetTarget name or ssh destination (user@host[:port] or ssh://…)no
sessionSession name or UUID; if omitted in TTY mode a picker is shownno
Options:
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected session
--globalKeep following across target session switches (requires –follow)true, false
--reconnect-foreverKeep reconnecting instead of stopping after bounded retriestrue, false

bmux new-session

Create a new session
Usage: bmux new-session [NAME]
Arguments:
NameDescriptionRequired
nameOptional session nameno

bmux list-sessions

List active sessions
Usage: bmux list-sessions [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint sessions as JSONtrue, false

bmux list-clients

List connected clients
Usage: bmux list-clients [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint clients as JSONtrue, false

bmux kill-session

Kill a session by name or UUID
Usage: bmux kill-session <TARGET> [OPTIONS]
Arguments:
NameDescriptionRequired
targetSession name or UUIDyes
Options:
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationstrue, false

bmux kill-all-sessions

Kill all sessions
Usage: bmux kill-all-sessions [OPTIONS]
Options:
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationstrue, false

bmux attach

Attach to a session by name or UUID
Usage: bmux attach [TARGET] [OPTIONS]
Arguments:
NameDescriptionRequired
targetSession name or UUIDno
Options:
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected session
--globalKeep following across target session switches (requires –follow)true, false

bmux detach

Detach from the current session

bmux follow

Follow another client’s active target
Usage: bmux follow <TARGET_CLIENT_ID> [OPTIONS]
Arguments:
NameDescriptionRequired
target_client_idTarget client UUID to followyes
Options:
FlagDescriptionValuesDefault
--globalKeep following across target session switchestrue, false

bmux unfollow

Stop following a client

bmux session

Session management commands
Subcommands:
  • new — Create a new session
  • list — List active sessions
  • clients — List connected clients
  • kill — Kill a session by name or UUID
  • kill-all — Kill all sessions
  • attach — Attach to a session by name or UUID
  • detach — Detach from the current session
  • follow — Follow another client’s active target
  • unfollow — Stop following a client

bmux session new

Create a new session
Usage: bmux session new [NAME]
Arguments:
NameDescriptionRequired
nameOptional session nameno

bmux session list

List active sessions
Usage: bmux session list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint sessions as JSONtrue, false

bmux session clients

List connected clients
Usage: bmux session clients [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint clients as JSONtrue, false

bmux session kill

Kill a session by name or UUID
Usage: bmux session kill <TARGET> [OPTIONS]
Arguments:
NameDescriptionRequired
targetSession name or UUIDyes
Options:
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationstrue, false

bmux session kill-all

Kill all sessions
Usage: bmux session kill-all [OPTIONS]
Options:
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationstrue, false

bmux session attach

Attach to a session by name or UUID
Usage: bmux session attach [TARGET] [OPTIONS]
Arguments:
NameDescriptionRequired
targetSession name or UUIDno
Options:
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected session
--globalKeep following across target session switches (requires –follow)true, false

bmux session detach

Detach from the current session

bmux session follow

Follow another client’s active target
Usage: bmux session follow <TARGET_CLIENT_ID> [OPTIONS]
Arguments:
NameDescriptionRequired
target_client_idTarget client UUID to followyes
Options:
FlagDescriptionValuesDefault
--globalKeep following across target session switchestrue, false

bmux session unfollow

Stop following a client

bmux remote

Remote target utilities
Subcommands:
  • list — List configured connection targets
  • test — Verify connectivity to a configured target
  • doctor — Diagnose remote connectivity and runtime readiness
  • init — Create and validate a named remote target profile
  • install-server — Ensure remote bmux runtime is installed and reachable
  • upgrade — Upgrade remote bmux runtime for one or all targets
  • trust — Manage TLS gateway trust pins
  • complete — Shell completion helpers for targets/sessions

bmux remote list

List configured connection targets
Usage: bmux remote list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux remote test

Verify connectivity to a configured target
Usage: bmux remote test <TARGET>
Arguments:
NameDescriptionRequired
targetTarget name or ssh destinationyes

bmux remote doctor

Diagnose remote connectivity and runtime readiness
Usage: bmux remote doctor <TARGET> [OPTIONS]
Arguments:
NameDescriptionRequired
targetTarget name or ssh destinationyes
Options:
FlagDescriptionValuesDefault
--fixApply safe automatic fixes when possibletrue, false

bmux remote init

Create and validate a named remote target profile
Usage: bmux remote init <NAME> [OPTIONS]
Arguments:
NameDescriptionRequired
nameName for the target profileyes
Options:
FlagDescriptionValuesDefault
--sshConfigure as an SSH target (user@host[:port] or host)
--tlsConfigure as a TLS target (host[:port])
--irohConfigure as an iroh target (endpoint_id[?relay=https://…][&auth=ssh])
--userSSH username override
--portSSH/TLS port override
--set-defaultMark as default targettrue, false

bmux remote install-server

Ensure remote bmux runtime is installed and reachable
Usage: bmux remote install-server <TARGET>
Arguments:
NameDescriptionRequired
targetTarget nameyes

bmux remote upgrade

Upgrade remote bmux runtime for one or all targets
Usage: bmux remote upgrade [TARGET]
Arguments:
NameDescriptionRequired
targetTarget name (omit to upgrade all configured targets)no

bmux remote trust

Manage TLS gateway trust pins

bmux remote trust list

List effective TLS gateway trust pins

bmux remote trust add

Probe and trust a TLS gateway
Usage: bmux remote trust add <TARGET> [OPTIONS]
Arguments:
NameDescriptionRequired
targetTLS target URL or host[:port]yes
Options:
FlagDescriptionValuesDefault
--yesTrust without an interactive confirmation prompttrue, false

bmux remote trust remove

Remove a local TLS gateway trust pin
Usage: bmux remote trust remove <ENDPOINT>
Arguments:
NameDescriptionRequired
endpointEndpoint key (host:port)yes

bmux remote complete

Shell completion helpers for targets/sessions

bmux remote complete targets

Print target names for completion

bmux remote complete sessions

Print session names for a target
Usage: bmux remote complete sessions <TARGET>
Arguments:
NameDescriptionRequired
targetTarget nameyes

bmux server

Server lifecycle and status tools
Subcommands:
  • start — Start local bmux server
  • status — Check server status
  • whoami-principal — Show caller and server control principal identities
  • save — Trigger immediate server snapshot save
  • restore — Validate persisted snapshot without applying restore
  • stop — Request graceful server shutdown
  • gateway — Run a TLS gateway that exposes bmux over TCP/TLS

bmux server start

Start local bmux server
Usage: bmux server start [OPTIONS]
Options:
FlagDescriptionValuesDefault
--daemonRun server in background daemon modetrue, false
--pane-shell-integrationForce-enable pane shell integration hooks for this server starttrue, false
--no-pane-shell-integrationDisable pane shell integration hooks for this server starttrue, false
--rolling-recordingEnable hidden rolling recording on server boot for this runtrue, false
--no-rolling-recordingDisable hidden rolling recording on server boot for this runtrue, false
--rolling-window-secsOverride rolling recording window in seconds for this run
--rolling-event-kind-allEnable all supported rolling event kindstrue, false
--rolling-event-kindExplicit rolling event kind allowlist (repeatable)pane-input-raw, pane-output-raw, protocol-reply-raw, pane-image, server-event, request-start, request-done, request-error, custom, repeatable
--rolling-capture-inputOverride rolling capture of pane input bytes for this runtrue, false
--no-rolling-capture-inputDisable rolling capture of pane input bytes for this runtrue, false
--rolling-capture-outputOverride rolling capture of pane output bytes for this runtrue, false
--no-rolling-capture-outputDisable rolling capture of pane output bytes for this runtrue, false
--rolling-capture-eventsOverride rolling capture of lifecycle/request/custom events for this runtrue, false
--no-rolling-capture-eventsDisable rolling capture of lifecycle/request/custom events for this runtrue, false
--rolling-capture-protocol-repliesOverride rolling capture of protocol reply bytes for this runtrue, false
--no-rolling-capture-protocol-repliesDisable rolling capture of protocol reply bytes for this runtrue, false
--rolling-capture-imagesOverride rolling capture of extracted pane images for this runtrue, false
--no-rolling-capture-imagesDisable rolling capture of extracted pane images for this runtrue, false

bmux server status

Check server status
Usage: bmux server status [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint server status as JSONtrue, false

bmux server whoami-principal

Show caller and server control principal identities
Usage: bmux server whoami-principal [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint principal identity as JSONtrue, false

bmux server save

Trigger immediate server snapshot save

bmux server restore

Validate persisted snapshot without applying restore
Usage: bmux server restore [OPTIONS]
Options:
FlagDescriptionValuesDefault
--dry-runOnly validate snapshot readability and schematrue, false
--yesConfirm replace-restore of current in-memory server statetrue, false

bmux server stop

Request graceful server shutdown

bmux server gateway

Run a TLS gateway that exposes bmux over TCP/TLS
Usage: bmux server gateway [OPTIONS]
Options:
FlagDescriptionValuesDefault
--listenListen address (host:port)
--hostExpose gateway publicly via reverse SSH tunnel helpertrue, false
--host-modeHosting mode used by –host (iroh is default)iroh, sshiroh
--host-relayReverse SSH relay destination (user@host)nokey@localhost.run
--quickGenerate and use self-signed cert/key in runtime dir for quick setuptrue, false
--cert-filePEM encoded certificate chain path
--key-filePEM encoded private key path (PKCS8)

bmux logs

Logging diagnostics and utilities
Subcommands:
  • path — Print effective log file path
  • level — Print effective runtime log level
  • tail — Print recent log lines and optionally follow updates
  • watch — Interactive live log viewer with dynamic filters
  • profiles — Manage saved log watch profiles

bmux logs path

Print effective log file path
Usage: bmux logs path [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux logs level

Print effective runtime log level
Usage: bmux logs level [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux logs tail

Print recent log lines and optionally follow updates
Usage: bmux logs tail [OPTIONS]
Options:
FlagDescriptionValuesDefault
--linesNumber of recent lines to show before follow50
--sinceShow entries newer than a relative duration (e.g. 30s, 10m, 2h, 1d)
--no-followPrint recent lines only (disable follow)true, false

bmux logs watch

Interactive live log viewer with dynamic filters
Usage: bmux logs watch [OPTIONS]
Options:
FlagDescriptionValuesDefault
--linesNumber of recent lines to preload (defaults to saved profile value or 200)
--sinceShow entries newer than a relative duration (e.g. 30s, 10m, 2h, 1d)
--profileState profile for saved watch filters (default: global default)
--includeInclude regex filter (case-sensitive, repeatable)repeatable
--include-iInclude regex filter (case-insensitive, repeatable)repeatable
--excludeExclude regex filter (case-sensitive, repeatable)repeatable
--exclude-iExclude regex filter (case-insensitive, repeatable)repeatable

bmux logs profiles

Manage saved log watch profiles

bmux logs profiles list

List saved watch profiles
Usage: bmux logs profiles list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux logs profiles show

Show details for one profile
Usage: bmux logs profiles show [PROFILE] [OPTIONS]
Arguments:
NameDescriptionRequired
profileProfile name (default: global profile default)no
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux logs profiles delete

Delete a saved profile
Usage: bmux logs profiles delete <PROFILE>
Arguments:
NameDescriptionRequired
profileProfile name to deleteyes

bmux logs profiles rename

Rename a saved profile
Usage: bmux logs profiles rename <FROM> <TO>
Arguments:
NameDescriptionRequired
fromExisting profile nameyes
toNew profile nameyes

bmux diagnostics

Structured diagnostics event viewer
Subcommands:
  • watch — Interactive structured diagnostics event viewer with dynamic filters
  • view — Alias for watch

bmux diagnostics watch

Interactive structured diagnostics event viewer with dynamic filters
Usage: bmux diagnostics watch [OPTIONS]
Options:
FlagDescriptionValuesDefault
--linesNumber of recent events to preload (defaults to saved profile value or 200)
--sinceShow entries newer than a relative duration (e.g. 30s, 10m, 2h, 1d)
--profileState profile for saved watch filters (default: global default)
--includeInclude regex filter (case-sensitive, repeatable)repeatable
--include-iInclude regex filter (case-insensitive, repeatable)repeatable
--excludeExclude regex filter (case-sensitive, repeatable)repeatable
--exclude-iExclude regex filter (case-insensitive, repeatable)repeatable

bmux diagnostics view

Alias for watch
Usage: bmux diagnostics view [OPTIONS]
Options:
FlagDescriptionValuesDefault
--linesNumber of recent events to preload (defaults to saved profile value or 200)
--sinceShow entries newer than a relative duration (e.g. 30s, 10m, 2h, 1d)
--profileState profile for saved watch filters (default: global default)
--includeInclude regex filter (case-sensitive, repeatable)repeatable
--include-iInclude regex filter (case-insensitive, repeatable)repeatable
--excludeExclude regex filter (case-sensitive, repeatable)repeatable
--exclude-iExclude regex filter (case-insensitive, repeatable)repeatable

bmux config

Configuration management and inspection
Subcommands:
  • path — Print the config file path
  • show — Print the effective configuration
  • get — Get a configuration value by dotted key path
  • set — Set a configuration value in the config file
  • profiles — Manage composition profiles
  • scope — Inspect scoped configuration resolution

bmux config path

Print the config file path
Usage: bmux config path [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config show

Print the effective configuration
Usage: bmux config show [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSON instead of TOMLtrue, false

bmux config get

Get a configuration value by dotted key path
Usage: bmux config get <KEY> [OPTIONS]
Arguments:
NameDescriptionRequired
keyDotted key path (e.g. status_bar.max_tabs, behavior.mouse.enabled)yes
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config set

Set a configuration value in the config file
Usage: bmux config set <KEY> <VALUE>
Arguments:
NameDescriptionRequired
keyDotted key path (e.g. status_bar.max_tabs, behavior.mouse.enabled)yes
valueValue to set (booleans, integers, and strings are auto-detected)yes

bmux config profiles

Manage composition profiles

bmux config profiles list

List known profile ids
Usage: bmux config profiles list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles show

Show one profile patch and inheritance metadata
Usage: bmux config profiles show <PROFILE> [OPTIONS]
Arguments:
NameDescriptionRequired
profileProfile idyes
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles resolve

Show resolved active profile and effective layers
Usage: bmux config profiles resolve [PROFILE] [OPTIONS]
Arguments:
NameDescriptionRequired
profileOptional forced profile idno
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles explain

Explain layer-by-layer composition changes
Usage: bmux config profiles explain [PROFILE] [OPTIONS]
Arguments:
NameDescriptionRequired
profileOptional forced profile idno
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles switch

Set active profile in config file
Usage: bmux config profiles switch <PROFILE> [OPTIONS]
Arguments:
NameDescriptionRequired
profileProfile id to activateyes
Options:
FlagDescriptionValuesDefault
--dry-runPreview changes without writing configtrue, false
--jsonPrint output as JSONtrue, false

bmux config profiles diff

Diff two resolved profile configurations
Usage: bmux config profiles diff <FROM> <TO> [OPTIONS]
Arguments:
NameDescriptionRequired
fromFrom profile idyes
toTo profile idyes
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles lint

Validate profile graph and layer rules
Usage: bmux config profiles lint [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config profiles evaluate

Evaluate auto-select rules in current environment
Usage: bmux config profiles evaluate [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux config scope

Inspect scoped configuration resolution

bmux config scope explain

Explain scoped source discovery and effective config
Usage: bmux config scope explain [OPTIONS]
Options:
FlagDescriptionValuesDefault
--scopeScope name to resolve, e.g. pane, new-pane, or globalpane
--cwdCwd used for discovering local bmux.toml overlays
--jsonPrint output as JSONtrue, false

bmux perf

Runtime performance telemetry controls
Subcommands:
  • status — Show current runtime performance telemetry settings
  • on — Enable runtime performance telemetry
  • off — Disable runtime performance telemetry

bmux perf status

Show current runtime performance telemetry settings
Usage: bmux perf status [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux perf on

Enable runtime performance telemetry
Usage: bmux perf on [OPTIONS]
Options:
FlagDescriptionValuesDefault
--profileCapture profile levelbasic, detailed, tracedetailed
--jsonPrint output as JSONtrue, false

bmux perf off

Disable runtime performance telemetry
Usage: bmux perf off [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false

bmux doctor

Run system-wide health checks
Usage: bmux doctor [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint output as JSONtrue, false
--hostedRun hosted-mode focused checkstrue, false

bmux keymap

Keymap tools and diagnostics
Subcommands:
  • doctor — Print compiled keymap and overlap diagnostics
  • explain — Explain effective action for a key chord

bmux keymap doctor

Print compiled keymap and overlap diagnostics
Usage: bmux keymap doctor [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint diagnostics as JSONtrue, false

bmux keymap explain

Explain effective action for a key chord
Usage: bmux keymap explain <KEY> [OPTIONS]
Arguments:
NameDescriptionRequired
keyKey chord to resolve (e.g. “ctrl+b n”, “alt+h”, “escape”)yes
Options:
FlagDescriptionValuesDefault
--modeResolve inside a specific modal mode id
--jsonPrint output as JSONtrue, false

bmux terminal

Terminal capability tools and diagnostics
Subcommands:
  • doctor — Show terminal capability profile used for panes
  • install-terminfo — Install bmux-256color terminfo entry

bmux terminal doctor

Show terminal capability profile used for panes
Usage: bmux terminal doctor [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonPrint diagnostics as JSONtrue, false
--traceInclude recent protocol trace eventstrue, false
--trace-limitLimit number of trace events shown50
--trace-familyFilter trace events by protocol familycsi, osc, dcs
--trace-paneFilter trace events by pane id

bmux terminal install-terminfo

Install bmux-256color terminfo entry
Usage: bmux terminal install-terminfo [OPTIONS]
Options:
FlagDescriptionValuesDefault
--yesProceed without interactive confirmationtrue, false
--checkCheck installability/status without installingtrue, false

bmux playbook

Headless playbook execution and testing
Subcommands:
  • run — Run a playbook from a file or stdin
  • validate — Validate a playbook without executing it
  • interactive — Start an interactive playbook session with a socket for agent control
  • dry-run — Dry-run: parse, validate, and print the execution plan without running
  • diff — Compare results from two playbook runs
  • cleanup — Clean up sandbox temp directories from previous playbook runs

bmux playbook run

Run a playbook from a file or stdin
Usage: bmux playbook run <SOURCE> [OPTIONS]
Arguments:
NameDescriptionRequired
sourcePath to playbook file, or - for stdinyes
Options:
FlagDescriptionValuesDefault
--jsonOutput results as JSONtrue, false
--interactiveRun visual interactive live tour (TTY; non-TTY falls back to prompt controls)true, false
--target-serverRun against the live server instead of an ephemeral sandboxtrue, false
--recordRecord the playbook execution (overrides playbook config)true, false
--export-gifExport the recording as a GIF to the given path (implies –record)
--viewportOverride viewport dimensions as COLSxROWS (e.g. 120x40)
--timeoutOverride max playbook timeout in seconds
--shellOverride shell
--varDefine a variable (repeatable). Format: KEY=VALUErepeatable
-v, --verbosePrint step-by-step progress to stderrtrue, false

bmux playbook validate

Validate a playbook without executing it
Usage: bmux playbook validate <SOURCE> [OPTIONS]
Arguments:
NameDescriptionRequired
sourcePath to playbook file, or - for stdinyes
Options:
FlagDescriptionValuesDefault
--jsonOutput results as JSONtrue, false

bmux playbook interactive

Start an interactive playbook session with a socket for agent control
Usage: bmux playbook interactive [OPTIONS]
Options:
FlagDescriptionValuesDefault
--socketSocket path override (default: auto-generated in sandbox temp dir)
--recordRecord the sessiontrue, false
--viewportViewport dimensions as COLSxROWS (default: 80x24)80x24
--shellShell override
--timeoutMax session lifetime in seconds (default: no limit)

bmux playbook dry-run

Dry-run: parse, validate, and print the execution plan without running
Usage: bmux playbook dry-run <SOURCE> [OPTIONS]
Arguments:
NameDescriptionRequired
sourcePath to playbook file, or - for stdinyes
Options:
FlagDescriptionValuesDefault
--jsonOutput as JSONtrue, false

bmux playbook diff

Compare results from two playbook runs
Usage: bmux playbook diff <LEFT> <RIGHT> [OPTIONS]
Arguments:
NameDescriptionRequired
leftPath to first (baseline/left) playbook result JSONyes
rightPath to second (new/right) playbook result JSONyes
Options:
FlagDescriptionValuesDefault
--jsonOutput diff as JSONtrue, false
--timing-thresholdTiming regression threshold in percent (default: 50)50

bmux playbook cleanup

Clean up sandbox temp directories from previous playbook runs
Usage: bmux playbook cleanup [OPTIONS]
Options:
FlagDescriptionValuesDefault
--dry-runOnly list orphaned dirs without deletingtrue, false
--jsonOutput as JSONtrue, false

bmux sandbox

Run bmux in an isolated ephemeral sandbox environment
Subcommands:
  • dev — Run bmux in a dev-friendly isolated sandbox (prefers local debug build)
  • run — Run bmux in an isolated ephemeral environment
  • list — List known sandbox directories and runtime status
  • status — Show a summary of sandbox runtime and index health
  • inspect — Inspect a sandbox by id or absolute path
  • tail — Print sandbox log tail without full manifest output
  • open — Open sandbox paths and repro context quickly
  • rerun — Rerun command from an existing sandbox manifest
  • triage — One-shot sandbox failure triage summary
  • doctor — Diagnose sandbox readiness and health checks
  • bundle — Bundle sandbox diagnostics and logs into a single directory
  • verify-bundle — Verify a sandbox bundle against its recorded metadata
  • cleanup — Clean up sandbox temp directories from sandbox runs
  • clean — Opinionated cleanup defaults for day-to-day sandbox hygiene
  • rebuild-index — Rebuild sandbox index from discovered sandbox manifests

bmux sandbox dev

Run bmux in a dev-friendly isolated sandbox (prefers local debug build)
Usage: bmux sandbox dev <COMMAND> [OPTIONS]
Arguments:
NameDescriptionRequired
commandbmux arguments to execute inside sandbox (pass after –)yes
Options:
FlagDescriptionValuesDefault
--bmux-binPath to bmux binary to execute (default: ./target/debug/bmux if present)
--env-modeSandbox environment modeclean, inherit, hermeticclean
--jsonOutput sandbox metadata as JSONtrue, false
--print-envPrint fully resolved environment map before executing commandtrue, false
--timeoutKill sandbox command if it exceeds this timeout in seconds
--nameOptional human-friendly sandbox label

bmux sandbox run

Run bmux in an isolated ephemeral environment
Usage: bmux sandbox run <COMMAND> [OPTIONS]
Arguments:
NameDescriptionRequired
commandbmux arguments to execute inside sandbox (pass after –)yes
Options:
FlagDescriptionValuesDefault
--bmux-binPath to bmux binary to execute (default: current executable)
--env-modeSandbox environment modeclean, inherit, hermeticclean
--keepKeep sandbox directory after command exitstrue, false
--jsonOutput sandbox metadata as JSONtrue, false
--print-envPrint fully resolved environment map before executing commandtrue, false
--timeoutKill sandbox command if it exceeds this timeout in seconds
--nameOptional human-friendly sandbox label

bmux sandbox list

List known sandbox directories and runtime status
Usage: bmux sandbox list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--statusFilter to matching status onlyrunning, stopped, failed, allall
--sourceFilter to a sandbox sourcesandbox-cli, playbook, recording-verify, allall
--limitMaximum entries to show20
--jsonOutput as JSONtrue, false

bmux sandbox status

Show a summary of sandbox runtime and index health
Usage: bmux sandbox status [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonOutput as JSONtrue, false

bmux sandbox inspect

Inspect a sandbox by id or absolute path
Usage: bmux sandbox inspect [SANDBOX] [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathno
Options:
FlagDescriptionValuesDefault
--latestInspect the most recent sandboxtrue, false
--latest-failedInspect the most recent failed sandboxtrue, false
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logs80
--jsonOutput as JSONtrue, false

bmux sandbox tail

Print sandbox log tail without full manifest output
Usage: bmux sandbox tail [SANDBOX] [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathno
Options:
FlagDescriptionValuesDefault
--latestTail the most recent sandboxtrue, false
--latest-failedTail the most recent failed sandboxtrue, false
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logs80
--jsonOutput as JSONtrue, false

bmux sandbox open

Open sandbox paths and repro context quickly
Usage: bmux sandbox open [SANDBOX] [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathno
Options:
FlagDescriptionValuesDefault
--latestOpen the most recent sandboxtrue, false
--latest-failedOpen the most recent failed sandboxtrue, false
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--jsonOutput as JSONtrue, false

bmux sandbox rerun

Rerun command from an existing sandbox manifest
Usage: bmux sandbox rerun [SANDBOX] [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathno
Options:
FlagDescriptionValuesDefault
--latestRerun the most recent sandboxtrue, false
--latest-failedRerun the most recent failed sandboxtrue, false
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--bmux-binOverride bmux binary path from manifest
--env-modeOverride sandbox environment mode from manifestclean, inherit, hermetic
--keepKeep rerun sandbox directory after command exitstrue, false
--jsonOutput sandbox metadata as JSONtrue, false
--print-envPrint fully resolved environment map before executing commandtrue, false
--timeoutKill rerun command if it exceeds this timeout in seconds
--nameOptional human-friendly sandbox label

bmux sandbox triage

One-shot sandbox failure triage summary
Usage: bmux sandbox triage [SANDBOX] [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathno
Options:
FlagDescriptionValuesDefault
--latestTriage the most recent sandboxtrue, false
--latest-failedTriage the most recent failed sandboxtrue, false
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logs80
--rerunRerun command from selected sandbox manifesttrue, false
--bmux-binOverride bmux binary path from manifest for rerun
--env-modeOverride sandbox environment mode from manifest for rerunclean, inherit, hermetic
--keepKeep rerun sandbox directory after command exitstrue, false
--print-envPrint fully resolved environment map before rerun commandtrue, false
--timeoutKill rerun command if it exceeds this timeout in seconds
--nameOptional human-friendly sandbox label for rerun
--bundleBundle selected sandbox diagnostics after triagetrue, false
--bundle-outputOptional output directory for triage bundle (default: ./sandbox-bundles)
--bundle-strict-verifyFail triage when bundle verification reports unexpected extra artifactstrue, false
--jsonOutput as JSONtrue, false

bmux sandbox doctor

Diagnose sandbox readiness and health checks
Usage: bmux sandbox doctor [OPTIONS]
Options:
FlagDescriptionValuesDefault
--idOptional sandbox id/path for targeted checks
--fixApply automatic sandbox repair actionstrue, false
--dry-runPreview repair actions without mutating state (requires –fix)true, false
--jsonOutput as JSONtrue, false

bmux sandbox bundle

Bundle sandbox diagnostics and logs into a single directory
Usage: bmux sandbox bundle <SANDBOX> [OPTIONS]
Arguments:
NameDescriptionRequired
sandboxSandbox id (bmux-sbx-…) or full pathyes
Options:
FlagDescriptionValuesDefault
--outputOptional output directory path (default: ./sandbox-bundles)
--include-envInclude environment/context snapshot in bundletrue, false
--include-index-stateInclude current sandbox index state in bundletrue, false
--include-doctorInclude doctor checks snapshot in bundletrue, false
--verifyVerify generated bundle against recorded metadatatrue, false
--jsonOutput as JSONtrue, false

bmux sandbox verify-bundle

Verify a sandbox bundle against its recorded metadata
Usage: bmux sandbox verify-bundle <BUNDLE_DIR> [OPTIONS]
Arguments:
NameDescriptionRequired
bundle_dirBundle directory pathyes
Options:
FlagDescriptionValuesDefault
--strictFail when bundle contains unexpected extra artifactstrue, false
--jsonOutput as JSONtrue, false

bmux sandbox cleanup

Clean up sandbox temp directories from sandbox runs
Usage: bmux sandbox cleanup [OPTIONS]
Options:
FlagDescriptionValuesDefault
--dry-runOnly list orphaned dirs without deletingtrue, false
--failed-onlyRemove only failed/aborted sandboxestrue, false
--all-statusInclude both failed and non-failed sandboxestrue, false
--older-thanMinimum age in seconds before sandbox is eligible for cleanup
--sourceFilter to a sandbox sourcesandbox-cli, playbook, recording-verify, all
--jsonOutput as JSONtrue, false

bmux sandbox clean

Opinionated cleanup defaults for day-to-day sandbox hygiene
Usage: bmux sandbox clean [OPTIONS]
Options:
FlagDescriptionValuesDefault
--dry-runOnly list orphaned dirs without deletingtrue, false
--all-statusInclude both failed and non-failed sandboxestrue, false
--older-thanMinimum age in seconds before sandbox is eligible for cleanup
--sourceFilter to a sandbox sourcesandbox-cli, playbook, recording-verify, all
--jsonOutput as JSONtrue, false

bmux sandbox rebuild-index

Rebuild sandbox index from discovered sandbox manifests
Usage: bmux sandbox rebuild-index [OPTIONS]
Options:
FlagDescriptionValuesDefault
--jsonOutput as JSONtrue, false

bmux slot

Manage bmux slots (multi-version installs)
Subcommands:
  • list — List all declared slots and the presentational default
  • show — Show one slot’s full resolved detail
  • paths — Print this slot’s resolved paths (config/runtime/data/state/log)
  • doctor — Validate the slot manifest: names, duplicate runtime dirs, binaries, per-slot configs
  • install — Register a new slot
  • uninstall — Remove a slot from the manifest and delete its bmux-<name> binary
  • shell — Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
  • exec — Run a command with a slot’s env applied (re-execs via execvp)
  • print — Print the resolved env-var set as structured data

bmux slot list

List all declared slots and the presentational default
Usage: bmux slot list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux slot show

Show one slot’s full resolved detail
Usage: bmux slot show [NAME] [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot name. Defaults to the active slotno
Options:
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux slot paths

Print this slot’s resolved paths (config/runtime/data/state/log)
Usage: bmux slot paths [NAME]
Arguments:
NameDescriptionRequired
nameSlot name. Defaults to the active slotno

bmux slot doctor

Validate the slot manifest: names, duplicate runtime dirs, binaries, per-slot configs

bmux slot install

Register a new slot
Usage: bmux slot install <NAME> <BINARY> [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot name (validates as [A-Za-z0-9._-]+, not reserved)yes
binaryPath to the source bmux binaryyes
Options:
FlagDescriptionValuesDefault
--no-inherit-baseDisable base-config inheritance for this slottrue, false
--modeSymlink (default) or copy the binary into bin_dirsymlink, copysymlink
--bin-dirDestination bin dir for bmux-<name>. Defaults to ~/.local/bin (or $BMUX_SLOTS_BIN_DIR)
--formatOutput format for the printed blocktoml, json, nixtoml
--dry-runDo not modify disk; only print what would happentrue, false
--overwriteReplace an existing slot with the same name. Without this flag duplicates are refused (after an interactive prompt, if a TTY is attached)true, false
-y, --yesSkip interactive confirmation prompts. When replacing an existing slot, --overwrite is still requiredtrue, false

bmux slot uninstall

Remove a slot from the manifest and delete its bmux-<name> binary
Usage: bmux slot uninstall <NAME> [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot nameyes
Options:
FlagDescriptionValuesDefault
--purgeAlso remove the slot’s config/data/state/log dirstrue, false
--bin-dirDestination bin dir the slot binary lives in

bmux slot shell

Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
Usage: bmux slot shell [OPTIONS]
Options:
FlagDescriptionValuesDefault
--shellauto, bash, zsh, fish, nushell, powershell, posixauto

bmux slot exec

Run a command with a slot’s env applied (re-execs via execvp)
Usage: bmux slot exec <SLOT> <ARGV>
Arguments:
NameDescriptionRequired
slotSlot name to activateyes
argvCommand and argumentsyes

bmux slot print

Print the resolved env-var set as structured data
Usage: bmux slot print [OPTIONS]
Options:
FlagDescriptionValuesDefault
--formatshell, json, nix, fishshell

bmux env

Alias for bmux slot ... (same subcommand tree; useful alongside the standalone bmux-env binary for symmetry)
Subcommands:
  • list — List all declared slots and the presentational default
  • show — Show one slot’s full resolved detail
  • paths — Print this slot’s resolved paths (config/runtime/data/state/log)
  • doctor — Validate the slot manifest: names, duplicate runtime dirs, binaries, per-slot configs
  • install — Register a new slot
  • uninstall — Remove a slot from the manifest and delete its bmux-<name> binary
  • shell — Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
  • exec — Run a command with a slot’s env applied (re-execs via execvp)
  • print — Print the resolved env-var set as structured data

bmux env list

List all declared slots and the presentational default
Usage: bmux env list [OPTIONS]
Options:
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux env show

Show one slot’s full resolved detail
Usage: bmux env show [NAME] [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot name. Defaults to the active slotno
Options:
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux env paths

Print this slot’s resolved paths (config/runtime/data/state/log)
Usage: bmux env paths [NAME]
Arguments:
NameDescriptionRequired
nameSlot name. Defaults to the active slotno

bmux env doctor

Validate the slot manifest: names, duplicate runtime dirs, binaries, per-slot configs

bmux env install

Register a new slot
Usage: bmux env install <NAME> <BINARY> [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot name (validates as [A-Za-z0-9._-]+, not reserved)yes
binaryPath to the source bmux binaryyes
Options:
FlagDescriptionValuesDefault
--no-inherit-baseDisable base-config inheritance for this slottrue, false
--modeSymlink (default) or copy the binary into bin_dirsymlink, copysymlink
--bin-dirDestination bin dir for bmux-<name>. Defaults to ~/.local/bin (or $BMUX_SLOTS_BIN_DIR)
--formatOutput format for the printed blocktoml, json, nixtoml
--dry-runDo not modify disk; only print what would happentrue, false
--overwriteReplace an existing slot with the same name. Without this flag duplicates are refused (after an interactive prompt, if a TTY is attached)true, false
-y, --yesSkip interactive confirmation prompts. When replacing an existing slot, --overwrite is still requiredtrue, false

bmux env uninstall

Remove a slot from the manifest and delete its bmux-<name> binary
Usage: bmux env uninstall <NAME> [OPTIONS]
Arguments:
NameDescriptionRequired
nameSlot nameyes
Options:
FlagDescriptionValuesDefault
--purgeAlso remove the slot’s config/data/state/log dirstrue, false
--bin-dirDestination bin dir the slot binary lives in

bmux env shell

Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
Usage: bmux env shell [OPTIONS]
Options:
FlagDescriptionValuesDefault
--shellauto, bash, zsh, fish, nushell, powershell, posixauto

bmux env exec

Run a command with a slot’s env applied (re-execs via execvp)
Usage: bmux env exec <SLOT> <ARGV>
Arguments:
NameDescriptionRequired
slotSlot name to activateyes
argvCommand and argumentsyes

bmux env print

Print the resolved env-var set as structured data
Usage: bmux env print [OPTIONS]
Options:
FlagDescriptionValuesDefault
--formatshell, json, nix, fishshell

bmux device-seal-broker

Internal sshenv device-seal broker used by panes