CLI Reference

bmux

Server-backed terminal multiplexer CLI
Usage: bmux [OPTIONS]
FlagDescriptionValuesDefault
--configMerge an additional config file (highest precedence layer)path
--recordStart interactive bmux with full-session recordingbooleanfalse
--no-capture-inputDo not capture pane input bytes when using –recordbooleanfalse
--recording-id-fileWrite recording id to a file when using –recordpath
--record-profileRecording profile when using –recordfull, functional, visual
--record-nameRecording name when using –recordstring
--record-event-kindExplicit event kind allowlist when using –record (repeatable)pane-input-raw, pane-output-raw, protocol-reply-raw, pane-image, server-event, request-start, request-done, request-error, custom (repeatable)
--stop-server-on-exitStop the server when exiting a –record runbooleanfalse
--recordings-dirOverride recordings root directory for this invocationpath
--recording-auto-exportEnable automatic GIF export after user-initiated recording stop/cutbooleanfalse
--no-recording-auto-exportDisable automatic GIF export after user-initiated recording stop/cutbooleanfalse
--recording-auto-export-dirOverride directory for auto-exported recording GIFspath
--targetExecute command against a configured target (local or remote)string
--runtimeSelect named runtime instance (default: default)string
-v, --verboseEnable verbose loggingbooleanfalse
--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
  • 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
  • recording — Recording and replay controls
  • 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)

bmux setup

First-run setup wizard for hosted mode (p2p default)
Usage: bmux setup [OPTIONS]
FlagDescriptionValuesDefault
--checkCheck hosted readiness without starting or changing runtime statebooleanfalse
--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]
FlagDescriptionValuesDefault
--listenOptional listen address for local gateway bridgestring127.0.0.1:7443
--nameOptional friendly name hintstring
--copyCopy the resulting join link to clipboardbooleanfalse
--daemonRun host runtime in the backgroundbooleanfalse
--statusShow hosted-mode runtime statusbooleanfalse
--stopStop hosted-mode runtime if runningbooleanfalse
--restartRestart hosted-mode runtime in backgroundbooleanfalse
--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:
  • <LINK> — Link or target name (bmux://, iroh://, https://, or configured target)
  • <SESSION> — Session name or UUID

bmux hosts

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

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]
FlagDescriptionValuesDefault
--no-browserDo not try to open a browser automaticallybooleanfalse

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]
FlagDescriptionValuesDefault
--agentAdd all currently loaded SSH agent keysbooleanfalse
--key-fileAdd a public key from file (repeatable)path (repeatable)
--public-keyAdd a public key line directly (repeatable)string (repeatable)
--github-userImport public keys from a GitHub username (repeatable)string (repeatable)
--yesSkip interactive confirmation promptsbooleanfalse

bmux access add

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

bmux access list

List currently authorized SSH keys
Usage: bmux access list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux access remove

Remove an SSH key from the allowlist
Usage: bmux access remove <FINGERPRINT> [OPTIONS]
Arguments:
  • <FINGERPRINT> (required) — Key fingerprint to remove
FlagDescriptionValuesDefault
--yesSkip interactive confirmation promptsbooleanfalse

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]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux kiosk init

Initialize/update kiosk bootstrap files from config
Usage: bmux kiosk init [OPTIONS]
FlagDescriptionValuesDefault
--profileKiosk profile to reconcile (repeatable)path (repeatable)
--all-profilesReconcile all configured profilesbooleanfalse
--dry-runPreview actions without writing filesbooleanfalse
--yesSkip confirmation promptsbooleanfalse

bmux kiosk issue-token

Issue a kiosk token scoped to a profile
Usage: bmux kiosk issue-token <PROFILE> [OPTIONS]
Arguments:
  • <PROFILE> (required) — Kiosk profile name
FlagDescriptionValuesDefault
--sessionOptional session override stored in tokenstring
--ttl-secsOptional token TTL in seconds (defaults to profile/default TTL)string
--one-shotMark token as one-shot (defaults to profile/default one_shot)booleanfalse
--multi-useMark token as reusable until expirybooleanfalse

bmux kiosk revoke-token

Revoke one issued kiosk token by id
Usage: bmux kiosk revoke-token <TOKEN_ID>
Arguments:
  • <TOKEN_ID> (required) — Token id to revoke

bmux kiosk attach

Attach using a kiosk token (intended for forced SSH command)
Usage: bmux kiosk attach <PROFILE> [OPTIONS]
Arguments:
  • <PROFILE> (required) — Kiosk profile name
FlagDescriptionValuesDefault
--tokenRaw kiosk tokenstring

bmux kiosk ssh-print-config

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

bmux share

Share helpers for hosted links
Usage: bmux share [TARGET] [SECONDARY] [OPTIONS]
Arguments:
  • <TARGET> — Target/link to share
  • <SECONDARY> — Optional second positional argument (used by bmux share revoke <name>)
FlagDescriptionValuesDefault
--nameOptional stable share namestring
--roleOptional access role hintstringcontrol
--ttlOptional invite TTL (example: 24h, 30m)string
--one-timeMark the share as one-time usebooleanfalse
--copyCopy resulting share link to clipboardbooleanfalse
--qrRender a terminal QR code for the share linkbooleanfalse

bmux unshare

Remove a named shared link
Usage: bmux unshare <NAME>
Arguments:
  • <NAME> (required) — Share name/slug to remove

bmux connect

Connect to a target and attach to a session
Usage: bmux connect [TARGET] [SESSION] [OPTIONS]
Arguments:
  • <TARGET> — Target name or ssh destination (user@host[:port] or ssh://…)
  • <SESSION> — Session name or UUID; if omitted in TTY mode a picker is shown
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected sessionstring
--globalKeep following across target session switches (requires –follow)booleanfalse
--reconnect-foreverKeep reconnecting instead of stopping after bounded retriesbooleanfalse

bmux new-session

Create a new session
Usage: bmux new-session [NAME]
Arguments:
  • <NAME> — Optional session name

bmux list-sessions

List active sessions
Usage: bmux list-sessions [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint sessions as JSONbooleanfalse

bmux list-clients

List connected clients
Usage: bmux list-clients [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint clients as JSONbooleanfalse

bmux kill-session

Kill a session by name or UUID
Usage: bmux kill-session <TARGET> [OPTIONS]
Arguments:
  • <TARGET> (required) — Session name or UUID
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationsbooleanfalse

bmux kill-all-sessions

Kill all sessions
Usage: bmux kill-all-sessions [OPTIONS]
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationsbooleanfalse

bmux attach

Attach to a session by name or UUID
Usage: bmux attach [TARGET] [OPTIONS]
Arguments:
  • <TARGET> — Session name or UUID
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected sessionstring
--globalKeep following across target session switches (requires –follow)booleanfalse

bmux detach

Detach from the current session

bmux follow

Follow another client’s active target
Usage: bmux follow <TARGET_CLIENT_ID> [OPTIONS]
Arguments:
  • <TARGET_CLIENT_ID> (required) — Target client UUID to follow
FlagDescriptionValuesDefault
--globalKeep following across target session switchesbooleanfalse

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:
  • <NAME> — Optional session name

bmux session list

List active sessions
Usage: bmux session list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint sessions as JSONbooleanfalse

bmux session clients

List connected clients
Usage: bmux session clients [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint clients as JSONbooleanfalse

bmux session kill

Kill a session by name or UUID
Usage: bmux session kill <TARGET> [OPTIONS]
Arguments:
  • <TARGET> (required) — Session name or UUID
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationsbooleanfalse

bmux session kill-all

Kill all sessions
Usage: bmux session kill-all [OPTIONS]
FlagDescriptionValuesDefault
--force-localBypass policy checks for local kill operationsbooleanfalse

bmux session attach

Attach to a session by name or UUID
Usage: bmux session attach [TARGET] [OPTIONS]
Arguments:
  • <TARGET> — Session name or UUID
FlagDescriptionValuesDefault
--followFollow target client UUID and attach to its selected sessionstring
--globalKeep following across target session switches (requires –follow)booleanfalse

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:
  • <TARGET_CLIENT_ID> (required) — Target client UUID to follow
FlagDescriptionValuesDefault
--globalKeep following across target session switchesbooleanfalse

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
  • complete — Shell completion helpers for targets/sessions

bmux remote list

List configured connection targets
Usage: bmux remote list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux remote test

Verify connectivity to a configured target
Usage: bmux remote test <TARGET>
Arguments:
  • <TARGET> (required) — Target name or ssh destination

bmux remote doctor

Diagnose remote connectivity and runtime readiness
Usage: bmux remote doctor <TARGET> [OPTIONS]
Arguments:
  • <TARGET> (required) — Target name or ssh destination
FlagDescriptionValuesDefault
--fixApply safe automatic fixes when possiblebooleanfalse

bmux remote init

Create and validate a named remote target profile
Usage: bmux remote init <NAME> [OPTIONS]
Arguments:
  • <NAME> (required) — Name for the target profile
FlagDescriptionValuesDefault
--sshConfigure as an SSH target (user@host[:port] or host)string
--tlsConfigure as a TLS target (host[:port])string
--irohConfigure as an iroh target (endpoint_id[?relay=https://…][&auth=ssh])string
--userSSH username overridestring
--portSSH/TLS port overridestring
--set-defaultMark as default targetbooleanfalse

bmux remote install-server

Ensure remote bmux runtime is installed and reachable
Usage: bmux remote install-server <TARGET>
Arguments:
  • <TARGET> (required) — Target name

bmux remote upgrade

Upgrade remote bmux runtime for one or all targets
Usage: bmux remote upgrade [TARGET]
Arguments:
  • <TARGET> — Target name (omit to upgrade all configured targets)

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:
  • <TARGET> (required) — Target name

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
  • recording — Control hidden rolling recording on a running server
  • gateway — Run a TLS gateway that exposes bmux over TCP/TLS

bmux server start

Start local bmux server
Usage: bmux server start [OPTIONS]
FlagDescriptionValuesDefault
--daemonRun server in background daemon modebooleanfalse
--pane-shell-integrationForce-enable pane shell integration hooks for this server startbooleanfalse
--no-pane-shell-integrationDisable pane shell integration hooks for this server startbooleanfalse
--rolling-recordingEnable hidden rolling recording on server boot for this runbooleanfalse
--no-rolling-recordingDisable hidden rolling recording on server boot for this runbooleanfalse
--rolling-window-secsOverride rolling recording window in seconds for this runinteger
--rolling-event-kind-allEnable all supported rolling event kindsbooleanfalse
--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 runbooleanfalse
--no-rolling-capture-inputDisable rolling capture of pane input bytes for this runbooleanfalse
--rolling-capture-outputOverride rolling capture of pane output bytes for this runbooleanfalse
--no-rolling-capture-outputDisable rolling capture of pane output bytes for this runbooleanfalse
--rolling-capture-eventsOverride rolling capture of lifecycle/request/custom events for this runbooleanfalse
--no-rolling-capture-eventsDisable rolling capture of lifecycle/request/custom events for this runbooleanfalse
--rolling-capture-protocol-repliesOverride rolling capture of protocol reply bytes for this runbooleanfalse
--no-rolling-capture-protocol-repliesDisable rolling capture of protocol reply bytes for this runbooleanfalse
--rolling-capture-imagesOverride rolling capture of extracted pane images for this runbooleanfalse
--no-rolling-capture-imagesDisable rolling capture of extracted pane images for this runbooleanfalse

bmux server status

Check server status
Usage: bmux server status [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint server status as JSONbooleanfalse

bmux server whoami-principal

Show caller and server control principal identities
Usage: bmux server whoami-principal [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint principal identity as JSONbooleanfalse

bmux server save

Trigger immediate server snapshot save

bmux server restore

Validate persisted snapshot without applying restore
Usage: bmux server restore [OPTIONS]
FlagDescriptionValuesDefault
--dry-runOnly validate snapshot readability and schemabooleanfalse
--yesConfirm replace-restore of current in-memory server statebooleanfalse

bmux server stop

Request graceful server shutdown

bmux server recording

Control hidden rolling recording on a running server

bmux server recording start

Start hidden rolling recording
Usage: bmux server recording start [OPTIONS]
FlagDescriptionValuesDefault
--rolling-window-secsOverride rolling recording window in secondsinteger
--nameOptional human-readable recording namestring
--rolling-event-kind-allEnable all supported rolling event kindsbooleanfalse
--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 bytesbooleanfalse
--no-rolling-capture-inputDisable rolling capture of pane input bytesbooleanfalse
--rolling-capture-outputOverride rolling capture of pane output bytesbooleanfalse
--no-rolling-capture-outputDisable rolling capture of pane output bytesbooleanfalse
--rolling-capture-eventsOverride rolling capture of lifecycle/request/custom eventsbooleanfalse
--no-rolling-capture-eventsDisable rolling capture of lifecycle/request/custom eventsbooleanfalse
--rolling-capture-protocol-repliesOverride rolling capture of protocol reply bytesbooleanfalse
--no-rolling-capture-protocol-repliesDisable rolling capture of protocol reply bytesbooleanfalse
--rolling-capture-imagesOverride rolling capture of extracted pane imagesbooleanfalse
--no-rolling-capture-imagesDisable rolling capture of extracted pane imagesbooleanfalse

bmux server recording stop

Stop hidden rolling recording

bmux server recording status

Show hidden rolling recording status and disk usage
Usage: bmux server recording status [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux server recording path

Print hidden rolling recording storage path
Usage: bmux server recording path [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux server recording clear

Clear hidden rolling recording data
Usage: bmux server recording clear [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse
--no-restartDo not restart rolling recording when it was activebooleanfalse

bmux server gateway

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

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]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux logs level

Print effective runtime log level
Usage: bmux logs level [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux logs tail

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

bmux logs watch

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

bmux logs profiles

Manage saved log watch profiles

bmux logs profiles list

List saved watch profiles
Usage: bmux logs profiles list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux logs profiles show

Show details for one profile
Usage: bmux logs profiles show [PROFILE] [OPTIONS]
Arguments:
  • <PROFILE> — Profile name (default: global profile default)
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux logs profiles delete

Delete a saved profile
Usage: bmux logs profiles delete <PROFILE>
Arguments:
  • <PROFILE> (required) — Profile name to delete

bmux logs profiles rename

Rename a saved profile
Usage: bmux logs profiles rename <FROM> <TO>
Arguments:
  • <FROM> (required) — Existing profile name
  • <TO> (required) — New profile name

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

bmux config path

Print the config file path
Usage: bmux config path [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config show

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

bmux config get

Get a configuration value by dotted key path
Usage: bmux config get <KEY> [OPTIONS]
Arguments:
  • <KEY> (required) — Dotted key path (e.g. status_bar.max_tabs, behavior.mouse.enabled)
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config set

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

bmux config profiles

Manage composition profiles

bmux config profiles list

List known profile ids
Usage: bmux config profiles list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config profiles show

Show one profile patch and inheritance metadata
Usage: bmux config profiles show <PROFILE> [OPTIONS]
Arguments:
  • <PROFILE> (required) — Profile id
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config profiles resolve

Show resolved active profile and effective layers
Usage: bmux config profiles resolve [PROFILE] [OPTIONS]
Arguments:
  • <PROFILE> — Optional forced profile id
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config profiles explain

Explain layer-by-layer composition changes
Usage: bmux config profiles explain [PROFILE] [OPTIONS]
Arguments:
  • <PROFILE> — Optional forced profile id
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config profiles switch

Set active profile in config file
Usage: bmux config profiles switch <PROFILE> [OPTIONS]
Arguments:
  • <PROFILE> (required) — Profile id to activate
FlagDescriptionValuesDefault
--dry-runPreview changes without writing configbooleanfalse
--jsonPrint output as JSONbooleanfalse

bmux config profiles diff

Diff two resolved profile configurations
Usage: bmux config profiles diff <FROM> <TO> [OPTIONS]
Arguments:
  • <FROM> (required) — From profile id
  • <TO> (required) — To profile id
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux config profiles lint

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

bmux config profiles evaluate

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

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]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux perf on

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

bmux perf off

Disable runtime performance telemetry
Usage: bmux perf off [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux doctor

Run system-wide health checks
Usage: bmux doctor [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse
--hostedRun hosted-mode focused checksbooleanfalse

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]
FlagDescriptionValuesDefault
--jsonPrint diagnostics as JSONbooleanfalse

bmux keymap explain

Explain effective action for a key chord
Usage: bmux keymap explain <KEY> [OPTIONS]
Arguments:
  • <KEY> (required) — Key chord to resolve (e.g. “ctrl+b n”, “alt+h”, “escape”)
FlagDescriptionValuesDefault
--modeResolve inside a specific modal mode idstring
--jsonPrint output as JSONbooleanfalse

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]
FlagDescriptionValuesDefault
--jsonPrint diagnostics as JSONbooleanfalse
--traceInclude recent protocol trace eventsbooleanfalse
--trace-limitLimit number of trace events showninteger50
--trace-familyFilter trace events by protocol familycsi, osc, dcs
--trace-paneFilter trace events by pane idinteger

bmux terminal install-terminfo

Install bmux-256color terminfo entry
Usage: bmux terminal install-terminfo [OPTIONS]
FlagDescriptionValuesDefault
--yesProceed without interactive confirmationbooleanfalse
--checkCheck installability/status without installingbooleanfalse

bmux recording

Recording and replay controls
Subcommands:
  • start — Start explicit full-fidelity recording
  • stop — Stop active recording or one by id
  • status — Show recording status, config defaults, and storage usage
  • path — Print recordings storage root path
  • list — List available recordings
  • delete — Delete one recording by id or unique id prefix
  • delete-all — Delete all recordings
  • cut — Snapshot the active rolling recording without stopping it
  • inspect — Inspect recording timeline events
  • analyze — Analyze diagnostics and bottlenecks from a recording
  • replay — Replay a recording timeline
  • verify-smoke — Run machine-readable verify smoke report
  • export — Export a recording as media
  • prune — Delete completed recordings older than the retention period

bmux recording start

Start explicit full-fidelity recording
Usage: bmux recording start [OPTIONS]
FlagDescriptionValuesDefault
--session-idRestrict capture to one session idstring
--no-capture-inputDo not capture pane input bytesbooleanfalse
--nameOptional human-readable recording namestring
--profileRecording profile to usefull, functional, visual
--event-kindExplicit 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)

bmux recording stop

Stop active recording or one by id
Usage: bmux recording stop [RECORDING_ID]
Arguments:
  • <RECORDING_ID> — Recording id to stop (defaults to active)

bmux recording status

Show recording status, config defaults, and storage usage
Usage: bmux recording status [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux recording path

Print recordings storage root path
Usage: bmux recording path [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse

bmux recording list

List available recordings
Usage: bmux recording list [OPTIONS]
FlagDescriptionValuesDefault
--jsonPrint output as JSONbooleanfalse
--limitLimit number of rows (table default is 10; JSON default is all)integer
--allShow all rows (disables default table limit)booleanfalse
--sortSort fieldstarted, name, events, size
--orderSort orderasc, desc
--statusFilter by recording statusall, active, done
--matchMatch by ID prefix or case-insensitive name substringstring

bmux recording delete

Delete one recording by id or unique id prefix
Usage: bmux recording delete <RECORDING_ID>
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix

bmux recording delete-all

Delete all recordings
Usage: bmux recording delete-all [OPTIONS]
FlagDescriptionValuesDefault
--yesProceed without interactive confirmationbooleanfalse

bmux recording cut

Snapshot the active rolling recording without stopping it
Usage: bmux recording cut [OPTIONS]
FlagDescriptionValuesDefault
--last-secondsWindow to snapshot, in seconds (default: full rolling window)string
--export-fpsOverride GIF auto-export frames per second for this cutinteger
--nameOptional human-readable recording namestring

bmux recording inspect

Inspect recording timeline events
Usage: bmux recording inspect <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
--limitLimit number of eventsinteger200
--kindFilter events by kindstring
--jsonPrint output as JSONbooleanfalse

bmux recording analyze

Analyze diagnostics and bottlenecks from a recording
Usage: bmux recording analyze <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
--perfAnalyze performance telemetry (bmux.perf custom events)booleanfalse
--jsonPrint output as JSONbooleanfalse

bmux recording replay

Replay a recording timeline
Usage: bmux recording replay <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
--modeReplay modewatch, interactive, verifywatch
--speedPlayback speed multiplier in watch modenumber1
--target-bmuxOptional target bmux binary for verify modestring
--compare-recordingCompare with another recording id in verify modestring
--ignoreOptional comma-separated ignore rules in verify modestring
--strict-timingPreserve full recorded input timing in verify modebooleanfalse
--max-verify-durationMaximum verify runtime in seconds before abortinginteger
--verify-start-timeoutTimeout in seconds for target verify server readinessinteger

bmux recording verify-smoke

Run machine-readable verify smoke report
Usage: bmux recording verify-smoke <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
--target-bmuxOptional target bmux binary for verifystring
--compare-recordingCompare with another recording idstring
--ignoreOptional comma-separated ignore rulesstring
--strict-timingPreserve full recorded input timingbooleanfalse
--max-verify-durationMaximum verify runtime in seconds before abortinginteger
--verify-start-timeoutTimeout in seconds for target verify server readinessinteger

bmux recording export

Export a recording as media
Usage: bmux recording export <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
--formatExport formatgifgif
--outputOutput file pathpath
--view-clientOverride view client id for display track selectionstring
--speedPlayback speed multipliernumber1
--fpsTarget frames per second (defaults to recording.export.fps)integer
--max-durationMaximum export duration in secondsinteger
--max-framesMaximum exported framesinteger
--rendererRenderer mode for frame rasterizationfont, bitmapfont
--cell-sizeCell size in pixels as WIDTHxHEIGHT (e.g. 8x16)integer
--cell-widthOverride glyph cell width in pixelsstring
--cell-heightOverride glyph cell height in pixelsstring
--font-familyComma-separated preferred font family namesstring
--font-sizeFont size in pixels for font renderernumber
--line-heightLine-height multiplier for font renderernumber
--font-pathAdditional font file path (repeatable)path (repeatable)
--palette-sourcePalette source for indexed/default color resolutionauto, recording, terminal, xterm
--palette-foregroundForeground default override for palette resolution (auto or color)string
--palette-backgroundBackground default override for palette resolution (auto or color)string
--palette-colorIndexed color override INDEX=COLOR (repeatable)string (repeatable)
--cursorCursor rendering mode for exportauto, on, off
--cursor-shapeCursor shape override for exportauto, block, bar, underline
--cursor-blinkCursor blink mode for exportauto, on, off
--cursor-blink-period-msCursor blink period in millisecondsstring
--cursor-colorCursor color override for export (auto or #RRGGBB)string
--cursor-profileCursor behavior profile for export timingauto, ghostty, generic
--cursor-solid-after-activity-msKeep cursor solid after activity for this duration in msstring
--cursor-solid-after-input-msKeep cursor solid after input activity for this duration in msstring
--cursor-solid-after-output-msKeep cursor solid after output activity for this duration in msstring
--cursor-solid-after-cursor-msKeep cursor solid after cursor movement activity for this duration in msstring
--cursor-paint-modeCursor paint mode for block cursor renderingauto, invert, fill, outline
--cursor-text-modeCursor text mode for filled block cursor glyph readabilityauto, swap-fg-bg, force-contrast
--cursor-bar-width-pctCursor bar width as a percent of cell width (1-100)string
--cursor-underline-height-pctCursor underline height as a percent of cell height (1-100)string
--export-metadataWrite export metadata JSON to this pathstring
--no-progressDisable export progress outputbooleanfalse

bmux recording prune

Delete completed recordings older than the retention period
Usage: bmux recording prune [OPTIONS]
FlagDescriptionValuesDefault
--older-thanOverride retention period in days (default: use config value)integer
--jsonOutput as JSONbooleanfalse

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
  • from-recording — Generate a playbook stub from an existing recording
  • 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:
  • <SOURCE> (required) — Path to playbook file, or - for stdin
FlagDescriptionValuesDefault
--jsonOutput results as JSONbooleanfalse
--interactiveRun visual interactive live tour (TTY; non-TTY falls back to prompt controls)booleanfalse
--target-serverRun against the live server instead of an ephemeral sandboxbooleanfalse
--recordRecord the playbook execution (overrides playbook config)booleanfalse
--export-gifExport the recording as a GIF to the given path (implies –record)string
--viewportOverride viewport dimensions as COLSxROWS (e.g. 120x40)string
--timeoutOverride max playbook timeout in secondsinteger
--shellOverride shellstring
--varDefine a variable (repeatable). Format: KEY=VALUEstring (repeatable)
-v, --verbosePrint step-by-step progress to stderrbooleanfalse

bmux playbook validate

Validate a playbook without executing it
Usage: bmux playbook validate <SOURCE> [OPTIONS]
Arguments:
  • <SOURCE> (required) — Path to playbook file, or - for stdin
FlagDescriptionValuesDefault
--jsonOutput results as JSONbooleanfalse

bmux playbook interactive

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

bmux playbook from-recording

Generate a playbook stub from an existing recording
Usage: bmux playbook from-recording <RECORDING_ID> [OPTIONS]
Arguments:
  • <RECORDING_ID> (required) — Recording id/name or unique id/name prefix
FlagDescriptionValuesDefault
-o, --outputOutput file path (default: stdout)path

bmux playbook dry-run

Dry-run: parse, validate, and print the execution plan without running
Usage: bmux playbook dry-run <SOURCE> [OPTIONS]
Arguments:
  • <SOURCE> (required) — Path to playbook file, or - for stdin
FlagDescriptionValuesDefault
--jsonOutput as JSONbooleanfalse

bmux playbook diff

Compare results from two playbook runs
Usage: bmux playbook diff <LEFT> <RIGHT> [OPTIONS]
Arguments:
  • <LEFT> (required) — Path to first (baseline/left) playbook result JSON
  • <RIGHT> (required) — Path to second (new/right) playbook result JSON
FlagDescriptionValuesDefault
--jsonOutput diff as JSONbooleanfalse
--timing-thresholdTiming regression threshold in percent (default: 50)integer50

bmux playbook cleanup

Clean up sandbox temp directories from previous playbook runs
Usage: bmux playbook cleanup [OPTIONS]
FlagDescriptionValuesDefault
--dry-runOnly list orphaned dirs without deletingbooleanfalse
--jsonOutput as JSONbooleanfalse

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:
  • <COMMAND> (required) — bmux arguments to execute inside sandbox (pass after –)
FlagDescriptionValuesDefault
--bmux-binPath to bmux binary to execute (default: ./target/debug/bmux if present)string
--env-modeSandbox environment modeclean, inherit, hermeticclean
--jsonOutput sandbox metadata as JSONbooleanfalse
--print-envPrint fully resolved environment map before executing commandbooleanfalse
--timeoutKill sandbox command if it exceeds this timeout in secondsinteger
--nameOptional human-friendly sandbox labelstring

bmux sandbox run

Run bmux in an isolated ephemeral environment
Usage: bmux sandbox run <COMMAND> [OPTIONS]
Arguments:
  • <COMMAND> (required) — bmux arguments to execute inside sandbox (pass after –)
FlagDescriptionValuesDefault
--bmux-binPath to bmux binary to execute (default: current executable)string
--env-modeSandbox environment modeclean, inherit, hermeticclean
--keepKeep sandbox directory after command exitsbooleanfalse
--jsonOutput sandbox metadata as JSONbooleanfalse
--print-envPrint fully resolved environment map before executing commandbooleanfalse
--timeoutKill sandbox command if it exceeds this timeout in secondsinteger
--nameOptional human-friendly sandbox labelstring

bmux sandbox list

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

bmux sandbox status

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

bmux sandbox inspect

Inspect a sandbox by id or absolute path
Usage: bmux sandbox inspect [SANDBOX] [OPTIONS]
Arguments:
  • <SANDBOX> — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--latestInspect the most recent sandboxbooleanfalse
--latest-failedInspect the most recent failed sandboxbooleanfalse
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logsstring80
--jsonOutput as JSONbooleanfalse

bmux sandbox tail

Print sandbox log tail without full manifest output
Usage: bmux sandbox tail [SANDBOX] [OPTIONS]
Arguments:
  • <SANDBOX> — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--latestTail the most recent sandboxbooleanfalse
--latest-failedTail the most recent failed sandboxbooleanfalse
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logsstring80
--jsonOutput as JSONbooleanfalse

bmux sandbox open

Open sandbox paths and repro context quickly
Usage: bmux sandbox open [SANDBOX] [OPTIONS]
Arguments:
  • <SANDBOX> — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--latestOpen the most recent sandboxbooleanfalse
--latest-failedOpen the most recent failed sandboxbooleanfalse
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--jsonOutput as JSONbooleanfalse

bmux sandbox rerun

Rerun command from an existing sandbox manifest
Usage: bmux sandbox rerun [SANDBOX] [OPTIONS]
Arguments:
  • <SANDBOX> — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--latestRerun the most recent sandboxbooleanfalse
--latest-failedRerun the most recent failed sandboxbooleanfalse
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--bmux-binOverride bmux binary path from manifeststring
--env-modeOverride sandbox environment mode from manifestclean, inherit, hermetic
--keepKeep rerun sandbox directory after command exitsbooleanfalse
--jsonOutput sandbox metadata as JSONbooleanfalse
--print-envPrint fully resolved environment map before executing commandbooleanfalse
--timeoutKill rerun command if it exceeds this timeout in secondsinteger
--nameOptional human-friendly sandbox labelstring

bmux sandbox triage

One-shot sandbox failure triage summary
Usage: bmux sandbox triage [SANDBOX] [OPTIONS]
Arguments:
  • <SANDBOX> — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--latestTriage the most recent sandboxbooleanfalse
--latest-failedTriage the most recent failed sandboxbooleanfalse
--sourceFilter source when resolving –latest or –latest-failedsandbox-cli, playbook, recording-verify, allall
--tailNumber of log lines to tail from sandbox logsstring80
--rerunRerun command from selected sandbox manifestbooleanfalse
--bmux-binOverride bmux binary path from manifest for rerunstring
--env-modeOverride sandbox environment mode from manifest for rerunclean, inherit, hermetic
--keepKeep rerun sandbox directory after command exitsbooleanfalse
--print-envPrint fully resolved environment map before rerun commandbooleanfalse
--timeoutKill rerun command if it exceeds this timeout in secondsinteger
--nameOptional human-friendly sandbox label for rerunstring
--bundleBundle selected sandbox diagnostics after triagebooleanfalse
--bundle-outputOptional output directory for triage bundle (default: ./sandbox-bundles)string
--bundle-strict-verifyFail triage when bundle verification reports unexpected extra artifactsbooleanfalse
--jsonOutput as JSONbooleanfalse

bmux sandbox doctor

Diagnose sandbox readiness and health checks
Usage: bmux sandbox doctor [OPTIONS]
FlagDescriptionValuesDefault
--idOptional sandbox id/path for targeted checksstring
--fixApply automatic sandbox repair actionsbooleanfalse
--dry-runPreview repair actions without mutating state (requires –fix)booleanfalse
--jsonOutput as JSONbooleanfalse

bmux sandbox bundle

Bundle sandbox diagnostics and logs into a single directory
Usage: bmux sandbox bundle <SANDBOX> [OPTIONS]
Arguments:
  • <SANDBOX> (required) — Sandbox id (bmux-sbx-…) or full path
FlagDescriptionValuesDefault
--outputOptional output directory path (default: ./sandbox-bundles)path
--include-envInclude environment/context snapshot in bundlebooleanfalse
--include-index-stateInclude current sandbox index state in bundlebooleanfalse
--include-doctorInclude doctor checks snapshot in bundlebooleanfalse
--verifyVerify generated bundle against recorded metadatabooleanfalse
--jsonOutput as JSONbooleanfalse

bmux sandbox verify-bundle

Verify a sandbox bundle against its recorded metadata
Usage: bmux sandbox verify-bundle <BUNDLE_DIR> [OPTIONS]
Arguments:
  • <BUNDLE_DIR> (required) — Bundle directory path
FlagDescriptionValuesDefault
--strictFail when bundle contains unexpected extra artifactsbooleanfalse
--jsonOutput as JSONbooleanfalse

bmux sandbox cleanup

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

bmux sandbox clean

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

bmux sandbox rebuild-index

Rebuild sandbox index from discovered sandbox manifests
Usage: bmux sandbox rebuild-index [OPTIONS]
FlagDescriptionValuesDefault
--jsonOutput as JSONbooleanfalse

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]
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux slot show

Show one slot’s full resolved detail
Usage: bmux slot show [NAME] [OPTIONS]
Arguments:
  • <NAME> — Slot name. Defaults to the active slot
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:
  • <NAME> — Slot name. Defaults to the active slot

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:
  • <NAME> (required) — Slot name (validates as [A-Za-z0-9._-]+, not reserved)
  • <BINARY> (required) — Path to the source bmux binary
FlagDescriptionValuesDefault
--no-inherit-baseDisable base-config inheritance for this slotbooleanfalse
--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)path
--formatOutput format for the printed blocktoml, json, nixtoml
--dry-runDo not modify disk; only print what would happenbooleanfalse
--overwriteReplace an existing slot with the same name. Without this flag duplicates are refused (after an interactive prompt, if a TTY is attached)booleanfalse
-y, --yesSkip interactive confirmation prompts. When replacing an existing slot, --overwrite is still requiredbooleanfalse

bmux slot uninstall

Remove a slot from the manifest and delete its bmux-<name> binary
Usage: bmux slot uninstall <NAME> [OPTIONS]
Arguments:
  • <NAME> (required) — Slot name
FlagDescriptionValuesDefault
--purgeAlso remove the slot’s config/data/state/log dirsbooleanfalse
--bin-dirDestination bin dir the slot binary lives inpath

bmux slot shell

Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
Usage: bmux slot shell [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:
  • <SLOT> (required) — Slot name to activate
  • <ARGV> (required) — Command and arguments

bmux slot print

Print the resolved env-var set as structured data
Usage: bmux slot print [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]
FlagDescriptionValuesDefault
--formatOutput formattoml, json, nixtoml

bmux env show

Show one slot’s full resolved detail
Usage: bmux env show [NAME] [OPTIONS]
Arguments:
  • <NAME> — Slot name. Defaults to the active slot
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:
  • <NAME> — Slot name. Defaults to the active slot

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:
  • <NAME> (required) — Slot name (validates as [A-Za-z0-9._-]+, not reserved)
  • <BINARY> (required) — Path to the source bmux binary
FlagDescriptionValuesDefault
--no-inherit-baseDisable base-config inheritance for this slotbooleanfalse
--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)path
--formatOutput format for the printed blocktoml, json, nixtoml
--dry-runDo not modify disk; only print what would happenbooleanfalse
--overwriteReplace an existing slot with the same name. Without this flag duplicates are refused (after an interactive prompt, if a TTY is attached)booleanfalse
-y, --yesSkip interactive confirmation prompts. When replacing an existing slot, --overwrite is still requiredbooleanfalse

bmux env uninstall

Remove a slot from the manifest and delete its bmux-<name> binary
Usage: bmux env uninstall <NAME> [OPTIONS]
Arguments:
  • <NAME> (required) — Slot name
FlagDescriptionValuesDefault
--purgeAlso remove the slot’s config/data/state/log dirsbooleanfalse
--bin-dirDestination bin dir the slot binary lives inpath

bmux env shell

Print shell code that prepends $BMUX_SLOTS_BIN_DIR to PATH
Usage: bmux env shell [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:
  • <SLOT> (required) — Slot name to activate
  • <ARGV> (required) — Command and arguments

bmux env print

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