Skip to content

sbsh Command

The sbsh command launches a client attached to a terminal. It's designed for interactive use and can be set as your login shell.

Usage

sbsh [flags]
sbsh terminal [flags] [-- command [args...]]

Commands

sbsh (default)

Launches a client attached to a terminal:

sbsh
sbsh -p profile-name

Behavior:

  • Client stays attached to terminal
  • Press Ctrl-] twice to detach
  • Terminal continues running after detach

sbsh terminal

Launches a terminal in the background with no attached client:

sbsh terminal --name my-terminal
sbsh terminal --name my-terminal -p profile-name

Behavior:

  • Terminal runs independently
  • No client attached initially
  • Attach later with sb attach <name>
  • Important: Always use --name to identify the terminal

Flags

Persistent Flags

These flags apply to all sbsh commands:

  • --run-path <path>: Optional run path for the client
  • --config <file>: Config file (default: $HOME/.sbsh/config.yaml). See the Configuration guide for the Configuration document schema.
  • --profiles-dir <path>: Directory scanned recursively for TerminalProfile YAML documents (default: $HOME/.sbsh/profiles.d/)

Client Flags

  • --id <id>: Optional ID for the client
  • --socket <file>: Optional socket file for the client
  • --log-file <file>: Optional log file for the client
  • --log-level <level>: Optional log level (debug, info, warn, error)
  • -d, --detach: Detach client immediately
  • --disable-detach: Disable detach keystroke (Ctrl-] twice)

Terminal Flags

  • --terminal-id <id>: Optional terminal ID (random if omitted)
  • --terminal-name <name>: Optional name for the terminal (must be unique across active terminals — see Name uniqueness)
  • -p, --terminal-profile <name>: Profile for the terminal
  • --terminal-command <cmd>: Command to run (default: /bin/bash)
  • --terminal-socket <file>: Optional socket file for the terminal
  • --terminal-capture-file <file>: Optional filename for the PTY transcript capture
  • --terminal-log-file <file>: Optional filename for the terminal log
  • --terminal-log-level <level>: Optional log level for the terminal
  • --terminal-disable-set-prompt: Disable setting the prompt

All flags above are terminal-scoped — they configure the embedded terminal that sbsh launches. Client-scoped flags (without the --terminal- prefix) configure the client process itself.

Examples

Start with Default Profile

sbsh

Start with Profile

sbsh -p terraform-prd

Start Background Terminal

sbsh terminal --name my-terminal -p k8s-default

Start with Custom Command

sbsh --terminal-command /bin/zsh

Start with Detach Flag

sbsh -d -p my-profile

Subcommands

sbsh terminal

Launch a terminal without an attached client. The workload command and its arguments are passed positionally after a -- separator and executed via execve semantics (no shell re-tokenization), the way docker run, kubectl exec, runc exec, ctr run, sudo, env, and nsenter all take their argv. With no positional argv, the profile default (/bin/bash) applies.

sbsh terminal [flags] [-- command [args...]]
sbsh terminal --name my-terminal
sbsh terminal --name my-terminal -- /bin/zsh
sbsh terminal -p devprofile -- /bin/sleep 3600

Name uniqueness

Terminal names must be unique across active (non-Exited) terminals sharing the same run path. A launch that would collide with an existing active terminal fails fast with a clear error rather than silently spawning a shadow:

$ sbsh terminal --name my-terminal &
$ sbsh terminal --name my-terminal
Error: terminal name already in use by an active terminal: "my-terminal" (id 7c4f3a02)

The check applies regardless of how the name reached the spec — flag (--name, --terminal-name), stdin (sbsh terminal -), or --file spec. Names from terminals that have exited (or whose owner process is gone, reconciled to Exited on scan) can be reused immediately; you do not need to sb get terminals --prune first. Two simultaneous launches with the same name can both pass the check and briefly coexist; downstream tools (sb attach/detach/stop <name>) resolve the collision by returning the first match, so the racing loser remains addressable by ID.

sbsh version

Show version information:

sbsh version

sbsh autocomplete

Generate shell completion:

sbsh autocomplete bash
sbsh autocomplete zsh

Environment Variables

  • SBSH_PROFILES_DIR: Path to profiles directory (overrides --profiles-dir; default $HOME/.sbsh/profiles.d/)
  • SBSH_ROOT_CLIENT_SOCKET: Default client socket path
  • SBSH_CLIENT_ID, SBSH_CLIENT_NAME, SBSH_CLIENT_SOCKET: Client identity overrides
  • SBSH_CLIENT_LOG_FILE, SBSH_CLIENT_LOG_LEVEL: Client logging overrides
  • SBSH_CLIENT_DETACH, SBSH_CLIENT_DISABLE_DETACH_KEYSTROKE: Client behavior flags

See Also