Automation reference Look up the YAML fields, CLI commands, execution rules, and retained results for hob automations.
Use this reference for the detailed automation contract and examples. Start with
Automations to build and run the guestbook
check-and-review workflow. Continue with
Building automations to add inputs,
validated agent results, and deliberate failure behavior. Use
Secrets, schedules, and trust to prepare unattended work.
Scope Location Shared with team? Shared .hob/automations/<uuid>/ in the project's canonical checkoutYes Private {configDir}/automations/{projectID}/<uuid>/No Global {configDir}/automations/global/<uuid>/No
Field or rule Contract version, id, nameVersion 1, UUID identity, required display name. Installed directory UUID matches id; init generates it description, categoryOptional description and grouping label Action Exactly one of command or steps commandShell source normalized to a foreground run step with id: main; source YAML remains unchanged shell, surface, ptyTop-level forms only with command; explicit plans put them on the owning step Assets Keep scripts, templates, styles, and schemas inside the bundle; scripts/, assets/, and schemas/ are useful conventions Validation Rejects unknown fields, extra YAML documents, symlinks, invalid identity, and oversized bundles Bundle limits At most 256 supporting files and 16 MiB of supporting content Staging Ordinary staging-directory names are accepted; installed bundles use UUID directories Draft Inactive until applied; retained for editing, absent from the runnable registry Run snapshot Captures the complete hash-checked bundle and static nested bundles; live edits do not change an admitted run
These definitions have the same execution plan:
version : 1 id : 5af1c74e-f97a-4db8-9eca-e76b9ed5afe3 name : Guestbook check shell : sh command : node --check app.js version : 1 id : 5af1c74e-f97a-4db8-9eca-e76b9ed5afe3 name : Guestbook check steps : - id : main name : Guestbook check shell : sh run : node --check app.js Both people and agents use the same managed registry. Commands below begin with
hob automation, except the final view command. Use --help for command flags.
Command Result list [--scope shared|private|global]Registry entries, including invalid definitions and diagnostics init <name> [--scope …]Create a scaffold; default scope is shared init --stdin [--scope …]Create from a complete ID-free definition; invalid input writes nothing init --bundle <dir> [--scope …]Create from an ID-free manifest plus all supporting assets, atomically show <id-or-name>Definition details and exact managed paths apply <id-or-name> --stdinValidate and replace the complete definition; preserve identity apply <id-or-name> --bundle <dir>Replace manifest and all assets together; include everything to retain validate <bundle-or-automation.yaml> or validate --stdinAnchored diagnostics without saving or running inspect <id-or-name> --step <id> --data-file <json>HTML template injection and inline JavaScript preflight; no run or durable artifact run <id-or-name> [--input key=value …]Start with repeatable structured input values run <id-or-name> --inputs-json <json-or->Supply a string-valued JSON object; - reads stdin run <id-or-name> --wait [--timeout <seconds>]Wait for completion; default wait limit 300 seconds, exit 0 only on success runs [<id-or-name>]Recent run states and results logs <run-id>Captured output delete <id-or-name> / restore <id-or-name>Move the complete automation to Trash / restore it delete <id-or-name> --permanentDelete an already trashed automation, including its history and stored assets hob open view automationsOpen the full Automations view
Authoring context Rule Linked builder agent May omit the automation ID for show, apply, and inspect; the pane identifies its automation New inactive draft Author inside its provided bundle, then promote with apply --bundle "$HOB_AUTOMATION_DIR" Saved automation Stage a complete asset replacement before apply --bundle; use apply --stdin for a definition-only change Invalid apply Returns diagnostics, exits 1, and leaves the working copy unchanged Shared run May pause for human trust approval; the CLI cannot approve it Nested execution Automation shell steps use an automation: step, not recursive hob automation run
Name Meaning HOB_AUTOMATION_DIR / ${{ automation.dir }}Captured authored bundle during execution; read scripts, templates, and schemas here HOB_RUN_DIR / ${{ run.dir }}Writable run output directory; write generated files here HOB_OUTPUTPrivate output-record file for the current process step; watched while it runs Single-line record Append NAME=value followed by a newline Multiline record Append NAME<<END, newline, value lines, then a line containing only END; choose a delimiter absent from the value Output limits Up to 128 named values, each bounded to 256 KiB Published value Later steps read ${{ steps.<id>.outputs.NAME }}; stdout is not a control channel Cleanup Captured artifacts remain in history after temporary run output is removed
YAML examples below are fragments unless they include version. Add them to a
complete definition; provide any referenced scripts, schema files, and child automations.
Common field Contract id, nameRequired; IDs are unique across steps and finally, matching [A-Za-z_][A-Za-z0-9_-]* descriptionOptional step description Action Exactly one: run, exec, agent, present, automation, or refresh ifOne condition expression; false records a skipped step on-error, retry, timeoutSee Control flow and results parallelConsecutive new-agent cohort name; see parallel constraints env, cwdProcess steps only (run or exec); top-level forms supply automation context Environment names [A-Za-z_][A-Za-z0-9_]*; HOB_*, FORCE_COLOR, and CLICOLOR_FORCE are reservedartifactsExplicit files to capture at the step; forbidden within parallel cohorts
Field Contract runStatic shell source; use for pipes, redirects, or chaining shellOptional platform default, or sh, bash, zsh, fish, pwsh, powershell, cmd; valid only with run exec, argsStatic executable plus argument list; arguments support interpolation without shell expansion detach: trueValid on run and exec; launches in the background and moves on, so later completion is not the step's result Detached constraints No timeout, surface, or pty; captured bundle/run paths stay available until process exit surface, ptyForeground process status; see Surfaces and retained results Supporting helper Prefer authored Bash under scripts/, explicitly invoked with exec: bash; use the actual executable when wrapping existing project tooling
Field or result Contract promptRequired, interpolated, never secret-bearing permission-modeRequired for a new pane: ask, approve_all, deny_all, plan, or plan_approve_all backend, model, effortOptional static picker values; omitted values use normal pane defaults accountBackend account; an explicit empty string selects its default account paneReuse an existing conversation, usually ${{ steps.review.pane-id }}; backend/model/effort/permission-mode overrides are invalid Reused context Conversation stays intact; each step has its own prompt marker, transcript slice, status, and result result.formatjsonresult.schemaStatic self-contained schema under ${{ automation.dir }}/…; validates this step's immediate response Accepted JSON Bare JSON or one JSON Markdown fence; only validated canonical JSON becomes the result Contract scope Constrains result shape, not the correctness of the agent's work Result access steps.<id>.result; compatibility spelling steps.<id>.outputs.output
- id : review name : Review the guestbook agent : prompt : Review app.js without editing it and return your verdict as JSON. permission-mode : ask result : format : json schema : ${{ automation.dir }}/schemas/review.schema.json on-error : retry retry : max-attempts : 3 The complete Building example
includes the schema. hob supplies its contents to the agent; the prompt need not repeat them.
Field Contract Source Exactly one of file, content, or template; captured when execution reaches the step fileExisting regular file; as may be auto (default), source, or web File inference Extension selects Markdown, HTML, image, video, audio, PDF, or source rendering contentInline text; explicitly set as: markdown, source, or web templateAuthored HTML; always web, with exactly one __HOB_DATA__ marker in JavaScript value position dataTemplate-only mapping; valid JSON values become native JSON types, other values stay strings Capture Safely serialized data and an immutable run asset; HTML uses a sandboxed web view Paths Run directory is the generated-file convention; an explicitly managed accessible regular file elsewhere can also be captured
< script > const report = __HOB_DATA__; </ script > - id : show-report name : Show report present : template : ${{ automation.dir }}/assets/report.html data : review : ${{ steps.review.result }} Use hob automation inspect with concrete JSON before handing over a template automation.
Field or rule Contract automationStatic shared:<uuid>, private:<uuid>, or global:<uuid>; names and paths are invalid inputsChild input names mapped to interpolated parent values; no secrets or secret-marked inputs secretsChild secret name → parent secret name; both definitions must declare their respective names timeoutOptional positive duration; cancellation stops the child Outputs Child's top-level outputs become steps.<nested-id>.outputs.<name>
- id : child-review name : Run the shared review automation : shared:44444444-4444-4444-8444-444444444444 inputs : scope : ${{ inputs.scope }} secrets : SERVICE_TOKEN : REVIEW_TOKEN timeout : 10m Replace the illustrative UUID with the child's installed ID.
refresh: on-reconnect arms connected browser clients to reload once a replacement
backend is serving. Use it for a rebuild-and-relaunch workflow, not to refresh a report.
Field or outcome Rule on-error: failDefault; failure stops the plan on-error: continueRecords failure and lets later steps run on-error: retryRequires retry.max-attempts, 2–20 total attempts retry.delayOptional positive duration; retry is invalid with other error policies timeoutPositive duration on foreground run, exec, agent, or nested steps; timeout records timed-out Ordinary failure Retry starts the step again Invalid agent JSON Retry supplies validation feedback in the same conversation Invalid schema file Setup failure, not retried steps.<id>.statussuccess, failure, canceled, timed-out, interrupted, or skippedSkipped condition Empty exit code, not 0; cannot satisfy a success-by-exit-code check Not run Remaining planned steps retain a Not run outcome after failure or cancellation
Continue after a failed check - id : check name : Check syntax exec : node args : [ --check , app.js ] on-error : continue - id : report name : Report a failed check if : ${{ steps.check.status != 'success' }} run : echo 'The syntax check needs attention' Constraint Rule Membership Up to 8 consecutive new-pane agent steps with the same parallel identifier Ordering Cohort name is contiguous and single-use; next step waits for every member References Earlier steps allowed; sibling references forbidden Exclusions No pane reuse, retry, artifacts, process/nested/present/refresh actions, surfaces, PTYs, or detach Failure Wait for all members; required failure fails the run, while on-error: continue permits downstream synthesis Stop or timeout Cancels live members, waits for settlement, then bounded finally cleanup Automatic execution Every member needs a finite timeout and approve_all or deny_all; also applies through a scheduled parent into nested work Interaction Manual cohorts may ask questions; automatic cohorts reject ask-user and plan-exit prompts Shared files Distinct pane/run directories do not isolate repository edits
Rule Contract Start boundary Runs after execution environment preparation, including runtime failure or user Stop Earlier failure Queued cancellation, input failure, or environment-resolution failure does not run cleanup in an unrelated checkout Actions Only run or exec, each with a required timeout Exclusions No detach, surface, or PTY Identity IDs share the main steps' namespace Failure Failing cleanup makes an otherwise successful run fail
Form Contract Interpolation ${{ reference }} substitutes a string; each token contains one bare referenceLocations Env, arguments, step cwd, prompts/pane targets, presentations, surfaces, artifacts, nested inputs, outputs; secret restrictions still apply Condition Entire if value is one ${{ … }} expression Operators ==, !=, !, &&, ||, parentheses; precedence: !, then equality, &&, ||Literals Single-quoted strings with next-character escapes, double-quoted Go-style strings, true/false, unsigned decimal text Equality Exact string equality, including numeric literals Truthiness After trimming whitespace, non-empty and neither 0 nor false
Reference Value inputs.<name>Declared input value secrets.<NAME>Declared secret in permitted locations steps.<id>.exit-codeEarlier step's exit code; empty for skipped steps.<id>.statusEarlier step's conclusion steps.<id>.pane-idEarlier agent step's pane steps.<id>.promptFully expanded agent prompt steps.<id>.resultAgent's final answer, canonical JSON when a result contract applies steps.<id>.outputs.<name>Published process or child-run output hob.web-idetrue when the browser IDE is served, otherwise falseautomation.dir, run.dirCaptured bundle and writable run directories run.idAvailable for execution-environment branch/start-point expressions
Unsupported Use instead Functions, arithmetic, JSON property traversal Process the value as data in a shell/executable step Operators in interpolation tokens Conditions in if; plain references elsewhere Dynamic run, executable path, health probe, child reference, backend/model/effort Static program selection; pass data through env or args Arbitrary top-level cwd interpolation Only ${{ automation.dir }} or ${{ run.dir }} roots there; use step cwd for dynamic process paths
Types: text (default), textarea, choice, bool, number, integer, date,
time, datetime, file, directory. Names match [A-Za-z_][A-Za-z0-9_-]*.
Field Valid for Meaning descriptionall Label shown in the run form defaultall Prefilled value; must itself pass the input's validation placeholdertext, textarea, number, integer, date, time, datetime Hint text shown while empty optionschoice The selectable values — at least one, non-empty, unique multiplechoice, file, directory Allow several selections; the value becomes a YAML list min / maxnumber, integer, date, time, datetime Inclusive bounds; min must be ≤ max stepnumber, integer, time, datetime Increment from min (or 0 / midnight); seconds for temporal types rowstextarea Editor height in rows acceptfile File-type filter for the picker appearancechoice auto, select, radio, segmented, checkboxes, or chipssecrettext, textarea, number, integer, date, time, datetime Password-style field, scrubbed from logs and history, barred from the same display sinks as declared secrets group / group-title / group-descriptionall Group related inputs in the run form show-whenall Show the input only when other inputs have expected values
inputs : scope : type : choice options : [ app , styles , all ] review_note : type : textarea required : false show-when : scope : [ styles , all ] Input rule Contract Required Defaults to true; required: false permits empty show-whenAll mapped conditions must match; a scalar is equality, a list is any-of Hidden value Must remain empty; supplying one fails the run Dependencies Self-reference and cycles rejected Automatic triggers Structured inputs prohibited even with defaults; no interactive PTY input
Top-level outputs: { verdict: "${{ steps.review.result }}" } publishes named
values to a parent via its nested step's outputs. Values cannot contain secrets.
Definition sourcing and execution targeting are separate. Shared bundles come
from the canonical checkout; choosing a worktree to execute in does not select
its copy of the definition.
Field Contract Omitted Manual/nested runs inherit the admitted environment; scheduled/restart runs use the project default environment: defaultPin the project checkout environment: floatingUse the project checkout while permitting branch changes; later steps see its current files environment.branchLocal target branch; global automations cannot target a branch environment.if-missingfail (default), or createenvironment.start-pointExplicit committed ref required for creating a missing branch Branch expressions Only non-secret inputs.* and run.id in branch/start-point fields Manual override run --environment <id> or --branch <name> [--if-missing create --start-point <ref>]; literal values, no expressions
Execution rule Contract Worktree Reuse a matching hob environment or create a managed worktree for an unoccupied branch; reject unattached external worktrees Creation No dirty-file copy, visible workspace, or switching of another checkout Cwd Within resolved environment, captured bundle, or run directory; arbitrary outside working directories invalid Pinned identity Commits allowed on the pinned branch; changing that branch or pinned detached commit fails the run Floating identity Initial branch/HEAD retained as provenance; branch changes permitted Detached lifetime Bundle/run paths retained until exit; if the Host exits first, it leaves them available History Records definition source/hash, execution branch/initial HEAD, creation and override markers; Open in workspace reveals the target Branch lifecycle No automatic cleanup, deletion, merge, rebase, push, commit, or checkout
For setup and a worked example, see Secrets, schedules, and trust .
Field or boundary Rule Declaration Top-level secrets: [NAME] lists every required secret Resolution Host environment variable → project store → global store; missing required values fail setup Stored project/global values Encrypted at rest; replacement UI does not reveal the saved value Automation-level value An env: entry in the definition, not encrypted secret storage Allowed secret expressions Automation/step env, exec arguments, step cwd, and if conditions; prefer step-level environment variables Rejected secret expressions Agent prompts/panes/result schemas, presentations, surfaces, artifact paths, outputs, and nested inputs Secret inputs Inputs marked secret: true are barred from the same display sinks Nested delivery Explicit child-name → parent-name secrets mapping; both definitions declare their names Scrubbing Known values are scrubbed from automation output and history; arbitrary files and transformed values are outside that guarantee
For the worked setup, see Run a check each night .
Field Contract on.user-triggerDefault true; false removes manual Run for people, agents, and CLI on.scheduleAt most 64 entries; same cadence with conflicting policies rejected every elapsedNominal start-to-start spacing, 1s–2880h; examples 30m, 1h30m, 24h every calendarInteger d, w, mo, count 1–120; m means minutes atRequired HH:MM for calendar schedules weekdayRequired for weeks; sun through sat, rejected for other intervals dayRequired for months; 1–31 or last; missing numbered dates skipped timezoneDefault Host local; pin an IANA zone for consistent shared wall-clock time dstcompatible (default), earlier, later, skip; invalid with a fixed-offset zonemissed-runskip (default) or at most one catch-up with run-once; elapsed schedules skip missed ticksoverlapDerived from concurrency; explicit value must match it concurrencyallow, forbid (default), queue, replace; queue coalesces scheduled ticks into at most one pending run
Scheduling rule Contract Availability Running Host with project open, including headless; another window does not duplicate scheduling Interaction No structured inputs, even defaulted, or interactive PTY; automatic agent cohorts have additional constraints Calendar phase First matching selector anchors the recurrence; cadence persists across project close Compatible DST Spring gap moves forward; fall repeat runs once at the earlier occurrence Skip DST Drops both nonexistent and ambiguous local times Shared trust Human trust and automatic-run permission required before scheduled execution
Elapsed and calendar schedules on : schedule : - every : 30m - every : 1d at : "09:00" timezone : America/Chicago - every : 2w weekday : tue at : "09:00" - every : 1mo day : last at : "09:00" missed-run : run-once See the service recipe for setup and the schedule/restart comparison.
Field or action Rule restartno (default) or unless-stoppedEligible plan Exactly one foreground shell run step, including command shorthand Concurrency Must be forbid (default) Interaction No structured inputs or pty: { input: true } Activation Declaring the policy makes it eligible; a manual Run activates it Running service An existing manual run can be adopted without starting a second copy Stop Deactivates lifecycle restart until another manual Run Project load An active policy starts a fresh process through a staggered queue Exit blocking Restart-managed services do not block project/window close by default; block-on-exit: true opts in
Only valid with restart: unless-stopped. See Check that the service is responding .
Field Rule Probe Exactly one of http (absolute HTTP(S) URL), tcp (host:port), or run (shell command) shellOptional shell for a run probe Probe target Static; no expressions. Pass values through automation env intervalElapsed duration, minimum 2s, default 30s timeoutPositive, no greater than interval, default 3s start-periodStartup grace before first probe; none by default failuresConsecutive failures before unhealthy, 1–100, default 3 successesConsecutive successes before healthy, 1–100, default 1 on-unhealthyreport (default) surfaces state; restart also restarts the process
See Review shared work before it runs for the current confirmation UI.
Decision Rule Initial trust Human confirmation before the first shared run, including agent, CLI, and nested requests Recorded identity Local hash of the canonical execution definition; an equivalent command-to-step rewrite preserves it Automatic runs Require trust plus recorded automatic-run permission; the current trust box grants both when the definition declares a schedule or restart policy Editor save Can carry an existing trust record and automatic-run choice to the saved version External change A repository update or external edit that changes the trusted execution definition requires renewed review Approval owner The person using hob; an agent cannot approve it
Field or form Contract surface: urlFirst matching HTTP(S) URL from output, opened in a hob web pane regex, groupExtract a match; default group is first capture, or whole match without captures labelOptional display label valueInterpolated named output, such as ${{ outputs.progress }} search-timeoutFirst-match search window; default 5 minutes updateonce (default) or latest for changing valuesPlacement Top level with command, otherwise the owning foreground run or exec step Output search Bounded recent buffer; completed lines only, including carriage-return progress Updates Default stops after first match; latest continues until process exit, publishing changes only Named outputs Event-driven through HOB_OUTPUT pty: trueLatest terminal line as read-only status pty: { input: true }Also accepts keyboard input; not valid for automatic triggers
surface : regex : '^Progress:\s+(.+)$' group : 1 update : latest Field or rule Contract Declaration artifacts: [{ path: "${{ run.dir }}/review.json", name: review }]Placement Top-level or producing step; paths support interpolation, never secrets Collection Each path must exist and be a regular file; missing files/directories fail the producing step or run Snapshot Exact collected bytes retained after run-local cleanup Limit 256 artifacts across the automation and all steps
Record Contract Lifecycle Queued, Waiting, Running, Stopping; separate from final conclusion Completion Records success/failure and reasons such as Stopped, Replaced, hob closed, Timed out, Interrupted Steps Status, duration, output, transcript slices, and artifacts; Skipped and Not run remain distinguishable Project History Runs appear unless muted for that automation Retention Completed visible history: 90 days and newest 500 top-level runs per automation; active and explicitly trashed runs excluded from automatic retention
