Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command-Line Help for muster

This document contains the help content for the muster command-line program.

Command Overview:

muster

Terminal session group management built on tmux.

Muster organizes terminal sessions into named, color-coded groups with saved profiles, runtime theming, and push-based state synchronization via tmux control mode.

Usage: muster [OPTIONS] <COMMAND>

Subcommands:
  • list — List profiles and running sessions
  • up — Create or attach to a profile’s session
  • down — Destroy a session
  • new — Create an ad-hoc session
  • color — Manage session colors
  • ps — Show processes running inside sessions
  • ports — Show listening ports inside sessions
  • top — Show resource usage (CPU, memory, GPU) for session processes
  • status — Show all sessions with details
  • peek — Peek at recent terminal output
  • pin — Pin the current tab to the session’s profile
  • unpin — Unpin the current tab from the session’s profile
  • profile — Profile management
  • notifications — Notification management
  • release — Release a muster-managed session back to plain tmux
  • adopt — Adopt an existing tmux session under muster management
  • shell-init — Output shell integration code for automatic profile suggestions on cd
  • settings — Show or update settings
Options:
  • --config-dir <CONFIG_DIR> — Path to the config directory
  • --json — Output in JSON format

muster list

List profiles and running sessions

Usage: muster list

muster up

Create or attach to a profile’s session

Usage: muster up [OPTIONS] <PROFILE>

Arguments:
  • <PROFILE> — Profile name or ID
Options:
  • --tab <TAB> — Switch to this tab index on attach
  • --detach — Create session but don’t attach

muster down

Destroy a session

Usage: muster down <SESSION>

Arguments:
  • <SESSION> — Profile name, ID, or session name

muster new

Create an ad-hoc session

Usage: muster new [OPTIONS] <NAME>

Arguments:
  • <NAME> — Display name
Options:

  • --tab <TAB> — Tab definition (name:cwd[:command]), repeatable

  • --color <COLOR> — Color (hex)

    Default value: #808080

  • --detach — Create session but don’t attach

muster color

Manage session colors

Usage: muster color [OPTIONS] [SESSION] [COLOR]

Arguments:
  • <SESSION> — Profile name, ID, or session name
  • <COLOR> — New color (hex or named)
Options:
  • --list — List available named colors

muster ps

Show processes running inside sessions

Usage: muster ps [PROFILE]

Arguments:
  • <PROFILE> — Profile name or ID (shows all sessions if omitted)

muster ports

Show listening ports inside sessions

Usage: muster ports [PROFILE]

Arguments:
  • <PROFILE> — Profile name or ID (shows all sessions if omitted)

muster top

Show resource usage (CPU, memory, GPU) for session processes

Usage: muster top [PROFILE]

Arguments:
  • <PROFILE> — Profile name or ID (shows all sessions if omitted)

muster status

Show all sessions with details

Usage: muster status

muster peek

Peek at recent terminal output

Usage: muster peek [OPTIONS] <SESSION> [TABS]...

Arguments:
  • <SESSION> — Profile name, ID, or session name
  • <TABS> — Tab names to show (all if omitted)
Options:

  • -n, --lines <LINES> — Lines of output per tab

    Default value: 50

muster pin

Pin the current tab to the session’s profile

Usage: muster pin

muster unpin

Unpin the current tab from the session’s profile

Usage: muster unpin

muster profile

Profile management

Usage: muster profile <COMMAND>

Subcommands:
  • list — List all profiles
  • delete — Delete a profile
  • save — Save a new profile (or snapshot a running session with –from-session)
  • add-tab — Add a tab to an existing profile
  • show — Show a profile’s full definition
  • edit — Edit a profile in $EDITOR
  • update — Update profile fields inline
  • remove-tab — Remove a tab from a profile

muster profile list

List all profiles

Usage: muster profile list

muster profile delete

Delete a profile

Usage: muster profile delete <ID>

Arguments:
  • <ID> — Profile name or ID

muster profile save

Save a new profile (or snapshot a running session with –from-session)

Usage: muster profile save [OPTIONS] <NAME>

Arguments:
  • <NAME> — Profile name
Options:

  • --tab <TAB> — Tab definition (name:cwd[:command]), repeatable

  • --color <COLOR> — Color (hex or named)

    Default value: #808080

  • --from-session <SESSION> — Snapshot tabs from a running tmux session

muster profile add-tab

Add a tab to an existing profile

Usage: muster profile add-tab [OPTIONS] --name <NAME> --cwd <CWD> <PROFILE>

Arguments:
  • <PROFILE> — Profile name or ID
Options:
  • --name <NAME> — Tab name
  • --cwd <CWD> — Working directory
  • --command <COMMAND> — Startup command

muster profile show

Show a profile’s full definition

Usage: muster profile show <ID>

Arguments:
  • <ID> — Profile name or ID

muster profile edit

Edit a profile in $EDITOR

Usage: muster profile edit <ID>

Arguments:
  • <ID> — Profile name or ID

muster profile update

Update profile fields inline

Usage: muster profile update [OPTIONS] <ID>

Arguments:
  • <ID> — Profile name or ID
Options:
  • --name <NAME> — New display name
  • --color <COLOR> — New color (hex or named)

muster profile remove-tab

Remove a tab from a profile

Usage: muster profile remove-tab <PROFILE> <TAB>

Arguments:
  • <PROFILE> — Profile name or ID
  • <TAB> — Tab name or 0-based index

muster notifications

Notification management

Usage: muster notifications <COMMAND>

Subcommands:
  • setup — Install macOS notification app bundle
  • remove — Remove macOS notification app bundle
  • test — Send a test notification to verify the notification system works

muster notifications setup

Install macOS notification app bundle

Usage: muster notifications setup

muster notifications remove

Remove macOS notification app bundle

Usage: muster notifications remove

muster notifications test

Send a test notification to verify the notification system works

Usage: muster notifications test

muster release

Release a muster-managed session back to plain tmux

Usage: muster release [OPTIONS] <SESSION>

Arguments:
  • <SESSION> — Profile name, ID, or session name
Options:
  • --name <NAME> — New name for the released session (defaults to session name without muster_ prefix)

muster adopt

Adopt an existing tmux session under muster management

Usage: muster adopt [OPTIONS] <SESSION>

Arguments:
  • <SESSION> — Existing tmux session name
Options:

  • --name <NAME> — Display name (defaults to session name)

  • --color <COLOR> — Color (hex or named)

    Default value: #808080

  • --save — Also save as a persistent profile

  • --detach — Adopt without attaching

muster shell-init

Output shell integration code for automatic profile suggestions on cd

Usage: muster shell-init <SHELL>

Arguments:
  • <SHELL> — Shell type: fish, bash, or zsh

muster settings

Show or update settings

Usage: muster settings [OPTIONS]

Options:
  • --terminal <TERMINAL> — Set terminal emulator (e.g. ghostty, alacritty, kitty, wezterm, terminal, iterm2)
  • --shell <SHELL> — Set default shell
  • --tmux-path <TMUX_PATH> — Set tmux binary path

This document was generated automatically by clap-markdown.