shelbi attach
View as markdownshelbi attach [OPTIONS] <WORKSPACE>shelbi attach wires your terminal to a
workspace's Shelbi session, dropping you straight
into the agent so you can watch or drive it interactively. The session is
rendered full-screen: Shelbi draws the agent's screen rather than piping raw
bytes, so attaching from an 80-column terminal to a session sized for a wide
desktop window stays legible, and several terminals can view the same session
at once.
Where shelbi open ensures a workspace's session is up so the
TUI can show it, attach connects your terminal to that session directly,
from any terminal on the machine where the session runs. attach only finds
sessions on the local machine, so for a workspace on a remote machine, SSH to
that machine and run shelbi attach there. No terminal multiplexer is involved:
the session is a small Shelbi process that owns the agent's PTY and outlives the
connection, so detaching leaves the agent running.
Detach with the configured key (default Ctrl+]). Shelbi shows the detach key
on a one-line hint along the bottom row for a few seconds after you attach.
Detaching never stops the agent.
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
<WORKSPACE> | string | — | Workspace name (or a session name or short id from shelbi session ls) to attach to (required). Must be a live session. |
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--detach-key <DETACH_KEY> | string | ctrl-] | Key that detaches, written as modifiers plus a key joined by - or +, e.g. ctrl-], ctrl-b, alt-d, esc, f12. |
--root <PATH> | string | install-time default / $SHELBI_ROOT / ~/.shelbi | Override the Shelbi root directory. The flag wins over both the env var and the compile-time default. |
-p, --project <PROJECT> | string | env / cwd lookup | Project used to break ties when several sessions match. |
How <WORKSPACE> is matched
The argument is a session selector, tried in this order, stopping at the first unique hit:
- exact session short id
- exact session name
- workspace name (the last
/segment of a session name) - unique short-id prefix
- unique substring of a session name
When several sessions match, Shelbi prefers the ones under the current project
(-p), then the single live one. A dead session is refused with a pointer to
shelbi session snapshot, which shows its final screen.
Modifiers for --detach-key are ctrl, alt (or opt, meta), shift, and
super (or cmd). The key is a single character or one of enter, esc,
tab, space, backspace, delete, or a function key such as f12. The spec is
case-insensitive.
Examples
Attach your terminal to the alpha workspace's session:
shelbi attach alphaAttach with a different detach key:
shelbi attach alpha --detach-key ctrl-bSee also
- Workspaces — what a workspace is and how its session is created and owned.
shelbi open— ensure a workspace's session is up so the TUI can show it, rather than attaching your own terminal to it.shelbi session— the low-level debug surface over the same sessions (ls,new,kill,send,snapshot).