Using this reference
Run hai from a Haicue-managed agent session. Most commands require the running desktop engine. Use the IDs returned by discovery commands. This page lists the implemented command surface; run hai help to check your installed version.
hai help
hai --help
hai version
hai --versionIn the syntax below, <value> is required, [value] is optional, and a|b means choose one. Replace placeholders and omit the brackets; these are command signatures, not scripts to run as a batch. Quote text and JSON so the shell passes them as one argument. Definition inputs accept a YAML or JSON file path, quoted inline data, or - to read standard input where shown.
Discover sessions and threads
Inspect the calling session and discover registered sessions, threads, and skills. Add --all to include closed sessions.
hai whoami
hai list
hai list sessions [--all]
hai list threads
hai list skills
hai list all [--all]Sessions
Open, inspect, focus, send input to, or close a registered session. Opening creates a fresh session. Closing terminates its pane.
hai session open <thread> [--agent claude|codex] [--label <label>] [--model <model>] [--effort <effort>]
hai session inspect [session-id]
hai session focus [session-id]
hai session send [session-id] <text...>
hai session send --session <session-id> <text...>
hai session close <session-id>Inspect, focus, and send default to the caller when the ID is omitted. Close requires a full session UUID. Model availability is validated against the chosen runtime; omit model and effort to use configured defaults. There is no agent-facing stop command.
Thread context and moves
Read a thread’s context, change the calling session’s thread, or reorganize thread folders while retaining session identities.
hai thread.inspect [thread] [--format preload|json] [--max-bytes <n>] [--extra-files <paths>] [--out <path>]
hai thread switch <thread>
hai thread.move-plan <manifest.json> --dry-run [--threads-root <path>] [--haicue-home <path>]
hai thread.move-plan <manifest.json> --apply [--threads-root <path>] [--haicue-home <path>]A thread can be a canonical key or path. Inspection defaults to the caller’s thread; it does not switch attendance. Extra files are comma-separated paths. Preview a move manifest with --dry-run before applying it. The root and home flags select the state directories for offline maintenance.
Git
List repositories registered to a thread, then inspect a returned repository path. Both commands are read-only.
hai git repos [thread]
hai git repo <thread> <repo-path>Automations
Create scheduled or event-driven work, control its lifecycle, and report a run’s progress and outcome.
hai automation list
hai automation inspect <automation-or-run-id>
hai automation create <definition|file|->
hai automation update <automation-id> <definition|file|->
hai automation pause <automation-id>
hai automation resume <automation-id>
hai automation run <automation-id> [--effort low|medium|high]
hai automation delete <automation-id>
hai automation heartbeat <run-id> [progress...]
hai automation report <run-id> <outcome> [--summary <text>] [--question <text>] [--retry-after <seconds>]Outcomes are success, retry, needs_user, failed, and skipped. Reports and heartbeats take a run ID. The run effort override applies to Brain automations; session automations inherit their session’s model and effort. Use the Automations skill for definition fields and the Automations guide for scheduling behavior.
Skills and tools
Inspect the schema before creating a custom skill. Save its tools, verify their behavior, then install the skill for your agents.
hai skill schema [--example]
hai skill list
hai skill inspect <skill-id>
hai skill create <definition|file|->
hai skill tool save <skill-id> <definition|file|->
hai skill tool remove <skill-id> <tool-id>
hai skill build-manifest <skill-id>
hai skill check <skill-id> <connection|read|action> <pass|clear>
hai skill install <skill-id> [--agent <agent>]
hai skill uninstall <skill-id> [--agent <agent>]
hai skill delete <skill-id> [--with-thread]Checks record verification results; they do not run tests for you. Install and uninstall target all registered agents unless --agent is supplied; repeat the flag to select multiple agents. Deleting with --with-thread also removes the development thread. See Skills and tools.
Awaiting and notifications
Keep loose ends on a thread and publish actionable notifications. Awaiting takes a JSON payload with an ID, an operation, and an item for set operations.
hai await <thread-key> <json>
hai notification list [--unread] [--dismissed]
hai notification publish <definition|file|->
hai notification read <id>
hai notification read-all
hai notification dismiss <id>
hai notification act <id> <action-id>
hai notification preferences <definition|file|->Awaiting operations are set and remove. Use the Awaiting and Notifications skills for their payload fields. Notification act executes the named action; preferences writes notification settings. See Awaiting. Loops use thread files and their lifecycle skill; there is no separate hai loop command.
Windows and Cues
Open and update typed windows, manage Cues cards, and export decks. Window IDs and card IDs come from the window or deck you are working with.
hai show
hai spawn <type> <window-id> [json]
hai close <window-id>
hai push <window-id> <json> [--async]
hai ping <window-id> <card-id> <message...>
hai settle <window-id> <card-id> [--unsettle]
hai cards.dump <window-id> [path]
hai cues.export <window-id> [path]
hai cues.import <path> [--session <session-id>] [--id <window-id>]Push validates JSON and waits up to five seconds for acknowledgment. --async skips that validation and acknowledgment wait. Settle marks a card complete; --unsettle revives it. Cards dump writes Markdown, while Cues export writes a lossless .cues.json snapshot. Import opens a deck from that snapshot. Use the Cues skill for window and card payloads.
Live Capture
Control the capture daemon. Start and arm accept source, language, mode, and ownership options.
hai lc start [source] [--language <iso>] [--mode diarize|window|vad] [--session <session-id>] [--window <name>]
hai lc arm [source] [--language <iso>] [--mode diarize|window|vad]
hai lc status
hai lc pause
hai lc resume
hai lc stop [--session <session-id>] [--window <name>]
hai lc enroll [source]
hai lc enroll-stop
hai lc screen snapshot
hai lc screen start
hai lc screen stopScreen commands resolve the caller and require it to own the active managed capture. Use the Live Capture skill for source selection, voice enrollment, permissions, and session ownership. See Live Capture.
Web Connector
Attach a local web app to the current thread, inspect it, and manage the connection. Attach requires a loopback URL and a name.
hai web-connector attach <local-url> --name <name> [--new] [--started-by-agent <ref>] [--session <session-id>]
hai web-connector list
hai web-connector inspect <connector-id>
hai web-connector reload <connector-id>
hai web-connector reattach <connector-id>
hai web-connector assets <connector-id> [--type <kind>]
hai web-connector asset read <connector-id> <url>
hai web-connector dom query <connector-id> <selector>
hai web-connector dom snapshot <connector-id> [selector]
hai web-connector dom highlight <connector-id> <selector>
hai web-connector eval <connector-id> <expression>
hai web-connector console <connector-id> [--level error|warn|all]
hai web-connector network <connector-id> [--failed] [--since <cursor>]
hai web-connector listen <connector-id> <event-spec>
hai web-connector unlisten <connector-id> <subscription-id>
hai web-connector send <connector-id> <channel> <json>
hai web-connector agent-status <connector-id> <work-id> <on-it|done|failed|clear> [message...]
hai web-connector claim <connector-id>
hai web-connector stop <connector-id>Listen accepts an event name or JSON specification. Use the returned subscription ID to unsubscribe. Network cursors limit results to newer events. Claim takes ownership; stop ends the connector. See LiveApps for the attachment workflow and Browser control for Chromium and DevTools capabilities.
Diagnostics and webviews
Inspect a Haicue webview or observe engine events. Prefer typed commands for routine work.
hai eval [@label] <javascript>
hai shot [@label] [path]
hai tap
hai tap.cards <window-id>
hai say <text...>
hai raw <protocol-line>Eval executes JavaScript in the selected webview and can change its state. Shot saves a PNG. Tap listens continuously; tap.cards follows one deck and exits when it closes. Say broadcasts a message. Raw sends a protocol line and requires a documented protocol contract. The retired hai repl command is replaced by one-shot hai push calls.