CLI Guide

Connection and identity

The CLI connects to the running Termdock app through the local control socket and Terminal API. --token overrides the bearer token resolved from local configuration. hostinfo detects the host terminal and Terminal/AST API ports offline; identify returns the focused workspace, pane, and session identity.

Complete commands and flags

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>      Terminal API bearer token (resolved from local config by default)

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)
  workspace list --json
  session create --workspace <id> [--name <name>] [--background] --json
  session list [--workspace <id>] --json
  session rename <id> <name> --json
  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
  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]

Terminal input and output

Use session input with --enter to submit a command. session submit is for terminals already at an interactive prompt and can wait for settling or readiness. --since uses nextCursor from a previous output read. --follow supports raw, text, and content, not screen. Filter session list with --workspace.

termdock workspace list --json
termdock session create --workspace <id> --background --json
termdock session input <id> "npm test" --enter --json
termdock session output <id> --mode text --lines 100 --json

Layout snapshots and keep-alive

Capture a full snapshot with layout get --full --json before layout restore --file. The CLI rejects slim snapshots. keepalive set takes one of --interval, --idle, or --daily. Use the HTTP API for a promptRef resolved from the Prompt Library at trigger time.

Notifications and external events

notify pushes a message to the configured Discord/Telegram remote. The session defaults to $TERMDOCK_SESSION_ID; --title names the Discord thread created on that session’s first push. agent callback delivers only to an existing AgentSession, without starting an agent or falling back to raw terminal input. metadata must be a JSON object; dedupe-key does not automatically deduplicate events.

Agent hooks

hooks status, setup, and uninstall support claude, codex, and gemini. --dry-run previews setup or removal. hook ingest accepts provider events; --wait waits for a reply, while --wait-timeout and --request-timeout bound the waits.