hadron CLI¶
Command surface and stable contracts of the hadron command-line
interface. Installation and sign-in live in
Install the hadron CLI. The CLI also
documents itself: hadron agentic-usage prints the complete agent-facing
contract, and hadron <command> --help covers every flag.
Source: hadron-memory/hadron-cli.
Command surface (v1)¶
hadron auth login | logout | whoami | status | token create|list [--include-hidden]|validate|revoke <id>|delete <id>|hide <id>|unhide <id>
hadron memory ls [--shared-with-me] | get <id-or-urn> | set [<id-or-urn>] [--org <ref> | --owner-me | --app <ref> --agent <ref>] [--class <c>] [--max-rev-count <n>] [--schema <json> | --schema-file <path>] | attach <memory> --app <ref> --agent <ref> | set-active <id-or-urn> | rm <id-or-urn> | clone <id-or-urn> --target-urn hrn:mem:<root>:<slug> | extract (<parentRef> | <loc> -m <memory>) <targetUrn> [--move] | export <id-or-urn> [--out <dir>] | validate <memoryRef> [--check <kind>]… [--limit N] [--fail-on-findings] | encrypt <memory> --data-key - | link-user <memoryRef> --external-user <id> [--data-key -] --yes | transfer <memoryRef> (--org <ref> | --user <ref>) [--class <c>] [--reset-group-members] [--apply | --yes] | approve-all -m <memory> [--yes] | reembed-failed <memoryRef> | usage <memoryRef> | merge <memoryRef> --into <memoryRef> [--field CONTENT|ABSTRACT|DESCRIPTION|TAGS|DATA|PROPERTIES|EDGES]... [--delete-source] --yes | verify <memoryRef> | sync pull <memoryRef> [--yes] | loc-segments --memory <id-or-URN> [--memory <id-or-URN> ...] [--parent <loc>] [--limit <n>] [--after <cursor>] [--json]
hadron memory config get <memoryRef> | config rule add|update <memoryRef> <role> [--author-task <ref>] [--validation-task <ref>] [--description-node <ref>] [--writers all|admin|owner] [--validate-by agent|platform] [--strict-sub-roles[=false]] [--enabled[=false]] | config rule rm <memoryRef> <role> --yes | config rule unlock <memoryRef> <role> [--yes] | config template list [--owner-server | --owner-org <ref> | --owner-me | --owner-app <ref>] | config template get <templateId> | config template create --file <path> (--owner-server | --owner-org <ref> | --owner-me | --owner-app <ref>) | config template update <templateId> --file <path> [--expected-revision <n>] | config template rm <templateId> --yes | config template apply <templateId> <memoryRef> [--dry-run] [--expected-revision <n>] [--yes]
hadron memory member ls <memory> | member add|set-role <memory> --user <id> --role <r> | member rm <memory> --user <id>
hadron memory share ls <memory> | share create|set-role <memory> --grantee <user-ref> --role <r> | share rm|revoke <memory> [--grantee <user-ref>] [--yes]
hadron memory subscription ls <memory> | subscription create|set-role <memory> --org <id> --role <r> | subscription rm <memory> --org <id>
hadron automation ls | approval [<name>] [--depth] | approve [<name>] [--yes] | decline [<name>] [--yes] # all take --app <ref>, else the active App
hadron automation preview <kind> <ref> | re-adopt <kind> <ref> --expected-hash <digest> [--yes] | approval|approve|decline --run <run-id> (in place of <name>)
hadron automation team-snapshot-grant set <app-ref> --trigger-kind SCHEDULE|WEBHOOK --trigger-id <id> [--yes] | revoke <grant-id> [--yes] [--instruction <kind>:<ref>] | list <app-ref> [--include-revoked] [--limit n] [--offset n] [--instruction <kind>:<ref>]
hadron automation grant set <app-ref> --memory <ref> --trigger-kind SCHEDULE|WEBHOOK --trigger-id <id> [--prefix <loc>] [--yes] | revoke <grant-id> [--yes] | list [--app <ref>] [--memory <ref>] [--include-revoked]
hadron access check <user> <resource> # effective access for one (user, resource) pair, with the grants that confer it
hadron node ls [-m <memory>] [--children-of <loc>] | get <node-urn> | add | update <node-urn> | set-properties <urn>|<loc> -m <memory> (--patch <json>|--patch-file <path>) [--reason <text>] | move <node-urn> (--to-urn <urn> | --to-memory <memory>) | clone <node-urn> (--to-urn <urn> | --to-memory <memory>) | merge <node-urn> --into <urn> [--field <f>]… [--delete-source] --yes | rm <node-urn> [--hard] | export <node-urn> [-o <file>] [--format md|json] | import [<file>|- | --url <url>] [-m <memory>] [--loc <loc>] [--as-content] [--with-edges] [--task <ref> [--task-args <json>] [--app <ref>] [--agent <ref>]]
hadron node approve <node-ref> [-m <memory>] [--revision N] [--lint-warnings] [--as-worker] | verify <node-ref> [-m <memory>] | mint -m <memory> [--dry-run] [--yes] | sign <node-ref> [-m <memory>] [--revision N] [--signer <user-id>] | signatures <node-ref> [-m <memory>] [--check]
hadron node signing-request get <request-id> | signing-request list <node-ref> [-m <memory>] [--state open|completed|declined|expired|stale|withdrawn] [--limit 1-100] | signing-request withdraw <request-id>
hadron node recovery list -m <memory> [--limit 1-200] [--offset N | --all] | recovery get <node-ref> [-m <memory>] [--content] | recovery graph -m <memory> [--edge <id>]… [--limit 1-200] [--offset N | --all] | restore <node-ref> [-m <memory>] [--lint-warnings] | edge-removals <node-ref> [-m <memory>] [--limit N]
hadron node next <parent> [--after <current>] [-m <memory>] [--raw] | open <node-ref> [-m <memory>] [--print]
hadron node revision list <node-ref> [-m <memory>] [--limit N] | revision get <revision-id> | revision restore <revision-id> [--truncate [--yes]] | revision label <revision-id> --label <text> | revision delete <revision-id> [--yes] | revision clear <node-ref> [-m <memory>] [--yes]
hadron edge ls <node-urn> | get <edge-id>|<edge-urn> | add | update <edge-id> | rm <edge-id>
hadron object create -m <memory> --type <t> (--fields '<json>' | --fields-file <path>) [--key <seg>] [--name <n>] | get <ref> | update <ref> (--fields '<json>' | --fields-file <path>) [--reason <text>] | find -m <memory> --type <t> [--match '<json>'] [--where '<json>'] [--sort '<json>'] [--limit N] [--offset N] | delete <ref> [--hard] [--yes]
hadron asset ls -m <memory> [--mine] [--mime <type>] [--include-deleted] [--limit N] [--offset N] | get <asset-ref> [-o <path>|-] [--force] | url <asset-ref> [-m <memory>] | public-link <asset-ref> (--on | --off) [--yes] | upload <file> -m <memory> [--mime <t>] [--name <n>] [--description <d>] | rm <asset-ref> [--yes] | restore <asset-ref> | link <asset-ref> --node <new-node-urn> [--name <n>] [--description <d>]
hadron search <query> [-m <memory>]… [--scope <name|id|app|global>] [--mode hybrid|keyword|vector|regex] [--prefix <loc>] [--type <t>] [--tag <t>]… [--limit N] [--offset N] [-l]
hadron scope list [--owner-org <ref> | --owner-app <ref> | --owner-agent <ref>] [--name <n>] | get <name|id> [--by-name] | create <name> (--owner-org|--owner-app|--owner-agent <ref>) -m <memory>… [--description <d>] | update <name|id> [--by-name] [--name <new>] [-m <memory>…] [--description <d>] | rm <name|id> [--by-name] [--yes] | explain <name|id> [--by-name] [--loc <address>] | set-active|use <name|id|app|global> [--no-verify]
hadron replace text <old> <new> --field <f>… (--node <node-urn> | -m <memory>)… [--prefix <loc>] [--regex] [--ignore-case] [--max-nodes N] [--reason <text>] [--dry-run] [--yes]
hadron task run (<node-urn> | <loc> -m <memory>) [--arg k=v]… [--app <ref> [--as-self] [--agent <ref>]]
hadron skill lint (-m <memory>... | --all | --node <ref>...) [--strict] [--json] | status (-m <memory>... | --all) [--host <host>] [--to user|project|plugin|<dir>] [--strict] [--json] | export [--dry-run] [--force] [--prune] [--json] | plugin --out <dir> [--name <name>] [--scope <name|id>] [--zip] [--dry-run] [--json]
hadron chat read [--since <seq>] [--node <urn> | -m <memory> --messages-loc <prefix>] | post (--body <text|-> | --body-file <path>) [--node <urn>] [--handle <h>] [--identity <i>] [--role <r>] [--reply-to <loc>] | config show [--node <urn> | -m <memory> --messages-loc <prefix>] | doctor [--node <urn> | -m <memory> --messages-loc <prefix>] | config set (--node <urn> | -m <memory> and/or --messages-loc <prefix>)
hadron channel list [--owner-app <ref>] [-m <memory>] | get <id|address> | create <name> -m <memory> --loc <loc> [--description <d>] | update <id|address> [--name <n>] [--description <d>] | rm <id|address> [--yes] | read <id|address> [--since <seq>] [--before <seq>] [--limit N] [--offset N] [--mentions <ref>] | post <id|address> <body|-> (--session <id> | --as-me) [--reply-to <seq>] | mark-read <id|address> --attendee <ref> --seq N [--owner-app <ref>] | read-state <id|address> --attendee <ref> [--owner-app <ref>] | register list [--channel <ref>] [--attendee <ref>] [--owner <ref>] [--org <id>] [--limit N] [--offset N] | register add --channel <ref> --owner <ref> (--attendee <ref> | --all-attendees) [--role both|post|watch] [--mention-only] [--description <d>] | register set <entry-id> (--role <r> | --mention-only[=false] | --description <d>)... | register rm <entry-id> [--yes] | search <id|address> <query> [--limit <n>] [--cursor <c>]
hadron team init [--app <ref> | -m <team-memory>] (uses --app, the context, or the binding)
hadron team worker cast --name <n> (--role <role> | --agent <ref>) [--dry-run] [--instruction <kind>:<ref>] (uses --app) | ls [--include-retired] (uses --app or the binding) | get <name-or-id> | terminal-title <name-or-id> [--json] | change-agent <name|id|URN> --agent <id|URN> [--instruction <kind>:<ref>] [--yes] | update <name-or-id> [--signature <text>] [--trailer <text>] | set-boot-prompt <worker> (<node-ref> [-m <memory>] | --clear) | approve [--only <a,b>] [--apply] [--as-worker] [--json] | set-reports-to <worker> (<target> | --clear) | onboard --name <worker> --host <id> --repo <token> --branch <branch> --label <label> --family <family> --worktrees-root <absolute-path> --config <router.json> [--base main] [--display-name <text>] [--coordinator] [--apply] [--as-person] [--timeout 2m] | release <name-or-id> [--yes] | retire <name-or-id> --yes [--instruction <kind>:<ref>] | rm <name-or-id> --yes --confirm-no-external-attribution [--instruction <kind>:<ref>]
hadron team role ls [--team-agent <ref>] (uses --app or the binding) | get <role> [--team-agent <ref>] | create <role> [--description <d>] [--team-agent <ref>] | update <role> --description <d> | rm <role> [--yes]
hadron team grant list [--limit N] [--offset N] | get <id> | request --action <name> --values <json|@file> --reason <text> [--holder worker|agent] [--holder-id <id>] [--starts-at <time>] [--expires-at <time>] [--max-uses <n>] | request-signature <grant-id> | signing-request get <request-id> | withdraw <request-id> (a bound worker session; exist only where signing is on)
hadron team session work-items --worker <ref> [--limit N] [--offset N] | start --as <worker> [-m <team-memory>] [--repo <r>] [--branch <b>] [--transcript <path>] [--host <h>] [--tool <t>] [--model <m>] [--force] | start [--session <id>] [--tool <t>] (no worker named: resume) | resume-claim [--session <id>] | whoami | log (--pr | --issue | --commit | --branch) <ref> [--action <a>] [--detail <json>] [-m <team-memory>] | sync-model [--hook] | set-model [<model>] [--family <token>] | shed [--auto] [--print-prompt] [--offline] [--cooldown <d>] [--transcript <path>] | end [--handoff <text> | --handoff-file <path>] [--summary <text>] [--session <id>] [--resume-claim] | list [--active] [--as <worker>] [--repo <r>] [--limit N] [--offset N] | list (--pr | --issue | --commit | --branch) <ref> [-m <team-memory>]
hadron team chat post <body|-> [--reply-to <seq>] [--as-me] (uses --app or the binding) | read [--since <seq>] [--before <seq>] [--limit <n>] [--all] [--mentions-me | --mentions <ref>] (uses --app or the binding) | search <query> [--limit <n>] [--cursor <c>] (uses --app or the binding) | mark-read --through <seq> [--channel <ref>] | inbox [--after <endCursor> | --ack-file <path|->] | check (all three need the binding)
hadron team attention [--since <token>] | attention switchover preview | apply --proof <proof> [--yes] (uses --app or the binding)
hadron team router poll [--config <path>] (your login; never a worker session)
hadron team wakes due [--worker <ref>]… [--first N] [--after <cursor>] [--accept-stop] | ack <proof>… (as you, never a worker session)
hadron team wake-settings get --worker <id-or-URN> | set --worker <id-or-URN> [--mentions immediate|off] [--paused-until <RFC3339>] [--clear-pause]
hadron team delivery-settings get | set [--check-period-seconds N] [--failed-checks-to-overdue N] [--dark-alarm-window-seconds N] [--batch-window-seconds N] [--busy-delay-seconds N] [--stuck-window-seconds N] (uses --app or the binding)
hadron team roster | events [--since <t>] [--after <id>] [--alarms] [--task <id>] [--type <t>]… | alarm ack <eventId> (uses --app or the binding)
hadron team availability get | set (--worker <ref> | --family <token>) --state available|unavailable [--reason <r>] [--until <t>] (uses --app or the binding)
hadron team task create <title> [--assignee <party>] [--owner <party>] [--parent <id>] [--project] [--status backlog|pending] […] | assign|reassign <taskId> --assignee <party> | update <task> […] | start|progress|cancel|park|ready <taskId> | finish <taskId> --outcome <word> [--summary <s>] [--evidence <url>] [--findings-file <path|->] | findings <task> [--limit N] [--offset N] | hand-back <taskRef> --code missing-input|cannot-do|refused|out-of-scope|duplicate [--text <t>] | find-untracked --integration <name> | get <taskId> | list […] | mine [--limit N] [--offset N] | tree <rootTaskId> (uses --app or the binding)
hadron team pr schedule <build-task> --slot <id> [--slot <id>…] | freeze <build-task> <sha> | seat <seat-task> --slot <id> --head <sha> [--supersedes <task>] | verdict <seat-task> --head <sha> --verdict <v> [--node <ref>] [--receipt <url>] | ready <build-task> --head <sha> | readiness <build-task> --head <sha> [--json]
hadron team stall-schedule get | set [--assignment-minutes N|default] [--not-started-minutes N|default] [--no-progress-minutes N|default] [--owner-reaction-minutes N|default] [--host-lapse-check-ins N|default] (uses --app or the binding)
hadron team host list | ops [--host <id>] [--status <s>] [--worker <ref>] [--limit N] [--after <cursor>] | issue <type> --host <id> --worker <ref> [--arg k=v]… [--as-person] (uses --app or the binding) | run --config <host.yaml> [--once] | status --config <host.yaml> | report-stops --config <host.yaml> (--reporter-worker <name> | --dry-run [--stale-after 10m])
hadron team composition (uses --app or the binding)
hadron team push <worker> (--text <message> | --message-file <path>) [--seq N] [--wait-timeout 120s] [--draft-wait 30s] [--draft-stable-for 30s] [--confirm-timeout 10s] [--poll-interval 250ms]
hadron team stop list [--worker <ref>] [--include-ended] | set --scope worker|team|host --level pause-dispatch|pause|halt [--worker <ref> | --host <id>] [--until <RFC3339>] | lift <signal-id> (uses --app or the binding)
hadron team pause | resume [--app <app>] # App-manager setting; regular wakes are held while paused; resuming an unpaused team stamps nothing
hadron team health sweep --config <host.yaml> | install --config <host.yaml> --interval <Nm> [--bin <abs hadron>] | uninstall | status
hadron team usage collect --config <usage.yaml> [-m <memory>] | show [--config <usage.yaml> | -m <memory>] [--limit 1-200] | install --config <usage.yaml> --interval <Nm> [--bin <abs hadron>] | uninstall | status | accounts [--json] | project [--account <label> [--host h] [--family f]] [--add-workers N | --move-worker <worker> --to-account <label> [--to-host h] [--to-family f]] [--json]
hadron team router loop [--interval 60s] [--config <path>] | status [--config <path>]
hadron app key scope grant <key-id> <scope> [--host-id <host>]
hadron app key list <app-ref> [--scopes [--host-uses <n>]] [--instruction <kind>:<ref>] | key revoke <key-id> [--yes] [--instruction <kind>:<ref>]
hadron app memory-grant list <app-ref> [--instruction <kind>:<ref>] | memory-grant rm <grant-id> [--yes] [--instruction <kind>:<ref>]
hadron spec ls [-m <memory>] | get <citation>|--prefix <p> | describe | use [<memory>] | register [--check] | find <query> [--match-exactly] | grep <pattern> [--regex] [-i] [--field content|abstract] [--prefix <loc>] | replace <pattern> <replacement> [--regex] [--word-boundary=false] [--dry-run] [--yes] [--max-specs N] | new … | edit <citation> | extract <citation> --to-feature <fff> | link <from> <to> | lint [<citation>] | check-tools [--prefix <loc>] | citations [--src <path>]… [--exclude <glob>]… [--loose] [--stale-abstracts] [--strict] | supersede <citation> | import spec-kit|code | label-report [-m <memory>] [--prefix <loc>] | reserve <citation> [--name <n>] | renumber <from-citation> <to-citation> [--dry-run] | backlinks <citation> | unresolved | mint [--dry-run] [--yes] | ledger [-m <memory>] [--registry <file>] | rescind <citation> --reason <text> (--summary <text|-> | --summary-file <path>) [--withdrawn] [--yes] [--dry-run] | document <citation> [-m <memory>] [-o <file>]
hadron coding review run [-m <memory>] [--base <ref>] [--head <ref>] [--diff <path|->] [--root <loc>] [--all] [--limit N] [--offset N] | review list -m <memory> [--root <loc>] [--broken] | review create <check-name> -m <memory> --trigger <cond> --description <d> [--scope <s>] [--tag <t>]… [--link <ref>[=<label>]]… [--seq N] [--content <text|-> | --content-file <path>] | review lint -m <memory> [--root <loc>] [--toolchain <t>|-] [--strict] [--suggest] [--fix [--yes]] | preflight list -m <memory> [--root <loc>] [--broken] | preflight create <loc> -m <memory> --route <action> --description <d> [--name <n>] [--symptom <s>] [--section <heading>] [--type <t>] [--tag <t>]… [--link <ref>[=<label>]]… [--seq N] [--content <text|-> | --content-file <path>] [--no-back-edge] [--no-body-line] [--dry-run] | preflight route <node-ref> -m <memory> --route <action> [--description <d>] [--symptom <s>] [--section <heading>] [--no-back-edge] [--no-body-line] [--dry-run] | preflight lint -m <memory> [--root <loc>] [--strict]
hadron agent ls [--org <id>] [--type ASSISTANT|CHATBOT] [--visibility ORGANIZATION|PERSONAL|PUBLIC] | ls --public [--type <t>] [--limit N] [--offset N] | get <ref> | create --org <id> --name <n> [<field flags>] | update <id> [<field flags>] | rm <id> --yes | set-base <agent> (<base> | --clear) | set-boot-prompt <agent> (<node-ref> [-m <memory>] | --clear) | tasks list <agentRef> | processes list <agentRef> | compile <agent> [--no-set-pointer] [--as-worker] | clone <source> --to <org> [--name <n>] [--slug <s>] | memory add <agent> <memory> [--role <r>] | memory set-role <agent> <memory> --role <r> | memory rm <agent> <memory> --yes | revision create <agent> [--description <t>] | lock acquire <agent> | lock release <agent> | model-group list <agent> | model-group set <agent> <name> [--pattern <glob>]… | model-group delete <agent> <name> [--yes] | boot-prompt <agent> [--app <app>] [--model <m>] [--json]
hadron agent ticker-templates list <agent-ref> | create <agent-ref> --name <n> --cadence-seconds <s> [--relevance all|mentions] [--reasons read-team-channel,every-tick,live-check] [--quiet-hours <json>] | update <template-id> --expected-revision <n> [--name <n>] [--cadence-seconds <s>] [--relevance all|mentions] [--reasons <csv>] [--quiet-hours <json> | --clear-quiet-hours] | delete <template-id> --expected-revision <n> [--yes] # singular alias ticker-template; Agent managers write, future casts only, existing workers and tickers untouched
hadron run trigger --app <ref> --entry <node-urn> [--arg k=v]… [--as-self] [--agent <ref>] [--ai-config <name>] [--budget-tokens <n>] [--budget-actions <n>] [--wait [--wait-timeout <dur>]] | get <id> | list [--app <ref> | --org <ref>] [--status <s>] | cancel <id> [--yes]
hadron schedule preview --app <ref> --entry <node-urn> (--cron '<expr>' | --run-at <RFC3339>) [--tz <zone>] [--agent <ref>] [--as-self] [--ai-config <n>] [--arg k=v]... [--disabled] [--budget-tokens N] [--budget-actions N] [--json]
hadron schedule create --app <ref> --name <n> --cron '<expr>' --entry <node-urn> [--tz <IANA>] [--arg k=v]… [--as-self] [--policy <json>] [--budget-tokens <n>] [--budget-actions <n>] [--disabled] | list [--app <ref>] | update <id> [--cron …] [--entry …] [--enabled=false] [--budget-tokens <n>|--clear-budget-tokens] [--budget-actions <n>|--clear-budget-actions] | rm <id> [--yes]
hadron webhook create --app <ref> --name <n> --entry <node-urn> [--args-schema <json>] [--as-self] [--policy <json>] [--budget-tokens <n>] [--budget-actions <n>] [--disabled] | list [--app <ref>] | rm <id> [--yes] | rotate <id> [--yes]
hadron ticket mint --org <ref> --action comm.outbound --count <n> [--app <id>] [--note <text>] [--expires <iso8601>] | list --org <ref>
hadron grant create --org <ref> --user <ref> --action <a>[,…] [--expires <iso8601>] | ls [--org <ref>] [--user <ref>] | get <id> | revoke <id> --yes
hadron app ls --org <org> | install (--org <id> | --owner-me) --agent <ref> --name <n> [--type <t>] [--urn <slug>] [--description <d>] | uninstall <app-ref> [--yes] | reinstall <app-ref> | delete|rm <app-ref> [--yes] | set-active|use <app-ref> | get <app-ref> | update <app-ref> [--name <n>] [--description <d> | --clear-description] [--session-timeout-seconds <n>] [--yes] | memories [<app-ref>] [--limit N] [--offset N] | member list | member add --user <ref> --role <role> [--yes] [--instruction <kind>:<ref>] | member remove --user <ref> [--yes] [--instruction <kind>:<ref>] | member roles | key create <app-ref> --out <file> [--label <t>] [--force] [--print-key] | key rotate <app-ref> --out <file> [--yes] [--force] [--print-key] | join <app-ref> | leave <app-ref> [--yes] [--instruction <kind>:<ref>] | model-group list <app-ref> | model-group set <app-ref> <name> [--pattern <glob>]… | model-group clear <app-ref> <name> [--yes] | user create --external-id <id> [--handle <h>] [--name <n>] | nodes <app-ref> [--prefix <loc>] [--type <type>] [--types <type,...>] [--object-type <collection>] [--tag <tag>] [--runnable[=false]] [--created-by <user-id>] [--role <family>] [--updated-after <RFC3339>] [--updated-before <RFC3339>] [--include-deleted] [--limit N] [--offset N] | chatbot-ai-config get|list|clear <app-ref> [--json] | chatbot-ai-config set <app-ref> <name-or-id> [--json]
hadron app action record <code> [--task <task>] [--payload <json> | --payload-file <path>] [--json]
hadron app agent ls [<app-ref>] (uses --app) | agent add <app> <agent> [--training-mode] | agent rm <app> <agent> --yes | agent set-boot-prompt <app> <agent> (<node-ref> [-m <memory>] | --clear) | agent customize <app> <agent> | agent compile <app> <agent> [--as-worker] | key scope revoke <key-id> <scope> [--instruction <kind>:<ref>]
hadron ai-config ls [--app <id-or-urn>] [--agent <id-or-urn>] | create ((--app|--agent|--org <id-or-urn>) --name <n> --provider <p> --model <m> [--api-key -] | --file <path>) | get <id> | endpoints <provider> | update <id> … | rm <id> | test <id> [--override-file <path|->] [--json]
hadron mcp-server ls [--org <ref>] | get <id> | tools <id> | create --org <ref> --slug <s> --name <n> --url <u> [--header 'Name: value']… [--allow <tool>]… [--disabled] | update <id> [--name <n>] [--url <u>] [--header …]… [--clear-headers] [--allow <tool>]… [--clear-allow] [--enabled|--disabled] | rm <id> --yes
hadron connection grant create --connection <ref> --app <ref> --scopes <s>[,…] [--expires-at <iso>] | grant ls [--connection <ref>] | grant get <grant-id> | grant revoke <grant-id> --yes
hadron connection connect <ms-exchange|gmail|google-cal|google-drive> --org <id|urn> [--no-browser] [--wait <duration>|--no-wait] [--json]
hadron connection flow <flow-id> [--json]
hadron secret create --name <n> --scope user|org|app|memory [--owner <ref>] --kind generic|webfetch-auth [--value-file -|@file] | ls --scope <s> [--owner <ref>] | get <id|urn> | update <id|urn> [--value-file -|@file] [--meta k=v...|--meta-json <obj>] [--type bearer|basic|header [--username <u>|--header-name <h>]] [--url-prefix <u>] | rm <id> --yes
hadron org list [--mine] | create --name <n> --urn <urn> | get <id> | public <org-ref> | update <id> | rm <id> | member ls <org-id> | member add|set-role <org-id> --user <id> --role <r> | member rm <org-id> --user <id> | invite create <email> --org <id> --role <r> | invite accept <slug> | invite show <slug> | set-active|use <orgRef> [--no-verify] | resend-sender create --org <ref> --from <identity> [--api-key-file <path|->] [--enabled=false] | resend-sender get <sender-id> | resend-sender list [--org-id <raw-id>] [--limit N] [--offset N] | resend-sender update <sender-id> [--from <identity>] [--api-key-file <path|->] [--enabled=false] | resend-sender rm <sender-id> --yes
hadron user invite [--email <email>] [--github-username <name>] [--name <display-name>] [--expires-in-days N] [--max-activations N] # platform invitation, not org membership; no email sent; deliver the returned acceptance slug privately
hadron user search [query] [--limit N] [--offset N] | set-roles <userRef> --role <r>… --yes | merge <source> --into <target> --yes | delete [--user <ref>] [--reason <text>] --yes
hadron decision log create <memory> --loc <loc> --decider <user-id>... [--eligible <user-id>...] [--name <n>] [--prefix <p>] | log get <log> | log set-deciders <log> --decider <user-id>... [--eligible <user-id>...] --expected-revision <n> --reason <text> | ask <log> --input-file <path|-> [--title <t>] [--context <c>] [--tier APPROVED|SIGNED] [--urgency NORMAL|URGENT] | get <decision> | get <code> --log <log> | list (--log <log> | --awaiting-me) [--state <s>...] [--tier <t>] [--urgency <u>...] [--authorizes[=false]] [--sort CODE|PORTAL_DEFAULT] [--limit N] [--offset N] | amend <decision> --expected-revision <n> --reason <text> [--input-file <path|->] [--title <t>] [--context <c>] [--tier <t>] [--urgency <u>] | withdraw <decision> --expected-revision <n> --reason <text> [--yes] | verify <decision> | purge <decision> --reason <text> [--yes]
hadron admin impersonation list [--org <org>] [--active] [--limit N] [--offset N] | get <id> # audit reads only; start/stop is `auth impersonate`; the server decides who may read: org ADMIN/OWNER for that org, platform admin for any, else refusal (exit 8)
hadron policy explain --action <a> --app <ref> [--user <ref>] | set --mine (<json> | @file | --clear)
hadron quota list --org <ref> [--app <ref>] | set --org <ref> [--app <ref>] --action <a> --limit <n> # org ADMIN
hadron slack status [--org <id|urn>] [--limit 0..200] [--offset N] | get <connection-id> # read-only Slack workspace connections; status is a recorded value, not a health check: ACTIVE = registered, not proof it works; ERROR = recorded as failed, reason not shown; get on an invisible id exits 4; --app and the saved org do not apply
hadron profile set [--name <n>] [--handle <h>] # --email is accepted and refused
hadron config get | set | list
hadron api <query-or-mutation> # raw GraphQL escape hatch
hadron server-info # the server's version + capability surface
hadron ticker list | get <id-or-URN> | create --name <n> --cadence-seconds <n> [--reasons read-team-channel,every-tick,live-check] | update <id-or-URN> [--reasons <list>] | delete <id-or-URN> --yes | subscribe <id-or-URN> --worker <id-or-URN> | unsubscribe <id-or-URN> --worker <id-or-URN> | apply-templates --worker <id-or-URN>
hadron usage events [--memory <ref>] [--loc <loc>] [--type <t>] [--since <time>] [--until <time>] [--limit 1-200] [--offset N] | activity [--from <iso>] [--to <iso>] [--bucket DAY|WEEK|MONTH] [--memory <ref>]... [--time-zone <IANA-zone>] | record --type <type> [--node-loc <loc>] [--session <id>] [--model <name>] [--tokens-in N] [--tokens-out N] [--action-args <json>] # events and activity read; record writes one usage event, sent once
hadron billing prices [--provider <p>] [--model <m>] [--tier <n>] [--limit N] [--offset N] | balance <org> | ledger <org> [--limit N] [--offset N]
hadron billing prices get <id> | prices set --provider <p> --model <m> --input <n> --output <n> [--tier 1-3] [--markup-bp N] [--effective-at <t>] [--yes] | grant <org> --amount <n> [--source-type <t> --source-id <i>] [--expires-at <t>] [--note <s>] [--yes] # prices set and grant are platform-admin writes; <org> is an ID or hrn:org:<slug>
hadron email connections --org <ref> # lists an org's connected email, calendar and Drive accounts; needs org admin
hadron calendar list --connection <id> | events --connection <id> [--calendar <id>] [--from <t>] [--to <t>] [--query <text>] [--top 1..100] | event get <eventId> --connection <id> [--calendar <id>] | event create --connection <ref> --title <t> --from <t> --to <t> [--all-day] [--tz <iana>] [--attendee <email>]... [--description <t>] [--location <t>] [--calendar <id>] [--no-notify] [--idempotency-key <k>] | event update <event-id> --connection <ref> [same flags, all optional] [--clear-attendees] | event delete <event-id> --connection <ref> --yes | event respond <event-id> --connection <ref> --response accepted|declined|tentative | freebusy --connection <id> --from <t> --to <t> [--schedule <id>]...
hadron drive list --connection <id> [--folder <id>] [--query <text>] [--name-contains <text>] [--mime-type <t>] [--modified-after <t>] [--top 1..100] [--page-token <token>] | get <fileId> --connection <id> | export <fileId> --connection <id> [--format MARKDOWN|TEXT|HTML] # READ only
hadron web-poll list --org <ref> | cancel <job-id> --org <ref> --yes
hadron ha list [--org <ref>] [--limit 1..200] [--offset N] | get <id> | ops <id>
hadron ha create --org <ref> --slug <s> --name <n> --url <u> [--token-file -|@path|path] [--allow-op <op>]... [--disabled] | update <id> [--name] [--url] [--token-file ...] [--allow-op <op>]... | [--clear-allow-ops] [--enabled|--disabled] | rm <id> [--yes] # create is org ADMIN/OWNER; the token is never an argv flag
hadron orca host plan --roster-file <path> [--json] # read-only snapshot of a roster file; no apply, launch, terminal input or session binding
hadron orca terminal status (<worker|terminal-id> | --all) # host-local: needs Orca on THIS host (exit 10 off-host); never types into a terminal
hadron version
hadron completion <shell>
hadron agentic-usage # prints the agent contract
profile set changes your name and handle. Changing your email address is not
supported here: --email is still accepted, so scripts that pass it fail loudly,
but it is refused locally with exit 2 and the message "Changing your email
address is not supported here." before any request is sent. That includes
--email "", since clearing an address is a change too. Passing only --name
and --handle works as before.
Global flags¶
| Flag | Effect |
|---|---|
--json |
Machine-readable output on stdout; progress and errors on stderr (see --json on the failure path). Field names are stable: new fields may be added, existing ones are never renamed or removed without a major version bump. |
--server <url> |
Hadron server base URL for this invocation (default https://srv.hadronmemory.com; persist with hadron config set server). |
--app <ref> |
App context for this invocation: hrn:app:<root>:<slug>, the <root>:<slug> short form, or an App id. Persist a default with hadron app set-active <ref> (alias use), which checks the value's shape — not that the App exists — stores it in canonical form, and clears with "". Most calls need none; a scope name and search --scope app do. |
With --json, errors are emitted on stderr as
{"error":{"code":<exit-code>,"message":"..."}} — with one exception, and a
consequence for stdout that scripts need to know about; both are covered under
--json on the failure path.
Memory references¶
Memory arguments accept a memory ID, hrn:mem:<root>:<slug>, the
<root>:<slug> / <root>::<slug> short forms, and the legacy hrn:memory:
prefix. A malformed memory reference is rejected locally with exit 2. A
well-formed reference that cannot be found returns exit 4 from commands that
look the memory up (memory get, spec get); spec list currently prints an
empty list and exits 0 instead. The CLI checks
that a memory URN is fully qualified, so hrn:mem:foo is malformed.
Exit codes (stable contract)¶
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | generic failure |
| 2 | usage error (bad flags/arguments, missing --yes) |
| 3 | authentication required or rejected |
| 4 | not found (or not visible to this principal) |
| 5 | conflict or validation failure (e.g. duplicate install; spec lint / spec check-tools / register --check findings; a suspected stale team chat read page) |
| 6 | cancelled / timed out waiting for the user |
| 7 | unavailable: the request never got an answer (gateway 5xx, reset, timeout) |
| 8 | forbidden: you are signed in, but not permitted to do this |
Scripts and agents should branch on exit codes, not parse error text.
--json on the failure path¶
Branching on the exit code matters more than it looks, because --json does
not guarantee that stdout holds JSON when a command fails.
| Situation | Exit | stdout | stderr |
|---|---|---|---|
| Success | 0 | JSON payload | progress / notes, if the command emits any |
A single-entity read fails (node get <missing>, memory get <missing>, spec get <missing>) |
4 | empty | {"error":{...}} |
Bad input (node get 'not-a-urn') |
2 | empty | {"error":{...}} |
| Server or transport failure (the server is down, a gateway returns 5xx) | 1 | empty | {"error":{...}} |
A batched read has some unavailable refs (node get <a> <b> …) |
4 | JSON payload, with the misses listed under unavailable |
progress / notes, if any |
| A list read finds nothing, including in a memory that doesn't exist or isn't visible | 0 | [] |
progress / notes, if any |
An unknown flag (--nosuchflag) |
2 | empty | plain text, not JSON |
Four practical consequences:
- Parse the exit code before parsing stdout. A script that pipes stdout straight into a JSON parser will fail with a decode error at character 0 — which looks like corrupt data rather than the actual cause. The real message is on stderr.
- A non-zero exit does not always mean stdout is empty. Batched reads
deliberately return their payload and a non-zero code, so partial results
are still usable: read
unavailableto see which refs missed. - An empty list is not an error. Listing a memory that does not exist — or
that the caller cannot see — returns
[]and exit 0, deliberately, so the CLI never reveals whether a resource exists. Do not treat[]as a failure, and do not infer existence from it. - Output on stderr is not a failure signal. Successful commands write
progress and diagnostics there too — the affected-node count printed before a
replace text --yeswrite, or the notesearchemits when it degrades to keyword mode on a memory with no vector index, or the messages-waiting line it can print. A script that treats "stderr is non-empty" as "it failed" will misread a normal run. Use the exit code.
Unknown-flag errors are the one case that ignores --json entirely: flag
parsing fails before --json is bound, so the message is plain text. Handle
exit 2 without assuming the stream is parseable.
Partial writes exit non-zero¶
A command that writes its primary entity but can't complete a secondary
step reports the partial success on stdout and exits 1 — it never
prints a clean success on a half-finished write. This covers the
edge-wiring commands: node import --with-edges, spec new,
spec extract, and spec supersede. The node (or spec) is written and the
unwireable edges are reported (unwiredEdges in --json, each with a
reason), but the non-zero exit tells a script the graph isn't fully
connected. spec supersede --json additionally reports each edge's
status (created / failed / skipped). Re-run once the missing
endpoints exist — edge wiring is idempotent.
memory set --slug on create has the same shape for a different reason: since
createMemory can't set the slug, a custom slug is applied by a follow-up
rename, and a failed rename leaves the memory under its name-derived slug. The
memory is reported and the command exits non-zero — re-run
memory set <urn> --slug <slug>.
Reference conventions¶
- Memory references are
org:memoryURNs (e.g.acme.com:kb, or the flatacme.com:kbform) or IDs — every command that takes an ID also accepts the URN. - Node references are fully-qualified URNs, flat and single-colon:
hrn:node:<root>:<memory>:<loc>(e.g.hrn:node:acme.com:kb:findings:flaky-ci). Keep thehrn:node:prefix (legacyurn:node:and the v1::form are also accepted). The prefix is what makes the reference unambiguous: the loc keeps its own colons (findings:flaky-ci), so without the type word there is no way to tell where the memory slug ends and the loc begins — a bare flat node ref is rejected for that reason. A bare loc is accepted only when you also pass-m <org:memory>(the flag fixes the arity, so bare is fine there); without-m, a bare loc is rejected with exit 2, since the same loc can exist in several memories. See URN composition. - Edges are directed, first-class entities: each carries an optional
name(the relationship) and alocthat is its identity (hrn:edge:<org>:<memory>:<loc>).edge add --from <node> --to <node>creates an edge (optionally--name <relationship>,--loc,--description, or--runnable);edge update/edge rmaddress it by its edge ID (shown byedge lsand innode get --json). A nameless edge prints its loc. Cross-memory edges are allowed. -
Portal links are server-built — copy them rather than assembling one. As of v0.12.0, three commands print the portal link as a
URL:line directly underurn::node get(single-ref and batched),team worker get, andteam session start's bind receipt. Those three, and not "anything that prints a URN" —worker lscarries aURNcolumn and noURLcolumn.Copy that line when citing a node or signing as a worker. A link you assemble is not inherently wrong, but you would have to be right about two things the platform holds and you may not: the portal origin, which is deployment configuration, and the exact URN, which has to be one the resolver knows. A legacy
::URN you genuinely copied still resolves — legacy forms stay valid input — but one you reconstructed from memory may not. Either mistake breaks for whoever clicks the link rather than for you, which is why the server builds it, and why this reference deliberately does not give you the route to reassemble (cor:api:230:01).A missing link always renders as nothing: no line, no placeholder, and never a locally-composed fallback. But why it can be missing differs by entity, and so does what survives it:
entity the link is null when is the urn:line still there?node the deployment configures no portal origin ( FRONTEND_URL)yes — Node.urnis non-null, so the line always printsworker that, or the App's URN predates the flat grammar-v2 arity only in the first case — the link is built from the same URN, so the second takes both Under
--jsonthe two differ again, and a consumer has to handle both: the node DTO carriesportalUrlomitempty, so the key is absent when there is no link; the worker DTO carries it as a presentnull— an explicit "no link", which per the table above does not tell you which of the two causes applies, and so is not a reading of the deployment's portal configuration. -
Null/omitted flags mean "unset" — update commands only change the fields you pass.
Write semantics¶
memory setcreates when called without a positional argument (requires--organd--name) and updates when given one. On create, the URN slug is derived from--name(kebab-cased, e.g."Project KB"→project-kb) unless you pass--slug <bare-slug>to set it explicitly (so a display name and slug can differ in one command); the output echoes the resulting URN and the server-assignedclassandvisibilityso you can confirm the effective values (an unset--classdefaults toknowledge; an unset--visibilitytakes the server default). Because create has no slug input server-side, a custom--slugon create is a create plus a rename: if that rename fails the memory still exists under its name-derived slug and the command exits non-zero (a partial write) naming the retry. On update,--slugrenames the memory, changing its URN and the URNs of every node and edge under it (their ids are stable, so links survive).- Three ways to create a memory.
memory setpicks one by which owner flags you pass:- Free-standing, org-owned —
--org <ref> --name <n>(the default described above;--classdefaults toknowledge). - User-owned —
--owner-me --name <n>creates a memory with no org, owned by you in your own handle namespace, so its URN roots on your handle (hrn:mem:<handle>:<slug>). Owner-only:--class personal|private(defaults topersonal);knowledge/groupstill require--org. The server derives the handle and bare URN — never construct it client-side. - App-scoped —
--app <ref> --agent <ref> --class app|personal|private --name <n>. Both refs accept an ID or a URN, and the Agent must be installed in the App. App-scoped create rejects--slug: App-class URNs are name-derived by the server, while personal/private URNs use a per-owner opaque id.
- Free-standing, org-owned —
memory attach <memory> --app <ref> --agent <ref>binds an existing free-standingpersonal/privatememory to that App and installed Agent. The memory must be caller-owned, and it keeps its URN, class, and owner — attaching re-scopes access, it doesn't re-address the memory. Typed server errors distinguish already-scoped, cross-org, membership, and install failures.node add|update|get|ls --install <app>/<agent>targets the App's install memory for that Agent instead of--memory. Both refs are ids or fully-qualified URNs, and--installexcludes--memory, even an explicitly empty one.getandupdatetake a bare loc, not a node id or URN. The firstnode addsends the install selector, so the server creates the install memory in that write's transaction; a refused write creates nothing.updatereads the memory without creating it, and--data-merge/--data-merge-fileare refused before any request with--install(use--data/--data-file, which keep the selector). Forget,lsandupdate, an unavailable install memory exits 4 before any node query or write and never turns into an unscoped list (the firstaddinstead creates it). Being able to read the memory's metadata is not permission to read its nodes or write to it: the server keeps those checks. There is no retry and no client-side memory creation. See Customize an installed Agent.app agent customize <app> <agent>only reads the install-memory record and creates nothing.--jsonis{ "memory": { "id", "urn", "name" } }or{ "memory": null };nullmeans unavailable (not created yet, missing, or not shown to you), never a claim that none exists.node addfails if the loc already exists;node updatepreserves unset fields. Content comes from--content "<text>",--content -(stdin), or--content-file <path>.- The
databag — replace vs. merge.--data '<json>'/--data-file <path>replace the node's wholedataobject (omit to preserve,--data nullto clear). To merge a few top-level keys while keeping the rest, use--data-merge '<json>'(-reads stdin) or--data-merge-file <path>: the patch overwrites the keys it names and leaves the others intact. The merge is shallow — a nested object value is replaced wholesale, not deep-merged — the patch must be a JSON object, and--data-mergeis mutually exclusive with the--datareplace. (This is the CLI counterpart of thehadron_update_node_dataMCP tool.) --runnable(the node flag).isRunnablegates whetherhadron task runwill execute a node.node addandnode updatetake--runnableto set it; onupdateit is tri-state —--runnablesets true,--runnable=falseclears it, omitting it preserves the current value.node getprints arunnable:line (and theisRunnablefield in--json);node lsadds aRUNcolumn (✓ for runnable) plusisRunnablein--json, andnode ls --runnablefilters server-side to runnable nodes (--runnable=falsefor the explicitly non-runnable; omit for all). This--runnableis distinct from theedge add --runnableflag above, which marks an edge runnable.node ls --children-of <loc>. Lists only the direct children of a loc: the nodes whose loc is exactly<loc>:plus one more segment, with grandchildren left out.--children-of ""lists the top-level nodes. It reads loc text only, not edges, so a child whose parent has no node of its own is still listed. It combines with--prefixand the other filters (all must match), and it applies the same access checks and default exclusions as the rest of the listing. Unlike--prefix, which returns the whole subtree, it returns one level. Merged in hadron-cli#1256 (5ae2bb4f) and first shipped in release v0.37.0 (v0.35.0 does not have it); the server side shipped in hadron-server#2834.-
node ls --has-unresolved-comments. Lists the nodes that still carry unresolved feedback, so you can groom them. First shipped in CLI v0.39.0 (so it needs that or later), and needs a server that carries hadron-server#3494 (hadron-server PR #3520). The three forms:- Omitted: the listing is unchanged. No comment summary is queried and none is printed.
--has-unresolved-comments(true) keeps nodes with a live open thread.--has-unresolved-comments=falsekeeps nodes with none.
The server applies the filter before each page, in search, install and seq modes too. The CLI does not scan threads itself.
With either boolean, two columns follow the normal ones:
OPEN THREADSandOLDEST. In the projected blocks of--with-dataand--with-properties, the two labels come after the node's metadata and before the data or properties JSON.OLDESTis the age of the oldest open root thread, floored to whole minutes, hours or days (5m,3h,12d). It reads<1mfor under a minute or for a timestamp in the future, and-when the node has no open thread.--jsonaddscommentSummarywithopenThreadsandoldestOpenThreadAt. The timestamp is the server's own string (nullwhen there is no open thread), never the displayed age.A node with no open thread is a valid answer: its row shows
0inOPEN THREADSand-inOLDEST(andcommentSummaryholdsopenThreads: 0witholdestOpenThreadAt: null). The CLI never turns an invalid answer into that zero. It checks the shape of every summary itself, and a summary that is missing, negative, has a non-zero count but no timestamp, has a zero count with a timestamp, or has an unparseable timestamp fails the whole command (exit 1, no partial rows). On a valid answer this does not trigger. The change that adds these fields (hadron-server#3494) also computes the count and the oldest time together, in one query that applies the same open-thread test to both. So any server that accepts the field returns a count of zero only withnull.A server that lacks hadron-server#3494 refuses the field, which is schema skew (exit 2). The CLI does not retry without the filter.
System memories are left out of a listing unless
-mnames one or you pass--memory-class system. Three ways to groom them:# boot prompts hadron node ls --has-unresolved-comments --memory-class system --role boot-prompt # role tasks hadron node ls --has-unresolved-comments --memory-class system --runnable # processes (replace the URN with your own team's system memory) hadron node ls --has-unresolved-comments -m hrn:mem:hadronmemory.com:hadron-dev-team-system --prefix processes:Resolve a thread once you have applied or rejected its feedback. Do not delete it, so the grooming history stays.
app nodesdoes not take this flag. - Restructuring nodes.node move <urn> (--to-urn <urn> | --to-memory <memory>)relocates a node and its whole loc-subtree (new loc and/or memory, keeping every node's identity);node clonecopies it to a new loc/memory; both scope a bare source<loc>with-m, and the destination is always the explicit--to-urn/--to-memory. A cross-memory move (--to-memory, or a--to-urnin another memory) carries the subtree's embeddings and rewrites its edges into the destination, but is refused (safe subset) when either the source or the destination memory is encrypted, the subtree contains a chat-root node, or a moved node would break the destination memory's schema. A Git-backed memory is not refused: the move is written back to the repositories instead — the moved files leave the source memory's repo and appear in the destination's. A collision refuses with an "already exists" error.node merge <urn> --into <target>folds one node into another —--field <f>(repeatable) picks which fields to carry over, and--delete-sourceremoves the source after.node mergemutates the target, so it requires--yesnon-interactively whether or not you pass--delete-source. -user merge.user merge <source> --into <target>globally consolidates a duplicate source user into the surviving target and returns the target;<source>is soft-deleted,--into <target>survives. Each reference is a user id, bare handle, orhrn:user:<handle>URN, passed through verbatim (the server resolves and authorizes — platformADMIN/OWNER, or an orgADMIN/OWNERover both members). There is no server dry-run, so it requires--yesnon-interactively. -memory link-user.memory link-user <memoryRef> --external-user <id> --yespromotes an anonymous memory to the App's own end user. It needs an App key: a personal user token is refused. The memory's URN is re-minted (the new URN is reported, and the previous one too on a best-effort basis; the old one stops resolving) and its anonymous expiry is cleared. With--data-key -it also encrypts the memory at rest in the same step, one-way, so keep the key. The key must be canonical base64 for exactly 32 bytes and is sent once in thex-hadron-operation-keyrequest header, never in the request body; a malformed key is refused locally before any request. hadron v0.21.0 or later is required: earlier builds put the key in the request body, and the server no longer accepts that. Pass the key on stdin (--data-key -) to keep it out of shell history. - Soft vs. hard delete.node rmsoft-deletes by default — the node disappears from reads but is recoverable from revision history.node rm --hardremoves the row entirely, cascading its edges and revision history; it's irreversible and prompts with a distinct warning. - Destructive commands (memory rm,memory encrypt,node rm,node merge,user merge,node revision restore --truncate,node revision delete,node revision clear,edge rm,node importwhen it overwrites an existing node,app uninstall,app delete(aliasapp rm),ai-config rm,org rm,org member rm,memory member rm,memory share rm,auth token revoke,grant revoke,spec supersede,run cancel,schedule rm,webhook rm,webhook rotate) prompt on a terminal and require--yeswhen run non-interactively. Without it they exit 2. (Anode importthat creates a new node is never gated.)
Node revision history¶
Every content-changing write to a node snapshots the prior state as a
revision, so edits are recoverable. node revision is the CLI over that
history:
hadron node revision list <node-ref> [-m <memory>] [--limit N]
hadron node revision get <revision-id>
hadron node revision restore <revision-id> [--truncate [--yes]]
hadron node revision label <revision-id> --label <text>
hadron node revision delete <revision-id> [--yes]
hadron node revision clear <node-ref> [-m <memory>] [--yes]
listshows the revisions of a node (newest first), each with its id, who edited it, and any label.getprints one revision in full.restorerolls the node back to a revision. By default it's non-destructive — the pre-restore state is itself snapshotted, so a restore is undoable.--truncateinstead collapses every revision newer than the selected one (which becomes the new baseline), discarding that forward history — so it requires--yes.labelattaches a human note to a revision (e.g.--label "before the auth refactor") so you can find it later.deleteremoves a single revision;clearremoves a node's entire history and prints the count purged. Both are destructive (--yes).
Reads (list, get) need memory read access; the mutations need memory
write access. A soft-deleted node is hidden from history reads, but its
history stays purgeable via delete / clear (the write path). The number
of revisions kept per node is capped by the memory's --max-rev-count
(hadron memory set … --max-rev-count <n>); the oldest overflow is pruned
as new revisions land.
Node approval, minting and signing¶
These commands record that a person reviewed a node, check that the record
still holds, and ask a person for a passkey signature. Behaviour below is what
each command's --help states at v0.32.1; the rules they enforce are the
platform specs cited per command. Approval and signing change the standing of a
node other people rely on, so read the notes before you run them against a
shared server.
hadron node approve <node-ref> [-m <memory>] [--revision N] [--lint-warnings] [--as-worker]
hadron node verify <node-ref> [-m <memory>]
hadron node mint -m <memory> [--dry-run] [--yes]
hadron node sign <node-ref> [-m <memory>] [--revision N] [--signer <user-id>]
hadron node signatures <node-ref> [-m <memory>] [--check]
hadron node signing-request get <request-id>
hadron node signing-request list <node-ref> [-m <memory>] [--state <s>] [--limit 1-100]
hadron node signing-request withdraw <request-id>
<node-ref> is a node URN, a node id, or a bare loc with -m.
| Command | What it does |
|---|---|
node approve |
Records that you reviewed the node's current version: the approver, the time and a SHA-256 hash of the title, abstract and content. A later change to the title, abstract or content supersedes the approval; a metadata-only change (tags, properties, role, description, alias, loc, edges) leaves it valid. --revision N refuses if the node changed since the revision you read; without it the server approves the revision current when it takes the node lock. Approving the same revision again leaves the existing approval unchanged. --lint-warnings also lists the node's current lint warnings after success (advisory, never blocks; --json carries lintWarnings: {items, total, nextCursor: null}, with null meaning the check could not answer). Rule: cor:dmo:120:02 (Approve a node). |
node verify |
Recomputes the approval hash over the current text and prints one state: INTACT (the approval still covers the current text, even if recorded at an older revision), TAMPERED (approved content changed outside revisioned editing), SUPERSEDED (a legitimate edit changed the title, abstract or content after approval) or NOT_APPROVED. Exits 5 for every state other than INTACT, after printing. Rule: cor:dmo:120:05 (Verify a node's integrity). |
node mint |
Marks a memory's approved, not-yet-minted notes as minted, so each loc becomes a citation other notes and repos can rely on. It is used for spec memories; hadron spec mint is the same call. It checks first and prints a report of the nodes it would mint and anything that blocks it: a current version that is not approved or whose approval no longer matches, a placeholder, a reference to a note that does not exist or is not minted, or a lint error. Any blocker refuses the whole mint (exit 5) and nothing is minted. Otherwise it asks before minting; --yes skips the question and is required when not at a terminal. --dry-run prints the report only. A write in flight to the memory refuses the mint for the moment (exit 5): retry. A writer of the memory can mint. Treat a mint as permanent: the command's help says the server does not yet enforce that a minted citation stays permanent. Rules: cor:dmo:120:06 (Mint a memory's nodes), cor:dmo:120:07 (What blocks a mint). |
node sign |
Creates a signing request for the node's current revision. The CLI never signs. A person completes the request with their passkey on the server's signing page, and agents may ask but never sign (cor:dmo:130:02). Any reader of the node may ask. Without --signer, any writer of the node's memory may sign; --signer <user-id> names one user, pinned for the life of the request. --revision N refuses if the node changed since you read it. Follow the request with node signing-request get <id>. |
node signatures |
Lists the node's signatures and their states, current signers first. The server re-verifies every record on each read; a record that fails is counted as an integrity problem and never listed as a signature. States: CURRENT (verifies, content unchanged since), EARLIER (verifies, but the content changed since), PENDING (a first passkey still in its cooling-off window), CANCELLED (that passkey was revoked inside its window), NOT_APPLICABLE (an encrypted memory). The roll-up state is empty when the node has no signatures. --check exits 5 after printing unless the roll-up state is CURRENT and there are no integrity problems. |
node signing-request get <request-id> |
One request, by the id node sign printed or signing-request list shows: its node and revision, its state (OPEN, COMPLETED, DECLINED, WITHDRAWN, EXPIRED or STALE) and, once a person has completed it, the signature. |
node signing-request list <node-ref> |
The node's requests, newest first, including ended ones (ls is an alias). --state filters on the effective state, so an open request past its deadline reads EXPIRED; --limit is 1-100 (server default 20). |
node signing-request withdraw <request-id> |
Withdraws an open request. Only the account that made it may withdraw it, from any of its sessions. A request that already ended is refused (exit 5) and stays as it ended. |
A signing request ends exactly once: completed, declined, withdrawn, expired,
or stale when the title, abstract or content changes. The lifecycle is
cor:dmo:130:03.
For the approve, mint and spec-drafting workflow end to end, see Maintain product specs and the Product specs explanation.
Deleted nodes, edge removals and reading in order¶
A soft-deleted node is invisible to node get|list|rm. node recovery is the
separate, writers-only surface for reading what was deleted so that
node restore can bring it back.
hadron node recovery list -m <memory> [--limit 1-200] [--offset N | --all]
hadron node recovery get <node-ref> [-m <memory>] [--content]
hadron node recovery graph -m <memory> [--edge <id>]… [--limit 1-200] [--offset N | --all]
hadron node restore <node-ref> [-m <memory>] [--lint-warnings]
hadron node edge-removals <node-ref> [-m <memory>] [--limit N]
hadron node next <parent> [--after <current>] [-m <memory>] [--raw]
hadron node open <node-ref> [-m <memory>] [--print]
recovery listshows the deleted nodes of a memory with their ids.recovery getshows one;--contentadds its content.recovery graphlists the links (edges) among live nodes and restorable deleted nodes: the whole graph as it would be after restoring.--edgelimits it to an edge id (repeatable, at most 200).listandgraphpage 20 at a time;--limitsets the page size (1-200),--offsetskips rows, and--allreads every page, failing as a whole if any page fails.restorebrings back ONE deleted node and the comment threads its own deletion removed: not its descendants, not comments deleted independently, not its revision history. It sends one request and never retries; if the answer is lost, verify withnode recovery getornode getbefore running it again. It refuses, with the server's own message, a governed node, a comment, a compiled boot prompt, a protected address, and a node whose parent is still deleted (restore the named ancestor first). Restoring a node that is already live is accepted.--lint-warningslists the node's lint warnings after success, as fornode approve.- Only a memory's writers can use it. For anyone else a deleted node and one that never existed are indistinguishable, so a miss does not say which.
edge-removalslists the audit entries a hard delete left on a node when it removed edges the node held to the deleted target: one entry per removed edge, newest first (--limit, default 20; a full page says more may exist). An entry names the removed edge and the deleted target, why, who deleted it and when. The target's loc, and the edge's loc derived from it, arenullwhen you cannot read the target's memory. A soft delete keeps its edges and records nothing.nextsteps through the notes under a parent in order: with no--afterit reads the parent's first child, with--after <current>the one after it. Order is byseq, lowest first (nodes without one last), then by loc. Each call stands alone and nothing remembers your place. The end of the chain, a missing or unreadable parent, and an--afterthat is not a direct child all give the same answer,end of sibling chain(nullwith--json), exit 0. Content is rendered by default;--rawreads the stored body.openopens a node in the web portal using the link the server gives for it, never a guessed address. Interactive output requests the platform browser launcher and prints the URL;--print,--jsonand non-terminal stdout only print the pointer ({id,urn,portalUrl}). A missing or unreadable node exits 4; a missing or invalid canonical URL exits 1 and no fallback is built.
Automations¶
hadron automation (alias automations) reviews and approves the schedules and
webhooks of an App, without a row id or a hash. A schedule or webhook runs only
after it is approved. How-to: Approve or decline an
automation.
The App is --app <ref>, else the active App. A trigger is schedule/<name> or
webhook/<name>; a bare <name> works when exactly one trigger has it. No match
and several matches both refuse.
| Command | What it does | Flags |
|---|---|---|
automation ls (list) |
The schedules and webhooks you may approve, each approved or not approved. Only an adopter sees a row, so an empty list never proves the App has no automations. |
--app |
automation approval [<name>] |
The plain summary of one automation: its state, what it reads, writes and calls, and what it cannot do. A fact the server cannot show says not stated. |
--depth adds the graph and the hash |
automation approve [<name>] |
Shows the summary on stderr, asks to confirm, and sends the hash just shown. | --yes / -y skips the prompt, never the display |
automation decline [<name>] |
On an approved automation, revokes the approval (its next run fails until approved again); on any other, records the decline. Needs no summary. | --yes / -y skips the prompt |
State is not approved, approved, or changed since it was approved (its next
run fails until approved again). ls shows approved (approval may be stale) for
anything approved at some point, changed or not; whether it changed since shows
on approval.
Exit codes: 4 no such automation, or not visible to you; 5 the automation
changed since the summary you approved (nothing is retried, run approval
again); 6 you answered no, or input ended, at the prompt. Without --yes a
non-interactive caller is refused and nothing is changed (exit 2). Display and prompt go
to stderr, so stdout carries only the result. Everything else follows the
exit-code contract.
Running tasks¶
A task is a runnable node (isRunnable: true) — usually a prompt template
whose accepted --args it declares in Node.data.args. hadron task run
(<node-urn> | <loc> -m <memory>) [--arg k=v]… has two modes:
- Render (default). Compiles the node's template with your
--args and prints the result — the instructions for you to run. - Execute (
--app <ref>). Instead of rendering, the server mints aMANUALheadless run of the task under that App (a real LLM run) and prints the run id; follow it withhadron run get <id>.--as-selfruns it on behalf of you (reaches your personal memories; authenticated user only). In--json,modeis"render"or"execute", and execute mode addsrunId.
node import --task <ref> is the same execute path bolted onto an import: after
the node is stored, the server runs <ref> against it (--task-args <json>,
--app <ref>, --agent <ref>) and returns the run id as jobId. --task,
--task-args, --app and --agent belong to content mode (see node
import — two modes). --url, --content-type and a
.pdf, .html or .htm input select content mode on their own; for a plain
Markdown, JSON or stdin input add --as-content, or the CLI refuses with
--task applies only to content import — pass --as-content to ingest this file
as raw content (exit 2).
Naming the Agent that serves a run¶
An executed run (task run --app, run trigger, node import --task) is
served as one of the App's installed Agents. --agent <ref> names it, as an
Agent ID or URN; the server resolves it and checks that it is installed in the
App. List the candidates with hadron app agent list <app>.
- One installed Agent: omit
--agent; that Agent serves the run. - Several installed Agents:
--agentis required. Without it the run is refused (the server'sRUN_AGENT_REQUIRED; fortask runandrun triggerbefore anything is written), and the CLI prints this and exits2:
hadron: This App has several installed Agents: pass agentRef to name the one the run is served as. — pass --agent <ID or URN> (list them with `hadron app agent list <app>`)
With --json the same text arrives as
{"error": {"code": 2, "message": "…"}}.
- An Agent that does not exist or is not installed in the App is refused
with hadron: agentRef does not name an agent installed in this App. and
exit 2.
- node import --agent without --task, in content mode, is refused with
hadron: --agent requires --task (it names the Agent the task run is served
as) and exit 2. For a plain Markdown file without --as-content the CLI
stops earlier, with hadron: --agent applies only to content import — pass
--as-content to ingest this file as raw content.
hadron task run hrn:node:acme.com:ops:tasks:brief --app acme.com:ops \
--agent hrn:agent:acme.com:coach
hadron run trigger --app acme.com:ops \
--entry hrn:node:acme.com:ops:tasks:nightly-digest \
--agent hrn:agent:acme.com:coach
Skills¶
hadron skill maintains the skill surface exported from runnable task
nodes. lint and status are read-only: lint touches no disk, status
writes nothing. export is the only writer into your skills folders;
plugin builds installable bundles elsewhere, under an explicit --out. For the task-shaped walk-through
of installing, updating and recovering, see
Install and update your Hadron skills.
The declaration¶
A node opts in by declaring properties.exports.<host> — an object keyed by
skill host, each entry {name, description, enable}:
| Field | |
|---|---|
name |
kebab-case, ≤64 chars. Stored, not derived — there is no --prefix and no org prefix field, so any prefix is part of the name you write. |
description |
≤1024 chars. The host truncates longer ones in its listing, so trigger phrases past the cut never fire. |
enable |
Must be true to publish, and defaults to OFF. A declaration alone does not ship a skill — a corpus holds many runnable nodes that were never meant to be skills. |
The retired top-level properties.skill and properties.claudeSkill are read
as aliases for the claudeSkill host, so nothing needs migrating.
exports.claudeSkill wins over both, so the new shape can sit beside an old
one. The enable default applies either way: a node carrying only
{name, description} is declared and not enabled.
skill lint¶
Checks the corpus. What it verifies: name present, kebab-case and ≤64;
description present and ≤1024; isRunnable set; body non-empty and
frontmatter-free; and no two nodes storing one name.
What it cannot check: with no prefix source, a name's prefix is
unverifiable — hadon-foo lints clean.
--all walks what the server lists for you: own-org, shared-with-you, and
other orgs' public memories, every class. A per-user agent memory is
never listed, so name it with -m.
Errors exit 5. Warnings alone exit 0 unless --strict promotes them.
skill status¶
Reads both sides and reports drift. It walks <root>/*/SKILL.md — --to user
is ~/.claude/skills, project is <git toplevel>/.claude/skills, plugin
is <git toplevel>/plugins/hadron-cli/skills, and anything else is taken as a
directory — then pairs each file to its node by the id in its provenance
header.
The drift class is the server's word, so the vocabulary cannot drift between the CLI, MCP and the portal.
- A file that exists but does not parse gets
class: nullwithparseFailure: true— a parse failure is a failure, not an eleventh class. Read the two together and neverclassalone. In the table that row's class cell is—with the reason in DETAIL; in--jsontheclasskey is present and null, never omitted, so "the server returned no class" stays distinguishable from "not asked for". - A file that parses and carries no Hadron header is somebody else's skill: never listed, moved or removed.
- A file that does not parse is reported either way — attributed to its node
when the provenance header below the broken frontmatter is still readable,
and otherwise listed locally under
unparseable, never sent, since an unidentifiable file must not be claimed as an orphan. - An unreadable file is listed under
unreadablewith its errno, likewise never sent.
There is deliberately no --node: the orphan and collision classes are
properties of a set.
A selection that resolves to no memory sends nothing and says so — it is not an all-clear.
The symbolic roots are host-specific, so a --host other than
claudeSkill must name a directory with --to <dir> rather than being
resolved against Claude's. --to plugin applies no visibility filter — it
covers every accessible task node, as the other targets do; curating which
tasks a bundle carries is a later feature.
An error finding exits 5; drift and warnings alone exit 0, so a CI gate is
an explicit --strict, which exits 5 on any drift, parse failure, orphan,
empty scope, or warning.
skill export¶
Writes every enabled declaration you can read, for every known host, into user-level roots, creating an absent root. It takes no selector, does no host detection and never prompts.
| Host | Root |
|---|---|
claudeSkill |
~/.claude/skills/<name>/SKILL.md |
codexSkill |
~/.agents/skills/<name>/SKILL.md |
The deprecated ~/.codex/skills is never written, moved or cleaned. The
server plans every action and renders the whole file. Export writes that body
byte for byte, atomically, and reports what actually happened on disk.
--dry-runreports the same outcome and changes nothing, not even an absent root.- A hand-edited file is refused (
refused), even when its declaration was disabled and it would otherwise be removed.--forceoverrides that for one invocation, and also regenerates a Hadron file that carries no node id. A file with no Hadron provenance header is never touched. - Orphans are reported (
orphaned) and removed only with--prune. A removal — a disabled declaration, a move's old directory, or a prune — deletesSKILL.md, then the directory only if it is empty. Anything left is listed inkept. - Links are refused. If a host's root, or any directory between
$HOMEand it, is a symbolic link, nothing is written for that host:failureis set and every one of its skills isfailed. A skill directory that is itself a link isrefused.$HOMEitself is resolved, not refused. - A declaration the host would truncate is skipped. A description over 1,024 characters is not written, and an older installed copy stays at its old version, so a skipped row is worth reading.
--json is {dryRun, hosts:[{host, root, failure, scanned, judged, written,
moved, removed, skipped, refused, failed, orphaned, pruned, unreadable,
unparseable}], unrecognized:[…]}, and every list is [] when empty. An item is
{node, nodeId, name, reasons, kept}; moved items add from. Each reason is
{code, message, origin}: origin: "server" is the planner's reason
verbatim (a drift class or lint rule), and origin: "client" is an I/O fact
about this machine (root-is-link, skill-dir-is-link, io-error,
directory-kept, …). unrecognized lists nodes whose exports names no host,
once, attributed to no host.
One failing item never stops the others. Exit 0 when nothing was refused or failed; 5 after the full report when any item was refused or failed, or a host could not be written. A run that cannot start exits with that error's code (auth, connection). Hosts load skills at session start.
skill plugin¶
Builds one installable unit per host under an explicit, required --out,
never inferred from the working directory or a git checkout. For the task-shaped
walk-through, see Build a Hadron skills plugin.
| Host | Artifact |
|---|---|
claudeSkill |
<out>/<name>/: a Claude plugin (.claude-plugin/plugin.json plus skills/<skill>/SKILL.md) that is also a one-plugin marketplace, so claude plugin marketplace add <out>/<name> then claude plugin install <name>@<name> installs it with no git |
codexSkill |
<out>/<name>-codex/: skill folders for ~/.agents/skills |
--zipalso writes<name>.zipand<name>-codex.zip, with the plugin at the zip's root. It needs a filesystem with hard links.--namedefaults tohadron: lowercase words joined by hyphens, up to 64 characters. Skills are invoked as/<name>:<skill>.- The Claude manifest's
versionis derived from the bundled content (0.0.0-h<hash>), so it changes exactly when a skill does. Claude Code updates on any version change. - Selection is every enabled declaration you can read, unless
--scopenarrows it to that scope's readable memories. A scope with no readable memory never plans and exits 2. A scope that doesn't exist or isn't readable exits 4 ("no scope … is readable here"), and a scope name needs an App context (--app, or an active App) or it is refused with exit 2. - Refused before any request, exit 2: an artifact at, inside or above a host
skills directory (
.claude/skills,.agents/skills,.codex/skills, user- or project-level), an empty--outor--scope, or a bad--name. - An existing artifact is replaced wholesale only if this command wrote it
(a
.hadron-pluginmarker, or the zip's comment). Anything else at the path, or a symbolic link, is left alone and fails the host (artifact-not-ours/artifact-is-link), even when it appears mid-build. --dry-runwrites nothing and reports the same refusals.
Each item is bucketed by the server's planned action: included, skipped,
refused, failed, or notForHost (declared only for the other host).
--json is {dryRun, name, out, scope, hosts:[{host, format, artifact, zip,
version, failure, scanned, judged, included, skipped, refused, failed,
notForHost, findings}], unrecognized}. scope is null when unscoped, and
otherwise {id, name, memoryCount, droppedCount, resolvedVia}. Items have the
same shape as skill export's, with kept always []. findings lists every
lint finding except an error on a refused or failed entry. It never affects the
exit, and passes unknown severities through.
Exit 5 after the full report on any refused or failed item or a host
failure, and 0 otherwise (skipped and notForHost don't count); 2 for
a bad flag, --out, or an empty scope; 4 for a scope that doesn't exist or
isn't readable.
hadron skill plugin --out ~/hadron-plugins --dry-run
hadron skill plugin --out ~/hadron-plugins --zip
Search¶
hadron search <query> retrieves nodes ranked by relevance — the CLI's
first-class search, distinct from spec find (which is scoped to spec
corpora). The default mode is hybrid (semantic + keyword, fused); on a
memory with no vector index it degrades to keyword and prints a note on
stderr.
hadron search <query> [-m <memory>]… [--scope <name|id|app|global>] \
[--mode hybrid|keyword|vector|regex] [--prefix <loc>] [--type <t>] [--tag <t>]… \
[--limit N] [--offset N] [-l] [--json]
--modeselects the ranking:hybrid(default),keyword(stemmed full-text with boolean operators — uppercaseAND/OR/NOT, quoted phrases,-term),vector(semantic only), orregex(POSIX over literal fragments).-m/--memory(repeatable) restricts to one or more memories by ID or URN; omit to search everything you can access. Under a scope,-mnarrows within it.--scopesearches under a named scope: a scope name (needs an App context —--apporhadron app set-active), a scope id,app(the App's attached memories — also needs an App context), orglobal(your active organization's view — set it withhadron org use). Without--scope, the default fromhadron scope useapplies, if you set one. Passing--scope ""does not switch the default off; clear it withhadron scope use "". A name orappwith no App context is refused with exit 2 before any network call.- The result says which scope applied. When one did, the text output
starts with
scope: <label> (<kind>, via <source>), flags a default you did not pass on this invocation, and reports how many of the scope's memories you could not read and were not searched. In--json, the envelope carries ascopeobject:selectedBy(flagorconfig),kind,label,source,ownerUrn,memoryUrnsanddroppedCount. --prefixfilters by node loc prefix;--typeby node type;--tag(repeatable) by tag.--limitcaps hits (default 15;0uses the server default);--offsetpages.- Each hit carries a relevance score plus the node's description and
abstract in
--json, so results are assessable without a follow-upnode getper hit.-l/--longprints the abstracts in the text output too.
hadron search "how do users report a bad actor" -m micromentor.org:mmdata
hadron search "(auth OR login) AND token" --mode keyword --prefix findings:
hadron search 'reportUser|contentConcern' --mode regex --limit 30 --json
hadron search "retrieval" --scope research --app hrn:app:acme.com:dev-team
Search scopes (hadron scope)¶
A scope — a "lens" — is a named, ordered list of memories owned by exactly one organization, App, or Agent. It narrows what a search looks at; it never widens what you may read. Memories in a scope that you cannot read are reported as a count, never by name.
hadron scope list [--owner-org <ref> | --owner-app <ref> | --owner-agent <ref>] [--name <n>]
hadron scope get <name|id> [--by-name]
hadron scope create <name> (--owner-org|--owner-app|--owner-agent <ref>) -m <memory>… [--description <d>]
hadron scope update <name|id> [--by-name] [--name <new>] [-m <memory>…] [--description <d>]
hadron scope rm <name|id> [--by-name] [--yes]
hadron scope explain <name|id> [--by-name] [--loc <address>]
hadron scope set-active|use <name|id|app|global> [--no-verify]
- Names and ids. A scope is addressed by its id (32 hex characters),
which needs no context, or by its name, which resolves in an App's
context (
--app, or the active App). That context is the App's own scopes, those of the Agents installed in it, and its organization's; where names collide, the server resolves App > Agent > organization — never a union. A name with no App context is refused with exit 2 before any network call. A scope name may be 1–64 characters of[a-z0-9_-], so an all-hex 32-character name looks like an id: pass--by-nameto force the name reading onget,update,rmandexplain.set-activehas no--by-name, so to make such a scope your default, look up its id withscope get <name> --by-nameand pass the id. createtakes exactly one owner flag and at least one-m. Creating on an organization needsCONTRIBUTORor above there; on an App or an Agent,ADMINof its organization, or ownership of a user-owned one. An Agent need not be installed anywhere to own a scope.-mis repeatable and ordered: the order you pass is the scope's order, and it decides which memory wins for an address. The server enforces the name rules — unique per owner, and neverapporglobal, which are reserved.updatechanges only the flags you pass.-mreplaces the whole list rather than appending, so pass every memory, in order.--descriptioncannot clear a description:--description ""stores an empty string.rmdeletes the lens, never the memories it listed, and frees the name immediately. It needs--yeswhen non-interactive.explainshows the scope as it applies to you: which memories it resolves to, in order; which owner level it resolved at; how many memories you cannot read; and any lower-precedence scopes of the same name that it shadowed.--loc <address>also names the memory that would win for that address. A name that two installed Agents both own is refused as ambiguous (SCOPE_NAME_AMBIGUOUS); pass the id instead.set-active(aliasuse) stores a default search scope in~/.config/hadron/config.toml, whichsearchapplies whenever--scopeis omitted — and says so on every result. It takes the values--scopetakes. A name or id is verified when you set it (a scope you cannot read is refused with exit 4);appandglobalare stored as keywords and resolved on each search.--no-verifyskips the check for offline use. The value is stored as typed, not pinned to an id, so a name resolves in whichever App context you search from.""clears it.
hadron scope create research --owner-org acme.com -m hrn:mem:acme.com:papers -m hrn:mem:acme.com:notes
hadron scope explain research --loc findings:retrieval --app hrn:app:acme.com:dev-team
hadron scope use research --app hrn:app:acme.com:dev-team # a name needs an App context
hadron scope use "" # clear the default
scope list --json shows memories: [] for every scope
list does not fetch each scope's memories, so its --json entries carry
an empty memories array that means not requested, not empty. Use the
memoryCount field, or scope get for the list itself.
Object store¶
hadron object is the collection-oriented CRUD-and-query surface over
structured storage — the legible "records, not graph
nodes" projection. An object is a node with an objectType, presented as a
flat record { id, type, ...fields }: id/type are the reserved envelope,
the node's typed properties are the top-level fields, and loc/name are
auto-derived and hidden. On a memory with a declared schema, writes are
validated against the collection. The command also answers to objects and
obj.
hadron object create -m <memory> --type <t> (--fields '<json>' | --fields-file <path>) [--key <seg>] [--name <n>]
hadron object get <ref>
hadron object update <ref> (--fields '<json>' | --fields-file <path>) [--reason <text>]
hadron object find -m <memory> --type <t> [--match '<json>'] [--where '<json>'] [--sort '<json>'] [--limit N] [--offset N]
hadron object delete <ref> [--hard] [--yes]
create—--fieldsis the record as a JSON object (or--fields-file).--keysets a natural id (a single loc segment, no:); omit for a server-generated id.--nameoverrides the auto-derived node name.idandtypeare reserved and can't be field names. Prints the flat record.get <ref>—<ref>is an object id or a node URN. Exits4(not found) when the ref names nothing readable, or a node that isn't an object.update <ref>—--fieldsis shallow-merged into the existing record (patch wins on collision, unmentioned fields kept; atomic server-side), then re-validated against the schema. Contrastnode update --properties, which replaces the whole bag.--reasonis recorded in revision history.find(aliasls) — query one collection.--matchis an equality shorthand ({field: value}, ANDed intoeqper field, cast inferred from the schema);--whereis the full predicate (thesearch --wheregrammar), AND-combined with--match;--sortis{"<field>":"asc"|"desc"}. Prints the matching objects and atotal.delete <ref>(aliasrm) — soft by default (row retained, hidden from reads);--hardremoves the row. Non-recursive.--yesskips the prompt.
hadron object create -m acme.com:market --type competitor \
--fields '{"name":"Letta","stage":"series-a","fundingUsd":12000000}' --key letta
hadron object find -m acme.com:market --type competitor \
--where '{"path":["fundingUsd"],"as":"number","gt":10000000}' \
--sort '{"fundingUsd":"desc"}' --json
See Work with objects from the CLI for the walkthrough and the "which layer?" guidance, and Object store API for the GraphQL + MCP equivalents.
Memory health audit¶
hadron memory validate <memoryRef> runs the server's memory health audit
(validateMemory) and reports its findings.
| Finding | Meaning |
|---|---|
broken-ref |
An edge pointing at a missing or soft-deleted node. |
embed-failed |
A node whose embeddingFailedAt marker is set — an embedding attempt actually failed. Not the same as "has no vector": a node still pending, or one with nothing embeddable, lacks a vector without being a finding. |
sparse |
No description, content, or abstract. |
schema |
objectType / properties violating the memory's declared schema. |
stale-abstract |
The abstract's origin hash no longer matches the content hash. |
Read stale-abstract narrowly
It fires when the body isn't the version the abstract was written against — including when the change altered nothing the abstract says. It means "the body moved under this abstract", not "this abstract is wrong". Measured on a live corpus it carries essentially no signal about whether the abstract still describes the body.
Two counts, deliberately: totalFindings is the true count across every
check before truncation — gate on that, never on findings.length —
while matchedFindings counts what was listed after --limit and
--check.
ok is false whenever a check was skipped, even with zero findings:
health can't be claimed for a check that didn't run. skippedChecks says
which and why — stale-abstract is skipped on an encrypted memory, because
the validator doesn't decrypt.
--check <kind> filters client-side, and the server caps findings
before that filter runs, so --check requests the server maximum (1000)
unless you pin --limit. If the result is still truncated, the report says the
filtered view may be incomplete.
Retrying failed embeddings, and counting node reads and writes¶
reembed-failedretries every node in the memory whose embedding failed. An embedding is the vector the server computes from a node's text so that search can find it by meaning (search --mode vectororhybrid); a node whose embedding failed is missing from those results. The server marks each such node (waiting to retry, or failed for good) to be tried again and returns how many it marked. The number is marked, not "now indexed": a node that fails every time, such as one too long for the embedding provider's time limit, fails again.0is a normal answer and also means the memory has no vector index. Confirm the outcome withhadron memory validate <memoryRef> --check embed-failed. It is a mutation, kept apart from the read-onlyvalidateso an audit never changes anything. Running it is the request, so it does not prompt. It is sent exactly once: a transport error leaves the outcome unknown and is not retried for you. The server's own gate applies (memory owner or organizationADMIN), as do its limits on encrypted memories.usagecounts how often each node was read and written: one row per node loc and kind (readorwrite) with the number of times, as the server recorded them. Counts stay after a node is deleted. It needs read access to the memory. It is not a cost or billing figure; AI calls and their cost are inhadron usage events. Old activity recorded without a node may be missing.--jsonprints an array of{nodeLoc,type,count},[]when there is none.
Listing the next level of a memory's structure¶
hadron memory loc-segments --memory <id-or-URN> [--memory <id-or-URN> ...]
[--parent <loc>] [--limit <n>] [--after <cursor>] [--json]
Returns one page of the next loc segments under a parent, including branches that have no node of their own. It is one level, not a recursive tree.
--memoryrepeats (without-m) and is never split on commas. Values and--parentgo to the server unchanged, with no scope or existence read first.--limitand--afterare sent only when you give them. A positive limit is forwarded (the server's default is 20 and its cap is 200).- Rows keep the server's order and carry their source memory, including inherited memory ids. Equal segment names stay separate rows.
- Text columns are
MEMORY ID,SEGMENT,HAS NODE.--jsonis{items:[{segment,hasNode,memoryId}],hasMore,endCursor}, with[]for no rows and a nullable cursor. - Only
hasMoreadds the stderr linemore segments remain — continue with --after <cursor>. The cursor is shell-quoted there when it holds anything outsidea-zA-Z0-9:._/@-; JSON carries it raw. Repeat the same scope with that cursor. There is no auto-drain and no snapshot guarantee.
Assets¶
hadron asset manages binary attachments stored in object storage and
addressed by id or URN (hrn:asset:<root>:<memory>:assets:<id>). The URN
carries its memory, which is why asset url accepts a URN alone but needs
-m with a bare id.
hadron asset ls -m <memory> [--mine] [--mime <type>] [--include-deleted] [--limit N] [--offset N]
hadron asset get <asset-ref> [-o <path>|-] [--force]
hadron asset url <asset-ref> [-m <memory>]
hadron asset public-link <asset-ref> (--on | --off) [--yes]
hadron asset upload <file> -m <memory> [--mime <t>] [--name <n>] [--description <d>]
hadron asset rm <asset-ref> [--yes] | restore <asset-ref>
hadron asset link <asset-ref> --node <new-node-urn> [--name <n>] [--description <d>]
lsrequires-m. The CLI's listing is memory-scoped by design — it won't fan out across memories. (The GraphQL API does have a cross-memoryassetsquery returning every asset the caller can reach; the CLI simply doesn't expose it yet.) It pages to exhaustion by default;--limitfetches one explicit page.--minenarrows to your own uploads.getmints a short-TTL presigned URL and streams the bytes to the asset's own filename,-o <path>, or-o -for stdout. It refuses to clobber an existing file without--force(the default name comes from server metadata, not from you) and deletes a partial file on failure.uploadis three steps behind one command: the server reserves the asset and returns a presigned PUT, the bytes go straight to object storage, and a final call marks it usable. Size and MIME are declared up front, so the cap and the MIME allowlist reject a bad upload before any bytes move.
Downloads are gated on virus scanning¶
A PENDING asset is refused because the verdict hasn't settled — that's
"not yet", not a dead end: the server's sweep retries on a backoff, so try
again shortly. A BLOCKED asset is refused permanently, its bytes deleted
and the row kept as an audit tombstone. An upload whose bytes fail the scan
fails on the last step, after the transfer, leaving a BLOCKED record on
purpose — re-uploading the same file always fails the same way. All three
exit 1. asset ls shows the scan status, and for a BLOCKED row the engine
signature that matched (scanSignature in --json, null on every other row).
lsalso shows each asset's public-link state: thePUBLIC LINK,CAN MANAGEandAVAILABLEcolumns (publicLinkEnabled,canManagePublicLinkandpublicLinkAvailablein--json).PUBLIC LINKreadsoff,on,on, serving disabled on this deploymentwhen the asset's switch is on but the deployment doesn't serve links, oron, no public URL on this serverwhen the switch is on and the deployment serves links but no URL is available for that asset (a scan not yet finished, or no public address configured).public-linksets the asset's own switch.--onasks you to confirm that anyone with the link may download the file, and in a script it exits 2 withrefusing to proceed without --yes in non-interactive modeunless you pass--yes.--offneeds no confirmation. The result prints the switch, whether you can manage it, and whether the deployment serves links. A caller who doesn't manage the memory getscaller does not manage this asset's memoryand exit 8, and the switch is unchanged.
asset url prints an unauthenticated link
The public hotlink has no read gate — anyone holding it can fetch the
file. It's absent (exit 5, with a reason) when the asset's own switch is
off, the asset isn't CLEAN, its memory is encrypted, the deployment has no
public origin, or — the default — the deployment hasn't turned public
hotlinks on (ASSET_PUBLIC_HOTLINK_ENABLED). The reason names the cases it
can tell apart: public link: off, on, serving disabled on this
deployment, or that the scan hasn't finished. A missing link never proves
the switch is off. Never construct that URL yourself.
Bulk search and replace¶
hadron replace text <old> <new> search-and-replaces a piece of text across
many nodes in one call — the CLI mirror of the hadron_replace_globally MCP
tool. replace is a top-level command group (not hadron node replace),
and <old>/<new> are positional arguments.
hadron replace text <old> <new> --field <field>… \
(--node <node-urn> | -m <memory>)… [--prefix <loc>] [--regex] [--ignore-case] \
[--max-nodes N] [--reason <text>] [--dry-run] [--yes] [--json]
Parameters¶
<old>(positional) — the text to find (literal by default; a regular expression with--regex).<new>(positional) — the replacement. With--regex, supports replacement patterns with backreferences ($1for a capture group,$&for the whole match).--field <field>(repeatable, required) — which text fields to search:content,name,alias,description,abstract,tags.- Selection — at least one of:
--node <node-urn>(repeatable) — specific nodes by URN or ID.-m/--memory <id-or-urn>(repeatable) — every node in one or more memories.--prefix <loc>— narrow a--memoryscope to a parent loc and its descendants (matched on:path boundaries, soauthmatchesauthandauth:tokensbut notauthoring).--regex— treat<old>as a regular expression.-i/--ignore-case— fold case.--max-nodes N— refuse to apply if more than N nodes would change (0= no limit). A guard against a whole-memory rewrite from a wrong--memoryURN or a forgotten--prefix.--reason <text>— recorded in the node's revision history.--dry-run— preview match counts without writing.--yes— skip the confirmation prompt; required in non-interactive use.
The blast-radius guard¶
A real run first previews the per-node match counts and asks for
confirmation before writing. Pass --yes to skip the prompt (an agent or
script must), or --dry-run to preview without writing. Even with
--yes, the affected-node count is printed to stderr before the write —
combined with --max-nodes, that's the guard against an accidental
whole-memory rewrite. Every change is saved to revision history, so
replacements are undoable.
--json output¶
{
"nodesScanned": 12,
"nodesChanged": 3,
"totalReplacements": 4,
"dryRun": false,
"results": [
{
"nodeId": "n1",
"loc": "findings:flaky-ci",
"memoryId": "mem1",
"replacements": 3,
"fields": ["content", "description"]
}
]
}
dryRun echoes whether this was a preview. A zero-match run returns
"results": [].
Examples¶
# Preview only — no write
hadron replace text old-url.com new-url.com \
-m acme.com:kb --field content --field description --dry-run
# Apply across a subtree, two fields, no prompt (agent-safe)
hadron replace text foo bar \
-m acme.com:kb --prefix services: \
--field content --field description --yes
# Regex with a backreference on one node
hadron replace text 'api/v(\d+)/users' 'api/v$1/users' \
--node hrn:node:acme.com:kb:api:users-endpoint --field content --regex --yes
# Cap the blast radius: refuse if more than 20 nodes would change
hadron replace text 'seperator' 'separator' \
-m acme.com:kb --field description --field tags \
--ignore-case --max-nodes 20 --yes
Import and export¶
Nodes and memories serialize to portable, self-describing files, and
node import has a second mode for ingesting external source.
node import — two modes¶
node import [<file>|-] does one of two things depending on its input:
- Restore (default) — reconstitute a node-export file produced by
node export(frontmatter-markdown, or--format json). Read-to import from stdin, so an export pipes straight into an import. The target memory and loc come from the file's own keys;-m/--memoryand--locoverride them to re-home a node into another memory. Outgoing edges are imported only with--with-edges(off by default).--create-onlyrefuses to update an existing node;--dry-runclassifies without mutating. The server recomputes content hashes, so a clean export→import round-trips losslessly. - Content — ingest raw external source (a web page, a captured HTML
DOM, a Markdown file, or a PDF) and let the server convert it to the
node's Markdown body. This mode is selected by
--url, by--as-content(force it for an otherwise-ambiguous.md/.json/stdin source), or automatically for a.pdf/.htmlfile. Target the node with-m/--memory+--loc, or with--node <node-urn>. Extra flags:--content-type(text/html·text/markdown·application/pdf; inferred from the extension, but required for a PDF over stdin),--name,--type(defaults towebpage, orinfofor a PDF), and--properties/--properties-file(a provenance JSON object merged into the node). A PDF's text layer is extracted to Markdown — the CLI base64-encodes the file for you; scanned/image-only PDFs error server-side.
An import onto an existing node overwrites it — and is gated
If the target loc already holds a node, node import overwrites it
(the prior version is kept in history). Like the destructive commands,
that prompts on a terminal and requires --yes non-interactively. An
import that creates a new node is never gated. With --with-edges,
an edge that can't be wired is reported under unwiredEdges (with a
reason) and the node is still written — but the command then exits 1
(see Partial writes); re-import is
idempotent.
Memory export, clone, and extract¶
memory export <id-or-urn> [--out <dir>]writes every node to a local directory (--outdefaults to.) as one frontmatter-markdown file per node (<out>/<loc>.md; colons in the loc become path segments) — the same layout the server's git sync produces, but on disk and with no remote.data-type nodes are skipped; nodes the read API can't return are listed underunavailablein the--jsonsummary (a client-side export is bounded by per-node read access). Existing files are overwritten; files for removed nodes are not deleted.memory clone <id-or-urn> --target-urn hrn:mem:<root>:<slug>deep-copies a memory (nodes, edges, pending edges) into a new memory named by--target-urn— the fully-qualifiedhrn:mem:<root>:<slug>form (the short<root>:<slug>and legacy<root>::<slug>spellings are accepted too) — rewriting references to the source URN inside node content and abstracts. The target org may differ from the source's, cloning into another org — you must be a non-reader member of that target org (cross-org clones drop edges to nodes in other memories). Version history, shares/subscriptions, assets, and git-sync config are not copied; encrypted and agent-system / app memories cannot be cloned.memory extract <parentRef> <targetUrn> [--move]lifts a parent node and its whole loc-subtree into a new memory named by<targetUrn>(a fully-qualifiedorg:slugURN), making the parent the new memory's root. Locs are rebased —findings:authbecomes the memory slug andfindings:auth:oauthbecomes<slug>:oauth.<parentRef>is the parent node's ID or fully-qualified URN; pass-m <org:memory>with a bare loc instead. Edges wholly inside the subtree carry over; boundary-crossing edges and unresolved pending edges are dropped. Without--movethe subtree is copied (source untouched);--moverelocates it, soft-deleting the source subtree —--moveneeds source write access and cannot target the source root (that would empty the source; clone then delete instead). The new memory preserves the source's class, so an extract never widens who can read the content (a member-restricted group stays group, a personal/private source stays owner-owned). The target org may differ from the source's, dropping the extract into another org. v1 limitation: node content is copied verbatim — because both the slug and node locs change, URN references among the moved nodes will break. Encrypted and system / app memories are rejected. See the GraphQLextractParentNodeToMemorymutation for the underlying operation. Not yet in a tagged CLI release (merged in hadron-cli#229; the latest release,v0.6.1, predates it) — until the next release ships, invoke the GraphQL mutation directly withhadron api.
# Round-trip one node through a file (or a pipe)
hadron node export hrn:node:acme.com:kb:findings:flaky-ci -o flaky.md
hadron node import flaky.md --with-edges
# Ingest external source as a node's content (server converts it)
hadron node import --url https://example.com/post -m acme.com:kb --loc clips:post
hadron node import paper.pdf -m acme.com:kb --loc papers:attention
hadron node import notes.md --as-content -m acme.com:kb --loc notes:today
# Export a whole memory to local markdown, one file per node
hadron memory export acme.com:kb --out ./kb-backup --json
# Extract a subtree into a new memory (copy, then a move into another org)
hadron memory extract hrn:node:acme.com:kb:findings:auth acme.com:auth-kb
hadron memory extract -m acme.com:kb findings:auth other-org:auth-kb --move
Memory transfer and approve-all¶
memory transfer <memoryRef> (--org <ref> | --user <ref>)previews, and with--applyor--yesperforms, a change of ownership. Exactly one destination owner is required. The default is a read-only preview of the transfer and how its dependents are handled; nothing is written.--applyshows the preview and asks for confirmation.--yesapplies without asking, for scripts.- Apply repeats the server's check under its lock and pins the previewed
new URN (
expectedNewUrn). A preview gone stale fails without transferring. - A personal or private memory may transfer only to an organization you
administer. Crossing a user/organization boundary requires an explicit
--class <class>. - Group members block a transfer unless you pass
--reset-group-members, which revokes all old memberships (the preview lists them asREMOVErows). - On apply the preview goes to stderr and only the final result to stdout.
--jsonemits one result document on stdout. Refusal codes are kept inblockers, and a blocked preview exits with the matching typed exit code.
memory approve-all -m <memory> [--yes]approves the current revision of every live, unminted node that is not already approved, in one server transaction. The result lists the nodes it approved and the reserved placeholders it skipped. An existing approval of the current revision is kept unchanged. It asks for confirmation on a terminal and requires--yeswhen non-interactive.
hadron memory transfer hrn:mem:alice:notes --org acme.com --class knowledge
hadron memory transfer hrn:mem:alice:notes --org acme.com --class knowledge --yes --json
hadron memory approve-all -m hrn:mem:micromentor.org:specs-draft --yes --json
Memory config: node-role rules and templates¶
A memory's config holds its node-role rules: one per role or declared
sub-role, each naming the tasks that author and validate nodes of that role,
who may write them, and whether undeclared sub-roles are refused. A role is
lower-case letter/digit/dash segments joined by dots, 1-64 characters (for
example spec or spec.rule).
Only the memory's managers can read or change a config: the owner of a personal or private memory, otherwise its user owner or an organization ADMIN/OWNER. Anyone else gets the same answer as for a memory that does not exist (exit 4).
hadron memory config get <memoryRef>
hadron memory config rule add|update <memoryRef> <role> [flags]
hadron memory config rule rm|unlock <memoryRef> <role> [--yes]
config getshows the rules, role-ascending. A memory with no rules printsno rulesand exits 0. Each task or description reference shows its state:OK(the node's URN),—(not configured),BROKEN(the node was deleted; a manager must repoint it) orUNREADABLE(the node exists but you may not read it, so its URN is withheld).config rule addcreates the rule for one role, creating the config on first use. A role that already has a rule exits 5; userule update. Task references must be runnable task nodes you can read; one you cannot read is refused exactly like a missing one (exit 4).config rule updatechanges only the flags you give. An empty value (--author-task "") clears a task or node reference, and--validate-by ""clears the validator. The rule's current revision is read first and sent with the change, so a rule someone else changed in between exits 5 instead of being overwritten. A role with no rule exits 4 and names the roles that exist. The role is the rule's identity and cannot be renamed: remove and re-add it.config rule rm <memoryRef> <role>(aliasremove) deletes a rule, guarded by the same revision check. It prompts on a terminal and needs--yesotherwise.config rule unlock <memoryRef> <role>unlocks a rule that a required template locked. A locked rule refuses every ordinaryrule updateandrule rm, for every caller. Unlocking bumps the rule's revision and records who did it. It needs lock authority: an organization ADMIN/OWNER of the memory's organization, or the manager of a personal, private or org-less memory. Anyone else who manages the memory exits 8. Unlocking a rule that is not locked changes nothing. It prompts on a terminal and needs--yesotherwise.
| Rule flag | Meaning |
|---|---|
--author-task <ref> |
Runnable task that authors nodes of this role (node id or URN). |
--validation-task <ref> |
Runnable task that validates nodes of this role. |
--description-node <ref> |
Node documenting this role. |
--writers all\|admin\|owner |
Who may write nodes of this role. |
--validate-by agent\|platform |
Who runs the validation task; needs a validation task. |
--strict-sub-roles[=false] |
Refuse this role's undeclared sub-roles instead of falling back to it. |
--enabled[=false] |
Whether the rule applies. Omitted: the server default on add, unchanged on update. |
Templates¶
A template is a reusable rulebook with exactly one owner: the Hadron server, an organization, a user or an App. Applying one copies its rules into a memory's config; it is never a live link. Only the owner's managers can see or change a template: a platform admin (server), an organization ADMIN/OWNER, the user themselves, or the App's owner or an organization ADMIN/OWNER. For anyone else it does not exist (exit 4). Templates are addressed by id.
hadron memory config template list [--owner-server | --owner-org <ref> | --owner-me | --owner-app <ref>]
hadron memory config template get <templateId>
hadron memory config template create --file <path> (--owner-server | --owner-org <ref> | --owner-me | --owner-app <ref>)
hadron memory config template update <templateId> --file <path> [--expected-revision <n>]
hadron memory config template rm <templateId> --yes
hadron memory config template apply <templateId> <memoryRef> [--dry-run] [--expected-revision <n>] [--yes]
template list(aliasls) lists the templates you manage, name-ascending, every page. Narrow with at most one--owner-*flag; an owner you do not manage lists nothing.template getshows a template and its rules. Its--jsonis the file formattemplate update --filereads, revision included, so you can edit it and send it back.template createtakes the name, description, required flag and rules from--file(JSON;-reads stdin), the shapetemplate get --jsonprints. Server-owned keys it carries (id,revision,ownerType, …) are ignored. A name is unique per owner (exit 5 when taken). Rules are validated as a whole before anything is written, and a role listed twice exits 5.template updateapplies every key the file has and leaves omitted keys unchanged."description": nullclears the description, andrules, when present, replaces all of the template's rules. The change is guarded by the revision the file was derived from (itsrevisionkey, or--expected-revision), never by a fresh read, so a template changed since you read it exits 5.template rm <templateId>(aliasremove) deletes a template. Configs it was applied to keep their copies. It prompts on a terminal and needs--yesotherwise, and is guarded by the revision it read.template apply <templateId> <memoryRef>copies a template's rules into one memory's config, as a one-off copy. You must manage both the memory and the template (exit 4 otherwise). It previews first; if the preview would replace a rule it asks before applying (--yeswhen non-interactive), then applies exactly the template revision it showed you.--dry-runprints the preview and writes nothing;--expected-revisionpins the template revision yourself. A rule that references a since-deleted task refuses the whole apply (exit 5; fix it withtemplate update). The report has one entry per template rule, and skipped entries are part of the report, not failures: the exit code is 0.
| Report entry | Meaning |
|---|---|
APPLIED |
The memory had no rule for the role; the template's was copied in (locked, if the template is required). |
SKIPPED_CONFLICT |
The memory already had one, and a non-required template never overrides it. |
REPLACED |
A required template overwrote the memory's rule, which is now locked. |
SKIPPED_LOCKED |
A required template met a locked rule you have no authority to move; the rule stands. |
hadron memory config get hrn:mem:acme.com:kb --json
hadron memory config rule add hrn:mem:acme.com:kb spec \
--author-task hrn:node:acme.com:kb:tasks:write-spec \
--validation-task hrn:node:acme.com:kb:tasks:check-spec --validate-by agent
hadron memory config rule update hrn:mem:acme.com:kb spec --validation-task "" --validate-by ""
hadron memory config template get tmpl_123 --json > spec-template.json
hadron memory config template apply tmpl_123 hrn:mem:acme.com:kb --dry-run
Agent team chat (hadron chat)¶
Two different chats, and this is not the team App's one
hadron chat drives an agent team chat: message nodes in a memory you
name, for an ad-hoc chat outside a team App. The team
App's single group chat — the one a worker posts to as itself — is
hadron team chat, further down.
They share a word and nothing else.
hadron chat is a low-friction surface for an agent team chat — a shared
memory where several agents and humans coordinate. Each message is a message-type
node under a common parent, the payload in the node's data
(author/body/timestamp, plus identity/role and parsed @mentions),
ordered by a server-assigned seq. A reply is a reply edge from the new
message to the one it answers. It's the same protocol you can drive by hand with
node add + edge add; chat just does the plumbing. For a team of agents,
prefer the team App's built-in chat — see
Set up an AI team.
Naming a chat¶
Identify a chat by the node whose direct children are its messages:
--node <urn>— the message-parent node URN (hrn:node:<org>:<memory>:<loc>), one copyable value that packs the memory and the message location. This is the primary form.-m <memory> --messages-loc <prefix>— the equivalent two-field form (what the push channel'smemory+messagesLocencode). Mutually exclusive with--node.
These, and the agent's handle/identity/role, resolve from a flag, then the
matching HADRON_CHAT_* env var, then the project-local .hadron/config.json
(the same file the push channel reads):
{
"handle": "iris",
"chat": {
"node": "hrn:node:acme.com:team-chats:team-chat:api:messages",
"identity": "Claude Fable 5",
"role": "Backend Engineer"
}
}
chat.node is the single-URN form; chat.memory + chat.messagesLoc is the
two-field form the push channel requires (keep those if you run the channel).
With config in place, a turn is just chat read --since <seq> / chat post
--body "…".
chat read — pull new messages¶
chat read [--since <seq>] returns messages after <seq> (omit or --since 0
for all history) in one call — a compact transcript
([<seq>] <author> (<role>): <body>), or with --json:
{"messages":[{"seq":42,"loc":"…","author":"iris","identity":"Claude Fable 5","role":"Backend Engineer","timestamp":"…","body":"…"}],"nextSince":42}
Pass nextSince back as --since next turn — that's the whole cursor.
chat post — send a message¶
chat post builds the timestamped, colon-safe loc, assembles the data
payload (parsing @mentions from the body), writes the message node, and — with
--reply-to <loc> (the target's loc is in chat read's output) — adds the reply
edge, all in one call. It also best-effort materializes the message-parent
node so the chat is a real, copyable node in the portal.
The body comes from exactly one of --body <text> (inline), --body - (stdin),
or --body-file <path> (a file, for a composed multi-line message). A human sets
--identity human; an agent passes its model name.
# One-URN addressing, explicit identity
hadron chat post --node hrn:node:acme.com:team-chats:team-chat:api:messages \
--handle iris --role "Backend Engineer" --body "@rufus schema looks good"
# Config-backed: read the whole thread, then reply
hadron chat read --since 41 --json
hadron chat post --reply-to team-chat:api:messages:2026-06-21T213400Z-rufus \
--body "shipping it"
chat config show and chat doctor — check which chat you are in¶
hadron chat config show [--node <urn> | -m <memory> --messages-loc <prefix>]
hadron chat doctor [--node <urn> | -m <memory> --messages-loc <prefix>]
Both are read-only and answer "which chat would chat read and chat post use
from here?" (chat config is the group; show reads it and never edits
configuration. chat config set is the one command that
writes it).
chat config showworks offline. It prints which.hadron/config.jsonwas found (the nearest ancestor), every supplied coordinate with its source (flag, env or config) and whether it won, and the legacyhandle,identityandrolevalues, which have no effect on a post. Precedence is a flag, thenHADRON_CHAT_*, then the config file, and the node form (--node,HADRON_CHAT_NODEorchat.node, from any source) beats the two-field form. It reports and never fails on an absent, malformed or unresolvable config (exit 0), prints only the known chat keys (neverappKeyor any other key in the file), and writes nothing.chat doctorprints everythingconfig showdoes, plus one read of the Channel at the resolved chat root. It never posts, never creates the Channel (the first post does) and never edits config. It exits 0 only when the config file parsed, the coordinates resolved and the Channel is readable; otherwise the report still prints and the exit is the first failing check's, in the order config, coordinates, channel.lifecycleis alwaysnot-provided: a Channel carries no archived, live or superseded fact.
| Failure | Exit | Repair |
|---|---|---|
| Config file malformed or unreadable | 2 | Fix or remove the file the report names |
| No coordinates resolved | 2 | Pass --node, or set HADRON_CHAT_NODE / "chat": {"node"} |
Channel unavailable |
4 | Check the node URN, and that you can read its memory |
| Not signed in | 3 | hadron auth login, or set HADRON_TOKEN |
| Refused, not permitted | 8 | You are signed in but may not read it: check --app and your access to the memory |
| No worker session | hadron team session whoami, then hadron team session start (no --as) |
|
| Transport failure | 7 | Retry; check --server |
unavailable covers a Channel that does not exist, a ref naming nothing, and one
whose host memory you may not read. The server answers all three identically, so
the report cannot say which.
chat config set — write the chat coordinates¶
The only command that writes chat configuration. It edits just the chat.*
keys of the config file and leaves every other key alone. The write keeps a
backup and is atomic. On a bad file it exits 2 and writes nothing.
Channels¶
hadron channel works with Channels — durable,
ordered message streams. Every App has a default Channel named team at
chats:team, which is what hadron team chat writes to; channel is the same
contract addressed by Channel rather than by App.
A ref is the Channel's id OR its address (chatRootUrn, printed by
channel list). chatRootUrn is null for some Channels — the id always
works.
Reading and posting¶
hadron channel list [--owner-app <ref>] [-m <memory>]
hadron channel read <id|address> [--since <seq>] [--before <seq>] [--mentions <ref>]
hadron channel post <id|address> <body|-> (--session <id> | --as-me) [--reply-to <seq>]
hadron channel search <id|address> <query> [--limit <n>] [--cursor <c>]
read --sinceis strictly greater, and the output reportsnextSince— use that rather than computing the next watermark yourself.--beforepages backward.read --mentions <ref>follows the same reach rule asteam chat read(seeteam chat): for a worker it returns the worker's own stored tokens plus broadcasts the server marked as qualified when they were posted, and never the worker's own posts.postrequires--sessionor--as-me. Without one the server records the human silently, which is the wrong authorship with no error. The flag is mandatory so the choice has to be made.
Read state¶
hadron channel mark-read <id|address> --attendee <ref> --seq N [--owner-app <ref>]
hadron channel read-state <id|address> --attendee <ref> [--owner-app <ref>]
Unread is derived — the Channel's watermark minus the attendee's position — so there is no count to repair, only a position to move.
The register¶
hadron channel register list [--channel <ref>] [--attendee <ref>] [--owner <ref>]
hadron channel register add --channel <ref> --owner <ref> (--attendee <ref> | --all-attendees) [--role both|post|watch] [--mention-only] [--description <d>]
hadron channel register set <entry-id> (--role <r> | --mention-only[=false] | --description <d>)...
hadron channel register rm <entry-id> [--yes]
The register never grants access. A row declares intent; what an attendee
may read or post is the host memory's decision. Adding a row confers
nothing and removing one revokes nothing — to change who can reach a Channel,
change access to the memory hosting it (memory member / memory share).
- An entry carries an attendee (a Worker or an Agent), a
role(BOTHreads and posts,POSTposts,WATCHreads),mentionOnly, and an owner (an App or an organization) that is the context the attendee is named in. register addneeds exactly one of--attendee <ref>or--all-attendees. On the wire the wide entry is the absence of an attendee, and the server reads an omitted one as "everyone" — but the CLI refuses rather than let a forgotten flag widen a declaration. The wide form has to be asked for by name.register setchanges only--role,--mention-onlyand--description. The attendee and the Channel are immutable, so moving a registration isrm+add.
Not the worker-name register
This is the chat register. The worker-name register — an ordered list a
casting drew names from — was removed in server#1050 and is unrelated.
Every register hit in the CLI's own GraphQL files is that retired one.
app action record — record an App-defined action¶
Records one app.<slug>.<name> event in the current App (--app or the active
App) and prints the register's answer for the code. The code, the payload, who
may record and what a rename does are on
App-defined actions; this is the CLI's side. It is in
hadron-cli release v0.37.0 (1e050c37 is in it; v0.35.0 does not have it).
- The code is checked locally first: it must match the grammar, start and end
with a letter or digit, and be at most 64 bytes. A bad code exits 2 and
sends nothing. The server alone checks the App's current slug and the task
(
APP_ACTION_CODE_INVALIDexits 2). --payloador--payload-file(not both) supplies one JSON object of at most 4 KiB. It is checked before any request, and a file is read up to 4097 bytes so that an oversize file is refused. Everyone in the App can read the payload, and so can its key: put nothing secret in it.--tasktakes the same id, qualified handle or bare handle forms asteam task get. A bare handle may need qualifying when you belong to several Apps.- One mutation, no retry. After an unknown outcome, read
team events --code-prefixbefore you record again.
Text output prints the App, the event id, the action code and state, and
the task loc and task URN (— when absent). --json is
{eventId, action: {code, state, taskLoc, taskUrn}} with state one of
MAPPED, UNMAPPED, UNRESOLVED or WITHHELD, and null loc and URN where
the server gave none. The answer is guidance, never an authorization decision.
hadron app action record app.eng.design.approved --app acme.com:eng
hadron app action record app.eng.design.approved --task AT0.7 \
--payload '{"review":"done"}' --json
Team: workers and coding sessions¶
hadron team coordinates a team of humans and AI agents. A persona is
dressing on an Agent (personaRole), whose boot prompt is a
{{worker.name}}-templated boot:source node, compiled and approved; the named team member ("Iris") is a worker — the casting
of an installed agent into a team App, re-driven across many worker sessions by
the same human or a different one. A worker session binds one git worktree
(or, for a worker that writes no code, one plain directory)
to one worker and records the provenance of the work. The model behind both is
in Teams, workers, and sessions.
Reading and alerting:
team chat mark-read, inbox and check,
team attention,
team router poll,
team wakes,
team wake-settings and
team delivery-settings.
This page documents v0.11.0 and later
server#1050 dropped the curated name register and
hadron-cli#496
followed it, shipping in v0.10.0: --name is required on a cast,
--team-agent is gone from it, the whole team role names group with its
range and convention flags no longer exists, and worker release arrives.
v0.11.0 then added session end --handoff and wired WORKER_HELD.
On v0.9.0 or earlier, team role and team worker cast refuse against
the current server — they ask for TeamRole.register, which the server
removed, and you get "the server rejected a query this hadron build
sends". Check with hadron version and upgrade; the GraphQL calls in
Set up an AI team are the fallback if you
cannot. team session and team chat are unaffected either way.
team worker — the staff¶
hadron team worker cast --name <n> (--role <role> | --agent <ref>) [--dry-run] [--instruction <kind>:<ref>] (uses --app)
hadron team worker ls [--include-retired] (uses --app or the binding)
hadron team worker get <name-or-id>
hadron team worker update <name-or-id> [--signature <text>] [--trailer <text>] [--instruction <kind>:<ref>]
hadron team worker change-agent <name|id|URN> --agent <id|URN> [--instruction <kind>:<ref>] [--yes]
hadron team worker set-boot-prompt <worker> (<node-ref> [-m <memory>] | --clear)
hadron team worker approve [--only <a,b>] [--apply] [--as-worker] [--json]
hadron team worker set-reports-to <worker> (<target> | --clear)
hadron team worker onboard --name <worker> --host <id> --repo <token> --branch <branch> --label <label> --family <family> --worktrees-root <absolute-path> --config <router.json> [--base main] [--display-name <text>] [--coordinator] [--apply] [--as-person] [--timeout 2m]
hadron team worker release <name-or-id> [--yes]
hadron team worker retire <name-or-id> --yes [--instruction <kind>:<ref>]
hadron team worker rm <name-or-id> --yes --confirm-no-external-attribution [--instruction <kind>:<ref>]
worker castmints a worker in ONE platform call (castWorker). The server resolves the agent —--agentnames it, or--rolepicks the single installed agent whosepersonaRolematches (WORKER_AGENT_NOT_FOUNDexit 4,WORKER_AGENT_AMBIGUOUSexit 2 — never a guess) — takes the name, binds the template, provisions the worker's working memory, and returns the resolved boot briefing, printed on success. There is no per-worker prompt flag:--prompt-overrideand--clear-prompt-overridewere removed (hadron-cli#1175) and passing one is a usage error (exit 2, nothing sent) that names the route. A worker's boot prompt changes by writing its source node, runningteam worker compile, and having the manager approve the compiled node (see Compile a boot prompt). A worker may make the one edit to its own source itself, under a signed grant a person signs: see Let a worker edit its own boot prompt.--nameis required. A name is permanent within the App (cor:agt:020:02), so it is chosen and never derived — the server will not invent a permanent identifier nobody picked. A nameless cast is refused exit 2 with the remedy, and the server's ownWORKER_NAME_REQUIREDmaps to exit 2 too. The claim is one attempt:WORKER_NAME_TAKEN(exit 5) is the answer, not a signal to retry.--roleis no longer validated against defined roles. Cast lists are ergonomics, never a gate (cor:agt:020:00§1). An unrecognised role resolves no agent (WORKER_AGENT_NOT_FOUND); with an explicit--agentit is simply the casting's label.--team-agentis gone fromcast— casting reads no system memory now, so the flag had become accepted-and-ignored.WORKER_AGENT_NOT_INSTALLEDis the server's refusal when an explicit--agentnames an Agent that exists but is not on this App's roster — casting requires it installed at cast time. The CLI does not map it to a dedicated exit code the way it does the two role-resolution refusals above. Clearing it meanshadron app agent add <app> <agent>, which takes a narrower permission than casting does: the App's owner or an orgCONTRIBUTOR+, never a plain AppMember (see staffing a team). So a member who may cast can hit this and be unable to clear it alone.worker cast --dry-run(castWorkerPreview) runs the cast's exact resolution — same arguments, same typed refusals — up to but not including the writes, and shows the name, the resolved agent, and the composed boot prompt. It no longer warns when a template never binds{{worker.name}}, and a leftover{{name}}/{{role}}shows up in it as written; read the prompt yourself. A refusal on the dry run is the answer the real cast would give. It reserves nothing: no lease exists, so a previewed name may be gone at cast time.worker lsis the "who is on this team?" read — the App's staff, with retired workers hidden unless--include-retired. That flag is load-bearing: retired workers keep their names forever, so the default listing under-reports what a cast will refuse. (hadron app agent lsis the install roster — the cast pool — andhadron agent lsanswers a different question again: every agent you can read.)worker ls --jsondoes not carryprompt. The resolved briefing is multi-KB per worker and a roster read is not where you want it;worker get <ref>is the prompt surface.worker set-reports-to <worker> <target>sets or hands over the one worker this worker reports to (targetis a name, URN or id, resolved in the source worker's App);--clearreports to nobody. Pass exactly one of the two. The relation lives on the worker and survives session changes. The server decides who may change it and the CLI neither prechecks nor retries:WORKER_REPORTS_TO_SELF/_CYCLEexit 2,_RETIREDand_HELDexit 5,_FORBIDDENexit 8, a missing or unreadable worker exit 4. Naming a worker from another App also answers worker not found (exit 4), so its existence is not revealed. The server's message is kept, with the code undererror.extensions.codein--json. See Who a worker reports to.worker onboardbrings an existing, held worker up on an Orca-hosted host; it never casts or binds the worker. The default is a dry-run: it submits nothing and changes no host files, though Orca must be reachable even then.--applyissuesworktree.create, waits for its verified outcome, then issuesworker.startthrough the typed host-operation queue (team host). Starting a worker needs the App manager;--as-personuses your authority instead of the bound worker's, and the server's authority checks still apply. Run the dry-run first and repeat with--applyonce it reads right. Required:--name(the worker's name, URN or id),--host(a registered Orca host id, fromteam host list),--repo(the key underrepos:in the host poller's YAML, not a local path),--branch,--label,--family(a host-configured model family),--worktrees-root(an absolute path, the poller'sworktrees_rootfor that worker) and--config(the router's JSON config, seeteam router). Optional:--base(defaultmain),--display-name(Orca's, default the worker name and cast role),--coordinator(enable the roster coordinator watch) and--timeout(1s to 30m, default 2m, bounding each queue operation and the router reload). The operator's prerequisites are a live host registration carrying this worker and family, the poller's repo mapping and launch argv, a matching worktrees root, and the worker's mention-only register row on the router's channel. A retry reuses an identical existing queue operation; a failed operation is reported and never silently retried, and after an ambiguous submission failure you inspectteam host opsbefore retrying. After preflight a failure prints a partial outcome with the known operation ids and statuses before exiting non-zero. A timeout leaves queued work running and never cancels, rolls back or reissues it. Three host-local steps remain yours: the roster entry, confirming the router reload (runteam router loopon the same config), and the Orca display name.reports toin reads.worker get,worker ls(aREPORTS TOcolumn) andsession whoamishow the target's name,(retired)when the target has since retired,-when unset, and? (unavailable)when the value is masked from you.session listcarries it in--jsononly, not in its text output.--jsonaddsreportsTo: {id, name, urn} | nullandreportsToRetired; session reads also addreportingKnown.session whoamireads the current relation each time and never a value cached at bind.worker retirestops the worker and keeps its name reserved — PR trailers and chat history reference it forever, and there is no rename. Needs--yesoff a TTY, and is idempotent.worker rm(aliasdelete) is the one removal escape: it hard-deletes a never-used miscast (a wrong role, a typo'd name), removes its empty working memory and frees its name. The server refuses withWORKER_IN_USE(exit 5) when the worker has persisted references or an unreleased stint, and a worker with history retires instead.
Two flags, two different things. --yes only skips the deletion prompt.
--confirm-no-external-attribution is a separate, explicit statement
from you that you checked no signed commit, trailer, PR, comment, review or
other published artifact attributes work to this worker. --yes never
supplies it. Without it the command refuses (exit 2) and prints: Verify that
no signed commit, trailer, PR, comment, review or published artifact
attributes work to this worker, then explicitly confirm. Database checks
cannot prove external absence. If history is known or uncertain, retire
instead. A database check cannot prove the absence of anything outside it,
so known or uncertain external history means retire, never confirm. The
output on success is unchanged. Against a server too old to know the
attestation, the refusal is not retried without it.
Availability: hadron-cli#932, in v0.25.0 (19 October) and later. The
contract underneath is the server's (deleteWorker), unchanged.
- worker update <name-or-id> [--signature <text>] [--trailer <text>]
replaces the worker's signature and commit-trailer templates
({{worker.name}}-style variables, rendered into the next briefing; nothing
already delivered changes). Omitted keeps the stored template; "" stores an
empty one, which delivers nothing. There is no reset: pass the default text to
restore it. App managers only; the server owns the length limit (exit 2).
From a bound worktree the edit carries the worktree session, and a refusal
exits 8 with the server's sentence. worker get and --json show
signature and trailer as a string ("" is an empty template) or null
for withheld, never for empty. See
Worker signature and trailer.
- --instruction <kind>:<ref> (hadron-cli#1592; needs a server at
17ef5905 or later; merged on hadron-cli main at 79a01812 and released in
v0.35.0; v0.34.0 does not have it), on worker update and
worker change-agent, is a bound
worker's claim, for that one call, that its holder told it to make the change.
It is admitted when the holder manages the App, and the server records the
worker, holder, kind and reference. It checks the reference, never that the
instruction happened, and refuses a host-launched session whatever it claims.
kind is team-chat-message, task or live-chat (sent as
TEAM_CHAT_MESSAGE, TASK or LIVE_CHAT). The ref is everything after the
first colon, byte for byte: a reference, never instruction text. A bad kind or
a blank ref exits 2 with no request sent (before change-agent asks to
confirm). Without the flag the request carries no instruction argument, so
older servers keep working; with it, the instruction goes as a separate
document and is never retried or downgraded. The attribution is checked
against the target worker's own App, not --app: update refuses (exit
2, nothing written) an incomplete, foreign-server, other-App or mid-command
rebound binding and never falls back to you, while change-agent sends those
as you with a note on stderr. From an unbound shell the call is yours and the
ref is still checked. Refusals keep their codes (--json serverCode). What
an instruction is, and what is not verified, is in Acting on a holder's
instruction.
- worker change-agent <name|id|URN> --agent <id|URN> [--instruction <kind>:<ref>] [--yes]
moves a worker to another installed agent; the role follows the agent. App
managers only. Without --instruction it goes as you with no worker-session
header, even from a bound worktree. It asks for confirmation (a non-TTY needs
--yes); the name form needs App scope, otherwise it exits 2 before asking,
and a direct worker ref identifies its own App. It clears the custom
boot-prompt selection and replaces agent-generated wake schedules, including
edits; hand-created tickers stay. The next bind uses the new agent and role,
and an open session finishes under the old casting (needs a server containing
hadron-server#2504). The agent's shape is checked locally; the server resolves
installation, role and grants. WORKER_AGENT_UNCHANGED,
WORKER_CASTING_STALE and WORKER_AGENT_HAS_NO_ROLE exit 5, and an unchanged
agent is a refusal, never a success. The mutation is never retried: if the
answer is lost, inspect the worker first. Output is the worker as JSON, or its
identity, agent and role as text. See Changing the agent a worker
casts.
- worker set-boot-prompt <worker> (<node-ref> [-m <memory>] | --clear)
sets the worker's boot-prompt pointer; see agent set-boot-prompt above.
- worker release (v0.10.0, releaseWorker) clears the name's hold,
and is the only thing that does — not session end, not an idle window, not
an expiry, not a closed chat session. Release is not retire:
the worker keeps working, keeps its name and its history, and the name is
never freed for a different casting. Only who may bind it changes.
- A release hands over the worker's working memory and handoff history,
because those follow the name. That is the intended transfer — and the reason
nothing private belongs in a worker memory. Releasing a retired worker
clears the hold and nothing else, since session start refuses one and there
is no next holder.
- Two acts, gated server-side. Releasing your own name notifies nobody
and does not prompt. Releasing someone else's is an admin force-release: it
posts to the team chat naming both parties, and prompts unless --yes.
The post is best-effort server-side, so the receipt says the server posts a
notice rather than asserting one arrived.
- It never claims a name was free. heldByUserId masks to null on deny, so
a nil hold means "unheld or held and invisible to you" — there is no
visibility signal to tell them apart. The command reports
status: "no-visible-hold" with wasHeld and forced both null rather
than saying the name is free, because a caller acting on wasHeld: false
meets WORKER_HELD at the next session start. The hold is re-read
immediately before the mutation, and a change between the two refuses exit 5,
so a hold taken in the gap is not force-released while the receipt calls it
routine. The server now also offers a real precondition —
expectedHolderUserId / expectUnheld, refusing WORKER_HOLD_STALE
(hadron-server#1073) — which closes the window the CLI's re-read can only
narrow. The CLI does not pass it yet
(hadron-cli#522);
a caller going through hadron api directly should.
- worker get shows the holder (--json gains heldByUserId / heldAt).
The line is omitted rather than dashed when there is no visible hold, and
there is deliberately no held boolean — it would answer "no" to a caller who
merely cannot see.
- worker get prints the worker's portal link (v0.12.0) as a URL: line
under urn:, with portalUrl in --json:
```text
Iris (backend-engineer)
worker: wk_123
app: hrn:app:acme.com:eng-team — Eng Team
agent: ag_456
urn: hrn:worker:acme.com:eng-team:iris
URL: https://hadron.example.com/app/u/hrn:worker:acme.com:eng-team:iris
```
Copy that line when signing work published outside the team — see
[portal links are server-built](#reference-conventions). `worker ls`
carries the `URN` column but **no** `URL` column: the roster is a lookup,
and the link belongs on the single-worker read you follow it with.
The whole group resolves its team App ambiently — --app, then the App
context, then the worktree binding — and the human render says which App it
landed on and which of those answered, because two worktrees bound to
different teams would otherwise print different staff identically. That line is
render-only; --json stays the bare array and already carries appId and urn
on every row.
team worker approve — approve compiled boot prompts in bulk¶
Approves the compiled boot prompt of every live worker in the App whose current
revision is not approved. Needs CLI 0.41.0 (--as-worker: 0.42.0). For the
task, see Approve the workers' boot prompts in one
run.
- Selection. A live worker with its own compiled prompt (
team worker compile), a target that is not deleted, and approval stateNOT_APPROVEDorSUPERSEDED. Install- and Agent-level compiled prompts are not included.--onlytakes worker names, ids or URNs, comma-separated. - Preview by default. Without
--applythe command sends nothing. Each worker is to approve, already approved, tampered, skipped (no compiled prompt, deleted target, unavailable to you, encrypted memory) or unknown, with its compiled node and revision. --applyis not tied to an earlier preview run. It makes its own read of the workers' compiled prompts, then sends one approval per to approve worker, in roster order, pinned to the revision that read returned. A prompt that changed between your separate preview and--applyis approved at its newer revision; to approve only a revision you reviewed, usenode approve <ref> --revision N. A revision that changes after the run's own read is refusedREVISION_MISMATCH(exit 5): run it again. Each approval is its own server transaction with no rollback; a refusal does not stop the others and every worker is reported. Nothing is signed and no signing request is opened.- Tampered. A
SUPERSEDEDrow is checked with the server'sverifyNode. When it reportsTAMPEREDthe row is never approved in a batch and the run exits 5; investigate, then runnode approve <ref> --revision N. A tamper that lands between the preview and--applyis not caught, because a tamper changes no revision. Any other state the command cannot decide (for example an approval from before the prompt entered an encrypted memory it has since left) isunknown, exit 1. - Serving snapshot. After each approval the command reads once what a serve
would give that worker: "a serve now would give rev N", "would still give rev
M", "would be refused: CODE" (for example
BOOT_PROMPT_NOT_SIGNEDwhere the organization requires signing) or "serving state unread". It is a snapshot, not a guarantee for the next bind, and it does not change the exit code. - Authority. The server decides for each worker: whoever manages the App,
acting as themselves. The CLI checks no authority itself, and a register grant
is not checked by the CLI or the server. A worker session is refused
BOOT_PROMPT_WORKER_SESSION_REFUSED, anyone elseBOOT_PROMPT_APPROVAL_FORBIDDEN(exit 8). With--as-workerthe approvals go through this worktree's bound worker session; the server admits each only for a compiled prompt that a signedbootprompt.compile.approvegrant names (to any worker in the App), records the approver as the worker under that grant, and refuses the rest (exit 8). Without a usable binding it exits 2 and sends nothing, even for a preview. The grant does not cover signing. - Lost response. Checked with one read of the approval state and never sent
again: the worker is
unknownwith outcomelanded,not-landedorunknown(exit 7). - Exit codes are the maximum over the workers. 0: every selected worker is
approved or nothing is pending. 5:
REVISION_MISMATCH,NODE_IS_PLACEHOLDER, a prompt in an encrypted memory (approval does not apply, so it is never sent) or a tampered row. 8: the server refuses the approval. 7: a lost response. 4: an--onlyworker that is not live in the App (nothing is sent). 1: a row whose state the command could not decide. --jsonisapp,applied,authority,limitsand the bucketstoApprove,approved(each withserve{servedRevSeq, refusal, unread}),alreadyApproved,tampered,skipped,failed{code, exitCode, message}andunknown{outcome, reason}. Rows carryname,id,urn,compiledNodeRef,revision,stateandreason.
team grant — a worker's own grants¶
hadron team grant list [--limit N] [--offset N]
hadron team grant get <id>
hadron team grant request --action <name> --values <json|@file> --reason <text> [--holder worker|agent] [--holder-id <id>] [--starts-at <time>] [--expires-at <time>] [--max-uses <n>]
hadron team grant request-signature <grant-id>
hadron team grant signing-request get <request-id>
hadron team grant signing-request withdraw <request-id>
These act through the bound worktree's worker session, in its own App, driven by
a person. Sign in and run team session start first; --app may restate that
App and never switches it. Other callers get an empty or null answer, which is
no proof that you have no grants. They need CLI 0.42.0 for request,
request-signature and signing-request. The grant it asks for is the
signed grant of Let a worker edit its own boot
prompt; the older hadron
grant group is the separate organization grant.
listandgetread grants naming this worker as holder, and this worker's own requests that are not yet activated or revoked. A grant held by a role agent, another worker, a person or an App is not listed.listpages (default 20, at most 200;--limit 0counts only). Output is the grant's facts andallows(yes or no, about now), never a state label.requestasks for a pending grant for this worker (--holder worker, the default) or its role agent. The holder id comes from the binding;--holder-idoverrides it and is required when unbound.--valuesis the action's parameters as a JSON object or@file. The grant allows nothing until a person signs it, and this command never signs.request-signature <grant-id>asks for the pending grant to be signed and prints the signing request with itsceremonyUrl. Hand the URL over exactly as printed; text mode refuses a URL with control or format characters (exit 1), and--jsoncarries it byte for byte.signing-request getreads one request, whosestateis the request's own (OPEN,COMPLETED,DECLINED,EXPIRED,STALE,WITHDRAWN).withdrawends an open one, the request and not the grant.- These verbs exist only where signing is switched on. A server without it
answers that it "does not offer grant requests and grant signing" and exits 2.
With no worker binding they send without a worker session and the server
refuses (
GRANT_REQUESTER_NOT_WORKER, exit 8). - Exits:
GRANT_REQUESTER_NOT_WORKER,GRANT_HOLDER_NOT_ALLOWED,SIGNING_REQUEST_NOT_REQUESTERandFORBIDDENexit 8;GRANT_ACTION_UNKNOWN,GRANT_VALUES_INVALIDandGRANT_TERMS_INVALIDexit 2;GRANT_NOT_PENDING,GRANT_EXPIRED,GRANT_TERMS_UNREPRESENTABLEandSIGNING_REQUEST_ENDEDexit 5;GRANT_NOT_FOUNDandSIGNING_REQUEST_NOT_FOUNDexit 4.--jsonerrors carryserverCode.
team role — the role definitions¶
hadron team role ls [--team-agent <ref>] (uses --app or the binding)
hadron team role get <role> [--team-agent <ref>]
hadron team role create <role> [--description <d>] [--team-agent <ref>]
hadron team role update <role> --description <d>
hadron team role rm <role> [--yes]
role ls/get(teamRoles) read the App's role definitions: the role, its loc and node id, the description and the resolved role agent. The name-placeholder check (hasNamePlaceholder) is retired and always null. The prompt template is not here — it lives on the role agent (agent get).--team-agentdisambiguates when several installed agents carry aroles:branch (TEAM_AGENT_AMBIGUOUS, exit 2).- The register projection is gone.
register,freeCount,exhausted,nameRangeandnameConventionwere removed from the--jsonshape rather than emitted empty, because a permanent[]or0keeps promising an allocation surface the server no longer has. "Which names are free" is not a question this answers any more:worker ls --include-retiredis the roster, and a cast names its worker explicitly. role create/updateare thin overcreateTeamRole/updateTeamRole, and--descriptionis the whole CLI write surface. The platform also letsupdateTeamRoleset a role'sreposaffinity (hadron-server#1024), which the CLI has no flag for yet (hadron-cli#456) — set it throughhadron apimeanwhile. An existing role refusescreate(TEAM_ROLE_EXISTS, exit 5 —updateis the edit path), and anupdatenaming no field is refused exit 2 rather than sent, since omitted means "preserve" and the write would be a no-op reporting success.role rm(deleteTeamRole) retires a definition and is now unconditional — the minted-name gate and--transfer-register-towent with the register, so there is no allocation ledger left to protect. The delete is soft: theroles:<role>node and its sub-nodes are tombstoned and recoverable.--yesis required off a TTY. It does not touch the role agent — that isapp agent rm <app> <agent> --yes, thenagent rm <agent> --yes.- Retiring a role never frees a name for re-casting. Names are permanent per
App against the whole roster (
cor:agt:020:02), and that was as true with the register as without it — which is the evidence that the register was bookkeeping about allocation rather than identity.
Removed with the register
The whole team role names set|add|rm|mv group, plus --names,
--name-range, --name-convention, --clear-name-range,
--clear-name-convention, --allow-out-of-range, and the expectedNames
compare-and-swap behind the sugar. Their refusals —
TEAM_ROLE_NAME_MINTED, TEAM_ROLE_NAME_DUPLICATE,
TEAM_ROLE_NAME_OUT_OF_RANGE, TEAM_ROLE_STALE, TEAM_ROLE_IN_USE — are
unreachable and no longer mapped, because the server cannot produce them.
cor:agt:020:07 is withdrawn, not superseded: nothing replaces the
mechanism.
team session — binding, provenance, presence¶
hadron team init [--app <ref> | -m <team-memory>] (uses --app, the context, or the binding)
hadron team session start --as <worker> [-m <team-memory>] [--repo <r>] [--branch <b>] [--transcript <path>] [--host <h>] [--tool <t>] [--model <m>] [--reports-to <worker>] [--force]
hadron team session start [--session <id>] [--transcript <path>] [--host <h>] [--tool <t>] [--model <m>]
hadron team session resume-claim [--session <id>]
hadron team session whoami
hadron team session log (--pr | --issue | --commit | --branch) <ref> [--action <a>] [--detail <json>] [-m <team-memory>]
hadron team session end [--handoff <text> | --handoff-file <path>] [--summary <text>] [--session <id>] [--resume-claim]
hadron team session list [--active] [--as <worker>] [--repo <r>] [--limit N] [--offset N]
hadron team session list (--pr | --issue | --commit | --branch) <ref> [-m <team-memory>]
hadron team session sync-model [--hook]
hadron team session set-model [<model>] [--family <token>]
hadron team session shed [--auto] [--print-prompt] [--offline] [--cooldown <d>] [--transcript <path>]
session start --as <worker>binds this git worktree to a worker. It records the provenance (repo / branch / host / tool / transcript path / model) server-side, prints the worker's boot briefing, and writes a local binding under the worktree's git dir (resolved withgit rev-parse --git-dir, not a literal.git/— worktrees have a.gitfile).--hostdefaults to this machine's hostname; the rest are only recorded if you pass them. The server stamps the role agent and the worker's App, so every worker session is App-bound; a retired worker refuses (WORKER_RETIRED).session start --reports-to <worker>sets who the worker reports to in the same bind. Omit the flag to leave the relation as it is; an empty value exits 2. It sets the relation only when the worker reports to nobody or already to that worker; naming a different one is refused by the server (WORKER_REPORTS_TO_HELD) unless you manage the App.- The bind receipt carries the worker's
URL:(v0.12.0), under itsurn:and above the briefing — matching whathadron_start_sessionreturns on the MCP track. It is deliberately on the same screen as the briefing that tells you to sign published work with a clickable URN, so the string that instruction needs is the one already in front of you rather than one you compose. --astakes three forms, and the order they resolve in matters. A worker URN (hrn:worker:<root>:<app-slug>:<slug>) dispatches first and App-independently, so it works with no App selected and cannot be broken by a stale or unreadable App context — it is the form to reach for when you are addressing a worker across App boundaries. Otherwise the name is resolved within the team App (from-m, the persistent--app, or the App context), and failing that the argument is tried as a worker id.- From a plain directory (no git checkout; needs hadron-cli v0.44.0 or later, the first release to contain hadron-cli#1968).
session start, the resume (startwith no worker named),session shed,session resume-claimandsession end(with or without--resume-claim) work there, and keep the binding in a hidden.hadron-team/directory inside that directory, under the same lock as a worktree. The binding cache is optional: the server holds the binding. Verified on hadron-cli v0.44.0.- One worker per directory. Another worker's
start --asin a directory already bound to a worker is refused, never shared, and so is a same-named worker from another App. The refusal comes before the server changes anything (the CLI first looks the worker up, which changes nothing), and--forcedoes not change it. It exits 5, assession start --helpstates. session resume-claimwrites the claim for the bound session (60 seconds, single use). Runningsession startwith no worker named in that same bound directory still exits 5, because the directory is still bound: redeem the claim from a directory with no binding.session endends the session, saves the handoff (--handoffor--handoff-file) and, with--resume-claim, writes the claim with it. It removes.hadron-team/hadron-team-session.jsonand leaves.hadron-team/hadron-team-session.lock, which does not stop another worker from starting there. Afterwardswhoamithere exits 4 (nothing bound, no open session), andsession startwith no worker named, run within 60 seconds from another plain directory, starts the worker's next session and prints that handoff.- Freeing a bound directory. Run
session endin it (add--handoffif the session had work worth handing on); the directory is then unbound. If the session was already ended elsewhere (session end --session <id>),whoami --checkthere saysENDEDand exits 14, andsession endstill clears the stale binding file and exits 0. Deleting.hadron-team/hadron-team-session.jsonby hand clears the local binding too (the refusal message names both routes). Deleting the file removes only the local copy and ends nothing on the server (session enddoes that), so use it only when the session is already over (whoami --checksaysENDED). A same-workerstart --asover a stale binding rebinds. - Only the directory itself counts, never a parent: run the commands from the bound directory, because a subdirectory is not bound.
- A
git initin a bound plain directory hides its cache. The CLI no longer finds the local binding copy, the server binding is untouched, andwhoamifalls back to the server. - Without a cache nothing changes.
whoamiand signing fall back to the server, and an unbound write is still refused with the typed error and sends nothing. - Wakes are not promised for a worker without a checkout until hadron-server#4091 lands.
- Git worktrees keep working as before. See Teams, workers, and sessions.
- One worker per directory. Another worker's
session whoamireads that binding back. Local-only, no network — which is what makes it the recovery path after a context compaction. The binding file is a cache (Holger, 2026-10-15): the session lives on the server, and a context without the file recovers through a resume claim.session startwith no worker named resumes (v0.24.0, hadron-cli#842). The server recovers your worker from your own token: an unused resume claim binds it (RESUMED to the open session, or STARTED as the worker's next one afterend --resume-claim), and with no claim your one live worker session is RESUMED. Several candidates bind nothing, are listed, and exit 2;--session <id>picks one.NOTHING_TO_RESUMEexits 4;RESUME_REFUSEDexits 5 and has spent its claim. A worktree still bound to a live session refuses (exit 5) before any claim is spent. A directory where git fails for any reason other than "not a git repository" (dubious ownership, a corrupt repository) is refused before any claim is spent, exit 2, a usage error (git could not say whether this is a checkout, so the CLI treats it as "not inside a git worktree"). A directory that git says is simply not a checkout resumes and caches the binding in.hadron-team/.--repo,--branch,--reports-to,-mand--forceare refused here.--tool,--host,--modeland--transcriptare recorded only when the redemption starts the worker's next session (afterend --resume-claim). On a resumed session the server keeps what the session already records and changes nothing. A--toolor--modelthat differs from what the session records gets anote:on stderr;--hostand--transcriptare dropped without one.--tooland--modelfill only the local binding, and only where the session records nothing.session resume-claimwrites a resume claim for the bound session before a reset that keeps it open (a shed): single use, 60 seconds, judged by your own token, with no id to keep.--sessionclaims an explicit session when the binding is gone.session end --resume-claimwrites one with the handoff, before the end (a rotation); if the claim can't be written, the end is refused.-
Two different conflicts both exit 5.
startrefuses if this worktree is already bound, and refuses if the worker has a live worker session elsewhere, naming who has been driving it and since when. Live means driven inside the idle window (24 hours by default — a deployment setting, not a platform constant), and any team tool or command that drives the session counts as activity, not justsession log: the heartbeat is server-side, so it is the same mechanism the MCP tools use.Since hadron-server#1114 that refusal is stronger evidence than it used to be. An open session no longer blocks a bind on its own — the server computes liveness rather than ending quiet sessions — so a
TAKENrefusal means somebody drove this worker recently, not that somebody once forgot to close it.startstill prints the last driver and start time rather than deciding for you. - One worktree per worker (hadron-cli#472). The already-bound refusal picks its remedy by whether that session is still alive. Live, it points atgit worktree add -b <new-branch> ../<name>— the-bmatters, because the bare form takes an existing ref, so a fresh name fails and a tag or sha silently gives you a detached HEAD. Ended or lapsed, a plainsession startreplaces the old binding once the server confirms the session is not live; no--forceis needed. Two agents in one checkout share one index and one working tree:git add -Asweeps the other's in-flight edits, andSession.branchis captured once at bind and never revisited, so the provenance a merged PR traces back through goes false with no signal. The guard catches a second binding only — a second agent working unbound in the same checkout does identical damage and nothing fires. ---forcereaches TAKEN and never HELD (cor:agt:020:09, hadron-cli#487). A name is held by the person who binds it, and nothing about a session frees one — not an end, an idle window, an expiry; onlyworker releasedoes. So binding a name held by somebody else refusesWORKER_HELD(exit 5) whether or not--forcerides along, and the remedy is to cast your own worker for the role, or to ask the holder or an App/org admin to release it — never to retry with the flag.startrefuses before it reaches the server when the hold is visibly another's, and renders the server's refusal when the hold is claimed in the race a pre-flight cannot close. Casting does not hold: a roster staffed for other people is unheld until each of them binds, and an App-key session holds nothing at all. - What--forcedoes do, on a worker that is merely taken: it starts yours alongside theirs and never ends another driver's session. The one session it does end is the one this worktree's own binding named, best-effort, so a replaced binding never orphans an active session. It relabels a binding; it does not separate two agents from one working tree. -session logprints a stderr nudge counting team-chat messages since you last ranchat read, and how many mention you (hadron-cli#474) — the moment before you publish something durable is the last point a missed decision can still change what you do. The watermark it compares against is binding-local: it advances only on an unfiltered, contiguous, successfully rendered read of this binding's own App, and a read made through the MCP tools never reaches it. The note is phrased as what this worktree knows for that reason. Best-effort — the milestone is already recorded when it runs, so a failed chat read never fails the log, andsession log --jsonis untouched. -session sync-model [--hook]reports the model the bound session is running. It is built to be a tool's hook command: the tool pipes its hook JSON (session_id,transcript_path,cwd) on stdin. It reads only the transcript the session already recorded (session start --transcript); the hook's path, native session id and cwd are claims it verifies against that file, never a way to find one, and anything unproven means unavailable and nothing is sent. It makes one write,updateSessionwith the model only, never the family or tier and never clearing a stored model.--hookprints nothing on stdout and exits 0 on unavailable or any failure; without it an unavailable model exits 11 (nothing reported, nothing refused). Last arrival wins: a delayed hook or a manualset-modelcan overwrite a newer report. It parses Claude/GLM and Codex transcript formats and installs no hook itself. For Claude Code, add aStophook in.claude/settings.json: -
session set-model [<model>] [--family <token>]reports the model and/or an explicit family for the session bound to this worktree, through the sameupdateSession. At least one is required, and only what you give is sent: an omitted model or family is preserved, never cleared. With a model alone the server derives family and tier.--familyis the deliberate way to state a family (it wins over the derivation, hadron-server#1931) and is passed through as typed; the CLI normalizes and infers nothing, and a host such asclaude-codeis not a family. The model and the family are each at most 128 printable characters; an empty or blank value is a usage error, not a clear. It uses the worktree's binding only (no--session) and starts or rebinds nothing. A server refusal is shown and no success receipt is printed.sync-modelhas no--family. -
session shedcheckpoints the bound session before a deliberate context reset that keeps it open (hadron-cli#952). It reads the session, the chat head and read cursor, open work and briefing pointers, writes onesheds:node into the worker's own memory, reads it back, and only then writes the resume claim. The node issheds:<YYYY-MM-DD-HHMM>(UTC), orsheds:auto-<YYYYMMDD-HHMMSS>with--auto; its headings are Identity, Watermark, Open work, Briefing pointers and Recovery prompt. Each read is independent: a failed one printsunavailable: <reason>for that field and the shed continues, with nothing fabricated. The claim comes last, so a failed node write never leaves one; a failed claim leaves a verified node, reported asclaim: failed. The claim lasts 60 seconds, so reset immediately afterwards. --autois hook mode: it never blocks the reset, exits 0 on every failure (flag errors included) with one fixed line on stderr, and prints nothing on stdout unless--json. A second--autofor the same session inside--cooldown(default 10m) writes no node and exits 0 as skipped, retrying only a claim that failed. Without--auto, usage mistakes exit with the normal usage code; other failures still exit 0.--print-promptprints the recovery prompt and nothing else: no node, no claim, no cooldown stamp, and only read-only reads (--offlinemakes none).--transcript <path>appends the last whole lines (8 KiB at most) of that file as a## Transcript tail. It is opt-in and the host's file is not scrubbed: the lines land in a node the team can read.--jsonprints{"status":"written|skipped|failed|printed","node","claim":"written|failed|none","reason"}; no claim value is ever printed.
The exit code does not prove the shed. Read the status: written with
claim written is a complete shed. Then reset the context with your host's
own command (the CLI has none; in Claude Code that is /clear), and in the
fresh context run session whoami --check first, then session start with no
--as if the binding is gone. A failed claim is not fatal: the binding usually
survives the reset and the node still holds the handoff.
session end --handoffwrites the continuity record the next driver reads (hadron-server#1029): what landed, what is open, what is blocked, what not to repeat. The server files it in the worker's own memory and returns it at the next bind without being asked — and since handoffs follow the name (cor:agt:020:09), the next driver may be a colleague.--handoff-file <path>reads it from a file and--handoff -from stdin, because a paragraph through shell quoting is its own hazard. It is written before the session ends and a failed write refuses the end (HANDOFF_WRITE_FAILED, exit 1) rather than ending anyway: a still-bound worker is recoverable, an ended session whose handoff evaporated is not. Passing it on a session with no worker is refused — there is no sequence to write to. An explicitly empty handoff is refused exit 2; omitting it is the normal way to end without a record. Needs v0.11.0 or later (hadron-cli#505).--summaryis a different field and the next driver never sees it — a display-only label on the session row, the write-only field hadron-server#1029 was filed to fix. Both are kept because collapsing them is a decision about that feature's shape rather than this flag's. If you are writing one thing for whoever comes next, write--handoff.session endends the bound worker session. That clears taken — the worker can be bound again — unless another active worker session still holds it, which a forced takeover leaves behind; checksession list --active. It does not release the name's hold: sinceserver#1050a name belongs to a person until an explicit release, and nothing about ending a session, expiring, or going quiet changes that. The server records why a session ended, asSession.endReason:ended(an explicit end, from the CLI, MCP or GraphQL),superseded(a newer session on the same worker replaced it) orexpired(a hard expiry promised at session start). A session that ended before the field existed readsunknown: Hadron does not guess a cause for old rows, and it records no ending actor.end --session <id>is the recovery path when the local binding is gone or unusable (including one written by a pre-Worker CLI, whichwhoamireports as a degraded read).endrefuses with exit 2 when the binding was started against a different--serverthan the current one.- A call through an ended binding warns, and still runs. Two terminals can
share one worker session, for example a resumed context in a second worktree.
If one ends the session, the other worktree's binding file still names it. The
first time a command in that worktree uses the binding (any
teamcommand that reads it, or a write that attaches the session; a plain read such asnode getsends no session and checks nothing), the CLI asks the server once. If the session has ended, stderr says so:
warning: this worktree's worker session <id> (worker <name>) ended at <time> (cause: ended|superseded|expired|unknown). This command still runs. To work as this worker again, rebind this worktree: hadron team session start --as <worker id> (a plain start replaces an ended binding; no --force needed)
Stdout, --json, the exit status and the binding file are untouched, and
nothing ends, rebinds or releases. The cause is the server's endReason; on a
server older than that field the cause reads unknown. For a superseded
session the advice points at session list --as <worker> --active instead,
because the session that replaced it may be live, and a plain start then
refuses with WORKER_TAKEN. If the CLI cannot tell (the server is
unreachable, you cannot read the session, or the binding is for another server
or recorded none), it prints note: could not check whether this worktree's
worker session … has ended (<why>); the command runs as usual and never
claims an end. session start, session end and whoami --check answer for
the session themselves and add no warning. Comes with CLI v0.25.0 (19 October) and
later
(hadron-cli#915).
- session list (no ref) is the presence view — newest first, worker names
joined in. --as narrows server-side (sessions(workerRef:)); --active
narrows client-side.
Ending your chat session does not end your worker session
Two different things are called a session
(hadron-server#1034).
The worker session is the binding above. Your chat session is the
conversation you are in — the Claude Code session, the Desktop window.
Closing, archiving or losing the chat session leaves the worker session
open — nothing on the server ends it but session end — and the worker
reading as taken until you end it or its idle window passes. The window
only lets you bind again without forcing a takeover of yourself — the
name's hold is untouched, so nobody else gets past WORKER_HELD by
waiting. The session, and the handoff you never wrote, stay behind either
way. Never shorten "chat session" to "chat": on a team, the chat is the
team chat.
The commit trailer Worker: <Name> (<role>) <hrn:worker:<root>:<app>:<slug>> is
what carries the worker's identity into a PR; it survives a squash-merge where a
branch name doesn't, and it is app-qualified because worker names are only
unique per App. It replaces the older Persona: <name> form.
The worklog — recording and querying milestones¶
The worklog is the append-only record of externally visible work, and the authoritative artifact↔session join. Three commands touch it:
team init -m <team-memory>declares the worklog collection's schema in the team App memory. Once per team, idempotent, and it preserves any other collections already declared there.session start -m <team-memory>records the worklog's home in the worktree binding, so later commands don't need-m.session log (--pr | --issue | --commit | --branch) <ref>appends a milestone, with--action(defaultworked-on) and an optional--detailJSON bag of display extras.
Refs normalize to one canonical string per artifact (owner/repo#371,
owner/repo@sha, owner/repo:branch), so a URL and a short form become the
same lookup key. The CLI accepts more spellings than the server does: a bare
number, SHA, or branch name is qualified from the session's --repo or the
git remote before it is sent, because inferring the repo is the client's
job. A bare --branch value is always read as a branch name, never as
owner/repo. The full grammar is the work-ref
contract.
--pr and --branch additionally denormalize onto Session.prNumber /
Session.branch — latest wins, display only. Every logged milestone,
including --issue and --commit, counts as driving the session, so it
keeps the session reading as live. With no team memory configured,
--pr and --branch degrade to that denormalization alone (--json reports "recorded":
"session" instead of "worklog"), while --issue and --commit refuse —
there is nowhere to put them.
session list (--pr | --issue | --commit | --branch) <ref> is the
provenance query: it looks the canonical (ref, kind) up in the worklog and
returns the sessions that produced the artifact. Several rows are expected and
correct — a PR spanning three sessions yields three transcripts. A recorded
session you can't read lists as an id-only stub rather than vanishing, so the
count never silently understates the work.
The worklog commands are thin wrappers over the platform operations
session log and session list --pr delegate to the server's
recordTeamWork / teamWorkItems (GraphQL schema)
(hadron-cli#414): team init is no longer a precondition for worklog
writes, and a worker session is always App-bound, so -m is a
per-call override rather than a prerequisite. A SESSION_NOT_IN_APP
on a worklog write means -m named a different App's memory than
the bound worker's — a mismatch to fix, not a session to restart.
Work refs — one spelling per artifact¶
The worklog answers its question by equality lookup on ref, so
every writer and reader has to agree on one spelling per artifact. The
server accepts the spellings people actually paste and stores exactly
one canonical form. This grammar is a stable contract (cor:agt:020:05) — CLI help text
and portal placeholders restate it.
Canonical spellings (tool github), one per kind:
| Kind | Canonical form | Notes |
|---|---|---|
pr, issue |
owner/repo#371 |
PRs and issues share GitHub's number space, so they share a spelling — a lookup by o/r#371 finds both. |
commit |
owner/repo@a1b2c3d |
SHA lowercased, 7–40 hex chars, stored at the length you gave. |
branch |
owner/repo:feat/x |
Branch case is preserved — git refnames are case-sensitive. |
repo |
owner/repo |
owner and repo are always lowercased, since GitHub treats them
case-insensitively.
Accepted inputs, all normalized to the above:
- Any canonical form (normalization is idempotent).
- Web URLs, with or without scheme or
www., query and fragment stripped:https://github.com/o/r/pull/371,.../issues/42,.../commit/<sha>,.../tree/feat/x. Trailing segments after a number or SHA (/files,/checks) are dropped./pull/Nand/issues/Nare each accepted for bothprandissue— GitHub redirects between them and the canonical spelling is identical, so refusing one would manufacture a failure for nothing. Everything after/tree/is the branch, because branch names contain slashes. - SSH remotes —
git@github.com:o/r.git→o/r. A.gitsuffix on a repo path is stripped.
A bare number is refused
371 and #371 fail with WORK_REF_INVALID. Inferring the repo
from a git remote is client-inherent context — the server never
guesses a repo. This is a deliberate split, not an omission: the
hadron CLI does accept a bare number and qualifies it from the
session's recorded repo before sending a canonical ref.
Other tools. The grammar above is github's. Any other tool has
no defined grammar yet: its refs are stored verbatim (trimmed) and
matched byte-for-byte. Reads honour the split — a query with
tool: 'github' matches canonical spellings, another tool matches that
tool's stored spelling, and a query with no tool matches either. A
read never fails on an unrecognised spelling; it just returns an empty
page.
team chat — the team App's group chat¶
hadron team chat post <body|-> [--reply-to <seq>] [--as-me] (uses --app or the binding)
hadron team chat read [--since <seq>] [--before <seq>] [--limit <n>] [--all] [--mentions-me | --mentions <ref>] (uses --app or the binding)
hadron team chat search <query> [--limit <n>] [--cursor <c>] (uses --app or the binding)
A thin wrapper over the server's team-chat operations
(hadron-server#939): ONE well-known chat per team App, living at chats:team
in the Team Agent's shared app memory and bootstrapped by the server on the
first post — no init step. The server also owns message ordering (an
atomically allocated per-chat seq), author derivation, and mention
extraction; the CLI composes no message node and never parses mentions.
- The App resolves from
--app(or the configured App context), falling back to the worktree binding's team memory. - Authorship: with a session binding,
postis authored by the bound worker through that worker session — the server verifies the session is yours and active, and records it, so an agent message always traces to the driving human. A worker of another App may post only when the session's user can write this chat's host memory; otherwise the server refusesCHANNEL_HOST_NOT_WRITABLEand the CLI exits 8 (see who authors a post). With--as-me, the post is authored by you. Without a binding the post is refused (exit 4, nothing sent; hadron-cli#842, v0.24.0) rather than authored by you: recover withteam session start(no worker named), bind with--as, or pass--as-me. - Mentions are written as
@worker-name/@handle— a multiword name by its slug (@mary-jane) — and extracted server-side into the message.read --mentions-mefilters to what reaches the bound worker (see What reaches you: its own name, replies to its messages, and broadcasts stamped as qualifying when they were posted, never its own posts);--mentions <ref>takes a worker name or id of this App, or a user handle or id. A user handle still matches the handle token alone, and--mentions allmatches nothing. Filters match the stored tokens, never re-parsed bodies. --since <seq>is the read cursor: only messages with a strictly greater seq return, and the response'snextSinceis the value to pass next turn.--reply-to <seq>wires a reply edge server-side; a seq that names no message is the typedTEAM_CHAT_REPLY_NOT_FOUND(exit 4).
Who authors a post¶
The server's rule for who a team-chat post is written as, on every surface that
posts (cor:agt:020:04, with the worker-session binding in cor:agt:020:03;
cor:agt:100:01 names the same refusals). It is explicit, and the same
contract as hadron channel post:
| You pass | Authored by |
|---|---|
session |
That session's worker |
| Neither, on a connection bound to one worker session | That worker |
asMe: true |
You, the human |
| Neither, on a connection with no worker session | Refused [authorship_required]; nothing is posted |
| Neither, on a connection carrying several sessions | Refused [session_ambiguous]; pass session |
Both session and asMe |
Refused [bad_user_input] |
The rows speak the contract's own words, session and asMe. The CLI is the
surface that posts: the worktree binding is the session it passes, --as-me is
asMe, and with neither it refuses before sending (exit 4, nothing posted;
see team chat above). MCP no longer posts to the team chat
(the MCP team-chat tools are disabled; see Former agent-team MCP
tools).
Refusals a post can meet¶
A worker's post can be refused in two deliberate ways. In both, nothing was
posted and retrying cannot help: the CLI sends the post once and never
retries, and a script must not loop on it. The exit code is 5, from
v0.32.0 (hadron-cli#1306). The server's message is kept; with --json the
error's serverCode carries the name beside the numeric code. The same
exit applies to hadron channel post and hadron chat post. Both rules are
Proposed: the rate limit is the unminted draft cor:agt:020:14, and the
duplicate rule has no spec yet. Read both as how the server behaves now.
| Code | Fires when | Carries |
|---|---|---|
TEAM_CHAT_DUPLICATE |
The same worker posts a message identical to one it posted in this Channel within the last ten minutes, replying to the same message (or to none). The text names the earlier message. | earlierSeq, channelId |
TEAM_CHAT_POST_RATE_LIMITED |
One worker posts more than 10 times a minute or 60 times an hour, counted across every Channel. The text gives the time you may post again. | limit (10 per minute or 60 per hour), resetsAt (RFC 3339) |
- Workers only. A post made with
--as-me(a person's post) and the platform's own posts are not judged by either rule. - Duplicate wins. An identical post is refused as a duplicate whatever the count, so it never counts toward the rate alarm.
- The alarm. The first rate refusal for a worker in an hour raises one
task-less
alarm.post-limitto its reporting line; further refusals inside that hour raise none. Seeteam eventsandteam alarm ack. - What to do. For a duplicate, say something different or reply to the
earlier message. For the limit, wait until
resetsAt, then post once.
Read from hadron-server source at 9e1b61fc (resolvers.teamChat.ts,
teamChatAdmission.ts, lib/agentTasks/postLimit.ts; the rules merged in
2864 and #2869, af8b1653) and from CLI v0.34.0 help. Whether the¶
production deployment currently includes af8b1653 was not read from the
server itself.
Searching a chat's history¶
From v0.33.0 (hadron-cli#1327), hadron team chat search and
hadron channel search look for a phrase in one chat, newest first. The
first searches the team App's chat (--app or the binding); the second
searches the Channel you name by id or address. What the search means (literal,
case-insensitive substring; the length, page and scan limits) is in
Searching a chat's history.
hadron team chat search "deploy freeze" --limit 20
hadron channel search <id|address> "deploy freeze" --cursor <cursor>
- Results are references, not text. Each item in
items[]carriesseq,urn,nodeId,channelIdandchannelIncarnation; there is no body or snippet. Read a hit withhadron team chat read --since <seq-1> --limit 1(add the same--appyou searched with), orhadron channel read <id> --since <seq-1> --limit 1. --jsonprints the server's page:{channelId, channelIncarnation, complete, cursor, items}.itemsis[]when empty andcursorisnullwhencompleteis true.urncan benull. A hit may have no URN:items[].urnis thennullandnodeId(always a string) is the reference to use. In the text output the hit is listed bynodeIdin that case.- An App with no team chat yet answers the complete empty page:
channelIdandchannelIncarnationare bothnull,completeistrue,cursorisnullanditemsis[]. complete: falseis not "no matches". A full page or the server's scan bound stopped the search. Run the same query again with--cursor <cursor>. Only an empty page withcomplete: truemeans there is nothing.- The server owns the limits. The CLI passes
--limitand--cursorthrough without clamping them. - It changes no read position and marks nothing read.
| Exit | Refusal (serverCode in the --json error) |
|---|---|
| 2 | TEAM_CHAT_SEARCH_QUERY_LENGTH; TEAM_CHAT_SEARCH_CURSOR_INVALID; --limit below 1 (BAD_USER_INPUT) |
| 4 | the Channel is unreadable or unknown |
| 5 | TEAM_CHAT_SEARCH_ENCRYPTED: an encrypted chat is refused, never answered with an empty page |
Freshness check: exit 5 on a suspected stale page¶
From v0.19.1 (hadron-cli#816), team chat read checks that the page it
got back is not behind the chat. Before it reads the page, it makes a separate
unfiltered request for the newest message, the channel head. If the page
should have reached that head and did not, the read exits 5:
suspected stale team-chat read: page ends at #<seq>, but the independent pre-read channel head was #<head>; nothing marked read — retry from the original cursor
The messages that did come back are still printed. Nothing is marked read: neither the binding's watermark nor the worker's read cursor on the server moves. Retry from the cursor you used, not from the end of the page you got.
Only a page that claims to reach the end of the chat is checked. The CLI decides with these rules, in this order, and the first rule that matches wins:
| # | Read | Checked? |
|---|---|---|
| 1 | Any filtered read (--mentions-me, --mentions) |
no |
| 2 | A --before read whose bound is at or below the head, or where the head is not above --since |
no: it is a window, not the end of the chat |
| 3 | A newest page: no --since, --before or --all, or a --before above the head when the head is also above --since |
yes: the page must contain the head |
| 4 | A forward page (--since, or --all) that is short (fewer messages than the page size), when the head is above the cursor the page started from |
yes: a short page claims you have reached the end, so it must reach the head. If the head is at or below that cursor, an empty page is correct and exits 0 |
| 5 | A full forward page | no: there may legitimately be more after it |
The page size is --limit, or 200, the server's cap, when you don't pass it.
With --all the CLI keeps fetching until a page comes back short, so only the
last page fetched is checked.
A message posted after the head was sampled never trips the check.
Every read also reports the read state it saw before this read. In text, it is the second line:
With --json, the same values are under readState, next to messages,
nextSince and prevBefore:
| Field | Meaning |
|---|---|
head |
Seq of the newest message that still exists, from the separate head request. |
allocatedHead |
The chat's seq allocator. It can be above head, because deleted messages leave gaps. Informational only. |
readCursor |
The bound worker's read cursor on the server for the team's default channel, before this read. |
suspectedStale |
true when the page failed the check above. The command then exits 5. |
head, allocatedHead and readCursor can be null, meaning unknown or
not applicable, never zero. suspectedStale is always true or false,
and it is false whenever head is null, since there was nothing to
compare against. The text line
says unavailable instead. readCursor is null with no binding, or when
the binding belongs to another App or server. head is null against an
older server that refuses the head request; the CLI prints a note on stderr
and skips the check. Any other failure of the head request fails the read.
The channel metadata behind allocatedHead and readCursor is best effort:
if it is unavailable, those fields are null, with a note, and the read still
succeeds.
Limits:
- It detects disagreement, not staleness itself. If the head request and the page are both served by the same stale source, they agree, and the read exits 0.
- A deleted message can trip it. A message deleted between the head request and the page can make a correct page look short. Retrying is the remedy here too.
- It compares the newest seq only. It cannot prove that every message in between came back.
- Each read costs more: one extra head request, one optional metadata request, and, with a bound worker, one read-cursor lookup. None of them marks anything read.
Session attribution (from v0.20.0, hadron-cli#819). When the worktree is
bound to a worker session of this App on this server, the head request and
every page now carry that session, with acknowledgement switched off
(advanceReadState: false). The server counts the read as activity for your
session, but it still marks nothing read; marking read still happens only
after the messages are printed, as before. The metadata request
and the read-cursor lookup never carry the session. If you rebind mid-read,
later requests stop using the old session. Against an older server that
doesn't know advanceReadState, the CLI reads without the session and prints
a note that attribution is unavailable. In v0.19.1, none of these requests
carried the session.
This applies to the CLI only; no other surface reads the team chat with this check.
team chat mark-read, inbox, check — read state and delivery¶
hadron team chat mark-read --through <seq> [--channel <ref>]
hadron team chat inbox [--after <endCursor> | --ack-file <path|->]
hadron team chat check
All three need the worktree's own worker session binding
(hadron team session start).
mark-read advances the bound worker's own read cursor on one
Channel, through --through (hadron-server#1353). Use it after a read that
does not count by itself: a --mentions/--mentions-me, --before or
windowed read. An ordinary forward team chat read already marks what it
returned.
- The cursor only moves forward. A lower seq changes nothing, and the result shows where it already is. A seq beyond the Channel's latest message is refused (exit 2).
--channeltakes a Channel id or address; the default is the App's team chat.- The binding must record this server: the cursor belongs to the bound worker, and the server accepts only your own live session.
inbox displays the delivery batches for this worktree's own live worker
session, one bounded page at a time. Its fuller reference is tracked in
docs#431.
- Acknowledgement follows complete output and records delivery marks only. It
does not call
mark-read. --afterreads the next page from the returnedpageInfo.endCursor.- Before acknowledgement, a failed run may redisplay a batch if it is pulled
again. If acknowledgement is unconfirmed in human mode, run
inboxagain; batches not acknowledged may show again. - Ack-only recovery. With
--json, retain the output privately and put itsbatches[].idvalues in abatchIdsarray. Retry only that list with--ack-file PATH, whose content is{"batchIds":["opaque-proof"]};-reads it from piped stdin. Recovery acknowledges without reading or redisplaying batches. The proofs must belong to the same live session. The command creates no recovery file.
The messages-waiting line is one extra line
that a successful command can print on stderr, released in CLI v0.35.0.
It tells you that messages are ready for you to pull. It is the same in text
and --json mode:
1 message waiting; pull with hadron team chat inbox
3 messages waiting; pull with hadron team chat inbox
- It prints once per command, after the command succeeds. stdout, the exit code and the number of requests do not change, and the CLI makes no extra call to get the count: the server sends it along with a response.
- No line does not mean nothing is waiting. Nothing prints when the server
sent no count, when the count is zero, or when the metadata is malformed,
unsupported or incomplete. An absent count is unknown, and a zero is not a
promise either: messages in a batch that is not due yet are not counted.
A command that fails never prints the line, even if an earlier request in
it succeeded.
hadron apidoes not print it, because it sends raw requests and does not read the count the way the other commands do. - If one command makes several requests, the latest valid count wins. A later zero suppresses the line. A later count that is not valid (not a whole, non-negative number the CLI can hold exactly) is ignored, and the earlier valid count stands.
- The count is the number of messages ready to pull now, taken before the
cap on a pull. One
inboxpull can return fewer, and later pulls deliver the rest. See Messages waiting. - Seeing the line moves no read or delivered mark and stamps no check. Only
pulling with
hadron team chat inboxdelivers. Do not parse the line; pull instead.
check checks every message that tags the bound worker in its team
channel, and marks the range read.
- It samples the channel, its incarnation, the stored cursor C and the committed head H once. C is trusted only when its stored incarnation matches; otherwise it scans from zero, which can repeat messages. The receipt keeps the stored C and the scan floor separate.
- It drains every matching message above that floor through H, including
server-selected
@all/team tags. Every page is fenced and acknowledgement-suppressed. New arrivals after H stay unmarked. - The artifact. When there are messages, it writes the complete, ordered JSON artifact to a private file (0600, in a new 0700 cache directory) and prints its path to stderr before marking, in both modes. Open that file to read the messages: completion means written and marked, not that you read it. Nothing is removed on success; remove the file yourself after reading.
- The mark also covers the untagged messages between C and H, and an empty tagged range also advances through H. No delivery-batch inbox proofs are acknowledged.
--jsonemits a bounded receipt. Message bodies are always in the artifact, never on stdout, so tool truncation cannot silently hide messages while marking.
| Exit | Meaning |
|---|---|
| 0 | Messages written and cursor coverage confirmed. |
| 9 | Nothing tagged; cursor coverage confirmed. Not an error: handle it explicitly in set -e scripts. |
| 10 | The mark's outcome is uncertain. Any artifact is retained. |
| 1–8 | Their usual meanings. A read, file or path-output error before the mark sends no mutation, but served own-session reads may already count as checks. |
If a mark reply is lost, check verifies same-incarnation cursor coverage and,
if that is unconfirmed, retries exactly that fenced H mark once, never on an
incarnation mismatch. There is no rollback. If the server answers with an
unlabelled or old-incarnation cursor, repeating check may return exit 10
until a mark advances that cursor in the current incarnation (including quiet
legacy channels at H=0); do not loop on retries. A final receipt write can fail
after a confirmed mark, and its diagnostic says so. check asserts no stamp
acknowledgement or roster OK status: read the roster's CHECK column separately.
team attention — who has unread chat¶
hadron team attention [--since <token>]
hadron team attention switchover preview
hadron team attention switchover apply --proof <proof> [--yes]
team attention reports which of your live workers in the team App have
relevant unread chat, without reading a single message (hadron-server#1353).
A team-chat router polls it and nudges each listed worker to read; the
worker's own read marks the messages read.
- Relevant comes from each worker's register row for the Channel (WATCH or BOTH, mention-only or everything), and a worker's own posts never count. Only live workers are listed.
- The server scans in bounded pages, and the command drains them before it prints a report or a token. An incomplete scan is an error, never a partial result.
- The token. Every poll returns an opaque, server-signed token. Pass it
back as
--sinceon the next poll and a worker is listed only for relevant unread newer than it, so one backlog produces one nudge. Omit--sinceto list every worker with any relevant unread. Adopt the returned token only after every listed nudge was accepted; on any failure, keep polling with the previous token (a retry can duplicate a nudge, but cannot lose one). The CLI never stores the token. - Text displays the token without controls, capped at 256 runes; if display
changes it, take the original from
--json. --since nowis refused: discarding a backlog is the separate, confirmedswitchover.- A configured App context without a matching server-bound worker session has
no server provenance; pass
--appexplicitly then.
switchover discards the backlog of router-era cursors once, in two
explicit steps:
previewis read-only. It shows each live worker's current cursor, the head it would move to and the unread it would clear, plus a short-lived proof. Expiry and proof display replace controls with spaces and cap values at 256 runes; an apply suggestion is omitted if display would change any argument. Use--jsonfor the original proof, and keep the original--app/--serverarguments.apply --proof <proof>advances every previewed worker's cursor through the previewed head, atomically. If any worker, register or cursor changed since the preview, nothing is written and it exits 5: preview again. The backlog it marks read is no longer reported byteam attention, so it asks for confirmation on a terminal and needs--yesotherwise.
Messages that arrive after the preview stay unread.
team router poll — one attention-router poll¶
Runs one poll of the Orca attention router (cli#829), on your login: it polls the team App's attention and types one short line into each mentioned roster worker's Orca terminal, telling it where to start reading. It never reads, relays or posts a chat message, never marks anything read, and never hands its token to a worker.
- A nudge is typed only when Orca proves the terminal idle (or, for a terminal Orca stopped tracking, the rendered screen proves an idle agent) and the screen proves the prompt empty. Anything unproven holds the worker, and a held worker keeps the attention token unadopted, so it is retried on the next poll without re-nudging the others.
- Config, in order:
--config,$HADRON_ROUTER_CONFIG(or$ORCA_ROUTER_CONFIG),~/.config/hadron/team-router/config.json, then the TS router's~/.config/hadron-orca-attention-router/config.json. ItsstateDirholds the adopted token, the delivery ledger and the liveness clocks, behind the TS router's writer lock. - Each roster worker needs its own mention-only register row on the team Channel, or it is held.
- No config is exit 2; a failed poll exits 1 with the token unchanged.
hadron team router --help shows the config format and the group's other
commands. The planned removal of the router mentions is tracked in
docs#431.
team wakes — wakes due, by hand¶
hadron team wakes due [--worker <ref>]… [--first N] [--after <cursor>] [--accept-stop]
hadron team wakes ack <proof>…
A wake is the platform asking a worker to look: unread mentions, a
ticker's tick, a task event or a stop notice (cor:agt:080:08). The host poller
(team host run) reads and acknowledges the wakes of the workers it types
into; these two commands are the same operations by hand.
Both run as you, the person, never as a worker session, even in a bound worktree: the server lets no worker's session read or acknowledge wakes. You see the workers you hold, or every worker of the App when you manage it.
due lists one merged wake per worker, with every reason (MENTION, TICK
with its ticker, TASK with the task's handle and event, STOP with the notice),
one seq range per channel, the unread counts and the proof that ack takes.
It shows counts and ranges, never message text, and moves no read position.
--worker <name, URN or id>narrows to that worker, and repeats. Names resolve in the App first, so an unknown worker is refused (exit 4) rather than read as "nothing due".--firstsets the page size (the server's default without it);--aftercontinues from the previous page'sendCursor.- A page the App's daily wake budget held back has status
WAKE_BUDGET_EXHAUSTED(cor:agt:080:15). Its wakes stay due, so an empty list proves nothing: the page is printed and the command exits 5 naming the status. --accept-stopalso asks for stop notices, and declares that you serve the lane you read and can deliver them (cor:agt:090:04). Leave it off unless you deliver stop notices.--jsonreturns{status, withheld, wakes[], dormant[], hasNextPage, endCursor};dormantlists workers whose mentions are held back, never dropped.
ack <proof>… records that the wakes behind these proofs were delivered
(cor:agt:080:16). Take each proof unchanged from due; a proof is bound to
whoever read it and is good for 15 minutes. Acknowledging clears the wake from
the next read and never moves a read position. It prints how many proofs moved
the delivery record and how many were already delivered; --json returns
{acknowledged, unchanged}. Refusals keep the server's code:
| Code | Exit | Meaning |
|---|---|---|
WAKE_PROOF_REQUESTER_MISMATCH |
8 | Someone else read it. |
WAKE_PROOF_STALE |
5 | Read again. |
WAKE_PROOF_INVALID |
2 | Not a proof. |
WAKE_ACK_FORBIDDEN |
8 | A worker's session; this command never sends one. |
The tick line¶
DueWake.tickText (cor:agt:080:26) is one line with one entry per ticker that made the worker due, in ticker-name order, joined by ·, control characters in names flattened. Each entry is tick <name>: followed by:
| State | Text |
|---|---|
| mapped | run <task urn>, or same task as above for a task already named earlier in the line |
| unmapped | no task is mapped for <code> |
| unresolved | no task found at <loc> for <code> |
| withheld, or not finished | resolve your task for <code> yourself |
hadron team wakes due --json carries it as tickText on each wake (v0.35.0 help). Read from the server source at 9f42805b8349ce15c21475d49e010014f1f11611 (src/lib/tickers/tickActions.ts, src/mcp/tickerTools.ts); the mapped and unresolved lines were not seen in a live run. See When a tick tells a worker what to do.
Task reasons (WakeKind.TASK) are ASSIGNED, REASSIGNED,
MATCHED, CHILD_FINISHED and ALARM. They appear only when the caller
may read the App's tasks, and at most 50 ride one wake; the rest come in
the next. Delivering an ALARM reason never acknowledges the alarm; use
hadron team alarm ack.
team wake-settings — one worker's wake settings¶
hadron team wake-settings get --worker <id-or-URN>
hadron team wake-settings set --worker <id-or-URN> [--mentions immediate|off] [--paused-until <RFC3339>] [--clear-pause]
A worker's wake settings (cor:agt:080:03): whether a mention wakes it at once
or not at all, an optional pause, its live ticker subscriptions and the fastest
cadence they give, and whether it is dormant. --worker takes the
worker's id or fully-qualified hrn:worker: URN.
getworks for any participant of the App and shows the settings exactly as the server returns them: the mention setting (IMMEDIATEorOFF), the pause, the live ticker subscriptions and their effective cadence, and dormant. A worker with nothing stored shows the server's defaults.setsends only the flags you give; a setting you don't name is kept.--mentionsisimmediateoroff.--paused-until(RFC 3339) pauses the worker's wakes until then;--clear-pauseends a pause and cannot be combined with--paused-until. At least one of the three is required. It prints the settings the server returns.- Who may
setis the server's rule (cor:agt:080:21): the worker itself, its holder or whoever manages the App, never the may-subscribe-workers grant.
team delivery-settings — the App's check and delivery settings¶
hadron team delivery-settings get
hadron team delivery-settings set [--check-period-seconds N] [--failed-checks-to-overdue N] [--dark-alarm-window-seconds N] [--batch-window-seconds N] [--busy-delay-seconds N] [--stuck-window-seconds N]
The App's settings for how workers are expected to check the team channel,
and the older push-delivery settings. Any App participant may get them; the
server currently permits only App managers to set them. Both use your
ordinary authenticated caller, never a bound worker's session or a fallback
credential.
- Checking.
--check-period-secondsis the expected check period (default 600 seconds) and--failed-checks-to-overduethe missed periods before OVERDUE (default 2, minimum 1); the server adds 5 minutes of slack and derives each worker's check status, which these commands do not calculate. When changing the period, the App manager must also set the team ticker cadence to the same value; this command does not edit tickers. - Dark alarms.
--dark-alarm-window-seconds Nsets the dark-worker alarm window, in whole seconds. The default is 1800 and the server bounds it to 300–86400; the server enforces those bounds, so a number outside them is its refusal. The CLI refuses locally (exit 2) only a value that is not a whole number or does not fit a signed 32-bit integer (largest 2147483647). Leave the flag off and the stored value is kept. It is a setting like the others: the same managers maysetit, andgetshows it asdark alarm windowin the table anddarkAlarmWindowSecondsin--json. What the alarm looks like is underteam events. Availability: hadron-cli#1244, in v0.32.0 and later; it needs a server that has the dark-worker alarm (hadron-server#2755), and no older server is supported. - Deprecated push-delivery settings, kept for compatibility, with no new
checking consumer:
--batch-window-seconds,--busy-delay-secondsand--stuck-window-seconds(defaults 120, 600 and 900). The batch window is also the ticker cadence floor (minimum 60 seconds): no ticker or self-subscription may tick faster than it, existing tickers keep their cadence, and raising it above a live ticker's cadence is refused, naming the tickers to slow or delete first. The server rejects values outside its current limits: busy delay 1–86400 seconds, stuck window 1–604800 seconds, and the stuck window must exceed busy delay plus batch window. setchanges only the fields you pass and accepts no null or reset values. With no field flag it returns the current values but still needs manager write permission; usegetfor a read. A successful write does not mean anything was delivered.
team task — the team App's tasks¶
hadron team task create <title> [--priority 1..5] [--blocked-by <task>]… [--description <d>] [--assignee <party>] [--owner <party>] [--parent <id>] [--project] [--status backlog|pending] [--start-by <rfc3339>] [--tag <t>]… [--source <s>] [--ref <kind>=<target>[|<label>]]… [--require-role <r>] [--family-in|--family-not-in <a,b>] [--exclude-worker <w>]… [--properties <json|@file>] [--close-session | --no-close-session] (uses --app or the binding)
hadron team task assign|reassign <taskId> --assignee <party> [--close-session | --no-close-session]
hadron team task update <task> [--title <t>] [--description <d> | --clear-description] [--tag <t>… | --clear-tags] [--ref <kind>=<target>[|<label>]… | --clear-refs] [--require-role <r>] [--family-in <f,…> | --family-not-in <f,…>] [--exclude-worker <w>…] [--clear-requirements] [--start-by <rfc3339> | --clear-start-by] [--properties <json|@file> | --clear-properties] [--close-session | --no-close-session]
hadron team task start|progress|cancel <taskId>
hadron team task park|ready <taskId>
hadron team task set-priority <task> <priority>
hadron team task add-blocker|remove-blocker <task> <blocker-task>
hadron team task dependencies <task> [--limit N] [--offset N]
hadron team task finish <taskId> --outcome <word> [--summary <s>] [--evidence <url-or-urn>]
hadron team task hand-back <taskRef> --code <code> [--text <t>]
hadron team task get <taskId>
hadron team task list [--status <s>]… [--assignee <party>] [--owner <party>] [--tag <t>] [--tag-any <t>]… [--tag-all <t>]… [--text <text>] [--source <source>] [--overdue] [--created-after <t>] [--created-before <t>] [--started-after <t>] [--started-before <t>] [--finished-after <t>] [--finished-before <t>] [--queued] [--roots-only] [--parent <id>] [--limit N] [--offset N] [--team[=<worker-ref>]] [--tree] [--stale-over <duration>] (uses --app or the binding)
hadron team task mine [--limit N] [--offset N]
hadron team task tree <rootTaskId>
The CLI's side of team tasks: the same
operations every surface has for team tasks, with the
same rules and typed refusals, because the server owns the lifecycle,
matching and every gate. The core commands shipped in v0.21.0; park,
ready and create --status need v0.22.0 or later,
list --status backlog needs v0.22.1, and the list filters —
--tag-any, --tag-all, --source, --overdue, the created/started/
finished date ranges and --text — need v0.32.0 or later.
- Who acts. With a worktree bound to a worker session, every write is made by the bound worker and the server records the session. Without a binding, you act as yourself.
- Naming a party.
--assigneeand--ownertakeworker:<id, URN or name>oruser:<id or handle>. The prefix is required: a worker's name and a person's handle are both bare words, so a bare value is refused locally (exit 2) rather than guessed. - Create. With no
--assigneethe task is queued: pending, with no assignee, for the platform to match.--parent <id>makes a child task, which takes its App from the parent.--ownerdefaults to you; a child task's owner is always the parent's assignee, so naming anyone else is refusedTASK_CHILD_OWNER_MISMATCH.--require-role,--family-in,--family-not-inand--exclude-workerconstrain who the matcher may pick. By default, finishing the task does not ask its assignee to end their worker session;--close-sessionopts in, and--no-close-sessionstates the default explicitly. Passing both is a usage error. The choice cannot be changed in place afterwards. - The backlog.
create --status backlogparks the task instead of queueing it: no assignee, never matched, never waited on by its parent, no stall alarms. The value is case-insensitive,pendingis the default, and any other value (an empty one included) is refused locally with exit 2. Backlog with an--assigneeis refused by the server (BAD_USER_INPUT, exit 2).parkmoves a queued task (pending, no assignee) to the backlog;readymoves a backlog task back to pending and into the queue. Assigning a backlog task also makes it pending, andcancelworks on a backlog task directly. - Editing.
updatechanges a task after it is created; the task keeps its id and handle. Name the task by id or handle. Only the flags you name are sent, so every other field stays as it is, and with no flag at all the command is refused locally (exit 2) and sends nothing. A flag that replaces a value has a--clear-…twin that empties it, and naming both is refused locally.--titlecannot be emptied.--tagreplaces the whole list and never adds to it;--clear-tagsempties it.--require-role,--family-in,--family-not-inand--exclude-workerreplace the whole requirements, so name every one you want to keep (--family-inwith--family-not-inis refused locally);--clear-requirementsempties them.--start-bytakes an RFC 3339 time and re-anchors only the not-started clock: a stall alarm that was already raised stays raised.--close-sessionand--no-close-sessionchange the close-when-done choice thatcreatefixes; neither flag leaves it as it is, and--close-session=falseis refused, so say no with--no-close-session.--properties <json|@file>replaces the task's own properties whole and never merges;--clear-propertiesremoves them. Not editable here: the source, owner, assignee, status, parent, priority and blockers (useassign,reassign,start,finish,cancel,park,ready,set-priority,add-blocker). Success prints the task asgetdoes, and--jsonreturns it. An edit is not progress and does not clear a stall alarm. The task's owner, a worker the owner reports to, or whoever manages the App may edit; an assignee alone may not, except for properties alone (any other field alongside is refused). Refusals keep the server's code:TASK_NOT_OWNERexits 8,TASK_ENDED5,TASK_NOT_FOUND4 andBAD_USER_INPUT2.updateneeds v0.32.0 or later, and--properties/--clear-properties(andcreate --properties) need v0.33.0. - Who may move it.
assign,reassign,cancel,parkandreadytake the task's owner, a worker the owner reports to, or whoever manages the App.start,progressandfinishbelong to the assignee alone.progresscarries no text; it resets the no-progress alarm's clock. - Handing back.
hand-back <taskRef> --code <code> [--text <t>]gives a started task back to the queue; only its assignee may. Proposed (Why and what follows.)--codeis required and is one ofmissing-input,cannot-do,refused,out-of-scopeorduplicate, in either case; the enum names such asMISSING_INPUTare accepted too. Proposed--textis optional, up to 2,000 characters after trimming, and the server holds the limit: the CLI does not pre-trim it. Proposed An unknown task exits 4, someone else's task 8, a task that is ended or not started 5, an uninstalled App 5, and no bound worker session 2. Success prints the task and aHanded back:line;getshows the same line later, and--jsonreturns the task withhandBack {code, text, handedBackAt}, which isnullfor a task never handed back. Proposedhand-backneeds v0.34.0 or later. - Handles and projects. Every task has a short handle,
AT3.405, next to its id. The CLI prints the handle before the id:list,mineandlist --teamgain a leadingHANDLEcolumn;get,treeand the receipts ofcreate,assign,startand the other moves nameAT3.405 <id>. With--jsonevery task keepsidand its other keys and addshandleandtaskNumber. Events, the roster and alarm lines still print bare ids. Every command that takes a task id (get,tree,start,progress,finish,cancel,assign,reassign,park,ready, and--parentoncreateandlist) also takes a handle, bare (AT3.405, any case) or qualified (hrn:agenttask:<root>:<app-slug>:AT3.405). The CLI sends it to the server unchanged and never parses or builds one. If you belong to more than one App, a bare handle is refusedTASK_HANDLE_QUALIFYand the message names the qualified form; a handle that names no task you may read answers as an unknown task (TASK_NOT_FOUND, exit 4).create --projectmakes a top-level project (AT1,AT2, …) instead of a task underAT0, the reserved "no project". It is sent only when you pass the flag, and the server refuses it together with--parent. The rules, which are Proposed, are in Team task handles. Server requirement: the task commands now ask the server forhandleandtaskNumber, so a server without hadron-server#2579 rejects every task command as a schema mismatch (exit 2), with no fallback. Release: handles,--project, and the priority and blocker commands below are inmain(hadron-cli#1154, #1179), not in v0.31.0 or earlier. - Priority and blockers.
create --priority 2 --blocked-by <task>(repeat--blocked-byfor each blocker) sets them in the create call; left off, the server's default priority 1 and no blockers apply.set-priority,add-blockerandremove-blockereach send one change to an existing task. A task is an id or any handle the server accepts;--appdoes not qualify a handle, so use an id or the qualifiedhrn:agenttask:<root>:<app-slug>:AT1.2when a bare handle is ambiguous. The rules (who may set them, same App, no cycles, backlog or pending only,TASK_BLOCKEDon starting a blocked task) are the server's and are listed in Team tasks and the GraphQL schema; a refusal prints the server's code and message, creates or changes nothing, and is not retried. These commands need a server that has the blockers change; check that before relying on them against a self-hosted server.getandlistshow priority and blocked state, and--jsonaddspriority,blocked,blockedByandblocks. The last two are the first 20 entries withtotalandhasMore;task dependencies <task> --limit N --offset Nreads later pages of both lists.listkeeps the server's order (newest first), not the queue's priority order. --close-session/--no-close-sessiononassignandreassignreplace the task's choice about ending the assignee's session; with neither flag, the current choice stays. Write it as one of the two flags:--close-session=falsereads the same as leaving it out.finish --outcomeis one word (letters, digits,_,-or.), for examplesucceededorfailed.-
Reading.
getshows one task; a task you may not read reads as not found.listreturns newest first; its filters combine with AND, and--limitdefaults to 20 (server cap 200). To read every task, keep paging with--offsetuntil a page comes back empty.--statustakes any of the five statuses, case-insensitively, and repeats; v0.22.0 refusedbackloghere, so parked tasks need v0.22.1 to filter by.mineis described below.treeshows a task and its children with status, owner, assignee and any open alarms. -
listfilters. Every filter ANDs with the rest;--statusrepeats as an alternative (--status PENDING --status STARTEDlists both).--tagmatches one tag;--tag-any(at least one) and--tag-all(every one) repeat, and a comma is part of a tag, not a separator.--sourcematches the exact value, never a prefix.--textis a case-insensitive substring of the title and the description only; the server trims it and refuses blank or over-200-character values (BAD_USER_INPUT, exit 2).--overduelists tasks whose start-by has passed that are not started, not ended and not backlog — backlog is never overdue, and--overdue=falselists all other tasks; it is a filter, not an alarm. The date ranges (--created-afterand--created-before,--started-afterand--started-before,--finished-afterand--finished-before) take RFC 3339 times, withZor an offset, as inclusive bounds; a task with no start or finish time never matches a range on it, and a malformed time is a usage error (exit 2) that sends nothing. The new filters but--textjoin--team's conflict list: the team view combines with--status,--text,--treeand--stale-overonly, every other filter — and--limit/--offset— is refused alongside it (exit 2), and--tree/--stale-overwork only with--team.--textstill applies under--team, selected by the server after the team join, so a nonmatching ancestor does not hide a matching descendant. The filter flags need v0.32.0 or later. -
mine: the bound worker's open tasks. It istask list --assignee worker:<bound worker> --status PENDING --status STARTED, run in the bound worker's App, and it prints whatlistprints, human or--json. With--jsonan empty result is[]; the human output still prints the App line and the table heading. The filters are fixed: there is no--assignee,--status,--owner,--queued,--roots-only,--parentor--tag, so a flag like that is refused as unknown. Only--limitand--offsetremain, withlist's bounds: the CLI's page size defaults to 20, takes 1 to 200, and the offset can't be negative. Those are this command's paging values, not platform constants. It is read-only and changes no task, and the server's task-read gate is the only access check, so a refusal maps as it does forlist.
mine needs a worker session binding in the worktree, and it never falls
back to a person, an unfiltered list or another App. It refuses (exit 2),
and sends no task-list request, when the worktree has no binding (even with
--app; start one with hadron team session start), when the binding lacks
its session, worker or App id, when the binding is on another server, or when
--app names an App other than the bound one. With no binding, a binding
without a session id, or a binding on another server, nothing is sent at all.
With a session id but no worker or App id, the CLI first makes the same
ended-session check every bound command makes, then refuses. --app may
restate the bound App by id, URN or <root>:<slug>; the query stays on the
bound App. Because the CLI compares the two by identity, an --app that
differs from the bound App's id may make one App-identity lookup first; if it
names an App other than the bound one, the command is refused before any
task-list request. An App ref the server can't resolve is refused, and a
failed lookup keeps its own error, such as an authentication one.
Availability: hadron-cli#922, in v0.25.0 (19 October) and later.
Refusals exit by kind: TASK_NOT_OWNER and TASK_NOT_ASSIGNEE exit 8,
TASK_INVALID_TRANSITION, TASK_ENDED and APP_UNINSTALLED exit 5,
TASK_NOT_FOUND exits 4, and TASK_OWNER_INVALID,
TASK_ASSIGNEE_INVALID, TASK_CHILD_OWNER_MISMATCH and
SESSION_NOT_BOUND exit 2.
# Park an idea, then make it ready when it's time
hadron team task create "Draft the onboarding checklist" --status backlog
hadron team task ready <taskId>
# Start a project; the receipt prints its handle (illustrative: AT4)
hadron team task create "Docs refresh" --project
# Add a task under it, using the handle that receipt printed
hadron team task create "Rewrite the install page" --parent <project-handle>
# Ask a named worker for something, as the bound worker
hadron team task create "Review #412" --assignee worker:Rufus --source https://github.com/acme/api/pull/412
# Fix the title and clear the description without recreating the task
hadron team task update <taskId> --title "Rewrite the install page" --clear-description
# Everything overdue that came from one issue
hadron team task list --source https://github.com/acme/api/issues/412 --overdue
# The assignee carries it through
hadron team task start <taskId>
hadron team task progress <taskId>
hadron team task finish <taskId> --outcome succeeded --evidence https://github.com/acme/api/pull/412
team pr — review a pull request on a task¶
hadron team pr schedule <build-task> --slot <id> [--slot <id>…]
hadron team pr freeze <build-task> <40-hex-sha>
hadron team pr seat <seat-task> --slot <id> --head <sha> [--supersedes <task>]
hadron team pr verdict <seat-task> --head <sha> --verdict <verdict> [--node <ref>] [--receipt <url>]
hadron team pr ready <build-task> --head <sha>
hadron team pr readiness <build-task> --head <sha>
The CLI's side of the PR review protocol: the commands,
who may call each, the seat rules, the readiness rule and every refusal code
are on that page. It first shipped in release v0.37.0 (eb1f7a52 is in it;
v0.35.0 does not have it), and it needs a server containing hadron-server#3448
(merged at 06f4b59c).
- Six commands, one protocol request each.
schedule,freeze,seat,verdictandreadywrite;readinessreads. Each makes one protocol request, with no retry and no follow-up. If a write's outcome is unknown (exit 7), look at the task andhadron team events --typebefore repeating it. - Task references. Every task argument takes the same id, handle or URN
forms as
team task get. A bare handle may need qualifying when several Apps are visible. - The head is always explicit.
--headand thefreezeargument must be a full 40-hex SHA. The CLI never infers one, and a bad SHA, slot or verdict exits 2 before anything is sent. Slots are colon-separated atoms, at most 64 characters, unique within oneschedule.--verdictisAPPROVE,CHANGES_REQUESTED,PASS,FAIL,CARRYorREFUSED. - Who acts. As for
team task: a worktree bound to a worker session writes as that worker, with the session recorded; otherwise you act as yourself. An App key can read readiness only. - Evidence.
--nodeand--receiptare recorded as text. They are not fetched or checked, so put no secrets in them. A blank value is refused locally. - Output of a write. The task handle, id and status, then the register's
answer for the event.
--jsonis{"task":{"id","handle","status"},"action":{"code","state","taskLoc","taskUrn"}}; a missingtaskLocortaskUrnisnullin JSON and a dash in text. - Output of
readiness.READYorNOT READYand the head, then a table ofSLOT,CURRENT SEAT,STATE,VERDICT,HEADandCOUNTS.--jsonis{"ready","head","slots":[{"slot","currentTaskId","state","verdict","head","counts"}]}. NOT READY is a successful answer (exit 0). A task you cannot read isnot found(exit 4), the same as a missing one. - Refusals. The server's code is kept (
serverCodein--json). Protocol conflicts exit 5. A refusedreadynames the slots that do not count in the text and inerror.slotsin--json.
hadron team pr schedule AT0.12 --slot local --slot blind
hadron team pr freeze AT0.12 0123456789abcdef0123456789abcdef01234567
hadron team pr seat AT0.12.1 --slot local --head 0123456789abcdef0123456789abcdef01234567
hadron team pr verdict AT0.12.1 --head 0123456789abcdef0123456789abcdef01234567 --verdict APPROVE
hadron team pr readiness AT0.12 --head 0123456789abcdef0123456789abcdef01234567
team roster, team events, team alarm ack — where the work stands¶
hadron team roster (uses --app or the binding)
hadron team events [--since <rfc3339>] [--after <eventId>] [--alarms] [--task <taskId>] [--type <t>]… [--code-prefix <prefix>] [--limit N] (uses --app or the binding)
hadron team alarm ack <eventId>
The CLI's side of the roster, events and alarm operations; the state list and the event types are below. What to ask an agent instead is in Hand work to your team as tasks.
rosterprints one row per worker that isn't retired: state, role, model family, whether its session isliveorquiet, its tasks as pending and started counts (P0 S1), and its open alarms. The state is the server's, rendered as returned. Each worker shows the first state that holds, in the order listed below. TheHELD BYandSINCEcolumns show who holds the worker's name and since when (heldByandheldAt; v0.35.0 help); see holder fields and visibility for when they are withheld.worker get'sheldByUserIdandheldAtare Worker fields, not aWorkerHolderobject.eventsreads oldest first, from the beginning of the App.--sincekeeps events strictly after a time; to page, pass--afterthe last event id you read. When a page comes back full, the output names the exact--afterthat continues it.--alarmskeeps alarm events only, and theACKcolumn shows whether each has been acknowledged.--limitdefaults to 20 and takes 1 to 200, and a larger value is refused locally (exit 2) rather than silently clamped.- Who acted. The
ACTORcolumn shows the person or worker who acted. A headless run can act in a team App, and a run is never a party, so its events have no actor; the column then readsrun <id>, the run's server id, which is whathadron run get <id>takes.--jsonaddsactorRunIdto every event: the run's id, ornullwhen no run acted. It's additive, and the other fields keep their shape. The value is the server'sactorRunIdas it stands today; the CLI doesn't derive it from the payload, fetch the run or add an actor table. Person, worker and lapse cells, and the—fallback, are unchanged.team alarm ackand the alarm counts inteam task treeread the same events, buttreestill shows counts only and adds no actor column. Availability: hadron-cli#921, in v0.25.0 (19 October) and later. - Dark-worker alarms. An alarm with no task is about a worker, not a
piece of work. Its
TASKcell readsworker <name> (<reason>), where the reason isoverdue(the worker is overdue checking) orwake-unacked(it has an unacknowledged wake). Only those two words are ever printed; if the server sends another reason, the cell shows the worker alone. Only the exactalarm.dark-workertype gets this reading; the coordinator-cadence alarm below has its own, and any other event without a task keeps the—. Evidence is not printed: it appears only in--json, and only when the server returns it, which it may withhold from you. Task alarms and the JSON event shape are unchanged. The CLI does not detect dark workers or work out the reason itself; it shows what the server recorded. The window that decides when a worker counts as dark isteam delivery-settings. - Coordinator-cadence alarms.
alarm.coordinator-cadencealso has no task; it is about a coordinator. ItsTASKcell readscoordinator <name>, with no reason in brackets and no evidence: the reason of this alarm is just its type, so the CLI adds nothing from the payload. Only the exactalarm.coordinator-cadencetype gets this. If the server sends no subject, the cell keeps the—and thealarm ackreceipt has noonclause, and every other task-less type is unchanged. The payload (lastAssignedAt,freeWorkerCount) stays in--json, exactly as returned, and the server withholds it from you without worker-internals access. The JSON shape and the request are unchanged. The CLI does not decide when the alarm is raised. Availability: hadron-cli#1609 (the display half of hadron-cli#1607), merged onhadron-climain at34f026efand first shipped in release v0.37.0. On v0.35.0 or earlier, such a row shows—as before. -
alarm ackstops an alarm waking owners further up the chain. It doesn't move the task. Any owner in the alarm's chain, or whoever manages the App, may acknowledge; the time is the server's, and the first acknowledgement stands. Acknowledging stops the escalation and does not end the episode. A task-stall episode goes on until the task moves. A dark-worker episode ends when the worker is checking again and no unacknowledged wake older than the alarm window remains. The receipt for a dark-worker alarm names the worker and reason, as in✓ acknowledged alarm <id> (alarm.dark-worker on worker <name> (overdue), at <time>); a coordinator-cadence alarm's names the coordinator and nothing else, as in✓ acknowledged alarm <id> (alarm.coordinator-cadence on coordinator <name>, at <time>); a task alarm's receipt names its task, as before. -
--code-prefix <prefix>keeps events whose type starts with the prefix. It combines with the other filters.app.<slug>.returns only the App's own recorded actions; a bareapp.also returns the platform'sapp.properties-changed,app.credential-actandapp.manager-act. Omitting the flag leaves the read unchanged. (Release v0.37.0 onward;1e050c37is in it, v0.35.0 does not have it.)
Refusals exit by kind: ALARM_NOT_IN_CHAIN exits 8,
ALARM_ALREADY_ACKNOWLEDGED exits 5, ALARM_NOT_FOUND exits 4, and
NOT_AN_ALARM exits 2.
hadron team roster --app acme.com:eng-team
hadron team events --app acme.com:eng-team --alarms
hadron team alarm ack <eventId>
Holder fields and visibility¶
GraphQL's TeamRosterEntry has
heldBy: WorkerHolder and heldAt: DateTime, the time the current hold was
taken. WorkerHolder is a closed identity
projection: required id, nullable handle, urn and name, never a full
User or an email field.
The worker's working-state gate can withhold the whole heldBy and heldAt,
even from someone who may read the roster. No holder or a deleted holder also
returns null. Neither null tells you the name is unheld or why the fields are
absent. Inside a visible holder, name is readable by the holder, a platform
admin or a co-member of one of their organizations; null can mean withheld or
genuinely unset, with no distinction. A handle-less user's urn is null
independently of name visibility.
The MCP roster tool that printed held by @handle (hrn:user:<handle>) is disabled
(hadron-server#3208). The roster command shows the
holder in its HELD BY and SINCE columns, and --json gives heldBy as
{id, handle, urn, name} or null (v0.35.0 help); GraphQL carries heldAt as
the field itself. These are source-level capabilities, not a claim that a particular
server deployment includes them.
Governed by cor:agt:020:09 and cor:dmo:050:11.
Roster states, event types and alarm refusals¶
These lists are the server's, carried here from the MCP reference when its team sections were removed (hadron-docs#585).
Roster states. Each worker shows the first state that holds, in this
order: YOUR_MOVE (an alarm has woken it and is unacknowledged, or a child
task it owns ended and it hasn't reacted), UNAVAILABLE, WAITING (its
started task has open children), WORKING, ASSIGNED_NOT_STARTED,
AVAILABLE, NO_FAMILY (bound, but its session reported no model family, so
it can't be matched), NOT_LAUNCHABLE (unbound, and no live host can launch
it). A bound worker whose session is quiet still reads AVAILABLE, but the
matcher hands queued work only to a live session. The states come from the
plan, not from a spec.
Event types. Task work: task.created, task.assigned,
task.reassigned, task.started, task.progress, task.finished,
task.cancelled, task.parked, task.ready, task.released,
task.priority, task.blocker-added, task.blocker-removed, task.edited,
task.properties-changed, task.warning, task.session-end-requested. PR review (see Team PR review protocol): review.scheduled, pr.frozen, review.seat.assigned, review.verdict, pr.ready. Matching: assignment.queued,
assignment.matched. Team and hosts: availability.changed,
worker.reports-to, host.registered, host.lost,
host.operation.succeeded, host.operation.failed, and the staffing acts
member.added, member.role-changed, member.removed, worker.cast,
worker.casting, worker.retired, worker.deleted. Alarms, which
--alarms keeps all eight: stall.not-started, stall.no-progress,
stall.owner-unreactive, assignment.unassignable, stall.finish-by,
alarm.dark-worker, alarm.coordinator-cadence and alarm.post-limit. The
last three are task-less: taskId is null and subjectWorker is the worker
the alarm is about (the worker gone dark, the coordinator that stopped
assigning, the worker whose post was refused). alarm.coordinator-cadence is
explained under When a coordinator stops
assigning.
Its payload's lastAssignedAt and freeWorkerCount are withheld from a reader
without access to worker internals. The list is ALARM_EVENT_TYPES in
hadron-server at 57493558. A payload carries ids,
counts and outcome words, never message text. An after that isn't an event
of this App is refused.
Some task events carry more than their name. task.warning is passive
history: it never wakes anyone, suppresses a wake or counts as activity, and its
payload is {code} only, with the recorded codes task.create.no-source and
task.finish.open-children (see Team task warnings).
The blocker events carry blockerTaskId, task.priority carries the new
priority, and task.released records a blocked task becoming free to start,
with no payload. task.edited is passive history like task.warning: its payload is the
changed field names only, never their values. task.properties-changed is passive too: its payload is {from, to}, each null or the size and SHA-256 of the canonical JSON, never the content (Team task properties).
Each of the six staffing events (member.added, member.role-changed,
member.removed, worker.cast, worker.retired, worker.deleted) records a
successful act at that door, by a person or by a worker session; actorWorkerId
is null when a person acted on their own. The payload holds ids and role words
only:
| Event | Payload |
|---|---|
member.added |
userId and the new role |
member.role-changed |
userId, fromRole and toRole |
member.removed |
userId and the role the member had |
worker.cast |
workerId, agentId, role and reportsToWorkerId (or null) |
worker.retired |
workerId |
worker.deleted |
workerId, in the payload only: the worker no longer exists, so the event has no subject worker |
worker.casting is older and records something different: an existing worker
moved to another installed agent. Its payload carries fromAgentId,
toAgentId, fromRole, toRole and clearedBootPromptNodeId. Only a person
acting as themselves can make that change, so it is never recorded for a worker
session. A new worker being added to the team is worker.cast, not
worker.casting.
Availability rules. reason is required with UNAVAILABLE and refused
with AVAILABLE, and only an unavailable record takes an until, which must
be in the future. When until passes, the mark stops counting at once. A
STALLED mark also ends when the worker acts again. Each change writes an
availability.changed event and re-runs matching.
Refusals: ALARM_NOT_FOUND (also for an alarm in an App you don't take part
in), NOT_AN_ALARM, ALARM_NOT_IN_CHAIN, ALARM_ALREADY_ACKNOWLEDGED;
AVAILABILITY_NOT_PERMITTED, WORKER_NOT_FOUND, WORKER_RETIRED,
APP_NOT_FOUND, and BAD_USER_INPUT for a malformed state, reason, until
or family token.
team availability — who is free for work¶
hadron team availability get (uses --app or the binding)
hadron team availability set (--worker <ref> | --family <token>) --state available|unavailable [--reason HOST_DOWN|OTHER|OUT_OF_TOKENS|STALLED] [--until <rfc3339>]
The CLI's side of the availability operations; the availability rules are with the roster lists. For who may set what, see When a worker is marked unavailable.
getlists every worker and model-family record, with its reason, itsuntil, and whether it is in effect now. A worker or family with no record is available. A record whoseuntilhas passed readsAVAILABLE (lapsed at <time>)once the server records the lapse.set --workertakes the worker's id, URN or name; a name needs the App.--reasonis required withunavailableand refused withavailable;--untilmust be in the future.set --familytakes the family token, such asclaudeorcodex, and always needs the App. Only whoever manages the App sets a family, so the write is always made as the person, never as a bound worktree's worker.
AVAILABILITY_NOT_PERMITTED exits 8, and WORKER_RETIRED exits 5.
# Keep Dara off new work until the evening
hadron team availability set --app acme.com:eng-team --worker Dara \
--state unavailable --reason OUT_OF_TOKENS --until 2026-10-14T18:00:00Z
# Pause every Claude worker in the App
hadron team availability set --app acme.com:eng-team --family claude \
--state unavailable --reason OTHER
team stall-schedule — when quiet work raises an alarm¶
hadron team stall-schedule get (uses --app or the binding)
hadron team stall-schedule set [--assignment-minutes N|default] [--not-started-minutes N|default] [--no-progress-minutes N|default] [--owner-reaction-minutes N|default] [--host-lapse-check-ins N|default] (uses --app or the binding)
An App's stall schedule: how long a task may sit before each of the
stall alarms is raised,
and how many missed check-ins lapse a host's registration. It shipped in
v0.23.0. The MCP server has no tool for it yet
(hadron-server#1926),
so today it's set here or through GraphQL (setAgentTaskStallSchedule).
| Flag | What it bounds | Range | Default |
|---|---|---|---|
--assignment-minutes |
A queued task waiting for an assignee | 1–10080 minutes | 30 |
--not-started-minutes |
An assigned task not yet started (when it has no later start-by time) | 1–10080 minutes | 15 |
--no-progress-minutes |
A started task whose assignee is silent; also the alarm's escalation step | 1–10080 minutes | 60 |
--owner-reaction-minutes |
An owner not reacting to a finished or cancelled child task | 1–10080 minutes | 20 |
--host-lapse-check-ins |
A host's own check-in intervals that may pass without a refresh before its registration lapses | 2–10 | 3 |
- Reading.
getshows the effective values, defaults included, and when the App last changed them. Anyone taking part in the App can read it. - Changing.
setchanges only the flags you pass, and needs at least one (exit 2 otherwise).defaultreturns a value to the platform default. Any other non-number, an empty value included, is refused locally (exit 2), and so is a value out of range, by the server. - Who may set it. Whoever manages the App. The write is always yours,
never a bound worktree's worker: the server never treats a worker as
managing an App, so a manager working from a bound worktree would
otherwise be refused. Anyone else is refused
APP_MANAGER_REQUIRED(exit 8). - The host-lapse count. A host checks in every poll interval it
registered with. Its registration lapses once the count of those
intervals has passed with no refresh. A lapsed host launches nothing, and
the App's event feed records
host.lostonce. When the host checks in again, its registration is live again andhost.registeredis recorded. - Not here yet. The schedule also holds
sessionEndGraceMinutes: how long a worker asked to end its session has before the platform ends it through its host (1–1440, default 10). The CLI has no flag for it yet (hadron-cli#880); GraphQL sets it.
# What the App uses now
hadron team stall-schedule get --app acme.com:eng-team
# Give slow reviewers two hours before the no-progress alarm, and put the owner window back to its default
hadron team stall-schedule set --app acme.com:eng-team --no-progress-minutes 120 --owner-reaction-minutes default
# A host on a flaky network may miss up to five check-ins before it lapses
hadron team stall-schedule set --app acme.com:eng-team --host-lapse-check-ins 5
team host — the machines that launch workers¶
hadron team host list (uses --app or the binding)
hadron team host ops [--host <id>] [--status issued|collected|succeeded|failed] [--worker <ref>] [--limit N] [--after <cursor>] (uses --app or the binding)
hadron team host issue <type> --host <id> --worker <ref> [--arg key=value]… [--as-person] (uses --app or the binding)
hadron team host run --config <host.yaml> [--once]
hadron team host status --config <host.yaml>
hadron app key scope grant <key-id> host:operate --host-id <host>
A team App's hosts, the operations issued to them, and the host's own poller. They need v0.24.0 or later. Setting up a host end to end, with the configuration file and the key custody rules, is the how-to Run a host that launches your team's workers.
listshows each host's id and label, its check-in interval, whether it is live now, and the workers it can launch with their family and worktrees.opslists the operations, newest first, with who issued each and, once reported, its result or failure reason.--limitis 1 to 200;--aftertakes theendCursorof the previous page. Whoever reads the App's tasks and events may read both.issueissues one operation from the closed set to a registered host. Its arguments are ids and name tokens, never a command or a credential, and the worker is named with--worker, never inside--arg.worktree.createtakesrepo,baseBranch,branchNameandlabel, whererepomust match a key under the host configuration'sreposexactly;worktree.removetakesworktree, the tree's full name token (api/dara-2for the example below, notdara-2): a token that names no tree on the host is reported succeeded, as already removed. These come from the worker's holder, the worker it reports to, or whoever manages the App. In a bound worktree the operation is issued as that worker, which qualifies only as the target's reports-to;--as-personissues it as you.runis the host poller andstatuschecks its configuration, key and registration without changing anything. Both authenticate with thehost:operatekey read from the configuration'skey_file, never fromHADRON_TOKENor an environment variable.app key scope grant … host:operate --host-id <host>gives a key the host scope for one host id. Only whoever manages the App can grant it.
| Code | Exit |
|---|---|
HOST_OPERATION_TYPE_UNKNOWN, HOST_OPERATION_NOT_ISSUABLE, BAD_HOST_OPERATION_ARGS, BAD_HOST_REGISTRATION, APP_KEY_SESSION_BOUND, a bad host configuration |
2 |
| No host key, or a key file readable by group or others | 3 |
HOST_NOT_FOUND |
4 |
APP_KEY_SCOPE_HOST_CONFLICT, HOST_OPERATION_NOT_COLLECTED, HOST_OPERATION_ALREADY_REPORTED, HOST_OPERATION_NOT_DONE, LAUNCH_REFUSED, WORKER_NOT_HELD, WORKER_LIVE, WORKER_START_PENDING |
5 |
run --once: a report did not reach the server |
7 |
HOST_OPERATION_NOT_PERMITTED, HOST_KEY_REQUIRED, APP_KEY_SCOPE_REQUIRED, LAUNCH_GRANT_INVALID |
8 |
# Ask the host build-box-1 for a fresh worktree for Dara
hadron team host issue worktree.create --app acme.com:eng-team --host build-box-1 --worker Dara \
--arg repo=acme/api --arg baseBranch=main --arg branchName=dara/412 --arg label=dara-2
# What happened to it
hadron team host ops --app acme.com:eng-team --worker Dara --limit 5
# Once per team: declare the worklog collection
hadron team init -m acme.com:eng-team-shared
# Cast a worker — the name is yours to choose and is permanent for this App
hadron team worker cast --name Iris --role backend-engineer --app acme.com:eng-team
# Bind this worktree and work under it
hadron team session start --as Iris -m acme.com:eng-team-shared \
--repo acme/api --tool claude-code \
--transcript ~/.claude/projects/acme-api/session-8f2.jsonl
hadron team session whoami
# Log milestones — the bare number is qualified from the session's --repo
hadron team session log --pr 412 --action opened
hadron team session log --commit a1b2c3d --action pushed
# Coordinate in the team chat (posts as Iris via the bound session)
hadron team chat post "@rufus rate-limit middleware is up in #412, over to you"
hadron team chat read --since 42 --mentions-me
hadron team session end --handoff "Rate-limit middleware + tests landed in #412. Review open; do not re-run the migration."
# Who is working right now, and what did Iris touch?
hadron team session list --active
hadron team session list --as Iris --limit 20 --json
# The provenance query: which sessions produced this PR? (a URL works too)
hadron team session list --pr acme/api#412 --json
team composition — who reports to whom¶
The team App's composition: its active workers grouped by the coordinator
they directly report to. It renders the server's teamComposition query as
returned; the CLI joins and judges nothing.
- Each lane names its coordinator (a retired coordinator stays named and is marked), lists the lane's non-retired workers in the server's order, and gives plain headcounts by role and by role and family. A worker with no role or no family is counted in its own bucket, shown as a dash.
- The lane with no coordinator holds the workers who report to nobody.
- A lane is a direct-report group, not a hierarchy rollup: a coordinator's own row sits in the lane of the worker it reports to.
- It is a read, not a capacity policy: it does not say whether the team is
balanced. A refused read, or a server that does not serve
teamComposition, is a failure, never an empty team. - The as-of value is control-free display text capped at 256 runes;
--jsonpreserves the original.
team push — one message into an agent's console¶
hadron team push <worker> (--text <message> | --message-file <path>) [--seq N] [--wait-timeout 120s] [--draft-wait 30s] [--draft-stable-for 30s] [--confirm-timeout 10s] [--poll-interval 250ms]
Sends one message directly to an agent's console, using code-only guards. It needs this worktree's open worker-session binding. The recipient must have exactly one connected, writable local terminal with a matching App, server and session binding and a positively recognized Claude or Codex interface. A busy console waits; an unknown one holds.
- An empty idle composer sends promptly. A draft waits at least 30s and must stay byte-for-byte unchanged for at least 30s (overlapping intervals, not their sum). A captured draft is cleared with the proven interface sequence, then included once, as labelled unfinished and not-author-submitted text, in the same input as the message.
- Fresh on-screen evidence that this attempt's turn started is required; accepted send receipts alone are not confirmation. There is no automatic resend and no follow-up Enter.
--seqis a provenance label only: it posts and marks nothing in chat. Prefer--message-filefor sensitive text, since--texthas ordinary argv visibility. No input, screen or draft text is logged or persisted.- Defaults: total pre-send wait 120s, draft wait 30s, exact-byte stability 30s (it cannot be set below 30s), confirmation 10s, poll 250ms. Every duration must be positive and at most 24h.
| Exit | Outcome | Retry? |
|---|---|---|
| 0 | sent | no |
| 9 | sent with a draft: success | never |
| 10 | held, busy (no composer input) | allowed |
| 11 | held, unknown (no composer input) | allowed |
| 12 | unconfirmed: the composer may have been changed | never |
Other failures keep their usual exit codes. --json carries only
outcome, phase, reason, recipient, seq and draftIncluded.
A local lock serializes only this command's own attempts, and Orca has no atomic conditional send, so a person or another sender can race the final read and input. A captured draft lives in memory only: process death can lose it. Merging the command migrates no unguarded caller and installs or enables nothing.
team stop — stop signals¶
hadron team stop list [--worker <ref>] [--include-ended] (uses --app or the binding)
hadron team stop set --scope worker|team|host --level pause-dispatch|pause|halt [--worker <ref> | --host <id>] [--until <RFC3339>] (uses --app or the binding)
hadron team stop lift <signal-id> (uses --app or the binding)
A set can be refused until a host can type the notice
The server refuses a set with STOP_SIGNAL_UNAVAILABLE while any worker
the signal would cover is on a lane whose stop-notice consumer has not
declared itself within the last 600 seconds. Listing and lifting are
unaffected. The consumer is hadron team host run (hadron-server#2169,
CLI v0.37.0 and later), which types the notice into an empty input; a
result still shows the server's stored signal, not proof that any worker
stopped or resumed. What the consumer does, and what has not been shown
yet, is in Stopping workers.
A stop signal stops covered workers at one level:
| Level | Effect |
|---|---|
pause-dispatch |
no new assignment |
pause |
also no ticks or stall time |
halt |
also an interrupt to save work and hand off |
Its scope is one worker, a team (a head worker and the whole reporting tree under it) or a host. Signals are independent: setting one never replaces another, and lifting one never ends another.
list(aliasls) lists every stop signal the server shows this caller, oldest set first, page by page to the end.--workernarrows to the signals covering that worker now (a team signal on a head also covers each worker in the reporting tree under it);--include-endedadds lifted and expired signals. A person in the App sees every signal; a worker's session sees the live signals covering it; a host key sees its own host's. This command sends the person's credential and attaches no worker session.setsets one signal.--scope workerand--scope teamneed--worker(a team is named by its head worker);--scope hosttakes--host(a host key may omit it, and the server takes its own host).--untilis an RFC 3339 time with an offset, later than now, sent as UTC; without it the signal lasts until lifted. Whoever manages the App may set any level and scope; a host key, ahalton its own host. It is the person's write: a bound worktree's worker session is never attached, and the server decides who may set what.lift <signal-id>lifts exactly one signal; other signals may still cover the same workers and nothing restarts by itself. A signal that had already ended is reported as unchanged, not as lifted. The receipt shows the id without controls, capped at 256 runes;--jsonkeeps the original. Whoever manages the App may lift any signal; a host key, ahalton its own host.
ticker apply-templates — give a worker its Agent's tickers¶
In CLI v0.33.0 and later. An Agent can declare ticker templates, and casting
a worker from it creates one ticker per template for the worker. apply-templates
is the repair for a worker cast before its Agent had templates. Managing the
templates themselves is not covered here.
It creates the template tickers that one worker is
missing, each owned by and subscribed to the worker. It edits and deletes
nothing: a template the worker already has a live ticker for is listed as
alreadyPresent and left as it is, so a second run creates nothing.
- Who may. Whoever manages the App, as themselves. It never sends a worker session; the server refuses one. It applies to one worker per call.
- Whole-call refusals. If the App's live-ticker cap cannot take every
missing ticker (
TICKER_LIMIT_REACHED) or a generated name is already a live ticker's (TICKER_NAME_TAKEN), nothing is created. The other refusals areFORBIDDEN,WORKER_NOT_FOUNDandWORKER_AGENT_NOT_INSTALLED. - Output. Text lists each created ticker with its template and effective
cadence, labelled "the App's floor" when it equals the floor, then the
templates already present.
--jsonis{created: [{ticker, template, effectiveCadenceSeconds}], alreadyPresent: [{id, name}]}.
team health — report your workers' terminal status¶
hadron team health sweep --config <host.yaml> [--status-timeout <duration>] [--json]
hadron team health install --config <host.yaml> --interval <Nm> [--bin <abs hadron>] [--json]
hadron team health uninstall
hadron team health status [--json]
These run on a host, the machine that runs Orca and launches your team's
workers (see team host). The sweep stores, for each worker the
host is registered for, what that worker's terminal looks like right now, so
the portal and team roster can show it. It checked out against the released
v0.44.0. How to set it up end to end is in
Run a host that launches your team's workers;
how to read the result is in
Watch your team for dark or stuck workers.
Known defect in v0.44.0: the sweep can hold back a due wake
On the released v0.44.0, every sweep that finds an idle terminal reads
due wakes the way a spending read does, not the no-spend preview. When
wakes are due, that read can reserve a slot of the App's daily wake
capacity, and when capacity is short it can withhold another worker's due
wake; the platform may then post its daily budget notice. With nothing due,
nothing is reserved. The sweep never acknowledges the wake or raises the
acknowledged-wake counter, and the withheld work stays due. Until
hadron-cli#1833
is fixed, do not schedule install. A sweep you run by hand makes the same
read, so use it sparingly.
sweep runs orca terminal status --all --json itself, reads
the terminal-status@1 answer, and stores the status of the host's registered
workers in one batch. The sweep itself reads no screen and never types into a
terminal. The orca terminal status it runs does read each terminal's screen,
on the host, to classify it; only the resulting codes and times leave the host.
status, prompt, reason, lastTurnAt and checkedAt are those of
terminal-status@1, described under Orca terminals.
- It uses the same
--confighost YAML and the same0600key_fileasteam host run. The host key is never an argument or an environment variable. Orca comes fromdelivery.orca_binwhen that is set, otherwise fromPATH. - Paused workers are still reported. A worker's App needs no coordinator.
- It raises no alarm and decides nothing from what it stores. The stored status is a report with a time on it, not a verdict.
- It repairs nothing. It does not restart a worker, reset its context or
post a repair notice. It does run
orca terminal status, and that command's own reads have side effects the sweep inherits: for a terminal that looks idle it reads the server's due wakes the way a deliverer does, so the server may reserve a due wake against the App's daily wake budget (and, once that budget is spent, the platform posts its usual daily notice to the team chat), and with--configthe host-key reads are recorded as host-key uses. Every idle-path run makes the due-wake read. The CLI's read does not ask for the server's no-spend preview, so it is the spending read: a wake it reserves counts against the daily budget although the sweep never delivers or acknowledges it, and once the budget is spent the due wakes are withheld, which the status command reports as an error rather than "nothing due". - Status rows for workers not registered on this host are ignored. A registered worker whose report is missing, unresolved or ambiguous refuses the whole batch before anything is written (exit 1).
- The status read is allowed 5 seconds per registered worker, at least 2
minutes.
--status-timeoutoverrides that. A read that runs out of time saysterminal status timed out after <duration>, exits 1 and writes nothing. - Only codes and times leave the host. Screen text, the local
detailline and the host key never do. A diagnostic on failure says so and includes none of them.
Text output is one line per reported worker: the worker, its status and its
reason (or -), plus (refused: <CODE>) for a worker the server turned away.
--json prints the reports that were sent and the refusals:
{"reports":[{"worker":"wrk_0001","status":"idle","prompt":"empty",
"reason":null,"lastTurnAt":"2026-01-01T00:00:00Z",
"checkedAt":"2026-01-01T00:00:05Z"},
{"worker":"wrk_0002","status":"dark","prompt":"unknown",
"reason":"no_terminal","lastTurnAt":null,
"checkedAt":"2026-01-01T00:00:05Z"}],
"refused":[{"worker":"wrk_0002","code":"TERMINAL_REPORT_STALE"}]}
In --json, worker is the worker's id, not the display name the text
output shows. WORKER_NOT_FOUND means the server does not have that worker registered to this
host (that item only). TERMINAL_REPORT_STALE means the server already holds a
newer report for that worker and skipped this older one.
A worker in reports is a report that was sent, not a storage
receipt: check refused as well. A per-worker refusal is printed, not retried, and does not
change the exit code. The two codes are WORKER_NOT_FOUND and
TERMINAL_REPORT_STALE.
A run can exit 0 while every worker was refused. Refusals do not change the
exit code, and team health status shows only the last run's time and exit code.
If the portal shows nothing new, run sweep --json by hand and read refused.
| Exit | Meaning |
|---|---|
0 |
The write succeeded. Per-worker refusals do not change this. |
1 |
A failed write, a malformed status answer, a status read that timed out, a batch refused for a missing, unresolved or ambiguous registered worker, or any other failure. |
2 |
Invalid arguments or host configuration, for example a negative --status-timeout. Nothing is written. |
3 |
The host key is missing or was rejected. |
7 |
The server is unreachable. |
8 |
Forbidden, including a host registration that is missing or not live. |
10 |
The status command cannot reach Orca. |
install adds a user-level scheduler entry that runs
<hadron> team health sweep --config <host.yaml> every --interval: a systemd
user timer on Linux (a crontab line where systemd user units are not available),
or a launchd agent on macOS.
- There is no default interval.
--intervalis required, in whole minutes of at least1m. Cron needs one that divides an hour or a day evenly, such as5m,15m,1hor6h. Those are examples of the syntax, not a recommended cadence: how often to run it is not decided here. Note that the portal hides a status 30 minutes after it was checked (see Watch your team), so an interval longer than that shows Stale between runs. - The entry carries your current
PATH, because schedulers start jobs with a minimal one.installrefuses (exit 2) when neitherdelivery.orca_binin the host config nor thatPATHresolvesorca, because the sweep could only fail unattended. The host key is never written into the entry. - Installing again changes nothing. A new
--intervalupdates the entry. There is one entry per user: another--configis refused untilteam health uninstall. --binis the absolute path ofhadronto run (default: the one onPATH).- Exit
2for a bad flag, path or interval, or when no scheduler is supported (nothing is written). Exit1when a scheduler call fails, naming the files written, whichuninstallremoves.
uninstall removes exactly what install wrote (the timer and service, the
crontab line or the launchd agent), including after an install that failed
midway. Other crontab lines are left alone. Nothing installed counts as
success.
status is read-only and exits 0 whether or not anything is installed. It
shows whether the sweep is installed, which scheduler holds it, the interval, the
hadron it runs, the orca it resolves, and the last run's time and exit code as
the scheduler recorded them (systemd, launchd). Under cron the last run is
unknown: cron does not record it and nothing is guessed. A partial install
(files present, scheduler not running them) shows as installed but not active.
installed: yes
scheduler: systemd
active: yes
interval: 15m0s
binary: /usr/local/bin/hadron
config: /etc/hadron/host.yaml
orca: /usr/local/bin/orca
last run: 2026-01-01T00:00:00Z (exit 0)
--json prints installed, scheduler, active, interval, binary,
config, orca, files, lastRun ({at, exitCode}, with null fields when
unknown, or null when nothing is installed) and notes.
team router — the Orca attention router¶
hadron team router loop [--config <path>] [--interval 60s]
hadron team router status [--config <path>]
Runs the Orca attention router on your login (a port of hadron-server's
scripts/orca-attention-router, cli#829): it polls the team App's attention and
types one short line into each mentioned roster worker's Orca terminal telling
it where to start reading. It never reads, relays or posts a chat message, never
marks anything read, and never hands its token to a worker.
- A nudge is typed only when Orca proves the terminal idle (or, for a terminal Orca stopped tracking, the rendered screen proves an idle agent) and the screen proves the prompt empty. Counts are recomputed immediately before the send and both proofs are re-checked after it. Anything unproven holds the worker, and a held worker keeps the attention token unadopted, so it is retried next poll without re-nudging the others.
-
Config is
router.ts's JSON, unchanged:--config, else$HADRON_ROUTER_CONFIG(or$ORCA_ROUTER_CONFIG), else~/.config/hadron/team-router/config.json, else the TS router's~/.config/hadron-orca-attention-router/config.json. ItsstateDirholds the adopted token, the delivery ledger and the liveness clocks (0700/0600) in the TS router's format, behind the same writer lock: point both at one state directory and they exclude each other.{"app": "<app ref>", "channel": "<team Channel id>", "stateDir": "~/.local/state/hadron-team-router", "orcaCli": "orca", "busyWaitMs": 60000, "submitWaitS": 15, "coordinatorWatchMinutes": 20, "roster": [{"worker": "<id>", "name": "Eli", "worktree": "~/orca/workspaces/x/eli", "terminal": "<optional pinned handle>", "coordinator": false, "lifecycle": false}]} -
Each roster worker needs its own mention-only register row on the team channel, or it is held (a broader row would wake it on every message).
looprepeats the poll every--interval(default 1m) in the foreground, by design: a failed poll is logged and retried next interval with the token unchanged, and a line is printed only for a poll that nudged or held someone, or failed (--jsonprints one object per such poll).SIGINTandSIGTERMstop it after the poll in flight, so a send is never cut off between Orca's receipt and the ledger write; a second signal exits at once. Configuration reloads between polls, andconfig-loaded.jsonrecords the loaded config's fingerprint and time without changing the adopted token.statusshows the router's local state with no network: whether a token is adopted (never the token itself), who was nudged under it, each held worker's last logged reason, whether the writer lock is held, the roster, and each flagged worker's liveness clock.
team usage accounts and team usage project¶
hadron team usage accounts [--json]
hadron team usage project [--account <label> [--host h] [--family f]]
[--add-workers N | --move-worker <worker> --to-account <label> [--to-host h] [--to-family f]] [--json]
Both print what the server returns, without filtering or re-sorting. They
are subcommands of team usage: there is no team accounts or team project.
team usage accountslists the team App's usage accounts in the server's order, one row per account, host and family. JSON is the envelope{asOf,accounts:[{account,host,family,newestSnapshotAt,workers:[],workersConfigured}],complete}. With no history it isaccounts: []andcomplete: true, never a bare[].complete: false(over 50 accounts, or the search stopped short) is exit 0 with a stderr note in text mode.workersConfigured: falseprints "not configured"; an empty configured list prints "none".APP_NOT_FOUNDpasses through. A server that lacks the field exits 1 with "too old" and the server's own message.team usage projectprints the server's token-burn projection. Each window showslowPctAtReset..highPctAtResetand a confidence ofLOW,MEDIUMorHIGH;runsOutAtappears only when the server returns one;statusisPROJECTED,INSUFFICIENT_DATAorUNKNOWN. Without--accountit projects every account the server lists, one call each, andcompleteis present only then. With--accountit projects that one account.--accountgiven empty or blank exits 2 before any call. A what-if needs--accountand exactly one of--add-workersor--move-worker.-mor--configwithout--accountexits 2 before any call.
Orca terminals¶
hadron orca is a host-local integration. It reads the terminals of the
Orca app, so it works only on the host that runs Orca and needs the Orca CLI
(orca) on PATH. Off that host it exits 10. It never types into a
terminal. It sits beside team host, the machines that launch
workers. The released --help does not say who may run it; the usage contract
says only that the server gates a read of another worker's due wakes.
orca terminal status classifies one worker's Orca terminal (found by the
worker's session binding in its worktree, or taken directly by terminal id) and
prints the versioned terminal-status@1 contract:
status |
Meaning |
|---|---|
busy |
A turn is running. |
idle |
An empty prompt, safe to push one line. |
locked |
An identifiable block (reason menu_or_question, and others), or, failing closed, a screen no rule recognizes (reason unrecognized). |
dark |
Broken: a ticker owed this worker a turn and none came (no_turn_for_due_ticker), or there is no terminal, a bare shell or no agent (no_terminal, bare_shell, no_agent). |
prompt is the terminal-level fact: empty, not_empty, menu or unknown.
Precedence is locked, then busy, then dark, then idle. Push only when prompt
is empty and status is idle or dark.
What makes a worker dark. A tick of a ticker the worker is subscribed to
has been due and unanswered for at least the interval of the worker's fastest
subscribed ticker. Each tick is aged by its own oldest unanswered tick (the
server's per-reason tickDueAt), so a tick merged into one wake with a mention,
a task or another ticker's tick is judged on its own. A worker with nothing due
is never dark, however old its last turn. Separately, dark also covers a
worker with no terminal, a bare shell, or an agent that is not connected; the
reason says which.
What fails closed. locked/unrecognized is also the answer for an
otherwise idle worker whose due-wake evidence is missing: a tick the server gives
no due time for (an older server, or withheld), a malformed one, a tick without
its ticker, or evidence that could not be read or was refused for you. A
coordinator asking about another worker is gated by the server. A terminal named
by id that no worker's binding claims has no ticker evidence, so it is never
dark by the ticker rule.
--all prints one JSON array, one entry per active worker of the App, in
the App's worker order. Text mode prints one line per worker, such as
example-worker idle or example-worker locked (menu_or_question); a dark
line also carries the local detail.
{"contract":"terminal-status@1","worker":"example-worker","terminal":"term_0000",
"status":"idle","prompt":"empty","reason":null,
"lastTurnAt":"2026-01-01T00:00:00Z","checkedAt":"2026-01-01T00:00:05Z"}
| Key | Values |
|---|---|
contract |
Always terminal-status@1; a breaking change ships as @2. |
worker |
The worker's name; null for a terminal bound to no worker. |
terminal |
The Orca terminal handle; null when the worker has none or has several agent terminals. |
status |
busy, idle, locked or dark, as in the table above. |
prompt |
empty, not_empty, menu or unknown. |
reason |
null unless locked or dark. Locked: menu_or_question (a selection menu, permission dialog or pending question: never send), unrecognized. Dark: no_turn_for_due_ticker, no_terminal, bare_shell, no_agent. |
lastTurnAt |
When the harness's screen shows its last finished turn; null when not shown, never guessed. It does not influence status. |
checkedAt |
When the status was produced, UTC. |
checkedAt is when the answer was produced. Read its age before you trust a
status you saved earlier: the status says nothing about the worker after that
moment.
Exit 0 whenever a status was produced (the status is in the output). Exit
10 means Orca is not reachable, which is distinct from a worker with no
terminal (dark/no_terminal, exit 0). The command only lists and reads
terminals and reads tickers and due wakes: it never types, stores nothing and never acknowledges a wake. Its reads can still reserve a due wake against the
App's daily wake budget when a terminal looks idle (the platform then posts its
daily notice once the budget is spent), and with --config the host-key reads
are recorded as host-key uses. The output carries codes only. The local
detail line (the ticker and due time behind a dark, or why a read was refused)
is printed in text mode only and is never part of the JSON. Reason codes for
capacity, rate-limit, budget, guardrail and staged-shed screens are deferred: such
a screen is locked/unrecognized, or idle/busy where the existing rules
already say so.
Product specs¶
hadron spec maintains product-spec nodes: a node is a spec when it
carries the spec tag (or the governed spec role), and its loc is its
citation. Any valid node loc is a spec address, at any depth and in any
shape; a loc implies no parent, and a spec's edges are the ones it was given.
From CLI v0.18.0 the read-side scans (spec list, get --prefix, grep,
replace, check-tools and find --match-exactly) also find a spec that
carries only the governed spec role, and spec lint no longer warns about the
missing tag. A spec write that does not pass --role still sets the spec
tag; an explicit --role writes only the tags you name.
Many corpora use a legal-code numbering convention, which spec new's
allocation and contract flags produce, and which spec register and
spec extract operate on:
<module>:<feature>:<rule>[:<flow>](e.g.msg:010:02);<product>:<module>:<feature>:<rule>[:<flow>](e.g.api:cha:010:01), when the numbering starts with a product.
It is a convention, not a rule: creating, reading, linking, editing and linting
accept a spec at any loc, and a memory has no declared "scheme". Only the
operations that allocate in the numbering need a numbered loc — spec new
--new-path, spec extract's source, and spec supersede without --to —
and each refuses any other loc with exit 2 and a pointer to the any-loc
alternative. It may mix both forms, or use
neither. A register node holds the frozen module-code table and the number
ledger. Every subcommand takes -m/--memory; specs are addressed by a bare
citation, not a full node URN. Every spec subcommand resolves -m the same way — it accepts a
memory PK, an hrn:/urn: URN, a bare org:memory, or a memory
name.
| Command | Purpose |
|---|---|
spec describe |
Inventory the memory's specs: specs, roots (first segments), maxDepth, and how many are legacyNumbered vs outsideNumbering. Also reports per-node approval/mint inventory: the corpus is DRAFT while no live node is minted, MINTED once any is; new unminted nodes can coexist with minted ones. Classifies no numbering scheme. --declare is retired: it is refused (exit 2) before any request, and writes nothing. A scheme a memory's data still stores from it is shown as retired and ignored. |
spec list [--prefix <loc>] |
List specs, optionally under a citation prefix. Paged to exhaustion unless --limit/--offset request one page. Aliased as spec ls. |
spec use <memory> |
Set the default memory hadron spec commands use when -m/--memory is omitted (stored as spec_memory in the CLI config); pass "" to clear it. Separate from the global active memory, so switching your working memory doesn't change your spec corpus. |
spec get <citation> (or --prefix <p>) |
Show one spec — abstract, edges, body, and a lint summary; --body-only prints just the raw body. With --prefix, dump every spec under a citation branch instead (paged; --limit/--offset fetch a single page). |
spec reserve <citation> |
Reserve an unminted placeholder at a free loc, in any memory. Writing nonblank content fills it; a live node already there refuses (exit 5). Rule: cor:spc:020:11 (Reserve a citation as a placeholder). |
spec renumber <from> <to> [--dry-run] |
Move an unminted spec subtree and rewrite corpus node-URN references. Any minted moved node refuses NODE_MINTED (exit 5). Text mentions are reported, not rewritten. The move is atomic but subsequent guarded reference edits can fail independently (exit 1). Rule: cor:spc:020:05 (Renumber a spec in a draft corpus). |
spec backlinks <citation> / spec unresolved |
Read references to a citation, or references that do not reach a written spec. |
spec label-report [--prefix <loc>] |
Read-only inventory of the corpus's citation edges. Each spec points at its citation parent with an edge (child to parent), and each edge carries a label, normally the child's title. For every parent you can see, it lists the incoming edges from its citation children with their labels, so you can spot labels that disagree with the child's name. It is an inventory, not a lint: it never says a label is wrong, and it covers only what you may read. A child you can read in the same memory prints as verified direct relationship (status=unavailable with an empty name when its current name cannot be read); an edge whose source you cannot read prints as unclassified candidate with null child fields. An empty label and a missing label are reported differently. Pages to exhaustion; a transport failure fails the command without a partial report. --prefix restricts the visible parents to a citation branch; the memory is -m, else the one chosen by spec use. |
spec mint [--dry-run] [--yes] |
Check live unminted nodes and stamp them only after blockers clear and confirmation. Dry run writes nothing and exits 5 when blocked. Findings and lifecycle; current CLI verified at v0.28.0. Rules: cor:dmo:120:06 (Mint a memory's nodes), cor:dmo:120:07 (What blocks a mint). |
spec register [--check] |
Print the number ledger derived from live nodes. The ledger covers the numbering convention; specs at any other loc are named in outsideNumbering ([] when there are none), never dropped. --check reports drift against the register node and exits 5 if any is found. |
spec find <query> [--match-exactly] |
Find specs by meaning (hybrid keyword + vector). --match-exactly switches to literal regex matching over name/loc/description/tags — use it for exact-fragment lookups such as a citation, since keyword search is now full-text ranked/stemmed rather than substring. |
spec grep <pattern> |
Exhaustive, line-oriented search over every spec's body + abstract across the corpus (one bulk read, not a per-spec loop), printing each match as citation:line: text. Literal by default; --regex (RE2), -i fold case, --field content\|abstract, --prefix <loc> to scope. The complement to spec find — use it to discover where a token actually lives in the prose (deliberately broad, no word boundary). |
spec replace <pattern> <replacement> |
Citation-aware bulk find/replace over spec bodies + abstracts. Word-boundary-aware by default (whole-token only, so h-read-node never hits h-read-nodes); --word-boundary=false for substring, --regex for a pattern with $1 backrefs. Gated like other bulk writes: --dry-run previews per-citation counts, --yes non-interactively, --max-specs N caps blast radius. In a DRAFT corpus, apply binds to the exact preview fingerprint; stale plans refuse SEARCH_REPLACE_PLAN_STALE with zero writes. In a MINTED corpus the CLI generic door skips governed specs. Versioned edits can leave abstracts stale; draft replacement details. |
spec new <loc> --title <t> |
Create exactly that spec, at any valid loc. No parent is required, no contract is created, no number is allocated; a numeric last segment only sets seq (sort order). Its only edge is an --inherit <loc> you name. A loc that already holds a node is refused (exit 2). Not combinable with the numbering flags below. --dry-run previews. |
spec new [--product <ppp>] [--module <mmm>] --title <t> … |
Allocate the next citation in the numbering convention and scaffold a starter body plus edges. With a positional <loc> and --role <spec-role> (from v0.18.0), create exactly that spec with the role, the plain --title as its name and only the tags you pass with --tag; --dry-run shows the role. Without --role, the name is citation-prefixed and the spec tag is added. --new-product / --new-module / --new-feature mint their respective tiers; --contract scaffolds the tier's general-provisions contract; --dry-run previews. Creating a root also scaffolds that tier's contract (<p>:gen / <m>:000 / <f>:00) unless --no-contract. |
spec new <citation> --new-path --title <t> |
Create that numbered citation and every missing ancestor in one call — each with its tier template, and each created root with its general-provisions contract. Ancestors are titled from their own citation segment (srv:api → api); rename with node update --name. Not combinable with the tier-selecting flags. A loc outside the numbering is refused (exit 2) with a pointer to drop --new-path. |
spec edit <citation> |
Open the spec's body and abstract together in $EDITOR (they are one logical unit). --content - / --content-file, --abstract - / --abstract-file, and --description - / --description-file replace fields non-interactively; description is not in the default editor buffer. An omitted field is preserved, and an unchanged field is not rewritten. Abstract replacements have a 2000-character limit (UTF-16 code units, including whitespace and newlines); over-limit proposals fail before preview or save. --dry-run previews without writing; --json includes nodeId, revision, proposalHash, the proposed field changes, and descriptionChanged. Every save targets the read node ID and revision. To replay an approved preview later, pass its --expected-node-id, --expected-revision, and --expected-proposal-hash together. A changed node or proposal is refused (exit 5); re-read and preview again. |
spec extract <citation> --to-feature <fff> [--rule <rr>] |
Split a sub-rule out of a fat parent into its own citation under another feature — piping the moved chunk via --content - / --content-file, auto-wiring the cross-ref edge. --strip-source also trims the chunk from the source body. Allocates in the numbering convention, so the source must be a numbered citation; for any other spec, use spec new <loc> and spec edit. |
spec link <from> <to> [--label <l>] |
Cross-reference one spec from another by their bare citations — a convention-aware edge add that validates both endpoints are specs in the same corpus and synthesizes the label when omitted. --dry-run previews. |
spec lint [<citation>] [--prefix <loc>] [--product <ppp>] [--module <mmm>] [--all] [--strict] |
Validate one spec, a subtree (--prefix, that node plus its descendants), a product, a module, or the corpus against the structural and stability rules. Exits 5 on errors; --strict promotes warnings to errors. A spec owes no parent, contract, inheritance edge or index at any loc, and names may be human-readable. Lint does not check content sections: from v0.18.0 a missing abstract, "what invalidates" statement or data.version, and an unedited scaffold body, are no longer findings. Type-specific section checks live in the corpus's own review checks and tasks. |
spec check-tools [--prefix <loc>] |
Scan the corpus for hadron_* tool references and flag any that aren't a real registered tool — the drift that let stale h-* shorthand rot. Checked against a manifest baked into the binary (the union of hadron-server's MCP + runner tool registries), with a small ignore-list for known non-tools (e.g. the hadron_token cookie). Exits 5 on findings, so CI can gate on it; --json and --prefix <loc> supported. |
spec citations [--src <path>]… [--exclude <glob>]… [--loose] [--stale-abstracts] [--strict] |
Scan source code for Spec: citations and check each against the corpus — the pointers that live outside the graph, where spec lint can't see them. Reports a citation that doesn't resolve (a typo, or a spec deleted rather than superseded) and one that resolves to a superseded spec, naming its replacement. Matching is anchored on the Spec: prefix and takes every citation on the line; --loose drops the anchor and scans every line for citation-shaped tokens (finds unconventional pointers, at the cost of false positives in prose). --stale-abstracts adds a warning when a cited spec's abstract has drifted from its body — off by default, because that's a property of the spec, not the pointer. Exits 5 on errors so it can gate CI; --strict promotes warnings too. Alias: check-citations. |
spec supersede <old> --title <t> [--to <loc>] [--copy-body] --yes |
Retire any spec and create its replacement with a superseded-by edge. --to names the replacement's loc (any valid, free loc; nothing derived). Without --to, a numbered rule or flow gets the next free number; any other spec is refused (exit 2) with nothing written. --dry-run previews. |
spec import spec-kit\|code <path> |
Planned extractors — not yet implemented (exit 2). |
Numbering and stability (the allocation rules apply to the numbering convention; the stability rules apply to every spec):
- Features are numbered in tens (
010,020, …); rules and flows increment by one. Allocation is monotonic — strictly above the current maximum — so a retired number is never recycled. - General-provisions contracts. A spec inherits a contract through an
inheritance edge, and only through the edge. The numbering reserves a
contract per tier: rule
00under a feature (msg:010:00), feature000under a module (msg:000), and — when the numbering starts with a product — modulegenunder a product (api:gen). Creating a root with--new-product/--new-module/--new-feature/--new-pathscaffolds that tier's contract alongside it unless--no-contractis passed, and allocation wires each new spec's edge to it;spec new … --contractadds one to a tier that lacks it. Existing siblings are not back-wired, andlintdoes not report the missing edge: link each one that should be bound withspec link <sibling> <contract> --label "inherits the shared contract (general provisions)". Outside the numbering, pass--inherit <loc>tospec new <loc>. - Minted citations are permanent by policy. Unminted drafts may use
spec renumber; a minted moved node refuses. Supersede published rules. Other citation-permanence enforcement is currently off; minting does not promise universal rejection of later edits, moves or removals. - The register is advisory. Next-free numbers come from the live nodes;
specnever writes the register node. Usespec register --checkto catch a stale ledger. - In numbered allocation, a missing parent tier is rejected before anything
is written — exit 4
(
NotFound), e.g.module "srv:qqq" does not exist — create it first with --new-module. Create the tier and re-run, or use--new-path. - A spec is never silently orphaned. Distinct from the case above:
spec new(andspec extractandspec supersede) fail loudly — exit 1 — when a required table-of-contents, cross-ref, or inheritance edge can't be wired, instead of reporting✓ createdon a node that ended up disconnected. Here the spec is written and the unwired edges are reported, so the run genuinely half-completed; fix the target and re-run, or wire the edge withhadron edge add.spec supersede --jsonreports each edge'sstatus(created/failed/skipped). This is the same partial-writes contract asnode import --with-edges. spec findis semantic by default and relies on the memory's vector index; without one it falls back to full-text keyword search and prints a note. Like the other destructive commands,spec supersederequires--yeswhen non-interactive.
hadron spec describe -m acme.com:platform-specs # what's in the corpus?
hadron spec new -m acme.com:specs --module msg --feature 010 \
--title "W4 — 7-day check-in" --dry-run # preview the allocation
hadron spec lint --all -m acme.com:specs # check the corpus
hadron spec find "re-engage idle users" -m acme.com:specs
See Read and cite product specs to find and resolve a spec, and Maintain product specs for the authoring workflow.
Coding-workflow graph¶
hadron coding reads, extends and validates the coding-workflow graph in
a memory — the review:* checklist tree and the preflight router. Those
nodes are executable infrastructure, not prose: a check is triaged by reading
its edge label back to the review parent, and preflight routes symptom →
finding along its outgoing edges. A malformed label makes the check or route
silently stop firing — the node still exists and simply never matches
again. list shows the graph as its readers see it, create adds a node
with every edge that makes it discoverable, and lint detects the
silent-skip defects mechanically.
hadron coding review run [-m <memory>] [--base <ref>] [--head <ref>] [--diff <path|->] [--root <loc>] [--all] [--limit N] [--offset N]
hadron coding review list -m <memory> [--root <loc>] [--broken]
hadron coding review create <check-name> -m <memory> --trigger <cond> --description <d> [--scope <s>] [--tag <t>]… [--link <ref>[=<label>]]… [--seq N] [--content <text|-> | --content-file <path>]
hadron coding review lint -m <memory> [--root <loc>] [--toolchain <t>|-] [--strict] [--suggest] [--fix [--yes]]
hadron coding preflight list -m <memory> [--root <loc>] [--broken]
hadron coding preflight create <loc> -m <memory> --route <action> --description <d> [--name <n>] [--symptom <s>] [--section <heading>] [--type <t>] [--tag <t>]… [--link <ref>[=<label>]]… [--seq N] [--content <text|-> | --content-file <path>] [--no-back-edge] [--no-body-line] [--dry-run]
hadron coding preflight route <node-ref> -m <memory> --route <action> [--description <d>] [--symptom <s>] [--section <heading>] [--no-back-edge] [--no-body-line] [--dry-run]
hadron coding preflight lint -m <memory> [--root <loc>] [--strict]
A node counts as a checklist item when it sits under the parent's loc prefix
(review: by default) and isn't tagged meta. Findings exit 5;
--strict promotes warnings to errors. --suggest proposes label fixes and
--fix applies them (with --yes to skip the prompt). --broken narrows a
listing to just the malformed rows.
review run — the checklist against a diff¶
coding review run returns the review checks a change could fire, with
their full bodies, in one response. The change set comes from git —
--base/--head, defaulting to the merge base with the default branch and
the working tree, untracked files included — or from --diff <path|->, a
unified diff. --diff - reads a pipe and is refused (exit 2) from an
interactive terminal, because a truncated paste silently drops files.
--diff with --base/--head is refused too. -m is optional: from a
checkout, the memory resolves from .hadron/config.json, the configured
memory, or the git remote's repository name, and the choice is printed to
stderr.
Each check lands in one bucket, decided structurally from the path patterns the check names, never from its prose:
matched— a named path changed;matchedOnrecords the (pattern, file) pair that fired.undecided— the check names no paths. Returned in full: "cannot tell" is not "does not apply". Most checks in a mature checklist land here.excluded— the check names paths and the diff touches none. Listed with its patterns, never silently dropped;--allreturns these checks too.
--limit/--offset page the checks, and nextOffset is non-null only when
they withheld some. --json is an object — unlike review list's array —
with memory, memorySource, base, head, diffSource, changedFiles,
total, returned, nextOffset, checks[], excluded[] and
unavailable[].
hadron coding review run --base origin/main --json
git diff origin/main | hadron coding review run --diff -
Adding a route¶
preflight create writes the three things a routed node needs to be
reachable, because a node with only some of them looks healthy and isn't:
- the router's outgoing edge, labelled
to <action>— whatpreflight listandpreflight lintread; - the mirrored back-edge, so the route reads the same when someone lands on
the node from search instead of via the index (
--no-back-edgeto skip); - the routing line in the router's body —
- **"<symptom>"** → [[<loc>]] — <description>— which is what a human or an agent readingpreflighttop to bottom actually scans.
<loc> is the target's full loc: route targets live wherever they belong
(findings:…, conventions:…, ops:…), with no prefix rule. Where the
routing line goes is resolved before anything is written. A router with one
routing list takes it automatically; one with several headed sections needs
--section <heading>; a router that routes purely by edge label needs
--no-body-line. An ambiguous router is a usage error listing the headings —
never a half-written route. --dry-run rehearses all three writes, including
which section the line lands in, and issues none of them.
If the route edge or the body update fails, the node still exists: the
command prints the exact repair — an hadron edge create line, or the
routing line to paste — and exits 1, never 0.
Routing at a node that already exists¶
preflight create mints the node it routes to. When the node is already there
— usually a finding or task somebody else wrote, and often in another
memory — route does the same wiring without creating anything:
hadron coding preflight route hrn:node:acme.com:specs:tasks:create-platform-spec \
-m hrn:mem:acme.com:dev --route "add or change a spec in the law corpus" \
--section "Maintaining the memories themselves"
Two differences from create:
--descriptionis optional. The target already describes itself, so its own description becomes the routing line's text unless you override it.- A cross-memory target is referenced as
`<loc>` in `<memory>`, not as a bare[[loc]]. A wikilink resolves against the router's memory, so a bare one would point at nothing there and render as a dead link with no error anywhere. The memory name is read from the server, so every accepted spelling of the ref you pass yields the same canonical label.
Re-running is safe: an existing edge is not duplicated, an edge under a
different label is recognised as a different route rather than mistaken for
this one, and a body that already references the target is left alone.
--dry-run rehearses all three writes and issues none.
AI service configs¶
hadron ai-config ls lists the masked set of AI service configs
resolvable in an App's chat context — every distinct config name a chat
could select. It is the config picker an app or UI presents; each row is the
one resolveAIConfig would pick for that name.
| Column | Meaning |
|---|---|
NAME |
Config name, unique per owner (e.g. default, fast, frontier). |
OWNER |
Tier that owns the winning row: HADRON_SERVER, ORGANIZATION, APP, or AGENT. |
PROVIDER / MODEL |
Provider id (anthropic, openai, glm, bedrock) and model identifier. |
ENABLED |
Whether the config is enabled. |
KEY |
Key preview (ellipsis + last 4 characters), or — when no key is set. |
Resolution and masking:
- Resolution walks App → Agent → Org → HadronServer, deduped by name with
the innermost owner winning, enabled-only. Only the agent you name with
--agentcontributes — sibling agents installed in the same App are not consulted. - Output is masked. It never carries key material — only
hasApiKeyand the shortapiKeyPreview.--jsonemits the full masked record:id,name,ownerType,ownerId,provider,model,hasApiKey,apiKeyPreview,params,enabled,createdAt,updatedAt. --appdefaults to the configured App context (hadron app useor the global--appflag);--agentnarrows to one agent. Both accept an ID or a URN.- You must be a member of the App, and — when
--agentis given — the agent must be installed in it. App membership, not org-admin, is the bar because the result is masked. Platform admins may omit--app.
hadron ai-config ls --app acme.com:juno-app
hadron ai-config ls --app acme.com:juno-app --agent acme.com:juno --json
Create, update, and remove configs¶
ai-config ls is read-only and masked; to manage the underlying provider rows
it resolves over, use create / update / rm:
hadron ai-config create (--app|--agent|--org <id-or-urn>) --name <n> \
--provider <p> --model <m> [--api-key -] [--param k=v]… [--disabled]
hadron ai-config create --file <path>|- # whole config (key included) from JSON
hadron ai-config update <id> [--name <n>] [--provider <p>] [--model <m>] \
[--api-key -] [--param k=v]… [--enabled=false]
hadron ai-config rm <id> [--yes]
createneeds an owner — exactly one of--app,--agent, or--org(an ID or URN) — plus--name,--provider, and--model. The name is unique per owner (1-64chars,[a-z0-9_-]).- The API key is a secret. It is read from stdin via
--api-key -and is never echoed back — output is the same masked recordlsreturns (hasApiKey+apiKeyPreviewonly). Pipe it in:printf '%s' "$KEY" | hadron ai-config create … --api-key -. --file <path>(or--file -for stdin) reads the whole config — key included — from a JSON object, so nothing sensitive touches argv or shell history. The keys mirror the flags (all optional):app/agent/org,name,provider,model,apiKey,params(an object),enabled. The file seeds every field and an explicit flag overrides the matching one (e.g.--file cfg.json --model gpt-4o);--paramreplaces the file'sparamswholesale. Unknown keys are rejected (catches typos), and passing both--file -and--api-key -is an error (both read stdin).update <id>changes only the fields you pass.--api-key ""clears the key; omitting--api-keykeeps it.--param k=v(repeatable) replaces the whole params object.--enabled=falsedisables the config.rm <id>requires--yeswhen non-interactive.
printf '%s' "$ANTHROPIC_KEY" | hadron ai-config create --org acme.com \
--name frontier --provider anthropic --model claude-opus-4-8 --api-key -
hadron ai-config create --file frontier.json # same config, key included, from JSON
hadron ai-config update cfg_123 --model claude-sonnet-4-6
hadron ai-config rm cfg_123 --yes
These rows are what ai-config ls resolves over; for the end-to-end provider
setup see
Configure your LLM provider.
Inspect one config and list endpoint suggestions¶
ai-config get <id>shows one config by id.endpointis the stored override andeffectiveEndpointis the destination the server resolves; a nullendpointuses the provider default. The full key is never returned. An unknown id reportsAI service config "<id>" was not found.ai-config endpoints <provider>shows the server's endpoint suggestions for one provider, asURL,LABEL,DEFAULTandNOTEcolumns (--json:url,label,isDefault,note). The default is the destination used when a config has no stored endpoint. Notes may explain billing or provider terms. An empty list means the server has no suggestions. The command never changes a config.
External MCP servers¶
hadron mcp-server manages registered external MCP servers — the conduit
that lets a headless run call tools that live outside Hadron.
hadron mcp-server ls [--org <ref>] | get <id> | tools <id>
hadron mcp-server create --org <ref> --slug <s> --name <n> --url <u> [--header 'Name: value']… [--allow <tool>]… [--disabled]
hadron mcp-server update <id> [--name <n>] [--url <u>] [--header …]… [--clear-headers] [--allow <tool>]… [--clear-allow] [--enabled|--disabled]
hadron mcp-server rm <id> --yes
Each registered row exposes its tools to runs as mcp__<slug>__<tool>,
which a node's data.tools declares. Registration alone grants nothing —
the run must still be allowed tool.mcp__<slug>__<tool> by the policy chain.
--allow narrows which of the server's tools are exposed at all;
--clear-allow / --clear-headers reset those lists rather than appending.
tools <id> lists what the remote server currently advertises.
See Call external MCP tools from a flow for the end-to-end walkthrough.
Connections and grants¶
hadron connection grant delegates scoped access on your own external
connection (email, calendar, or drive) to a specific App install — for example a
headless assistant that reads your inbox or answers free/busy.
hadron connection grant create --connection <ref> --app <ref> --scopes <s>[,…] [--expires-at <iso>]
hadron connection grant ls [--connection <ref>]
hadron connection grant revoke <grant-id> --yes
You must be the connection's owner to grant on it — there is no org-admin
bypass. Scopes are drawn from mail.read, mail.send, calendar.freebusy,
calendar.read, and drive.read. Grants may carry an expiry and are revocable
at any time; several operations (deleting, moving, marking read, flagging and
categorizing mail, and creating drive documents) are owner-only and no
scope reaches them. See Grant an App access to a
connection.
Connected accounts: email, calendar and Drive¶
Three read-only groups look at the external accounts an organization has
connected. They share one idea: a connection is an account someone linked.
calendar and drive name the one they read with --connection <id>, and
email connections lists the organization's connections (--org). The CLI never
picks a connection for you. To grant an App access to a connection instead, see
Connections and grants.
hadron email connections --org <ref>
hadron calendar list --connection <id>
hadron calendar events --connection <id> [--calendar <id>] [--from <t>] [--to <t>] [--query <text>] [--top 1..100]
hadron calendar event get <eventId> --connection <id> [--calendar <id>]
hadron calendar freebusy --connection <id> --from <t> --to <t> [--schedule <id>]...
hadron drive list --connection <id> [--folder <id>] [--query <text>] [--name-contains <text>] [--mime-type <t>] [--modified-after <t>] [--top 1..100] [--page-token <token>]
hadron drive get <fileId> --connection <id>
hadron drive export <fileId> --connection <id> [--format MARKDOWN|TEXT|HTML]
Written from --help and the spec, not from a live account
These commands need a connected account on the server. This page is worded
from the released --help and the connection model in the platform specs
(cor:dmo:080:04); the commands were not run against a connected account.
Anything not stated here is the server's to decide.
Finding the connection ID. hadron email connections --org <ref> lists the
organization's connected accounts: the ID, owner, mailbox address, provider,
whether syncing is on, the sync status and when it last synced. Mail, calendar
and Drive connections all appear in it, so the ID column is what you pass as
--connection to calendar and drive. It needs org admin; --org takes
an organization ID or hrn:org:<slug>. It only lists: it does not read mail,
reconnect an account or send anything. An empty result means nothing was
returned to you, not that none exist. Without --json it prints a table; with
--json an array of id, organizationId, userId, mailboxEmail,
provider, displayName, syncEnabled, syncStatus, lastSyncAt,
createdAt and updatedAt (unset values are null, an empty result is []).
Credentials are never requested.
Access. Listing connections is not access to what they hold. For calendar
and drive you need to own the connection or hold a grant on it (drive.read
for Drive; calendar.read for events and calendar.freebusy for free/busy,
which are separate permissions). An organization admin's connection list is not
by itself calendar or Drive access. If the provider refuses, you see the
server's own message and the usual exit code.
These commands only read. Nothing is created, changed, deleted or answered, no invites or notifications are sent, and nothing is retried. Text that comes from the provider (event titles, file names) is shown as data, not instructions.
calendar¶
calendar list(aliasls) lists the calendars you can see on the connection: each calendar's ID (pass it as--calendarelsewhere), name, time zone, whether it is the primary calendar and whether you can edit it.calendar eventslists events, optionally between--fromand--to, or matching--query(non-empty text). You get one list of at most--topevents (default 25, 1 to 100) with no next page, so narrow the window or the query to see more.--fromand--toare RFC 3339 date-times with a UTC offset, for example2026-10-30T00:00:00-07:00; a bare date is refused. Without--calendarthe provider's default calendar is used.calendar event get <eventId>reads one event by theidthatcalendar eventsreturned. Add--calendarwhen the event is not on the provider's default calendar.calendar freebusyshows the busy windows between--fromand--to(both required, with a UTC offset). Titles and attendees are not returned. Repeat--schedulefor each calendar ID or email address; without it the provider's default calendar is used. A calendar that is not shared with you has anerrormessage instead of busy windows: that is not the same as free.
An all-day event keeps its date as YYYY-MM-DD, never as midnight. Timed events
keep the instant and the zone apart. Fields with no value are null and empty
lists are []. Human output is the same JSON, labelled; --json prints only
that JSON.
hadron email connections --org hrn:org:acme.com
hadron calendar events --connection <connection-id> \
--from 2026-10-30T00:00:00-07:00 --to 2026-10-31T00:00:00-07:00
hadron calendar freebusy --connection <connection-id> \
--from 2026-10-30T09:00:00-07:00 --to 2026-10-30T17:00:00-07:00 \
--schedule alice@example.com --schedule bob@example.com
drive¶
drive list(aliasls) lists files, or narrows them with--folder(a folder ID fromdrive list),--query(text inside files),--name-contains,--mime-type(exact) or--modified-after(an RFC 3339 date-time with an offset). You get one page: 50 files when browsing, 25 when you search, or--top(1 to 100). When more exist the output ends with anextPageToken; run the same command again with the same filters plus--page-token <that token>. The last page has anulltoken.drive get <fileId>shows one file's details (name, kind, MIME type, size, parent folders, times and web link), not its text.sizeis in bytes and isnull, not 0, for Google documents and folders.drive export <fileId>prints a file's text to standard output with no heading and no added newline. There is no output-file option; redirect with your shell (> notes.md).--formatisMARKDOWN,TEXTorHTML(any letter case); without it the server picks the default for that file type. With--jsonyou get an object with the file's details, the format, the MIME type and the text incontent. Treat the text as untrusted: the CLI only prints it.
How exports are converted, and how large a file may be, is decided by the server.
A refusal such as file_too_large is shown as it came, and a file is never
silently cut short. No document is created in Drive by these commands.
hadron drive list --connection <connection-id> --name-contains budget
hadron drive export <file-id> --connection <connection-id> --format MARKDOWN > notes.md
Page-monitor watches¶
Both need organization ADMIN. list shows the organization's page-monitor
watches. The list is unpaged on the server, so it carries no total and is not
claimed to be complete. A job id from another organization, or an unknown one,
is NOT_FOUND. cancel needs --yes, and cancelling a watch that is already
cancelled succeeds with alreadyCancelled.
Home Assistant instances¶
hadron ha reads the registry of Home Assistant instances (smart-home hubs)
registered for your organizations, and the actions ("ops") an AI agent may take
on each.
Written from --help, not from a live instance
These commands were not run against a registered instance. The wording
below is the released --help.
These commands only read the registry. They never contact the Home
Assistant host and cannot show its access token. There is no command here to
register, change or remove an instance: an organization admin registers one
with the GraphQL mutation createHomeAssistantInstance, for example through
hadron api.
ha list(aliasls) lists instances sorted by slug, optionally only those of one organization (--org, an ID orhrn:org:<slug>). Each row has the instance ID thatha getandha opstake. You get one page of--limitrows (1 to 200, default 20); when more exist, stderr says which--offsetto use next.--jsonprints a plain array.ha get <id>(aliasshow) shows one instance: name, slug, address, owning organization, whether it is enabled, which ops are allowed, and who created and last changed it."allowlist": "all"means every op the server offers, not none. "Not found or not visible" means either no instance has that ID or it belongs to an organization you are not a member of; the server does not say which.ha ops <id>lists what an agent may do on the instance: each op with its description and aRUN-TOOL-NAMEof the formha__<slug>__<op>, which an author lists in a node'sdata.toolsto name that action. The list is every op the server knows, narrowed to the instance's allowlist. No request is sent to the Home Assistant host. A disabled instance is refused by the server (HA_INSTANCE_DISABLED) and that message is shown as it came.
Listing an op does not let a run use it. A run must still be allowed
tool.ha__<slug>__<op> by the policy chain (the rules that decide what a run
may use); registering an instance grants nothing by itself.
Secrets¶
hadron secret manages the owner-scoped secret store. Values are
write-only: create reads the material from stdin, a file, or an
interactive no-echo prompt — never from argv — and ls prints only the
inspectable half (name, kind, metadata, audit fields), never the value.
hadron secret create --name <n> --scope user|org|app|memory [--owner <ref>] --kind generic|webfetch-auth [--value-file -|@file]
hadron secret ls --scope <s> [--owner <ref>]
hadron secret rm <id> --yes
--scope user may omit --owner to mean the caller; the org, app, and
memory scopes require --owner. A webfetch-auth secret additionally takes
--type bearer|basic|header plus --url-prefix, and the server derives its
metadata.type. rm requires --yes non-interactively.
Agents¶
An Agent is a builder's creation — the thing an App installs and runs (see
Building an agent). hadron agent manages
their lifecycle.
agent ls— the member-scoped view: agents in orgs you belong to. Filter with--org,--type ASSISTANT|CHATBOT,--visibility ORGANIZATION|PERSONAL|PUBLIC, and page with--limit/--offset.agent ls --public— a separate surface: the cross-org marketplace slice of every live PUBLIC agent, readable without org membership, so you can grab a foreign agent's URN to subscribe to or install.--typestill filters;--org/--visibilitydon't apply (they're a usage error here).agent get <ref>— one agent by ID or URN (full detail in--json).agent create --org <id> --name <n>— with optional--type,--visibility,--description,--system-prompt,--system-memory <id>, and--surface <s>(repeatable).agent update <id> [<field flags>]changes only the fields you pass (--surfacereplaces the set).agent rm <id>requires--yeswhen non-interactive.agent set-base <agent> (<base> | --clear)sets the base Agent this one extends, or removes it with--clear. The base's system memory is inherited: its tasks and processes lists, and the nodes the Agent's workers read, come through the chain, deduped by the server. A chain may hold at most four Agents. Setting a base needs a licence to it: a PUBLIC base needs an active subscription, an organization-owned one needs an organization grant. Whoever manages the Agent may set its base.agent set-boot-prompt <agent> (<node-ref> [-m <memory>] | --clear),app agent set-boot-prompt <app> <agent> (...)andteam worker set-boot-prompt <worker> (...)set the boot-prompt pointer of an Agent, an installed Agent or a customized worker. The compiled node must be in the Agent's own system memory, the App's install memory for that Agent, or the same install memory for a worker.<node-ref>is a node id, a fully-qualified node URN, or a bare loc with-m <memory>;--clearclears the pointer. Passing both or neither exits 2 before any request. Each command sends one mutation and never retries. The manager sets it as themselves: the three commands never send a bound worktree's worker session, and a request that carries one is refusedBOOT_PROMPT_POINTER_SESSION_REFUSED(exit 8). Exits:_NOT_COMPILED,_WRONG_ROLE,_WRONG_MEMORYexit 2;_NOT_FOUNDexits 4 (a missing, deleted or unreadable node alike);FORBIDDENexits 8. Setting a pointer does not approve the prompt. See Boot-prompt pointers for what each refusal means.agent compile <agent> [--no-set-pointer] [--as-worker],app agent compile <app> <agent> [--as-worker]andteam worker compile <worker> [--no-set-pointer] [--as-worker]compile a boot prompt (see Compile a boot prompt). The App-Agent command always sets its pointer and has no--no-set-pointer; the other two set the pointer unless you pass it. They act as you, the manager, and send no worker session, unless you pass--as-worker(below). The server chooses the source and output addresses. A worker may be given as a name in the selected App. Each command sends one mutation and never retries.--jsonis{ "compiledNodeRef", "revision", "contentHash", "pointerSet", "approvalIssued" }. A compile writes a revision even for unchanged text and never approves:approvalIssued: falseis not the revision's approval status, so read that withnode get. Exits: permission or grant required 8; an unavailable include 4 (missing and unreadable look the same); retired target, missing or invalid source, a retired or unavailable include revision, orCONFLICT5; a malformed, cyclic, too-deep or disallowed include, or the compile limit, 2. A lost response is exit 7 with an unknown outcome: check the compiled node withnode getbefore compiling again.--as-workersends the bound worktree's worker session for that one mutation (reads stay yours). It never falls back to you: without a usable binding for this server and App it exits 2 and sends nothing. The CLI does not check the grant, and the server's refusals print with their codes (exit 8). The grant does not cover signing. See Let a worker edit its own boot prompt. Needs CLI 0.42.0.- On the compile commands the server admits only a new revision of an
existing compiled node that a signed
bootprompt.compile.approvegrant names. It never sets a pointer (pointerSetisfalsewhatever--no-set-pointersays) and never creates a node. - On
node approvethe flag approves one revision of a compiled node the grant names: the one you name with--revision, or, without it, the revision current when the server takes the node lock. It compiles nothing and writes no revision. - On
team worker approvethe flag sends the worker session with each of its per-worker approvals. Each is an approval of an existing compiled revision, as fornode approve; the command compiles nothing and creates no revision. A worker whose compiled node the grant does not name is refused for that worker alone (exit 8) while the others go on (seeteam worker approve).
- On the compile commands the server admits only a new revision of an
existing compiled node that a signed
-
agent clone <source> --to <org> [--name <n>] [--slug <s>]clones a PUBLIC Agent, or one you manage in its own organization, into an organization you administer. The server creates a newPERSONAL-draft Agent with its own copy of the system memory and copies its links and imports. Linked memories stay links, not copied knowledge.--tois required and must be an organization (id or URN); without--namethe clone carries the source's name, and the server decides both defaults. It prints the new Agent's URN;--jsonreturns the normal Agent fields. It sends one mutation and never retries. A typed refusal means nothing was created. Exit 7 means the outcome is unknown and the clone may exist: runhadron agent list --org <org> --visibility PERSONALbefore cloning again. A clone does not install anything. The new Agent records where it came from inclonedFromAgentRef. If the source has a base or imports, the target organization must be able to use each one. One it already holds an active license for is used as it is. If it has no license record at all, aPUBLICAgent is subscribed for it and an Agent from the target organization is granted to it. A license record that exists but is no longer active is never reactivated by a clone, and the clone is refused withCLONE_BASE_UNUSABLEorCLONE_IMPORT_UNUSABLE, as it is for any other Agent the target cannot use.Copied: the name, description, type, surfaces,
usesTasks,registerDefaults,installationPolicy,memoryProvisioningand persona role; the system memory graph (nodes, edges and pending edges, with the tasks and processes index pointers remapped); the links; and the imports and the base, re-pointed at the new Agent. Linked memories are not copied: the clone is linked to the same memories, so a linked memory the clone cannot read, or one that is encrypted, refuses the clone (CLONE_LINKED_MEMORY_UNREADABLE,CLONE_LINKED_MEMORY_ENCRYPTED).Not copied:
- visibility (the clone is
PERSONAL), AI service config, boot-prompt pointers and compiled boot-prompt nodes - node comments, decisions and decision logs, and node revision history
- derived include edges and embeddings (both are re-created for the clone)
- assets
- git-sync config, the editor lock and the published-revision pointer
- Worker castings and App installs
- the source organization's subscriptions and grants
A refusal prints the server's reason code in the text form (
... (clone refusal: CODE)) and carries it aserror.extensions.codewith--json. Reason codes with their exit codes:Reason code Exit Cause AGENT_URN_TAKEN5 The target organization already has an Agent or memory at the URN the clone would take. The server derives the last part of that URN from --slug, or from the name (--name, else the source's name) when there is no--slug; either way it is turned into a slug first. Cloning into the source's own organization with neither flag usually collides; pass--nameor--slug.AGENT_NOT_FOUND4 The source does not exist, or you cannot see it. ORGANIZATION_NOT_FOUND4 --tois not an organization you can see.FORBIDDEN8 You do not administer the target organization. The remaining refusals, with the exit code the CLI gives them:
Reason code Exit Cause AGENT_NOT_PUBLIC8 The source is not PUBLICand you do not manage it in its own organization.CLONE_BASE_UNUSABLE,CLONE_IMPORT_UNUSABLE8 The source's base, or one of its imports, cannot be used by the target organization (see above). The refusal's blockerslist has one blocker per reason code, and itssubjectsare the bases or imports that failed: each carries a name only if you can read it, and always aposition, the server's number for that subject, printed as received (position 2).CLONE_LINKED_MEMORY_UNREADABLE8 A memory linked to the source is not readable for the clone. CLONE_LINKED_MEMORY_ENCRYPTED2 A linked memory is encrypted. CLONE_ENCRYPTED_CONTENT2 The source holds encrypted content. CLONE_TARGET_UNSUPPORTED2 --tonames a user; clone into an organization.CONFLICTwith reasonAGENT_CLONE_SOURCE_CHANGED5 The source kept changing during the clone. The server marks it retryable; the CLI never retries for you, so run the command again. AGENT_RETIREDis also a possible refusal; the CLI has no clone-specific exit code for it. A refusal can list several blockers, and the exit code follows the first one. The CLI's own tests pin the listed exit codes, and the first-refusal rule, against simulated server answers;ORGANIZATION_NOT_FOUNDexits 4 by the CLI's general not-found rule.# Clone an Agent you manage into its own organization, under a new slug hadron agent clone hrn:agent:acme.com:coordinator \ --to hrn:org:acme.com --name "Our assistant" --slug our-assistant # hrn:agent:acme.com:our-assistant hadron agent get hrn:agent:acme.com:our-assistant --json # "visibility": "PERSONAL", "clonedFromAgentRef": "hrn:agent:acme.com:coordinator" - visibility (the clone is
-
agent tasks list <agentRef>(aliasls) lists the Agent's effective task list: the tasks its own index edge lists plus everything inherited from its base, deduped by the server. Columns:TRIGGER(the index edge that lists the task, blank when none does),NAME,URN, andINHERITED FROM(the base Agent a task comes through, blank for the Agent's own). A task can appear with a blankTRIGGER: that is a task with no index edge listing it. agent processes list <agentRef>(aliasls) lists the Agent's effective process list, own plus inherited, deduped by the server. Columns:TRIGGER,KIND,NAME,URNandINHERITED FROM.KINDisstarts(the process is listed in the Agent's own processes index) orinvolved(the process has a stage edge to one of the Agent's tasks). The text table prints it in lowercase;--jsoncarries it asSTARTSorINVOLVED.TRIGGERis the index edge's name forstartsrows and blank forinvolvedrows.
With --json, each row is { "node": { "id", "urn", "name", "inheritedFrom" },
"trigger" } for tasks, and the same plus "kind" for processes;
inheritedFrom and trigger are null when blank in the table.
<agentRef> must be a fully qualified agent URN or an id; a bare name is
refused with a message naming the expected org::agent-slug form. An Agent
with no tasks or processes prints [] with --json.
# Discover a public agent, then read it
hadron agent ls --public --type ASSISTANT --json
hadron agent get acme.com:support-bot --json
hadron agent create --org acme.com --name "Support Bot" --type CHATBOT \
--visibility ORGANIZATION --description "Front-line triage"
agent boot-prompt — read the boot prompt an Agent is served now¶
Prints the boot prompt the server serves for the Agent at this moment, with no
worker binding. Stdout is a header line, served boot prompt: <LEVEL>
<compiledNodeId> revision <N>, then the served text unchanged (a final newline
is added on a terminal only). --json prints {decision,text}.
Without --app it reads only the Agent's own pointer, never the configured
default App.
| Result | Exit |
|---|---|
AGENT_NOT_FOUND |
4 |
BOOT_PROMPT_NOT_SET, BOOT_PROMPT_TARGET_DELETED, BOOT_PROMPT_NOT_APPROVED, BOOT_PROMPT_NOT_SIGNED |
1 for all four, so tell them apart by the code printed, not the exit |
| A malformed decision | 1 |
| A valid decision with empty text | 0 (success) |
See Serve a boot prompt for what each refusal means.
Apps¶
An App is an Agent installed somewhere (see
Agents and Apps). hadron app installs and
removes them (install, uninstall, list, set-active; see the surface
above), and works with their members, memories and keys. Every command here
takes the App as a positional reference or from --app / the active App, as
each says. An App reference is an id, hrn:app:<root>:<slug>, or the
<root>:<slug> short form.
app chatbot-ai-config — pin the AI config an App's chatbot uses¶
hadron app chatbot-ai-config get|list|clear <app-ref> [--json]
hadron app chatbot-ai-config set <app-ref> <name-or-id> [--json]
The pin is the id of one of the App's own AI configs. Spec: cor:dmo:050:10 and cor:dmo:050:12.
get(andapp get) showchatbotAiConfigId, the server-returnedchatbotAiConfigNameandchatbotAiConfigListed. In JSON,chatbotAiConfigListedisfalsewhen nothing is pinned or when the pin is not among the App's enabled choices (the text says so and never calls it in use), andnullwhen the read of the choices failed, so membership is unknown. If the App does not exist,getexits 4. The explicitgetfails on a server that lacks the field;app getstill works there. The name comes from the choices list, never from the Agent, Org or Host.listshows the narrow set of choices the server returns: the App's own enabled configs plus adefaultmarker, which is not a config and has no id. JSON is an array of{value,name,isDefault,isAppChatbotConfig,provider,model}. It is notai-config list.setmatches an exact id first, then an exact name, among those choices only. A value that matches nothing is sent as given, and the server refuses a missing, foreign or deleted config alike. The argument is not trimmed. The worddefaultis never matched by name (set a config that is nameddefaultby its id).default, an ambiguous name and an empty value exit 2 with no mutation.clearsends an explicit null and removes only the selection.
set and clear are single mutations and are never retried; get and list only read. The server decides who may manage the
App. No key, preview or endpoint is requested.
app uninstall, app reinstall and app delete¶
Three commands, three outcomes. Spec: cor:dmo:050:21.
| Command | What it does | Resulting state | --json status |
|---|---|---|---|
app uninstall <app-ref> [--yes] |
Keeps the App, makes it read-only and frees its handle. Reversible. | Writes are refused APP_UNINSTALLED. |
uninstalled |
app reinstall <app-ref> |
Restores the same App: id, keys, members and memories. Nothing is created. | Installed again. | installed |
app delete <app-ref> [--yes] (alias app rm) |
Stops the App serving. The App is kept, but there is no undelete. | Deleted. | deleted |
- Breaking change in v0.43.0. Before it,
app uninstalldeleted the App. A script that ranapp uninstall --yesto delete now uninstalls instead, which is the reversible outcome and which the output says. To keep deleting, change the command toapp delete(orapp rm).app uninstallno longer has thermalias. Release note. - Confirmation.
app deleteandapp uninstallask on a terminal and need--yesotherwise (exit 2 without it).app reinstalldoes not ask. - Refs. An id or URN is sent to the server unchanged, with no preflight.
For
uninstallandreinstall, a URN names the installed App holding it, else the one uninstalled App with it. Fordelete, a URN names only the installed App holding it. Name an uninstalled App by id to delete or reinstall it: its former URN may now name another App. --jsonprints{"app": "<ref>", "status": "deleted" | "uninstalled" | "installed"}, wherestatusis the resulting state. The error envelope carries the server's code asserverCode.- Repeats.
uninstallandreinstallanswer a repeat as they do a real change, so a repeat prints the same thing. A repeatapp deleteby id is refusedAPP_DELETED(exit 5). A URN is resolved afresh on every call: while no installed App holds it, a repeat by URN gets the same refusal as a missing App (FORBIDDEN, exit 8), but once another App reclaims the handle the URN names that App and a repeat deletes it. Delete and retry by id to keep the target fixed. - Refusals.
APP_DELETED(exit 5): a deleted App can't be uninstalled, reinstalled or deleted again by id.APP_URN_IN_USE(exit 5): another installed App holds the handle, so reinstall is refused.- A missing App and a caller without the right get one identical refusal (exit 8), for all three commands.
app get, app update and app memories¶
app get <app-ref>reads one App's id, URN, name, type and description. It does not request settings, nested keys or AI configuration. A null description staysnullin--jsonand shows as-in text; that does not say whether the value is unset or withheld. The server decides access.app update <app-ref>changes an App's--name,--descriptionand--session-timeout-seconds, and nothing else: URN, type, surfaces, roles, identity and admission policy and AI keys stay in the portal. Only the flags you pass are sent.--clear-descriptionclears the description (name and timeout cannot be cleared). Passing no flag changes nothing and is refused. The command shows the resolved App and the names of the fields it will change, never their values, and asks first; without a terminal pass--yes. The server's validation and authorization refusals are shown as returned; the CLI invents no timeout default and clamps nothing. If the connection drops after the request is sent, the outcome is unknown: nothing is retried, so read the App back before trying again.app memories [<app-ref>]lists the memories a search across the whole App covers, one row per memory with every reason it is in scope. Omit the reference to use--appor the active App. The reasons areAGENT_SYSTEM(the system memory of an installed Agent),AGENT_LINK(a memory linked to an installed Agent),INHERITED_BASE(a base Agent's system memory, inherited by an installed one) andTEAM_SPACE(the App's own team space). An Agent's name follows its kind when you may read that Agent. App participants also get the team space; reading the App's organization does not add it. TheWRITE (ADVISORY)column says whether you may create nodes there:yes,no, orinheritedfor a memory in scope only as an inherited base, which belongs to the base Agent and is not a write target here. The column is advice: the server still decides every write.--limit(1 to 200, default 20) and--offsetpage the list, ordered by memory URN, and stderr says how to fetch the next page.--jsonprints{ "items", "total" }; each source addsagentNameand each row addswriteTarget. Exit 8 when you may not read the App's scope, 4 when the App is not found. The rule is cor:dmo:050:17.
app member — who belongs to an App¶
hadron app member list
hadron app member add --user <ref> --role <role> [--yes] [--instruction <kind>:<ref>]
hadron app member remove --user <ref> [--yes] [--instruction <kind>:<ref>]
hadron app member roles
member (alias members) manages an App's human members
(cor:dmo:050:04). There is no positional App: the App is --app, else the active
App. --user is an id, email, handle or hrn:user: URN, passed to the server
unchanged and never resolved by the CLI.
list(aliasls) shows the members you can see. An empty list means "no members visible to you", never "no members".addis an idempotent upsert: the same role is a repeat, a different role changes the membership. The command never reads the list first, so every add is confirmed: pass--yesto skip the prompt; a non-interactive caller without it is refused before anything is sent.remove(aliasrm) is reversible: add the user again. The server answers the same whether or not the user was a member, so success means "not a member now". An App member manager may remove anyone; anyone else only themselves, and every other target gets the same refusal, so it cannot be used to test whether a user exists. Confirmed first;--yesskips the prompt.rolesprints the roles the App offers, which are the valuesadd --roleaccepts: the union of its installed Agents' member roles, primary Agent first. Text is one role per line;--jsonis an array of strings. Change an Agent's roles withhadron agent update <ref> --member-roles ….
Roles are validated by the server only: an invalid --role is refused with the
server's own message. If a response is lost the outcome is reported as unknown
and the write is not retried; check with member list.
Instructed staffing and membership¶
hadron team worker cast … [--dry-run] [--instruction <kind>:<ref>]
hadron team worker retire <name-or-id> --yes [--instruction <kind>:<ref>]
hadron team worker rm <name-or-id> --yes --confirm-no-external-attribution [--instruction <kind>:<ref>]
hadron app member add --user <ref> --role <role> [--yes] [--instruction <kind>:<ref>]
hadron app member remove --user <ref> [--yes] [--instruction <kind>:<ref>]
These five commands take --instruction <kind>:<ref> (hadron-cli#1594, built by
hadron-cli#1606; merged on hadron-cli main at dd8fe73b and first
shipped in release v0.37.0, which v0.35.0 does not have; needs a server at
517eb1db or later). It is a bound
worker's claim, for that one call, that its holder told it to make the change.
kind is team-chat-message, task or live-chat; ref is everything after
the first colon, unchanged, and is a reference, never instruction text. A bad
kind or a blank ref exits 2 before any prompt or request. What the claim is, and
the two grants (workers.staff, app.members) that let a worker act without
one, are in Staffing and membership
doors.
- Without the flag the call is yours, as before: it carries no worker session, even from a bound worktree. A worker session that reaches these doors another way (for example the MCP tools, which take no instruction) needs its own grant.
- With the flag the claim goes through the worktree's worker session only when the binding, as it stood before the command's first lookup, is complete, for this server, for the App the change targets, and unchanged when sent. Otherwise the call goes out as you, and the server checks the reference but records no claim. When a binding exists but cannot be used, stderr says why; with no binding at all, the fallback is silent. Lookups made to decide this never carry the session.
- The holder still needs the right to make the change themselves. The server checks the reference, never that an instruction happened.
- Recorded. An admitted claim is recorded, also for a change that changes
nothing: a preview (
cast --dry-run), a cast of a worker that already exists, an already-retired worker, or a member that is already or not a member. - A host-launched session's claim is ignored (not checked, not recorded): it acts only on its own grant.
- No command for
leaveApp. Leaving an App by a worker session is the same rule on the server, but the CLI has no command for it.
Refusals keep their codes: FORBIDDEN is exit 8, with serverCode in --json
errors.
app agent ls — install method¶
hadron app agent ls [<app-ref>] lists the App's readable agents (the cast
pool). Each entry shows how the App installs the agent, in an INSTALL column:
installed for a physical install, derived for an agent that an installed
agent imports directly, and ? when the server withheld the answer. For a
derived entry the importer's name and URN follow. ? is not installed: the
CLI never guesses, and the server withholds the answer from a caller who may
not read every installed agent. With two importers of one agent, the entry
names the importer whose import took effect first. Ties go to the earlier
import, then to the lower importer ID (see Installed, and derived from an
import).
--json adds installMethod (ROW, DERIVED or null) and importer
({id, urn, name} or null) to each member. The header counts readable
agents. The listing is one request for the one App you name, and when it
fails it fails as a whole, not only the INSTALL column. It first
shipped in release v0.37.0 (b425bbf1 is in it; v0.35.0 does not have it),
and it needs a server containing hadron-server#3446 (merged at d0b374cd);
an older server rejects the listing and the CLI does not fall back.
app agent customize and app agent compile¶
app agent customize <app> <agent>reads the App's install memory: the separate memory where the App keeps its customization of an Agent. It only reads; it creates no memory and writes no node. Both references are ids or fully-qualified URNs.--jsonis{ "memory": { "id", "urn", "name" } }or{ "memory": null }. Null means not available: no customization exists yet, the target is missing, or it is not shown to you. It is not proof that nothing exists. To create one, usenode add --install <app>/<agent> --loc <loc> --name <name>; only an App manager may write, while the App is live and the Agent installed.app agent compile <app> <agent>compiles the server-selected boot prompt into the install memory for that Agent and always sets the pointer. It is described with the other compile commands under Agents.
app key scope revoke¶
Takes a scope back from an App key (the counterpart of app key scope grant,
shown under team host). The key's next call that needs the scope
is refused. Revoking a scope the key does not hold changes nothing. Revoking
host:operate frees the key to be granted it for another host.
Listing and revoking App credentials with --instruction¶
hadron app key list <app-ref> [--scopes [--host-uses <n>]] [--instruction <kind>:<ref>]
hadron app key revoke <key-id> [--yes] [--instruction <kind>:<ref>]
hadron app key scope revoke <key-id> <scope> [--instruction <kind>:<ref>]
hadron app memory-grant list <app-ref> [--instruction <kind>:<ref>]
hadron app memory-grant rm <grant-id> [--yes] [--instruction <kind>:<ref>]
These five commands take --instruction <kind>:<ref> (hadron-cli#1598,
merged on hadron-cli main at c28a4a71 and first shipped in release
v0.37.0, which v0.35.0 does not have; needs a server at c3ca05b5 or later).
It is a bound worker's claim, for that
one call, that its holder told it to list or revoke. It is admitted when the
holder manages the App. kind is team-chat-message, task or live-chat;
ref is everything after the first colon, unchanged, and is a reference, never
instruction text. The server checks the reference, never that an instruction
happened, and refuses a host-launched session whatever it claims: there is no
grant arm at these doors.
- With the flag, a complete, unchanged worktree binding for this server sends its worker session. An unbound, corrupt, incomplete or foreign-server binding refuses locally (exit 2) and never falls back to you. Nothing is retried or downgraded. Without the flag the call acts as you, as before.
- Minting, rotating and granting stay person-only and have no flag:
key create,key rotate,key scope grantandmemory-grant add. - An admitted instructed
listis not record-free: every call, so every page, records oneapp.credential-actevent. An instructed revoke that changed a row records one; a revoke that changed nothing records none. The event names the worker, holder, App, kind and instruction, never a key, scope or grant id. - A worker the server refuses learns nothing about whether the key, scope or
grant exists. Refusals keep their codes (
--jsonserverCode).
What the claim is, and what is not verified, is in Acting on a holder's instruction.
Headless runs¶
A headless run executes an entry (prompt) node under an App's
identity, off any interactive session. The same execution kernel is reached
three ways: a manual trigger (run), a recurring schedule, or an
inbound webhook. run is also the audit and control surface — what ran,
why, what it cost, and the kill switch — and ticket governs the consumable
grants a gated run spends.
Every trigger names an entry node by fully-qualified URN and runs under
an --app. By default the run acts as the App; --as-self runs on
behalf of you — required to reach your personal memories, and usable only
by an authenticated user (an App-key caller gets UNAUTHENTICATED).
run — trigger, audit, cancel¶
hadron run trigger --app <ref> --entry <node-urn> [--arg k=v]… [--as-self] \
[--agent <ref>] [--ai-config <name>] [--budget-tokens <n>] [--budget-actions <n>] \
[--wait [--wait-timeout <dur>]]
hadron run list [--app <ref> | --org <ref>] [--status <s>] # alias: ls
hadron run get <id>
hadron run cancel <id> [--yes]
triggerstarts a MANUAL run now and prints the run id.--arg k=v(repeatable) sets template args (each value parsed as JSON or string).--ai-config <name>selects a named AI config for the run.--agent <ref>names the installed Agent that serves it; an App with several installed Agents requires it (details).--budget-tokensand--budget-actionscap this run's LLM tokens and actions (see Per-trigger token and action limits).--waitpolls to a terminal status and then exits non-zero if the run ended non-COMPLETED(FAILED/TIMED_OUT/CANCELLED), so a script can branch on the outcome.listis the audit surface — status, trigger kind, and run id. Scope with--appor--org(mutually exclusive); filter with--status(one ofPENDING,RUNNING,COMPLETED,FAILED,CANCELLED,TIMED_OUT).getshows one run in full: status, budgets, policy, and the failure payload when present.cancelis the kill switch — transitions a live run toCANCELLED. Prompts on a TTY; requires--yesnon-interactively.
hadron run trigger --app acme.com:ops --entry hrn:node:acme.com:ops:tasks:nightly-digest
hadron run trigger --app acme.com:ops --entry hrn:node:acme.com:ops:tasks:brief \
--arg topic=security --as-self --wait --json
hadron run ls --app acme.com:ops --status FAILED
hadron run cancel run_123 --yes
schedule — recurring triggers¶
hadron schedule create --app <ref> --name <n> --cron '<expr>' --entry <node-urn> \
[--tz <IANA>] [--arg k=v]… [--as-self] [--ai-config <name>] [--policy <json>] \
[--budget-tokens <n>] [--budget-actions <n>] [--disabled]
hadron schedule list [--app <ref>] # alias: ls
hadron schedule update <id> [--cron …] [--entry …] [--enabled=false] \
[--budget-tokens <n> | --clear-budget-tokens] \
[--budget-actions <n> | --clear-budget-actions] …
hadron schedule rm <id> [--yes]
hadron schedule preview --app <ref> --entry <node-urn> \
(--cron '<expr>' | --run-at <RFC3339>) [--tz <IANA>] [--agent <ref>] \
[--as-self] [--ai-config <name>] [--arg k=v]… [--disabled] \
[--budget-tokens <n>] [--budget-actions <n>] [--json]
A schedule fires the entry node on a 5-field cron expression evaluated in
--tz (default UTC). The runs it spawns show up in hadron run ls.
--policy is a trigger-layer allow-list, e.g. '{"allow":["comm.outbound"]}'.
update changes only the fields you pass (--enabled=false disables;
--policy "" clears the allow-list). --budget-tokens and
--budget-actions cap each run the schedule spawns; on update,
--clear-budget-tokens and --clear-budget-actions put one back to the
platform default (a value and its clear flag together is a usage error).
rm requires --yes non-interactively.
hadron schedule create --app acme.com:ops --name nightly-digest \
--cron '0 6 * * *' --tz America/New_York \
--entry hrn:node:acme.com:ops:tasks:nightly-digest --as-self
schedule preview — what a schedule would be, before it exists¶
preview is one read. It creates no schedule, adoption or run, and never
retries or falls back to a write. It answers whether the entry could be
adopted as a schedule and, if so, what the schedule would be allowed to do.
Needs CLI 0.38.0 or later and a server that contains
hadron-server#3463.
- Inputs.
--app(an id or URN; defaults to your App context) and--entry(a fully-qualified node URN) are the target. Give exactly one of--cron(five fields, read in--tz, default UTC) or--run-at(an RFC3339 instant).--agent,--ai-config,--arg,--disabled,--budget-tokensand--budget-actionsmean what they do onschedule create;--disabledpreviews switched-off timing.--as-selfruns the preview as you, the authenticated person; an App key cannot use it. Empty timing flags are refused before any request.--name,--scopeand--policyare not preview inputs and are not accepted. - ADOPTABLE exits 0 with a hash and a summary of what the schedule would
read, write, be unable to do, which tools and flows it has, its schedule line
(the server's own string) and its limits. Text cells are bounded and made
terminal-safe;
--jsonkeeps the server's values. - CANNOT_BE_ADOPTED exits 5 with only a reason:
MEMORY_UNREADABLEorOTHER. A missing entry and one you cannot read answer the same, so do not read a reason as telling them apart or as naming a memory. --jsonis{ "outcome", "hash", "reason", "summary" }. ForCANNOT_BE_ADOPTED,hashandsummaryarenull; forADOPTABLE,reasonisnull. Summary lists are arrays, empty ones included.- Exits. 0
ADOPTABLE; 5CANNOT_BE_ADOPTED; 2 usage errors, before any request; server refusals keepcreate's mapping (3 unauthenticated, 4 not found, 8 forbidden); 7 transport failure. A malformed reply exits 7 too: a reply with no result, a missing or inconsistent hash, reason or summary, or an outcome or reason this CLI does not recognise. A server that does not support preview fails with a non-zero exit and writes nothing; the exact code for that case is not fixed, so do not script against it. - A snapshot, not a promise. Preview reserves nothing and gives you no authority to create. The hash is the one the created schedule's approval carries only while the automation's graph is unchanged; a changed automation can change it.
- It does not check everything
createchecks.--name,--scopeand--policyare not read by the hash or the summary, and preview validates neither policy nor scope.createcan still refuse them, or anything else it checks, after anADOPTABLEpreview. - Who may preview. Preview needs the same authority
createdoes, and the server checks it first, before it reads the entry or the Agent: an organization admin or a platform admin. Anyone else is refused as forbidden (exit 8) and learns nothing about the entry. An App owned by a user rather than an organization is not supported yet (exit 2). Being allowed to preview is the same bar as creating, not an extra permission, and anADOPTABLEresult grants nothing. - Who may create. Authority is
create's: an organization admin or a platform admin, withcreate's own refusals. Scheduling by a worker requires a person's authorization or the applicable grant; the server decides admission.
hadron schedule preview --app acme.com:ops \
--entry hrn:node:acme.com:ops:tasks:digest --cron '0 6 * * *' --json
webhook — inbound triggers¶
hadron webhook create --app <ref> --name <n> --entry <node-urn> \
[--args-schema <json>] [--as-self] [--ai-config <name>] [--policy <json>] \
[--budget-tokens <n>] [--budget-actions <n>] [--disabled]
hadron webhook list [--app <ref>] # alias: ls
hadron webhook rotate <id> [--yes]
hadron webhook rm <id> [--yes]
A POST to the webhook's URL fires the entry node. The URL path and platform
token are printed ONCE, at create and rotate — store them then; the
secret is never queryable again (list never shows it). --name is
lowercase alphanumeric/dash (1–64 chars) and is part of the URL.
--budget-tokens and --budget-actions cap each run the webhook spawns;
there is no webhook update, so to change them create a new webhook. rotate
invalidates the old URL/token immediately and prints the replacement once;
both rotate and rm require --yes non-interactively.
hadron webhook create --app acme.com:ops --name deploy-notify \
--entry hrn:node:acme.com:ops:tasks:on-deploy
ticket — action-ticket ledger¶
hadron ticket mint --org <ref> --action comm.outbound --count <n> \
[--app <id>] [--note <text>] [--expires <iso8601>]
hadron ticket list --org <ref> # alias: ls
A ticket is a consumable grant an org ADMIN mints into the org
ledger; a headless run consumes one per gated action (v1: comm.outbound).
The ledger records which run consumed each ticket, and expiries. --app
scopes tickets to one App (omit for org-wide); --note records why they
exist.
hadron ticket mint --org acme.com --action comm.outbound --count 100 \
--note 'nightly digest send budget'
hadron ticket ls --org acme.com --json
grant — per-user action grants¶
Where a ticket is a consumable budget for a metered action, a grant
is a standing permission: it hands one or more actions to a specific org
member so their runs pass the policy chain for those actions.
hadron grant create --org <ref> --user <ref> --action <a>[,…] [--expires <iso8601>]
hadron grant ls [--org <ref>] [--user <ref>] # alias: list
hadron grant revoke <id> --yes
create(org ADMIN) grants actions to a member.--actiontakes one or more action names — an exact action (memory.clone), a wildcard prefix (memory.*), or*for all.--expiressets an optional expiry. The grantee must be a live member; a grant dies with the membership.lsdefaults to your own grants; narrow with--organd/or--user(seeing another user's grants needs org-audit visibility).revokesoft-deletes a grant by id (requires--yes).
hadron grant create --org acme.com --user u_123 --action 'memory.*' --expires 2026-12-31T00:00:00Z
hadron grant ls --org acme.com --user u_123 --json
hadron grant revoke grant_456 --yes
Organizations¶
hadron org manages organizations and their members.
hadron org list [--mine]
hadron org set-active|use <orgRef> [--no-verify]
hadron org create --name <n> --urn <urn>
hadron org get <id>
hadron org update <id> [--name <n>] [--urn <u>] [--visible=false]
hadron org rm <id> [--yes]
hadron org member ls <org-id>
hadron org member add <org-id> --user <id> --role <role>
hadron org member set-role <org-id> --user <id> --role <role>
hadron org member rm <org-id> --user <id> [--yes]
listlists organizations;--minekeeps only those you are a member of.set-active(aliasuse) stores your active organization in~/.config/hadron/config.toml. It is whatsearch --scope globalsearches: without one, aglobalsearch is refused when you belong to more than one organization. Name the org by its root (acme.com), URN or id. The ref is verified when you set it: an org you cannot read is refused with exit 4, and one you can read but are not a member of is refused with exit 2, because aglobalsearch would silently return nothing for a non-member.--no-verifyskips both checks.""clears it.createrequires--nameand--urn(e.g.acme.com).updatechanges only the fields you pass;--visible=falsehides the org from listings.rmrequires--yeswhen non-interactive.- Members.
member lslists the org's members (user id, name, email, role).member addandmember set-roletake--user <id>and a--roleofOWNER,ADMIN,CONTRIBUTOR, orREADER(case-insensitive).member rmremoves a user and requires--yesnon-interactively.
hadron org use acme.com
hadron org create --name "Acme Inc" --urn acme.com
hadron org member add org_123 --user usr_456 --role CONTRIBUTOR
hadron org member ls org_123 --json
Memory access control¶
Two mechanisms grant access to a memory, both under hadron memory and
addressing the memory by id or org:memory URN:
memory member— team membership on a (group-class) memory. Roles areowner,writer, orreader; a member is part of the memory's team and may be anowner.memory share— a per-user grant on apersonal-class memory only (privateis owner-only;knowledge/groupuse org membership or team members instead). Roles arewriterorreader— a share never confers ownership. Only the memory's principal may manage its shares.
Both add / create upsert: naming a user who already has a row updates
their role instead of failing.
hadron memory member ls <memory>
hadron memory member add <memory> --user <id> --role <owner|writer|reader>
hadron memory member set-role <memory> --user <id> --role <owner|writer|reader>
hadron memory member rm <memory> --user <id> [--yes]
hadron memory share ls <memory>
hadron memory share create <memory> --grantee <user-ref> --role <writer|reader>
hadron memory share set-role <memory> --grantee <user-ref> --role <writer|reader>
hadron memory share rm <memory> [--grantee <user-ref>] [--yes]
--grantee is a server-resolved user reference — an id, email, handle, or
hrn:user:<handle> URN. On share rm (aliases revoke / delete), omit
--grantee to remove your own share: the leave / stop-sharing-with-me
path. Revocation takes effect on the next read. See
Share a memory with someone.
- Member vs share. Use
memberfor the owning team (symmetric access, may include owners); useshareto grant one user read or write access without adding them to the team. The role vocabularies differ accordingly —owner|writer|readerfor members,writer|readerfor shares. member ls/share lslist the rows (user id, name, email, role).member rmandshare rmare destructive and require--yeswhen non-interactive.
hadron memory member add acme.com:kb --user usr_456 --role writer
hadron memory member ls acme.com:kb --json
hadron memory share create acme.com:kb --grantee usr_789 --role reader
Access checks¶
hadron access check answers "what access does this user have to this
resource?" for a single (user, resource) pair — the server-computed
effective capabilities plus the grants that confer them. It is the
audit/troubleshooting counterpart to memory member / memory
share, which list who can reach a memory. The
answer is authoritative: it comes from the server's effectiveAccess
resolver, which reuses the enforced authorization paths rather than
re-deriving authz in the CLI.
<user>— id, email, or handle (a leading@sigil is accepted, e.g.@alice). Resolved to a User ID viasearchUsers, which is itself scoped to the caller. An exact match on id, email, handle, or githubUsername wins; an ambiguous match is a usage error (no arbitrary pick). User URNs are not a first-class input form yet — ahrn:user:wrapper is unwrapped client-side.<resource>— a fully-qualified URN:hrn:mem:…,hrn:node:…,hrn:app:…, orhrn:agent:…; or a bareAiServiceConfigid (the one URN-less kind). An under-qualified shorthand likeacme.com:kb(nohrn:prefix) is rejected locally with guidance, before any network round-trip.- Auditing requires rights on the resource. Reading the answer requires
audit permission: a platform admin, an ADMIN/OWNER of the resource's owning
org, or — for a strict-owner (
personal/private) memory — the memory's principal. Otherwise the server returnsFORBIDDEN(exit 1). This is distinct from the subject having no access. - An empty
grants[]is the first-class "no access" answer (exit 0). It means the subject genuinely has no grant on the resource — not that the caller was forbidden from auditing.
Output¶
The human view prints the resolved user and resource, a role label, a
capability table (READ / WRITE / MANAGE / DELETE as ✓/✗), and the grants:
$ hadron access check holger@baragaun.com hrn:mem:micromentor.org:academy
User: holger@baragaun.com (019d28f1…)
Resource: micromentor.org:academy (memory)
Role: ADMIN
READ WRITE MANAGE DELETE
✓ ✓ ✓ ✓
Grants:
SOURCE ROLE VIA
PLATFORM_ROLE ADMIN —
ORG_ROLE OWNER micromentor.org
--json emits the same data as a stable object:
{
"user": { "id": "...", "name": "...", "email": "...", "handle": "..." },
"resource": { "urn": "hrn:mem:acme.com:kb", "kind": "memory" },
"canRead": true, "canWrite": true, "canManage": false, "canDelete": false,
"role": "writer",
"grants": [ { "source": "MEMORY_SHARE", "role": "writer", "via": null } ]
}
Grant sources¶
Each entry in grants[] is { source, role, via }. source is the gate that
confers the access; via names the conferring entity where one applies (for
example, a node reports its memory's access as NODE_INHERITED with via set
to the memory URN):
source |
Confers access because… |
|---|---|
PLATFORM_ROLE |
the user holds a platform-level role (e.g. platform admin). |
ORG_ROLE |
the user is a member of the resource's owning org; via is the org. |
MEMORY_PRINCIPAL |
the user is the strict owner of a personal/private memory. |
MEMORY_MEMBER |
the user is on the memory's team (memory member). |
MEMORY_SHARE |
the user has a per-user share on the memory (memory share). |
NODE_INHERITED |
a node inherits its memory's access; via is the memory URN. |
APP_MEMBER |
the user is a member of the App. |
AGENT_SUBSCRIPTION |
the user has an active subscription to the Agent. |
AICONFIG_OWNER |
the user owns the tier that owns the AI service config. |
PUBLIC_VISIBILITY |
the resource is public and readable by anyone. |
Exit codes¶
| Code | Condition |
|---|---|
| 0 | success — including the "no access" answer (empty grants[]). |
| 1 | the caller lacks audit rights on the resource (server FORBIDDEN). |
| 2 | usage error — under-qualified resource, or an ambiguous user match. |
| 4 | the resource could not be resolved (not found / not visible). |
hadron access check alice@acme.com hrn:mem:acme.com:kb
hadron access check @alice hrn:node:acme.com:kb:start-here
hadron access check usr_123 hrn:app:acme.com:support --json
See Debug PERMISSION_DENIED errors —
access check is the fastest first diagnostic when a call is denied.
Usage and billing¶
Two read-only groups answer "what did the AI calls do" and "what is left to
spend". usage is the activity log; billing is credit. Neither changes
anything.
hadron usage events [--memory <ref>] [--loc <loc>] [--type <t>] [--since <time>] [--until <time>] [--limit 1-200] [--offset N]
hadron billing prices [--provider <p>] [--model <m>] [--tier <n>] [--limit N] [--offset N]
hadron billing balance <org>
hadron billing ledger <org> [--limit N] [--offset N]
Money is in micro-cents, never dollars. 1 USD = 100,000,000 micro-cents, so
5000000 is 5 cents. Amounts are base-10 integers exactly as the server keeps
them, signed on the ledger and never rounded. For usage events, --json gives
the cost as the string costMicroCents (null when unpriced), so parse it as a
big integer, never a float. The billing help does not state the JSON type of
its amounts; the CLI's agent contract (hadron agentic-usage) says they are
base-10 integer strings too. "unpriced" means no price was recorded; it does
not mean free.
usage events¶
Lists recent AI usage events, newest first: when each happened, its type, the memory and node it was for, the provider and model, tokens in and out, and what it cost. You only see events in memories you can read. The credit metering records are described in spec 046.
You get one page (20 by default, or --limit 1 to 200). To go further back,
run it again with --offset set to the number of events already seen; after a
full page stderr says more may exist. There is no total and no cost sum.
--sinceand--untilbound the window by creation time.--sinceis inclusive and--untilis exclusive: you get events withsince <= created < until. Either may be left out. Each is an ISO date-time with aZor an explicit offset (2026-10-22T00:00:00Z,2026-10-22T09:00:00+02:00); a date alone or a time without an offset is refused, and so is a window where--sinceis not before--until. Note thathadron team events --sinceis the opposite: it is exclusive.--memoryis a memory ID or URN.--locis an exact node loc, including hierarchical ones such asnotes:ideas.--typeis an exact event type. An empty value is refused; leave a flag out for no filter.- A token count shown as
unknownwas not recorded. A-under MEMORY ID, LOC, PROVIDER or MODEL means the event has none. --jsonprints an array of event objects ([]when empty), with the cost as the stringcostMicroCents. The action's arguments and caller identity are not requested, and no model or provider is called.
hadron usage events --memory hrn:mem:acme.com:notes --limit 100
hadron usage events --since 2026-10-22T00:00:00Z --until 2026-10-23T00:00:00Z
billing¶
billing priceslists what each model costs: one row per provider, model and tier, newest effective date first. Any signed-in caller can read them. Narrow with--provider,--modelor--tier(the number in each row's tier column). Rates are micro-cents per million tokens, input and output separately:300000000is 3 USD per million tokens.markupBasisPointsis a markup in hundredths of a percent (100 = 1%); when it isnullthe server's default markup applies (its value is not shown here).billing balance <org>shows the credit left, grants minus charges, as one line such as250000000 micro-cents (organization <id>). Requires org ADMIN.<org>is an organization ID orhrn:org:<slug>.billing ledger <org>lists every credit grant and charge, newest first, so you can see what produced the balance. Grants are positive and charges negative. Requires org ADMIN. Without--limitthe whole ledger is listed;--limitand--offsetask for one page.pricesbehaves the same.
These commands only read. Setting a rate or granting credit is a platform-admin action and has no command here.
hadron billing prices --provider anthropic
hadron billing balance hrn:org:acme.com
hadron billing ledger hrn:org:acme.com --limit 20 --offset 20
Authentication¶
Authenticating and operating from the CLI never requires the web portal — a
self-hosted hadron-server is sufficient. There are portal-free ways to get a
hdr_user_* credential:
| Mechanism | Use |
|---|---|
hadron auth login |
Full server-side OAuth against the configured server (discovery → Dynamic Client Registration → 127.0.0.1 loopback → PKCE → token exchange). No portal in the path; the token is stored in the OS keychain. Where the server has passkey registration on, an email-link sign-in ends with a passkey step: a person finishes a passkey step in the browser; the CLI runs no WebAuthn and stores a key only after it succeeds. 15-minute limit, exit 6. See Sign in with email and a passkey. |
printf '%s\n' "$TOKEN" \| hadron auth login --with-token |
Store an existing hdr_user_* token — e.g. one bootstrapped on the server host with pnpm admin:mint-token, or minted by auth token create elsewhere. |
HADRON_TOKEN env var |
Overrides stored tokens — CI and agent contexts. |
hadron auth status answers "am I signed in?" via exit code (0 yes / 3 no).
Transport and credential-store safety¶
- HTTPS is enforced for the bearer token. The CLI refuses to send your
credential over cleartext
http://to a non-loopback host. To point it at a trusted self-hosted server over plain HTTP, setHADRON_ALLOW_HTTP=1— the escape hatch is explicit and scoped tohttp(it never admits a non-httpscheme). A loopback host (127.0.0.1,localhost) is always allowed without the flag. - Failures are loud, not silent. A corrupt
auth.jsonfails with a clear error instead of masquerading as "not signed in", so you fix the store rather than re-authenticating blindly. When no OS keychain is available,loginwarns that the token is stored unencrypted on disk rather than storing it silently.
Personal access tokens¶
Once signed in, mint and manage long-lived hdr_user_* personal access tokens
directly from the CLI — no portal:
hadron auth token create [--label <text>] # mint a PAT — the raw key is shown ONCE
hadron auth token ls # list your PATs (masked to a preview)
hadron auth token validate # check a token: exit 0 valid / 3 rejected
hadron auth token revoke <id> [--yes] # revoke one
auth token requires a user login — an app/agent key can't manage user
tokens. The raw key is printed only once on create, so capture it then; ls
shows just a masked preview. validate checks whether a token authenticates
without storing it — it reads the candidate from stdin (printf '%s'
"$TOKEN" | hadron auth token validate), so it never lands in your shell
history, and exits
0 (printing the owning user) if the server accepts it, 3 if not.
Server info¶
hadron server-info reports the hadron-server this invocation targets —
{url, version, baseUrl, authenticated}.
It works signed out (the field is public), so it doubles as a reachability probe: a failure reaching the server points at the server or the network, not a missing login. (A credential store that can't be read still fails loudly rather than silently querying anonymously.)
Two fields are easy to misread:
versionis the server's API-surface contract version — bumped when the query/tool surface changes in a caller-visible way. It is not a release version, so use it to decide whether a surface exists, not to compare against a release tag.urlis where the query was sent;baseUrlis what the server calls itself. A mismatch between them is worth noticing — it usually means a proxy or a stale--server/hadron config set servervalue.
The escape hatch: hadron api¶
Anything the curated commands don't cover is reachable as raw GraphQL (see the GraphQL API reference):
hadron api 'query { me { id email } }'
hadron api 'query($id: ID!) { memory(id: $id) { urn name } }' -F id=mem_123
cat op.graphql | hadron api -
-F key=value binds variables — values that parse as JSON are sent as
JSON, otherwise as strings. The verbatim GraphQL response envelope prints
to stdout; GraphQL errors are reflected in the exit code.
Recipes¶
# Inspect a memory and its nodes
hadron memory get acme.com:kb --json
hadron node ls -m acme.com:kb --json
# Read one node's content and edges (keep the hrn:node: prefix)
hadron node get hrn:node:acme.com:kb:findings:flaky-ci --json
# Create a node from stdin (-m takes a memory ref — single- or double-colon)
cat finding.md | hadron node add -m acme.com:kb --loc findings:flaky-ci \
--name "Flaky CI" --content -
# Connect two nodes
hadron edge add --from hrn:node:acme.com:kb:findings:flaky-ci \
--to hrn:node:acme.com:kb:start-here --name routes-to
# Bulk search-and-replace (preview, then apply with --yes)
hadron replace text old-domain.com new-domain.com \
-m acme.com:kb --field content --field description --dry-run
hadron replace text old-domain.com new-domain.com \
-m acme.com:kb --field content --field description --yes
# Delete non-interactively (agents must pass --yes)
hadron node rm hrn:node:acme.com:kb:findings:flaky-ci --yes