boo

boo uses a client-daemon model to manage terminal sessions:

1. Client: Puts your TTY in raw mode and communicates with the daemon via a framed Unix-socket protocol.
2. Daemon: A persistent process that owns the session. It manages a PTY-attached child process.
3. Terminal State: The daemon uses libghostty-vt to parse all output from the PTY. This allows the daemon to maintain a perfect record of the screen state (contents, styles, cursor, scrollback, and modes).
4. Rehydration: When a client attaches, the daemon uses a TerminalFormatter to replay the screen from the saved libghostty state, ensuring a faithful redraw.
5. Detached Queries: While a session is detached, the daemon can answer terminal queries (like DSR or DA) using the stored state, preventing TUIs from hanging.

For Linux and macOS, you can install boo using the official installation script:

curl -fsSL https://raw.githubusercontent.com/coder/boo/main/install.sh | sh

Alternatively, pre-built binaries are available on the releases page.

You can control the installation behavior using these environment variables:

• BOO_VERSION: Pin a specific release version.
• BOO_INSTALL_DIR: Change the installation directory (defaults to /usr/local/bin if writable, otherwise ~/.local/bin).

The boo CLI manages sessions by spawning background daemons. The following internal mechanisms handle the transition from a foreground command to a detached daemon:

• Socket Binding (bindListen): Creates a UNIX domain socket for communication. If the socket path is already in use, it checks if a live session exists via a connection probe. If no session is active, it deletes the stale socket file and re-binds.
• Daemon Detachment (runDaemon): When a daemon starts, it detaches from the controlling terminal using setsid(). It redirects stdin and stdout to /dev/null and redirects stderr to a log sink (defined by the BOO_LOG environment variable, or /dev/null if unset) to ensure debug logs are preserved.

The wait command blocks until a specific condition is met in a session, useful for automation scripts.

Options:

• <name>: The name of the session.
• --idle: Wait until the session has been idle for a certain duration. The session must be idle for at least 2000ms (the idle_settle_ms) before the timer starts.
• --text <string>: Wait until the specified string appears in the session's screen output.
• --timeout <duration>: The maximum time to wait. Supports formats like 500ms, 2s, 1m, 4h, 1d. Defaults to 30s.

Example:

# Wait up to 1 minute for 'done' to appear in the screen
boo wait my-session --text "done" --timeout 1m

# Wait for the session to become idle for 5 seconds
boo wait my-session --idle --timeout 5s

The kill command terminates sessions.

Options:

• --all: Terminate all active sessions. This cannot be combined with a specific session name.
• <name>: The name of the session to terminate.

Example:

# Kill a specific session
boo kill my-session

# Kill all sessions
boo kill --all

Use the new command to start a new session. You can specify a session name, terminal dimensions, a working directory, or run a specific command.

Options:

• <name>: The name of the session. If omitted, a default name is used.
• --detached (-d): Start the session in the background and exit immediately (prints the session name to stdout).
• --rows <number>: Set the number of rows (1-65535).
• --cols <number>: Set the number of columns (1-65535).
• --cwd <path>: Set the working directory for the session. This must be an absolute, accessible directory.
• -- <command> [args...]: Use -- to separate boo options from the command you want to run inside the session.

Example:

# Create a named session running 'top' in a specific directory
boo new my-session --cwd /home/user -- top

# Create a detached session
boo new -d my-session

Use attach (or at, a) to connect to an existing session. If you provide a partial name, boo will attempt to resolve it to a unique session name.

Example:

# Attach to a session named 'work'
boo attach work

The send command allows you to inject text, key sequences, or stdin into a running session.

Options:

• <name>: The name of the target session.
• --text <string>: Send a specific string of text.
• --key <key1,key2,...>: Send specific key sequences (e.g., enter, tab, up, down, left, right, escape, backspace).
• --stdin: Read input from standard input and send it to the session.
• --enter: Append a carriage return (\r) to the end of the payload.

Constraints:

• --text and --key cannot be used together.
• --stdin cannot be used with --text or --key.
• You cannot send NUL bytes.

Example:

# Send 'ls' followed by Enter
boo send my-session --text "ls" --enter

# Send an Escape key sequence
boo send my-session --key escape

# Send content from a pipe
cat script.sh | boo send my-session --stdin

The peek command provides a snapshot of a session's current state without attaching to it.

Options:

• <name>: The name of the session.
• --scrollback: Peek at the scrollback buffer instead of the current screen.
• --json: Output the peek data in JSON format.

Example:

# Get a JSON snapshot of the screen
boo peek my-session --json

When using automation commands (like wait), boo returns the following exit codes:

• 0: Success
• 1: Error
• 2: Usage error
• 3: No such session
• 4: Wait timed out