Docs / Control CLI
The raven-term CLI
The raven-muxd daemon listens on a Unix control socket, whether or not a window is attached. The bundled raven-term CLI talks to it like tmux: query state, drive splits and focus, publish agent metadata, or type into any pane — from scripts, hooks, or your own tools.
How it works
The CLI sends its argv as a JSON array over the socket and prints the one-line reply. Queries print an aligned table for a person and are answered by the daemon, which owns the panes — no window has to be attached. Actions are acknowledged immediately, fire-and-forget, exactly like tmux. Override the socket path with RAVEN_TERM_SOCK.
Driving it from a script or an agent? Lead with --format json (shorthand --json) and every reply — success or failure, including a daemon that isn't running — becomes exactly one line of JSON ready for jq: queries return {"ok":true,"data":…}, actions are acknowledged with {"ok":true}, and failures return {"ok":false,"error":…} with a non-zero exit code.
Queries (an aligned table; --json for a program)
| Command | What it does |
|---|---|
| list-panes | lsp | Every pane across all spaces |
| list-tabs | lst | Every space with its panes |
| info | status | Full state: mode, active space, spaces |
| agents [--state s] | Panes with a detected agent; filter by idle/working/blocked |
Spaces
| Command | What it does |
|---|---|
| new-tab | neww | Open a new space (an agent space in agent mode) |
| next-tab / prev-tab | Cycle spaces |
| select-tab <n> | Activate a space by index |
Panes
| Command | What it does |
|---|---|
| split | splitw | Split focused pane / add agent side pane |
| focus <id> | Focus a pane by id |
| close-pane [id] | Close the focused pane, or one by id |
| move-pane <dest> [id] | Move a pane into another space, or `new` |
| break-pane [id] | Pull a pane out into its own space |
Mode & worktrees
| Command | What it does |
|---|---|
| mode <agent|default> | Switch the active space's layout mode |
| worktree | wt | Open the worktree picker (no chord — the verb is the way in) |
| worktree up [path] | Run the project's up scripts, one pane each |
| worktree down [path] | Run down scripts, close the env panes |
Metadata & input
| Command | What it does |
|---|---|
| report-agent … | Publish status / title / display name for a pane, with TTLs |
| send-keys … | Send tmux-style keys or literal text to any pane |
send-keys
Each word is a tmux-style key name (Enter, Escape, C-c, M-x, F1–F12, arrows, paging) or literal text. --literal forces plain text, --enter appends a carriage return, --pane targets any pane.
raven-term send-keys "git status" Enter
raven-term send-keys C-c
raven-term send-keys --pane 3 --literal "npm run dev" --enter
# a full scripted layout
raven-term split && raven-term split
raven-term send-keys --pane 2 --literal "claude" --enter
raven-term --json agents --state blocked | jq .data