hob CLI

The hob CLI connects the work people and agents share: projects, panes, conversations, commands, and the results they produce. Agents receive its guidance through managed instructions; use this reference to understand their actions, script supported operations, and look up what a command will change.

Namespace index

Choose the command context

A project directory identifies the work. A live hob connection and, for agent-only operations, a pane capability determine what the caller can do.

User Commands

Start with hob app --help, hob issue --help, or hob pr --help in an ordinary shell. Use --project-dir /path/to/project for project-aware commands. That flag selects a project; it does not create a connection or grant agent authority.

Agent commands

hob agent verify --json succeeds only with current agent authority. A hob terminal or automation shell step fails this check; an automation agent step receives its own capability. HOB_PANE_ID identifies a pane, but its presence alone is not proof of authorization.

Top-level help hides the agent-context namespaces when no pane context is present. Managed guidance normally arrives at agent launch through Settings → Agents → Agent instructions → hob instructions for agents, without editing repository files. See Working with your agent.

Run and license hob

Launch hob

Headless mode does not accept a project path. Choose the project from the connected desktop app or the Web IDE. Headless mode covers shutdown, the service, SSH, and the lifetime of the elected Host.

License activation

Use hob app license activate, hob app license status, or hob app license deactivate on the machine running hob. For non-interactive activation, supply the key on standard input:

printf '%s\n' "$HOB_LICENSE_KEY" | hob app license activate --key-stdin

Orient and arrange

An agent pane can choose --backend, --model, --effort, and supported --fast/--no-fast options. Models must be configured picker values; a started conversation cannot move to a different backend. See Parallel agents and Accounts and profiles.

For workspace creation, --environment <id> selects a live checkout; --worktree <branch> uses an existing branch, while --new-branch --start-point <ref> creates a branch and managed worktree. See Projects and workspaces for parallel writers.

Dock placement for cross-workspace work

Use hob pane open render --file notes/roadmap.md --surface dock --focus or hob pane move --to dock; specify --from if the pane has multiple placements. See Dock placement.

Read and recover

Terminal --watch subsumes --wait, conflicts with --json, and marks gaps caused by bounded retention. Interactive/TUI commands report unavailable live output and fall back to waiting. See Terminals.

For search grammar, snippets, and the recovery workflow, see History. Preserve the returned IDs for later commands rather than identifying a pane by a guessed title.

Deliver and collaborate

New messages use --pane to select the destination. Actions on an existing agent message take its receipt: message status, cancel, replace, or now. New messages and replacements both accept --text <text>, --text-file <path|->, or --stdin. Replacement returns a successor receipt for later actions.

A web node belongs to one snapshot. Use the node and fingerprint returned by the read together; substitute actual values for these illustrative placeholders:

hob pane view web_123
hob attention pane:web_123 --location node:n7 --fingerprint 'returned-fingerprint'

Continue reading that snapshot with --nodes and --fingerprint. Stale or missing elements degrade honestly. Annotations stay within one content surface; walkthroughs can mix surface types but use at most one web pane per set. See Working with your agent for what these interactions look like.

Record and review

Inside hob, prefix every Git command with hob. Run commits from the repository you intend to change, including nested repositories. Provenance links help you return to the conversation that produced something; they do not verify correctness. See Commits and artifacts and Issues.

Automate

Use paths returned by init/show; do not invent registry paths. Linked builder agents may omit the automation ID for supported show/apply/inspect operations. The Automation reference owns complete flags, YAML, expressions, environments, and run-history contracts. hob open view automations opens the human-facing builder and run view.

Change app preferences

Use these commands for clear requests to change running hob preferences. The /settings prefix is an optional helper. Scope defaults to global; --scope project targets the calling agent's project where supported. See Settings for the request and review workflow.

Write directly when the supported key and value are clear. Otherwise use list for discovery; it already includes current values. Read object values first: a replacement does not merge with the existing object. Current reads and writes require a live agent capability. Credentials and managed state retain dedicated operations. Writes return saved effective values and their sources for the affected keys, including inheritance after a project reset. Report that result without a separate read-back call. Saving a preference does not apply effects that require a restart. Clear follow-up requests do not need a /settings prefix.

Command boundaries

Compose a small workflow

These examples run from a hob agent. IDs below are illustrative: use the actual pane IDs from hob list, command ID returned by the terminal send, and the pane that sent the assignment. Run the example check only with Node installed.

Ask the terminal, read the result, reply

hob message --pane terminal_123 --text "node --check app.js" --wait
hob pane view terminal_123 --cmd 42
# Reply only after reading the actual result; use the source agent's pane ID.
hob message --pane agent_456 --text "The JavaScript syntax check passed. Behavior still needs review."

That final message assumes the check passed. If it failed, send the actual failure and relevant output instead. A syntax check does not verify guestbook behavior; Testing supplies the next checks.

Orient, open, point

When the person asks to see how the guestbook stores notes:

hob list
hob open file app.js --line 3 --placement right
hob attention file:app.js --location line:3 --message "This key keeps guestbook notes in this browser's local storage."

Line 3 is the storage key in the unmodified example; verify the line if the file has changed. Include the exact attention link printed by the last command in your reply, with a descriptive label, so the person can select it.

Options and agent-readable docs

Pane input, terminal commands, and initial agent tasks preserve literal text. For long multiline payloads, use a single-quoted heredoc and the supported stdin form. Never treat an unset project/window or unavailable content as permission to guess a target; inspect the error and resolve the context first.

Every guide has Copy Markdown and an Open menu for its .mdx URL. Give an agent the page relevant to the task; the prose and examples are available without downloading screenshots.

Next