shelbi session
View as markdownshelbi session <COMMAND> [OPTIONS]shelbi session is a low-level debug surface over the sessions that run every
Shelbi agent. A session is a small detached process that owns one PTY and one
headless terminal emulator, and outlives whatever launched it. In normal use the
orchestrator and the TUI drive sessions for you, and
shelbi attach is the rendered client you use by hand.
These subcommands are for inspecting and poking a session directly.
Subcommands
| Subcommand | Description |
|---|---|
ls | List sessions: name, short-id, state, size, task, launch time. |
new | Spawn a detached session running a command (everything after --). |
kill | Kill a session by signalling its child's process group. |
send | Send text to a session's PTY, delivered as a bracketed paste. |
snapshot | Print a session's visible screen as text, optionally with scrollback. |
kill, send, and snapshot take a <SESSION> selector, tried in this
order: an exact short-id, a full name, a workspace (the last / segment of a
name, e.g. alpha), a short-id prefix, then a name substring. When several
sessions match, -p <project> narrows to that project's sessions, and a live
session beats its dead predecessors. If none is live and they all share one
name, the newest wins. Anything still ambiguous is an error listing the
candidates; no match prints
no session matching `<sel>` (try `shelbi session ls`).
ls
shelbi session lsLists every session on this machine, across all projects, sorted by name then id:
NAME ID STATE SIZE TASK LAUNCHED
myapp/orch a563d23f83372c93 live 156x54 - 10-29 14:24
myapp/ws/alpha b307bef5303a3402 live 120x40 add-auth 10-29 22:02
myapp/ws/alpha b8a9ec12b4b02918 dead(code=143) - fix-login 10-29 21:50STATE is live, dead, dead(code=N), or dead(sig=N). SIZE is
<cols>x<rows> for a live session and - for a dead one. Dead sessions stay
listed until pruned, so a relaunch leaves its predecessors behind. With no
sessions it prints no sessions.
new
shelbi session new --name <NAME> [--cwd <CWD>] [--cols <COLS>] [--rows <ROWS>] [--task <TASK>] [--raw-log] -- <COMMAND>...| Option | Type | Default | Description |
|---|---|---|---|
--name <NAME> | string | — | Readable session name recorded in meta.json (required). |
--cwd <CWD> | string | current directory | Working directory for the child. |
--cols <COLS> | number | 80 | Initial screen width in columns. |
--rows <ROWS> | number | 24 | Initial screen height in rows. |
--task <TASK> | string | — | Task id this session serves, if any. |
--raw-log | flag | off | Keep the full raw output log. |
<COMMAND>... | string | — | The child program and its arguments, everything after --. |
Prints started session <id> (<name>) and the session's socket path. Session
state (meta.json, the socket, exit.json) lives under ~/.shelbi/sessions/.
kill
shelbi session kill [--signal <SIGNAL>] <SESSION>| Option | Type | Default | Description |
|---|---|---|---|
--signal <SIGNAL> | number | session's graceful default | Signal number to send. |
Killing a session that's already dead prints
session <id> (<name>) is already dead and exits 0.
send
shelbi session send [--enter] <SESSION> <TEXT>| Option | Type | Default | Description |
|---|---|---|---|
--enter | flag | off | Also send a carriage return after the text (submit the line). |
Fails if the session is dead.
snapshot
shelbi session snapshot [--history <HISTORY>] <SESSION>| Option | Type | Default | Description |
|---|---|---|---|
--history <HISTORY> | number | visible screen only | Include this many lines of scrollback above the visible screen. |
Works on dead sessions too: it prints the session's final screen, which is the way to inspect an agent that has exited.
Flags
Every subcommand accepts the same options:
| Flag | Type | Default | Description |
|---|---|---|---|
--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 | $SHELBI_PROJECT | Prefer this project's sessions when a selector is ambiguous (kill, send, snapshot). ls and new ignore it. |
Examples
List every session on this machine, all projects, live and dead:
shelbi session lsDump a stuck workspace's screen for inspection (-p disambiguates when
several projects have an alpha workspace):
shelbi session snapshot alpha --history 200 -p myappSee also
shelbi attach— the rendered, full-screen client for a session.- Workspaces — what a workspace session is and how it is owned.