CLI Workflows

CLI workflows

For account-free remote terminal pairing without a client-side server, see Remote pairing and daemonless clients.
The current CLI is server-backed by default. Running bmux with no subcommand starts or reuses a server, creates a session when needed, and attaches.
bmux server stop waits for the selected local process to exit, timing out after 30 seconds without observable shutdown progress (not 30 seconds total). Completed cleanup milestones advance an instance-bound status counter; repeated status reads and waiting diagnostics do not extend the wait. The last known step is included on inactivity timeout. Older servers without progress retain a bounded wait. Graceful completion requires an instance-matching cleanup record; an older server without that record is reported as stopped with cleanup unverified. Cleanup errors are failures, not successful stops. An unavailable endpoint never authorizes killing a numeric PID: a timed-out stop leaves cleanup ownership intact and directs you to the selected runtime’s logs. Remote endpoint loss alone cannot prove cleanup; remote completion remains unconfirmed until a completion protocol is available.
# Start or inspect the server bmux server start bmux server status bmux server stop # Create and attach sessions bmux new-session dev bmux list-sessions bmux attach dev # Work with named workspaces and tabs bmux workspace new --name project bmux tab new --name editor bmux tab list bmux workspace switch project # Multi-client collaboration bmux list-clients bmux follow <client-uuid> bmux unfollow # Remote targets over SSH bmux connect prod app bmux connect prod # picker when multiple sessions bmux remote list bmux remote test prod bmux remote doctor prod --fix bmux remote init prod --ssh [email protected] --set-default bmux remote install-server prod bmux remote upgrade prod bmux --target prod list-sessions bmux connect prod --reconnect-forever bmux remote complete targets bmux remote complete sessions prod # Streamlined hosted workflow (p2p default, no bmux control-plane required) bmux setup bmux host # Optional runtime instance selection (for parallel local runtimes) bmux --runtime dev server start --daemon bmux --runtime dev host # Native per-user login autostart (launchd, systemd user service, or Task Scheduler) bmux server autostart install bmux server autostart status bmux server autostart print # side-effect-free declaration output bmux server autostart uninstall # Named runtimes receive isolated native service identities: bmux --runtime dev server autostart install # Test the invoked binary with normal settings but fresh writable BMUX state. # No arguments after -- are needed for interactive startup. bmux sandbox dev --inherit-config # Reconnect or explicitly stop the retained test server using its printed id/path: bmux sandbox attach <id-or-path> bmux sandbox stop <id-or-path> # Ephemeral sandbox run (fully isolated config/runtime/data/state/logs) bmux sandbox run -- server status bmux sandbox run --bmux-bin ./target/debug/bmux --env-mode inherit -- --version bmux sandbox dev -- server status bmux sandbox list --limit 10 bmux sandbox status --json bmux sandbox list --source playbook --limit 10 bmux sandbox inspect --latest bmux sandbox inspect --latest --source recording-verify bmux sandbox inspect --latest-failed --tail 120 bmux sandbox tail --latest-failed --tail 120 --json bmux sandbox open --latest-failed --json bmux sandbox rerun --latest-failed --bmux-bin ./target/debug/bmux --json bmux sandbox triage --json bmux sandbox triage --latest-failed --bundle --bundle-output ./sandbox-artifacts --json bmux sandbox triage --latest-failed --bundle --bundle-strict-verify --json bmux sandbox triage --latest-failed --rerun --bmux-bin ./target/debug/bmux bmux sandbox bundle bmux-sbx-123 --output ./sandbox-artifacts bmux sandbox bundle bmux-sbx-123 --include-env --verify --json bmux sandbox verify-bundle ./sandbox-artifacts/bmux-sbx-123-1700000000000 --json bmux sandbox verify-bundle ./sandbox-artifacts/bmux-sbx-123-1700000000000 --strict --json bmux sandbox doctor --json bmux sandbox doctor --fix --dry-run --json bmux sandbox cleanup --dry-run --json bmux sandbox clean --dry-run --json bmux sandbox cleanup --all-status --source playbook --older-than 0 bmux sandbox cleanup --source recording-verify --older-than 600 # Optional control-plane mode for account/share links bmux setup --mode control-plane bmux host --mode control-plane bmux share --name my-host bmux join bmux://my-host # Bash/Zsh/Fish completion can call: # bmux remote complete targets # bmux remote complete sessions <target> # Internet-accessible TLS gateway bmux server gateway --listen 0.0.0.0:7443 --quick bmux connect tls-prod app # Or start the TLS gateway automatically with the local server by adding: # [server.gateway] # enabled = true # listen = "0.0.0.0:7443" # quick = true # Restart the bmux server after changing gateway settings. # Reverse-SSH hosted helper (prints public URL in ssh output) bmux server gateway --listen 127.0.0.1:7443 --quick --host --host-mode ssh bmux connect https://your-public-url app # Iroh hosted mode (default for --host) bmux server gateway --listen 127.0.0.1:7443 --host # prints: iroh://<endpoint_id>?relay=<url> bmux connect iroh://<endpoint_id>?relay=<url> app # Logging bmux logs path bmux logs level bmux logs tail bmux logs path --json bmux logs level --json bmux logs tail --since 15m --lines 200 bmux logs watch --exclude "bmux server listening" bmux logs watch --profile incident-db bmux logs profiles list
A TLS gateway can also start automatically with the local server:
[server.gateway] enabled = true listen = "0.0.0.0:7443" quick = true
For a production certificate, disable quick mode by omitting quick and provide both PEM files:
[server.gateway] enabled = true listen = "0.0.0.0:7443" cert_file = "/etc/bmux/gateway-cert.pem" key_file = "/etc/bmux/gateway-key.pem"
Restart the bmux server after changing gateway settings. Listening on 0.0.0.0 exposes the gateway to reachable networks; apply appropriate firewall and access controls. Reverse-SSH and Iroh hosting remain explicit bmux server gateway --host ... command flows.
bmux logs watch uses a ratatui interface and supports Vim-style navigation (j/k, g/G, Ctrl-u/Ctrl-d).
Top-level and grouped command forms are supported in many areas of the CLI.
All list commands with --json output a bare JSON array.
Logging defaults:
  • file sink is enabled by default
  • default level is info
  • --verbose raises level to debug
  • --log-level supports error|warn|info|debug|trace
Environment overrides:
  • BMUX_LOG_LEVEL: effective runtime log level
A native autostart service runs foreground bmux server start so the operating system owns supervision; it does not use --daemon. Installation is explicit and starts immediately unless --no-start is passed. Existing [server.gateway] configuration is loaded normally, so an enabled gateway also starts at login.
Imperative installation refuses symlinked, read-only, conflicting, or externally managed declarations. Nix/Home Manager users should define ${pkgs.bmux}/bin/bmux server start through systemd.user.services or launchd.agents and let Nix own the declaration; bmux never mutates bmux.toml. Linux autostart begins at login and does not enable lingering automatically.
Runtime selection vs sandbox isolation:
  • Use --runtime <name> to run multiple local bmux runtime instances side-by-side while still using your normal config/data/state roots.
  • Use bmux sandbox dev --inherit-config for local build testing with a private snapshot of your normal settings and fresh BMUX config/runtime/data/state/log directories. It uses the invoked binary (or explicit --bmux-bin), disables gateway startup, and preserves your shell environment and working directory. Detaching retains the server; use the printed sandbox attach or sandbox stop command. A changed binary requires stopping the old sandbox before testing the rebuild. This is not an OS security sandbox: configured external paths, plugin artifacts, and external services remain shared. Do not use config snapshots as shareable diagnostics; they can contain secrets.
  • Use bmux sandbox ... when you want a throwaway isolated environment (config/runtime/data/state/logs/home/tmp) for safe local build testing and failure triage.
  • BMUX_LOG_DIR: explicit log directory
  • BMUX_STATE_DIR: explicit state directory
  • BMUX_TARGET: default command target (same behavior as --target)
Connection targets can be configured in bmux.toml:
[connections] hosted_mode = "p2p" # or "control_plane" (hard-fail on control-plane errors) default_target = "local" [connections.targets.prod] transport = "ssh" host = "prod.example.com" user = "bmux" port = 22 identity_file = "~/.ssh/id_ed25519" known_hosts_file = "~/.ssh/known_hosts" strict_host_key_checking = true jump = "[email protected]" remote_bmux_path = "bmux" connect_timeout_ms = 8000 default_session = "main" [connections.targets.tls-prod] transport = "tls" host = "gateway.example.com" port = 7443 server_name = "gateway.example.com" ca_file = "~/.config/bmux/gateway-ca.pem"
Example shell wiring for target/session completion:
# Bash helper functions _bmux_targets() { bmux remote complete targets 2>/dev/null } _bmux_sessions() { local target="$1" bmux remote complete sessions "$target" 2>/dev/null } # Usage examples: # _bmux_targets # _bmux_sessions prod
Plugin command ownership policy is optional and declarative:
[plugins.routing] conflict_mode = "fail_startup" [[plugins.routing.required_namespaces]] namespace = "plugin" [[plugins.routing.required_paths]] path = ["recording", "start"]
Role policy: owner controls session and window mutations plus role changes, writer can send attach input, and observer is read-only.
Window presentation settings and the tab-bar/sidebar enablement combinations are documented in Window presentation plugins.

Examples

  • Prompt showcase (isolated in-process sandbox + attach prompt API):
    cargo run -p bmux_prompt_showcase
  • Plugin-provided prompt showcase (reuses example.native prompt sequence):
    cargo run -p bmux_prompt_plugin_showcase
  • Native plugin example:
    cargo build -p bmux_example_native_plugin ./scripts/install-example-plugin.sh
  • Minimal hello plugin example:
    cargo build -p bmux_example_hello_plugin
See the root README for installation and TESTING.md for validation. Examples using remote hosts, gateways, service installation, or plugin installation change runtime state; review them before running.