sirioctl overview
The control-socket CLI: how it connects, how to identify yourself, and the command groups.
sirioctl talks to a running Sirio over a local socket and is the way scripts and agents drive the app. Sirio exports SIRIO_PANE_ID, the id of the pane, in every terminal it starts, so a script can check for it before it does anything else.
[ -n "$SIRIO_PANE_ID" ] || exit 1
sirioctl ping
sirioctl identify --jsonping answers pong while Sirio listens. identify prints a worktree’s project, branch, path and id, and your pane id as surfaceId. The worktree is the one that worktree-set --session tied to your pane, or else the one selected in the sidebar.
Command groups
| Group | Commands |
|---|---|
| System | ping, version, capabilities, identify, quit |
| Projects | project list | add |
| Workspaces | list-workspaces, new-workspace, select-workspace, current-workspace, close-workspace, worktree-set, restore-session |
| Panels | panel create | split | list | write | key | read | state | scrollback | wait | focus | close |
| Panes and tabs | pane split | focus | close, tab cycle | select |
| Surfaces | surface changes open | read | stage | unstage | discard | stage-all | discard-all, surface settings open | select | read, surface change-requests show | read | filter | token, surface change-request open | tab | read | reveal | open-file | open-commit, surface tabs read | select | close, surface file read |
| Browser | browser open | navigate | get | snapshot | act | wait | eval | console |
| Status and notifications | notify, session-ref, list-notifications, clear-notifications |
Panels, Workspaces and panes, Surfaces and Browser automation cover the Workspaces, Panels, Panes and tabs, Surfaces and Browser groups in depth. Hooks and sirioctl notify covers notify and session-ref. Environment covers the variables and where the socket lives.
On your PATH
Agents drive Sirio through sirioctl from any terminal, so Sirio makes sure the command is there. It keeps its own copy of sirioctl up to date at ~/.local/share/Sirio/bin/sirioctl and links it onto your PATH:
- Linux:
~/.local/bin/sirioctl. - macOS:
/usr/local/bin/sirioctlor~/.local/bin/sirioctl. Install in PATH asks for your password only when/usr/local/binneeds it. - Windows: your user
Pathnames the folder that holds the copy.
Settings → General has a CLI card with Install in PATH. Sirio never replaces a file it did not put there. Terminals, agents, git and links start in the environment you launched Sirio from; see Environment.
Output
Without --json, a command prints fixed columns with a tab between each, one line per row. --json prints the whole answer as JSON. Some answers need it: surface tabs read prints an empty line without it, and surface file read prints only its state and error. browser act, browser wait and browser console print JSON either way.
A command that fails writes sirioctl: and the reason to standard error, and exits with a non-zero status.
Ids and the selected worktree
panel create and panel split print an id such as pane-81234-1. panel write, key, read, state, scrollback, wait, focus and close take it as --id or as the argument after the verb, and panel split takes it as --from, so capture it and pass it back.
Several groups follow the window instead. pane and tab commands, and most surface commands, act on the worktree selected in the sidebar and its active tab. browser commands act on the first Browser tab of that worktree, whatever surface id you pass. panel create and panel list use the selected worktree too, unless you pass --worktree. Pass --worktree wherever a command takes one, and leave the selection where it is while a script runs.