CLI Guide

Install the command-line tool

On macOS, open Settings > Skills > Command Line Tool and choose Install. The command is installed in ~/.local/bin; if an external shell cannot find it, add that directory to PATH and start a new shell. Reinstall there after moving the app. This installer does not support Windows; use the desktop interface or a configured Terminal API client rather than copying the macOS shim path.

termdock --version
termdock --help
termdock hostinfo --json

Normal CLI operations need the Termdock app running; hostinfo can discover host identity and service ports offline. identify returns the focused workspace, pane, and session, but still confirm your intended target before writing. Angle-bracket values below are placeholders; use the IDs from your actual JSON responses.

Start another agent and hand off a task

This example assumes Claude Code is installed and signed in. List workspaces, create a named background terminal, then use the returned session id. Creating a terminal starts a shell; it does not sign in to an agent for you.

termdock workspace list --json
termdock session create --workspace <workspace-id> --name docs-review --background --json
termdock session input <returned-session-id> "claude" --enter --json
termdock session output <returned-session-id> --mode screen --json

Confirm that the agent has finished startup, sign-in, and trust prompts and is at its input composer before sending the task. Include context, allowed files, and the validation you expect; another agent does not inherit the original conversation.

termdock session submit <returned-session-id> "Read README.md and report missing installation steps. Do not edit files." --json
termdock session output <returned-session-id> --mode text --lines 100 --json

Read the result before deciding the next step. Output text and completion messages are not evidence that tests passed. Take over from the background panel to bring the terminal into view. Use session destroy only when the work is no longer needed; it ends a regular terminal’s processes.

Query, edit, and wait on dispatches

Version 1.24 adds the dispatch queue. Target an existing eligible agent terminal. A successful enqueue only acknowledges admission, not submission. Use the returned handle.appInstanceId and handle.dispatchId to query or wait, and the current version when editing.

termdock dispatch enqueue <session-id> "Review README.md; report only." --workspace <workspace-id> --request-key <unique-task-key> --queue-timeout 60000 --json
termdock dispatch list --workspace <workspace-id> --json
termdock dispatch get <app-instance-id> <dispatch-id> --workspace <workspace-id> --json
termdock dispatch wait <app-instance-id> <dispatch-id> --workspace <workspace-id> --wait-timeout 30000 --json

Only queued items can be edited or cancelled. Read the current state first; cancel is not an interrupt for an already-running agent. waitTimeout is this call’s wait budget, while queueTimeout is the queue expiry. Respond in the terminal for waiting-human; reconcile delivery before resending an unknown result.

termdock dispatch edit <app-instance-id> <dispatch-id> "Review README.md and docs/ only; do not edit." --workspace <workspace-id> --expected-version <current-version> --json
termdock dispatch cancel <app-instance-id> <dispatch-id> --workspace <workspace-id> --json

Automatic safe-send and turn-end signals currently support local macOS Claude/Codex, including broker-owned terminals. Do not assume parity for Windows, peer, SSH, or other providers; unsupported signals leave work queued with unsupported-signal until expiry. completed means the corresponding turn ended, while outcome may remain unknown. It is not proof of task success. The queue does not continue dispatching after app quit merely because the broker is still running.

Wait for a screen condition, not task success

termdock session wait <session-id> --text "Ready" --timeout 30000 --workspace <workspace-id> --json
termdock session wait <session-id> --gone "Building" --timeout 30000 --json
termdock session wait <session-id> --regex "ready|listening" --flags i --timeout 30000 --json

--text waits for text on the current screen, --gone waits for that text to be absent, and --regex waits for a regex match. --gone does not wait for session exit. This examines the current screen, not full history; text scrolling off screen can satisfy gone. Check matched, timedOut, and errors instead of treating a successful response as a match. Timeout is 0–120000 ms, default 30000; 0 checks once.

Input, output, and layouts

• Use session input with --enter for a shell command. session submit is for a terminal already at an interactive composer and can wait for settling or readiness.
• Use the previous nextCursor with output --since. --follow supports raw, text, and content, not screen; screen is the current screen rather than output history.
• Capture layout get --full --json before layout restore. Slim snapshots are rejected.
• session keepalive set accepts --interval, --idle, or --daily. Use the HTTP API for a live Prompt Library reference.
• Local regular terminals use an available broker by default. session attach is an SSE/stdin bridge, not a broker writer grant. The app must still provide API access.

Notifications, events, and hooks

notify sends to configured Discord/Telegram providers and defaults to $TERMDOCK_SESSION_ID. --title names only the first Discord thread for a session. agent callback delivers only to an existing AgentSession, without creating an agent or falling back to raw terminal input. metadata must be a JSON object; dedupe-key does not automatically deduplicate events.

termdock hooks setup --agent claude --dry-run --json
termdock hooks setup --agent claude --json
termdock hooks status --json

hooks status, setup, and uninstall support claude, codex, and gemini. Preview changes with --dry-run before installing; Workstream depends on provider events and configured hooks. hook ingest uses --wait, --wait-timeout, and --request-timeout to bound reply waits.

Command reference

This reference matches the built-in help for the published 1.24 release. For a different installed build, check --version and --help first. --url and --token are global options before the command. Treat tokens as secrets and keep them out of shared command history. Default credential resolution verifies the loopback service before using cache/bootstrap.

Termdock CLI

Usage: termdock [options] <command>

Options:
  --help, -h           Show this help text
  --version, -v        Show the Termdock CLI version
  --url <url>          Terminal API base URL
  --token <token>      Bearer token (explicit/env, else verified loopback cache/bootstrap)

Commands:
  identify --json      Print focused workspace/pane/session identity
  hostinfo --json      Detect host terminal + Terminal/AST API ports (offline)
  notify <message> [--session <id>] [--title <text>] [--json]
                       Push a message to the configured Discord/Telegram remote
                       (session defaults to $TERMDOCK_SESSION_ID; --title names the
                       Discord thread created on the first push of a session)
  tool --list [--json]
  tool <name> [--input <json> | --input-file <path>] [--json]
                       [--workspace-id <id>] [--workspace-path <path>] [--session-id <id>]
                       Call Tool Runtime directly; omitted input defaults to {}.
  dispatch enqueue <session> <text> --workspace <id> --request-key <key> --queue-timeout <ms> --json
  dispatch list --workspace <id> [--session <id>] --json
  dispatch get|cancel <app-instance-id> <dispatch-id> --workspace <id> --json
  dispatch wait <app-instance-id> <dispatch-id> --workspace <id> --wait-timeout <0–120000 ms> --json
  dispatch edit <app-instance-id> <dispatch-id> <text> --workspace <id> --expected-version <n> --json
                       Admission is not submission/completion; unsupported signals stay queued until expiry.
  workspace list --json
  session create --workspace <id> [--name <name>] [--background] --json
  session list [--workspace <id>] --json
  session rename <id> <name> --json
  session wait <id> --text|--gone|--regex <value> [--flags im] [--timeout <ms>] [--workspace <id>] [--authority <value>] --json
                       Checks the current screen only; a match is not task completion. Timeout: 0..120000, default 30000.
  session output <id> [--mode raw|text|content|screen] [--lines <n>] [--since <cursor>] --json
  session output <id> [--mode raw|text|content] [--lines <n>] [--since <cursor>] --follow [--json]
  agent callback <session> --source <source> --event-kind <kind> --message <text>
                       [--dedupe-key <key>] [--metadata <json-object>] --json
                       Deliver an external event to an existing AgentSession only
  session input <id> <text> [--enter] --json
  session submit <id> <text> [--settle-ms <n>] [--queue-until-ready] [--ready-timeout <ms>] --json
  session key <id> <key> --json
  session interrupt <id> --json
  session status <id> --json
  session log <id> --json
  session ports <id> --json
  session keepalive list <id> --json
  session keepalive set <id> --message <text> (--interval <30m> | --idle <15m> | --daily <09:00>)
                       [--rule-id <id>] [--disabled] --json (live promptRef: use HTTP API)
  session keepalive rm <id> <rule-id> --json
  session attach <id>
  session destroy <id> --json
                       Local creates use the broker automatically when available; Quit keeps their processes running.
                       Broker output supports --since/--follow (Main attachment required); DOM is unavailable.
                       Output modes use App-owned rules; screen preserves blank/repeated rows and shares hash semantics.
                       session attach remains the SSE/stdin bridge, not a broker writer grant.
                       Closing a desktop tab or session destroy ends its processes and waits for acknowledgement.
                       Startup reconnects live terminals or restores ended ones from history; an unreachable broker waits.
  layout get [--full] --json
  layout set <type> [--sessions <id,id>] --json
  layout assign <pane-id> <session-id|none> --json
  layout activate <pane-id> --json
  layout activate-panel <panel-id> --json
  layout restore --file <path> --json   (snapshot from "layout get --full --json")
  hook ingest --json [--wait] [--wait-timeout <ms>] [--request-timeout <ms>]
  hooks status [--agent claude|codex|gemini] [--json]
  hooks setup [--agent claude|codex|gemini] [--dry-run] [--json]
  hooks uninstall [--agent claude|codex|gemini] [--dry-run] [--json]
  Read-only MCP: termdock-readonly-mcp --config <file> (separate executable)
  Exact HTTP reads: x-termdock-workspace-id guard; see docs/ref/api/READONLY-MCP.md

session/layout --json prints data; output --follow --json prints NDJSON; errors use stderr.

Troubleshooting

• command not found: inspect Settings > Skills and your shell PATH; reinstall the CLI after moving the app.
• Cannot connect: keep the app running, enable Terminal API, and inspect actual ports with hostinfo. Do not confuse development port 3036 with production 3037.
• SESSION_HELD_BY_PEER: take over on the host before writing. unsupported-signal: check platform, provider, and local/remote scope rather than blindly resending.
• Output appears complete: inspect actual files, diffs, tests, and the agent’s result. Screen conditions and turn events are not semantic-success guarantees.