Command line
terminal-delight with nothing after it opens a window and restores your session. Give it a directory and the first terminal starts there. Everything else is a verb that does one job and exits without opening a window.
The ones you're likely to type are ctl, to script a running window, and mcp, the relay you register with an agent. surface puts work on your pane's workbench from a script, and probe and bindings say what Terminal Delight would resume and which conversation each agent is in. A word it doesn't know is refused with the usage text, rather than opening a window.
Technical lists every verb, its arguments and its exit codes.
Verbs
| Command | Does | Exit |
|---|---|---|
terminal-delight | Open a window and restore this workspace's session. | |
terminal-delight <dir> | Open a window whose first terminal starts in <dir>. Only without the session host (TD_NO_SESSIOND=1) and with no layout to restore; with the session host, the default, the directory is ignored (issue 798). | |
ctl … | Script a running window. See ctl. | 0, 1, 2 |
mcp [--pid <N>] | The stdio MCP relay into a running window. See MCP server. | 0 at end of input; 1 no window; 2 window lost |
surface [file] | Put a work object on the calling pane's workbench, from a file or stdin. --catalogue prints what this build can draw; --derive <transcript.jsonl> prints what it would draw from a transcript. | 0 accepted; 2 nothing usable; 3 not inside a pane |
serve --session <name> | Run the session host for a session. Windows start this themselves. | 2 usage |
probe <pid> | For a shell pid: its foreground process, directory and resume command, as JSON. | 0; 1 bad pid; 2 failed |
bindings | Which conversation each running Claude or Codex process is in, and on what evidence, as JSON. | 0; 2 if /proc can't be read |
bindings <id> | Whether a conversation id is a whole conversation or part of one. | 0 |
conversation <root> [--json] | Read a conversation's bench back without a window: its surfaces, turns and answers. | 0; 2 usage |
skin | Resolve a skin against a theme and print every token as JSON. See Skins. | 0; 1 parse error; 2 usage |
agent-usage [update|list|where] [--only <id>] | Run the usage collectors for Claude, Codex and Fireworks and write one record per subscription. See Usage and vitals. | 1 only if every collector failed |
agent-vitals <transcript.jsonl>… | The three attention bars for transcripts, as JSON. --parts, --keys. | 2 with no arguments |
--version, -V | terminal-delight 0.3.0 | 0 |
--help, -h | The usage text. | 0 |
An unknown word prints terminal-delight: unknown command `<word>` and the usage text, and exits 2. An unknown option does the same with unrecognised option. Commands that print can be piped into head without an error.
probe#
Keys: shell_pid, fg_pid, kind, comm, cwd, cmdline, resume. resume is the command Terminal Delight would type to bring the agent back, such as claude --resume <id>.
bindings#
{"panes": […]}, one row per agent: shell_pid, agent_pid, mode, cwd, session, bond, certain, and the conversation's lineage. bond is how the binding was found: declared (the agent said so), birth (a transcript started with it), sole (the only conversation in its directory) or guess.
Environment the usage text names#
TD_SCRATCH=1 opens a throwaway window; TD_SEED_CWD=<dir> and TD_SEED_RESUME=<cmd> seed its first pane. The rest are in Environment flags.
Sources
- The verb table, usage text and exits: main.rs (
mainand itsVERBSroster).