Skip to content

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 unavailable to 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 --yes write, or the note search emits 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:memory URNs (e.g. acme.com:kb, or the flat acme.com:kb form) 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 the hrn:node: prefix (legacy urn: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 a loc that 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 rm address it by its edge ID (shown by edge ls and in node 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 under urn:: node get (single-ref and batched), team worker get, and team session start's bind receipt. Those three, and not "anything that prints a URN" — worker ls carries a URN column and no URL column.

    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.urn is non-null, so the line always prints
    worker 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 --json the two differ again, and a consumer has to handle both: the node DTO carries portalUrl omitempty, so the key is absent when there is no link; the worker DTO carries it as a present null — 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 set creates when called without a positional argument (requires --org and --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-assigned class and visibility so you can confirm the effective values (an unset --class defaults to knowledge; an unset --visibility takes the server default). Because create has no slug input server-side, a custom --slug on 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, --slug renames 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 set picks one by which owner flags you pass:
    • Free-standing, org-owned — --org <ref> --name <n> (the default described above; --class defaults to knowledge).
    • 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 to personal); knowledge/group still 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.
  • memory attach <memory> --app <ref> --agent <ref> binds an existing free-standing personal/private memory 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 --install excludes --memory, even an explicitly empty one. get and update take a bare loc, not a node id or URN. The first node add sends the install selector, so the server creates the install memory in that write's transaction; a refused write creates nothing. update reads the memory without creating it, and --data-merge / --data-merge-file are refused before any request with --install (use --data / --data-file, which keep the selector). For get, ls and update, an unavailable install memory exits 4 before any node query or write and never turns into an unscoped list (the first add instead 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. --json is { "memory": { "id", "urn", "name" } } or { "memory": null }; null means unavailable (not created yet, missing, or not shown to you), never a claim that none exists.
  • node add fails if the loc already exists; node update preserves unset fields. Content comes from --content "<text>", --content - (stdin), or --content-file <path>.
  • The data bag — replace vs. merge. --data '<json>' / --data-file <path> replace the node's whole data object (omit to preserve, --data null to 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-merge is mutually exclusive with the --data replace. (This is the CLI counterpart of the hadron_update_node_data MCP tool.)
  • --runnable (the node flag). isRunnable gates whether hadron task run will execute a node. node add and node update take --runnable to set it; on update it is tri-state — --runnable sets true, --runnable=false clears it, omitting it preserves the current value. node get prints a runnable: line (and the isRunnable field in --json); node ls adds a RUN column (✓ for runnable) plus isRunnable in --json, and node ls --runnable filters server-side to runnable nodes (--runnable=false for the explicitly non-runnable; omit for all). This --runnable is distinct from the edge add --runnable flag 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 --prefix and 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=false keeps 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 THREADS and OLDEST. In the projected blocks of --with-data and --with-properties, the two labels come after the node's metadata and before the data or properties JSON. OLDEST is the age of the oldest open root thread, floored to whole minutes, hours or days (5m, 3h, 12d). It reads <1m for under a minute or for a timestamp in the future, and - when the node has no open thread. --json adds commentSummary with openThreads and oldestOpenThreadAt. The timestamp is the server's own string (null when there is no open thread), never the displayed age.

    A node with no open thread is a valid answer: its row shows 0 in OPEN THREADS and - in OLDEST (and commentSummary holds openThreads: 0 with oldestOpenThreadAt: 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 with null.

    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 -m names 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 nodes does 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 clone copies 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-urn in 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-source removes the source after. node merge mutates the target, so it requires --yes non-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, or hrn:user:<handle> URN, passed through verbatim (the server resolves and authorizes — platform ADMIN/OWNER, or an org ADMIN/OWNER over both members). There is no server dry-run, so it requires --yes non-interactively. - memory link-user. memory link-user <memoryRef> --external-user <id> --yes promotes 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 the x-hadron-operation-key request 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 rm soft-deletes by default — the node disappears from reads but is recoverable from revision history. node rm --hard removes 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 import when it overwrites an existing node, app uninstall, app delete (alias app 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 --yes when run non-interactively. Without it they exit 2. (A node import that 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]
  • list shows the revisions of a node (newest first), each with its id, who edited it, and any label. get prints one revision in full.
  • restore rolls the node back to a revision. By default it's non-destructive — the pre-restore state is itself snapshotted, so a restore is undoable. --truncate instead collapses every revision newer than the selected one (which becomes the new baseline), discarding that forward history — so it requires --yes.
  • label attaches a human note to a revision (e.g. --label "before the auth refactor") so you can find it later.
  • delete removes a single revision; clear removes 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 list shows the deleted nodes of a memory with their ids. recovery get shows one; --content adds its content. recovery graph lists the links (edges) among live nodes and restorable deleted nodes: the whole graph as it would be after restoring. --edge limits it to an edge id (repeatable, at most 200). list and graph page 20 at a time; --limit sets the page size (1-200), --offset skips rows, and --all reads every page, failing as a whole if any page fails.
  • restore brings 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 with node recovery get or node get before 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-warnings lists the node's lint warnings after success, as for node 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-removals lists 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, are null when you cannot read the target's memory. A soft delete keeps its edges and records nothing.
  • next steps through the notes under a parent in order: with no --after it reads the parent's first child, with --after <current> the one after it. Order is by seq, 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 --after that is not a direct child all give the same answer, end of sibling chain (null with --json), exit 0. Content is rendered by default; --raw reads the stored body.
  • open opens 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, --json and 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 a MANUAL headless run of the task under that App (a real LLM run) and prints the run id; follow it with hadron run get <id>. --as-self runs it on behalf of you (reaches your personal memories; authenticated user only). In --json, mode is "render" or "execute", and execute mode adds runId.

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: --agent is required. Without it the run is refused (the server's RUN_AGENT_REQUIRED; for task run and run trigger before anything is written), and the CLI prints this and exits 2:
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: null with parseFailure: true — a parse failure is a failure, not an eleventh class. Read the two together and never class alone. In the table that row's class cell is — with the reason in DETAIL; in --json the class key 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 unreadable with 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

hadron skill export [--dry-run] [--force] [--prune] [--json]

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-run reports 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. --force overrides 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 — deletes SKILL.md, then the directory only if it is empty. Anything left is listed in kept.
  • Links are refused. If a host's root, or any directory between $HOME and it, is a symbolic link, nothing is written for that host: failure is set and every one of its skills is failed. A skill directory that is itself a link is refused. $HOME itself 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.

hadron skill export --dry-run
hadron skill export
hadron skill export --prune --json

skill plugin

hadron skill plugin --out <dir> [--name <name>] [--scope <name|id>] [--zip] [--dry-run] [--json]

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
  • --zip also writes <name>.zip and <name>-codex.zip, with the plugin at the zip's root. It needs a filesystem with hard links.
  • --name defaults to hadron: lowercase words joined by hyphens, up to 64 characters. Skills are invoked as /<name>:<skill>.
  • The Claude manifest's version is 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 --scope narrows 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 --out or --scope, or a bad --name.
  • An existing artifact is replaced wholesale only if this command wrote it (a .hadron-plugin marker, 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-run writes 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

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]
  • --mode selects the ranking: hybrid (default), keyword (stemmed full-text with boolean operators — uppercase AND/OR/NOT, quoted phrases, -term), vector (semantic only), or regex (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, -m narrows within it.
  • --scope searches under a named scope: a scope name (needs an App context — --app or hadron app set-active), a scope id, app (the App's attached memories — also needs an App context), or global (your active organization's view — set it with hadron org use). Without --scope, the default from hadron scope use applies, if you set one. Passing --scope "" does not switch the default off; clear it with hadron scope use "". A name or app with 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 a scope object: selectedBy (flag or config), kind, label, source, ownerUrn, memoryUrns and droppedCount.
  • --prefix filters by node loc prefix; --type by node type; --tag (repeatable) by tag.
  • --limit caps hits (default 15; 0 uses the server default); --offset pages.
  • Each hit carries a relevance score plus the node's description and abstract in --json, so results are assessable without a follow-up node get per hit. -l/--long prints 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-name to force the name reading on get, update, rm and explain. set-active has no --by-name, so to make such a scope your default, look up its id with scope get <name> --by-name and pass the id.
  • create takes exactly one owner flag and at least one -m. Creating on an organization needs CONTRIBUTOR or above there; on an App or an Agent, ADMIN of its organization, or ownership of a user-owned one. An Agent need not be installed anywhere to own a scope. -m is 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 never app or global, which are reserved.
  • update changes only the flags you pass. -m replaces the whole list rather than appending, so pass every memory, in order. --description cannot clear a description: --description "" stores an empty string.
  • rm deletes the lens, never the memories it listed, and frees the name immediately. It needs --yes when non-interactive.
  • explain shows 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 (alias use) stores a default search scope in ~/.config/hadron/config.toml, which search applies whenever --scope is omitted — and says so on every result. It takes the values --scope takes. A name or id is verified when you set it (a scope you cannot read is refused with exit 4); app and global are stored as keywords and resolved on each search. --no-verify skips 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 — --fields is the record as a JSON object (or --fields-file). --key sets a natural id (a single loc segment, no :); omit for a server-generated id. --name overrides the auto-derived node name. id and type are reserved and can't be field names. Prints the flat record.
  • get <ref> — <ref> is an object id or a node URN. Exits 4 (not found) when the ref names nothing readable, or a node that isn't an object.
  • update <ref> — --fields is shallow-merged into the existing record (patch wins on collision, unmentioned fields kept; atomic server-side), then re-validated against the schema. Contrast node update --properties, which replaces the whole bag. --reason is recorded in revision history.
  • find (alias ls) — query one collection. --match is an equality shorthand ({field: value}, ANDed into eq per field, cast inferred from the schema); --where is the full predicate (the search --where grammar), AND-combined with --match; --sort is {"<field>":"asc"|"desc"}. Prints the matching objects and a total.
  • delete <ref> (alias rm) — soft by default (row retained, hidden from reads); --hard removes the row. Non-recursive. --yes skips 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.

hadron memory validate <memoryRef> [--check <kind>]… [--limit N] [--fail-on-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

hadron memory reembed-failed <memoryRef>
hadron memory usage <memoryRef>
  • reembed-failed retries 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 vector or hybrid); 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. 0 is a normal answer and also means the memory has no vector index. Confirm the outcome with hadron memory validate <memoryRef> --check embed-failed. It is a mutation, kept apart from the read-only validate so 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 organization ADMIN), as do its limits on encrypted memories.
  • usage counts how often each node was read and written: one row per node loc and kind (read or write) 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 in hadron usage events. Old activity recorded without a node may be missing. --json prints 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.

  • --memory repeats (without -m) and is never split on commas. Values and --parent go to the server unchanged, with no scope or existence read first.
  • --limit and --after are 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. --json is {items:[{segment,hasNode,memoryId}],hasMore,endCursor}, with [] for no rows and a nullable cursor.
  • Only hasMore adds the stderr line more segments remain — continue with --after <cursor>. The cursor is shell-quoted there when it holds anything outside a-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>]
  • ls requires -m. The CLI's listing is memory-scoped by design — it won't fan out across memories. (The GraphQL API does have a cross-memory assets query returning every asset the caller can reach; the CLI simply doesn't expose it yet.) It pages to exhaustion by default; --limit fetches one explicit page. --mine narrows to your own uploads.
  • get mints 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.
  • upload is 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).

  • ls also shows each asset's public-link state: the PUBLIC LINK, CAN MANAGE and AVAILABLE columns (publicLinkEnabled, canManagePublicLink and publicLinkAvailable in --json). PUBLIC LINK reads off, on, on, serving disabled on this deployment when the asset's switch is on but the deployment doesn't serve links, or on, no public URL on this server when 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-link sets the asset's own switch. --on asks you to confirm that anyone with the link may download the file, and in a script it exits 2 with refusing to proceed without --yes in non-interactive mode unless you pass --yes. --off needs 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 gets caller does not manage this asset's memory and 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 ($1 for 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 --memory scope to a parent loc and its descendants (matched on : path boundaries, so auth matches auth and auth:tokens but not authoring).
  • --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 --memory URN 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/--memory and --loc override them to re-home a node into another memory. Outgoing edges are imported only with --with-edges (off by default). --create-only refuses to update an existing node; --dry-run classifies 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/.html file. 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 to webpage, or info for 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 (--out defaults 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 under unavailable in the --json summary (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-qualified hrn: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-qualified org:slug URN), making the parent the new memory's root. Locs are rebased — findings:auth becomes the memory slug and findings:auth:oauth becomes <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 --move the subtree is copied (source untouched); --move relocates it, soft-deleting the source subtree — --move needs 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 GraphQL extractParentNodeToMemory mutation 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 with hadron 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 --apply or --yes performs, 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.
    • --apply shows the preview and asks for confirmation. --yes applies 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 as REMOVE rows).
    • On apply the preview goes to stderr and only the final result to stdout. --json emits one result document on stdout. Refusal codes are kept in blockers, 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 --yes when 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 get shows the rules, role-ascending. A memory with no rules prints no rules and 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) or UNREADABLE (the node exists but you may not read it, so its URN is withheld).
  • config rule add creates the rule for one role, creating the config on first use. A role that already has a rule exits 5; use rule 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 update changes 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> (alias remove) deletes a rule, guarded by the same revision check. It prompts on a terminal and needs --yes otherwise.
  • config rule unlock <memoryRef> <role> unlocks a rule that a required template locked. A locked rule refuses every ordinary rule update and rule 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 --yes otherwise.
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 (alias ls) 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 get shows a template and its rules. Its --json is the file format template update --file reads, revision included, so you can edit it and send it back.
  • template create takes the name, description, required flag and rules from --file (JSON; - reads stdin), the shape template get --json prints. 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 update applies every key the file has and leaves omitted keys unchanged. "description": null clears the description, and rules, when present, replaces all of the template's rules. The change is guarded by the revision the file was derived from (its revision key, or --expected-revision), never by a fresh read, so a template changed since you read it exits 5.
  • template rm <templateId> (alias remove) deletes a template. Configs it was applied to keep their copies. It prompts on a terminal and needs --yes otherwise, 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 (--yes when non-interactive), then applies exactly the template revision it showed you. --dry-run prints the preview and writes nothing; --expected-revision pins the template revision yourself. A rule that references a since-deleted task refuses the whole apply (exit 5; fix it with template 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's memory + messagesLoc encode). 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 show works offline. It prints which .hadron/config.json was found (the nearest ancestor), every supplied coordinate with its source (flag, env or config) and whether it won, and the legacy handle, identity and role values, which have no effect on a post. Precedence is a flag, then HADRON_CHAT_*, then the config file, and the node form (--node, HADRON_CHAT_NODE or chat.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 (never appKey or any other key in the file), and writes nothing.
  • chat doctor prints everything config show does, 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. lifecycle is always not-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

hadron chat config set (--node <urn> | -m <memory> and/or --messages-loc <prefix>)

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 --since is strictly greater, and the output reports nextSince — use that rather than computing the next watermark yourself. --before pages backward.
  • read --mentions <ref> follows the same reach rule as team chat read (see team 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.
  • post requires --session or --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 (BOTH reads and posts, POST posts, WATCH reads), mentionOnly, and an owner (an App or an organization) that is the context the attendee is named in.
  • register add needs 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 set changes only --role, --mention-only and --description. The attendee and the Channel are immutable, so moving a registration is rm + 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

hadron app action record <code> [--task <task>] [--payload <json> | --payload-file <path>] [--json]

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_INVALID exits 2).
  • --payload or --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.
  • --task takes the same id, qualified handle or bare handle forms as team 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-prefix before 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 cast mints a worker in ONE platform call (castWorker). The server resolves the agent — --agent names it, or --role picks the single installed agent whose personaRole matches (WORKER_AGENT_NOT_FOUND exit 4, WORKER_AGENT_AMBIGUOUS exit 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-override and --clear-prompt-override were 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, running team 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.
  • --name is 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 own WORKER_NAME_REQUIRED maps to exit 2 too. The claim is one attempt: WORKER_NAME_TAKEN (exit 5) is the answer, not a signal to retry.
  • --role is 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 --agent it is simply the casting's label. --team-agent is gone from cast — casting reads no system memory now, so the flag had become accepted-and-ignored.
  • WORKER_AGENT_NOT_INSTALLED is the server's refusal when an explicit --agent names 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 means hadron app agent add <app> <agent>, which takes a narrower permission than casting does: the App's owner or an org CONTRIBUTOR+, 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 ls is 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 ls is the install roster — the cast pool — and hadron agent ls answers a different question again: every agent you can read.)
  • worker ls --json does not carry prompt. 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 (target is a name, URN or id, resolved in the source worker's App); --clear reports 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 / _CYCLE exit 2, _RETIRED and _HELD exit 5, _FORBIDDEN exit 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 under error.extensions.code in --json. See Who a worker reports to.
  • worker onboard brings 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. --apply issues worktree.create, waits for its verified outcome, then issues worker.start through the typed host-operation queue (team host). Starting a worker needs the App manager; --as-person uses your authority instead of the bound worker's, and the server's authority checks still apply. Run the dry-run first and repeat with --apply once it reads right. Required: --name (the worker's name, URN or id), --host (a registered Orca host id, from team host list), --repo (the key under repos: 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's worktrees_root for that worker) and --config (the router's JSON config, see team router). Optional: --base (default main), --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 inspect team host ops before 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 (run team router loop on the same config), and the Orca display name.
  • reports to in reads. worker get, worker ls (a REPORTS TO column) and session whoami show the target's name, (retired) when the target has since retired, - when unset, and ? (unavailable) when the value is masked from you. session list carries it in --json only, not in its text output. --json adds reportsTo: {id, name, urn} | null and reportsToRetired; session reads also add reportingKnown. session whoami reads the current relation each time and never a value cached at bind.
  • worker retire stops the worker and keeps its name reserved — PR trailers and chat history reference it forever, and there is no rename. Needs --yes off a TTY, and is idempotent.
  • worker rm (alias delete) 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 with WORKER_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

hadron team worker approve [--only <a,b>] [--apply] [--as-worker] [--json]

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 state NOT_APPROVED or SUPERSEDED. Install- and Agent-level compiled prompts are not included. --only takes worker names, ids or URNs, comma-separated.
  • Preview by default. Without --apply the 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.
  • --apply is 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 --apply is approved at its newer revision; to approve only a revision you reviewed, use node approve <ref> --revision N. A revision that changes after the run's own read is refused REVISION_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 SUPERSEDED row is checked with the server's verifyNode. When it reports TAMPERED the row is never approved in a batch and the run exits 5; investigate, then run node approve <ref> --revision N. A tamper that lands between the preview and --apply is 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) is unknown, 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_SIGNED where 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 else BOOT_PROMPT_APPROVAL_FORBIDDEN (exit 8). With --as-worker the approvals go through this worktree's bound worker session; the server admits each only for a compiled prompt that a signed bootprompt.compile.approve grant 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 unknown with outcome landed, not-landed or unknown (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 --only worker that is not live in the App (nothing is sent). 1: a row whose state the command could not decide.
  • --json is app, applied, authority, limits and the buckets toApprove, approved (each with serve{servedRevSeq, refusal, unread}), alreadyApproved, tampered, skipped, failed{code, exitCode, message} and unknown{outcome, reason}. Rows carry name, id, urn, compiledNodeRef, revision, state and reason.

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.

  • list and get read 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. list pages (default 20, at most 200; --limit 0 counts only). Output is the grant's facts and allows (yes or no, about now), never a state label.
  • request asks for a pending grant for this worker (--holder worker, the default) or its role agent. The holder id comes from the binding; --holder-id overrides it and is required when unbound. --values is 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 its ceremonyUrl. Hand the URL over exactly as printed; text mode refuses a URL with control or format characters (exit 1), and --json carries it byte for byte.
  • signing-request get reads one request, whose state is the request's own (OPEN, COMPLETED, DECLINED, EXPIRED, STALE, WITHDRAWN). withdraw ends 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_REQUESTER and FORBIDDEN exit 8; GRANT_ACTION_UNKNOWN, GRANT_VALUES_INVALID and GRANT_TERMS_INVALID exit 2; GRANT_NOT_PENDING, GRANT_EXPIRED, GRANT_TERMS_UNREPRESENTABLE and SIGNING_REQUEST_ENDED exit 5; GRANT_NOT_FOUND and SIGNING_REQUEST_NOT_FOUND exit 4. --json errors carry serverCode.

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-agent disambiguates when several installed agents carry a roles: branch (TEAM_AGENT_AMBIGUOUS, exit 2).
  • The register projection is gone. register, freeCount, exhausted, nameRange and nameConvention were removed from the --json shape rather than emitted empty, because a permanent [] or 0 keeps promising an allocation surface the server no longer has. "Which names are free" is not a question this answers any more: worker ls --include-retired is the roster, and a cast names its worker explicitly.
  • role create / update are thin over createTeamRole / updateTeamRole, and --description is the whole CLI write surface. The platform also lets updateTeamRole set a role's repos affinity (hadron-server#1024), which the CLI has no flag for yet (hadron-cli#456) — set it through hadron api meanwhile. An existing role refuses create (TEAM_ROLE_EXISTS, exit 5 — update is the edit path), and an update naming 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-to went with the register, so there is no allocation ledger left to protect. The delete is soft: the roles:<role> node and its sub-nodes are tombstoned and recoverable. --yes is required off a TTY. It does not touch the role agent — that is app agent rm <app> <agent> --yes, then agent 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 with git rev-parse --git-dir, not a literal .git/ — worktrees have a .git file). --host defaults 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 its urn: and above the briefing — matching what hadron_start_session returns 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.
  • --as takes 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 (start with no worker named), session shed, session resume-claim and session 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 --as in 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 --force does not change it. It exits 5, as session start --help states.
    • session resume-claim writes the claim for the bound session (60 seconds, single use). Running session start with 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 end ends the session, saves the handoff (--handoff or --handoff-file) and, with --resume-claim, writes the claim with it. It removes .hadron-team/hadron-team-session.json and leaves .hadron-team/hadron-team-session.lock, which does not stop another worker from starting there. Afterwards whoami there exits 4 (nothing bound, no open session), and session start with 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 end in it (add --handoff if the session had work worth handing on); the directory is then unbound. If the session was already ended elsewhere (session end --session <id>), whoami --check there says ENDED and exits 14, and session end still clears the stale binding file and exits 0. Deleting .hadron-team/hadron-team-session.json by 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 end does that), so use it only when the session is already over (whoami --check says ENDED). A same-worker start --as over 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 init in a bound plain directory hides its cache. The CLI no longer finds the local binding copy, the server binding is untouched, and whoami falls back to the server.
    • Without a cache nothing changes. whoami and 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.
  • session whoami reads 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 start with 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 after end --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_RESUME exits 4; RESUME_REFUSED exits 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, -m and --force are refused here. --tool, --host, --model and --transcript are recorded only when the redemption starts the worker's next session (after end --resume-claim). On a resumed session the server keeps what the session already records and changes nothing. A --tool or --model that differs from what the session records gets a note: on stderr; --host and --transcript are dropped without one. --tool and --model fill only the local binding, and only where the session records nothing.
  • session resume-claim writes 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. --session claims an explicit session when the binding is gone. session end --resume-claim writes 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. start refuses 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 just session 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 TAKEN refusal means somebody drove this worker recently, not that somebody once forgot to close it. start still 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 at git worktree add -b <new-branch> ../<name> — the -b matters, 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 plain session start replaces the old binding once the server confirms the session is not live; no --force is needed. Two agents in one checkout share one index and one working tree: git add -A sweeps the other's in-flight edits, and Session.branch is 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. - --force reaches 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; only worker release does. So binding a name held by somebody else refuses WORKER_HELD (exit 5) whether or not --force rides 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. start refuses 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 --force does 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 log prints a stderr nudge counting team-chat messages since you last ran chat 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, and session log --json is 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, updateSession with the model only, never the family or tier and never clearing a stored model. --hook prints 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 manual set-model can overwrite a newer report. It parses Claude/GLM and Codex transcript formats and installs no hook itself. For Claude Code, add a Stop hook in .claude/settings.json:

    {"hooks":{"Stop":[{"hooks":[{"type":"command",
      "command":"hadron team session sync-model --hook"}]}]}}
    
  • session set-model [<model>] [--family <token>] reports the model and/or an explicit family for the session bound to this worktree, through the same updateSession. 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. --family is 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 as claude-code is 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-model has no --family.

    hadron team session set-model claude-opus-5-5
    hadron team session set-model glm-4.6 --family glm
    hadron team session set-model --family codex
    
  • session shed checkpoints 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 one sheds: node into the worker's own memory, reads it back, and only then writes the resume claim. The node is sheds:<YYYY-MM-DD-HHMM> (UTC), or sheds:auto-<YYYYMMDD-HHMMSS> with --auto; its headings are Identity, Watermark, Open work, Briefing pointers and Recovery prompt. Each read is independent: a failed one prints unavailable: <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 as claim: failed. The claim lasts 60 seconds, so reset immediately afterwards.

  • --auto is 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 --auto for 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-prompt prints the recovery prompt and nothing else: no node, no claim, no cooldown stamp, and only read-only reads (--offline makes 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.
  • --json prints {"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 --handoff writes 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).
  • --summary is 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 end ends 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; check session list --active. It does not release the name's hold: since server#1050 a 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, as Session.endReason: ended (an explicit end, from the CLI, MCP or GraphQL), superseded (a newer session on the same worker replaced it) or expired (a hard expiry promised at session start). A session that ended before the field existed reads unknown: 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, which whoami reports as a degraded read). end refuses with exit 2 when the binding was started against a different --server than 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 team command that reads it, or a write that attaches the session; a plain read such as node get sends 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 (default worked-on) and an optional --detail JSON 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/N and /issues/N are each accepted for both pr and issue — 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 .git suffix 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, post is 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 refuses CHANNEL_HOST_NOT_WRITABLE and 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 with team 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-me filters 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 all matches 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's nextSince is the value to pass next turn.
  • --reply-to <seq> wires a reply edge server-side; a seq that names no message is the typed TEAM_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-limit to its reporting line; further refusals inside that hour raise none. See team events and team 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.

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[] carries seq, urn, nodeId, channelId and channelIncarnation; there is no body or snippet. Read a hit with hadron team chat read --since <seq-1> --limit 1 (add the same --app you searched with), or hadron channel read <id> --since <seq-1> --limit 1.
  • --json prints the server's page: {channelId, channelIncarnation, complete, cursor, items}. items is [] when empty and cursor is null when complete is true.
  • urn can be null. A hit may have no URN: items[].urn is then null and nodeId (always a string) is the reference to use. In the text output the hit is listed by nodeId in that case.
  • An App with no team chat yet answers the complete empty page: channelId and channelIncarnation are both null, complete is true, cursor is null and items is [].
  • complete: false is 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 with complete: true means there is nothing.
  • The server owns the limits. The CLI passes --limit and --cursor through 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:

read state before this read: cursor #412; channel head #430 (allocated #431)

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).
  • --channel takes 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.
  • --after reads the next page from the returned pageInfo.endCursor.
  • Before acknowledgement, a failed run may redisplay a batch if it is pulled again. If acknowledgement is unconfirmed in human mode, run inbox again; batches not acknowledged may show again.
  • Ack-only recovery. With --json, retain the output privately and put its batches[].id values in a batchIds array. 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 api does 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 inbox pull 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 inbox delivers. 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.
  • --json emits 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 --since on the next poll and a worker is listed only for relevant unread newer than it, so one backlog produces one nudge. Omit --since to 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 now is refused: discarding a backlog is the separate, confirmed switchover.
  • A configured App context without a matching server-bound worker session has no server provenance; pass --app explicitly then.

switchover discards the backlog of router-era cursors once, in two explicit steps:

  • preview is 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 --json for the original proof, and keep the original --app/--server arguments.
  • 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 by team attention, so it asks for confirmation on a terminal and needs --yes otherwise.

Messages that arrive after the preview stay unread.

team router poll — one attention-router poll

hadron team router poll [--config <path>]

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. Its stateDir holds 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".
  • --first sets the page size (the server's default without it); --after continues from the previous page's endCursor.
  • 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-stop also 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.
  • --json returns {status, withheld, wakes[], dormant[], hasNextPage, endCursor}; dormant lists 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.

  • get works for any participant of the App and shows the settings exactly as the server returns them: the mention setting (IMMEDIATE or OFF), the pause, the live ticker subscriptions and their effective cadence, and dormant. A worker with nothing stored shows the server's defaults.
  • set sends only the flags you give; a setting you don't name is kept. --mentions is immediate or off. --paused-until (RFC 3339) pauses the worker's wakes until then; --clear-pause ends 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 set is 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-seconds is the expected check period (default 600 seconds) and --failed-checks-to-overdue the 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 N sets 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 may set it, and get shows it as dark alarm window in the table and darkAlarmWindowSeconds in --json. What the alarm looks like is under team 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-seconds and --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.
  • set changes 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; use get for 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. --assignee and --owner take worker:<id, URN or name> or user:<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 --assignee the 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. --owner defaults to you; a child task's owner is always the parent's assignee, so naming anyone else is refused TASK_CHILD_OWNER_MISMATCH. --require-role, --family-in, --family-not-in and --exclude-worker constrain who the matcher may pick. By default, finishing the task does not ask its assignee to end their worker session; --close-session opts in, and --no-close-session states the default explicitly. Passing both is a usage error. The choice cannot be changed in place afterwards.
  • The backlog. create --status backlog parks the task instead of queueing it: no assignee, never matched, never waited on by its parent, no stall alarms. The value is case-insensitive, pending is the default, and any other value (an empty one included) is refused locally with exit 2. Backlog with an --assignee is refused by the server (BAD_USER_INPUT, exit 2). park moves a queued task (pending, no assignee) to the backlog; ready moves a backlog task back to pending and into the queue. Assigning a backlog task also makes it pending, and cancel works on a backlog task directly.
  • Editing. update changes 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. --title cannot be emptied. --tag replaces the whole list and never adds to it; --clear-tags empties it. --require-role, --family-in, --family-not-in and --exclude-worker replace the whole requirements, so name every one you want to keep (--family-in with --family-not-in is refused locally); --clear-requirements empties them. --start-by takes an RFC 3339 time and re-anchors only the not-started clock: a stall alarm that was already raised stays raised. --close-session and --no-close-session change the close-when-done choice that create fixes; neither flag leaves it as it is, and --close-session=false is refused, so say no with --no-close-session. --properties <json|@file> replaces the task's own properties whole and never merges; --clear-properties removes them. Not editable here: the source, owner, assignee, status, parent, priority and blockers (use assign, reassign, start, finish, cancel, park, ready, set-priority, add-blocker). Success prints the task as get does, and --json returns 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_OWNER exits 8, TASK_ENDED 5, TASK_NOT_FOUND 4 and BAD_USER_INPUT 2. update needs v0.32.0 or later, and --properties / --clear-properties (and create --properties) need v0.33.0.
  • Who may move it. assign, reassign, cancel, park and ready take the task's owner, a worker the owner reports to, or whoever manages the App. start, progress and finish belong to the assignee alone. progress carries 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.) --code is required and is one of missing-input, cannot-do, refused, out-of-scope or duplicate, in either case; the enum names such as MISSING_INPUT are accepted too. Proposed --text is 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 a Handed back: line; get shows the same line later, and --json returns the task with handBack {code, text, handedBackAt}, which is null for a task never handed back. Proposed hand-back needs 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, mine and list --team gain a leading HANDLE column; get, tree and the receipts of create, assign, start and the other moves name AT3.405 <id>. With --json every task keeps id and its other keys and adds handle and taskNumber. 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 --parent on create and list) 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 refused TASK_HANDLE_QUALIFY and 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 --project makes a top-level project (AT1, AT2, …) instead of a task under AT0, 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 for handle and taskNumber, 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 in main (hadron-cli#1154, #1179), not in v0.31.0 or earlier.
  • Priority and blockers. create --priority 2 --blocked-by <task> (repeat --blocked-by for each blocker) sets them in the create call; left off, the server's default priority 1 and no blockers apply. set-priority, add-blocker and remove-blocker each send one change to an existing task. A task is an id or any handle the server accepts; --app does not qualify a handle, so use an id or the qualified hrn:agenttask:<root>:<app-slug>:AT1.2 when a bare handle is ambiguous. The rules (who may set them, same App, no cycles, backlog or pending only, TASK_BLOCKED on 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. get and list show priority and blocked state, and --json adds priority, blocked, blockedBy and blocks. The last two are the first 20 entries with total and hasMore; task dependencies <task> --limit N --offset N reads later pages of both lists. list keeps the server's order (newest first), not the queue's priority order.
  • --close-session / --no-close-session on assign and reassign replace 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=false reads the same as leaving it out.
  • finish --outcome is one word (letters, digits, _, - or .), for example succeeded or failed.
  • Reading. get shows one task; a task you may not read reads as not found. list returns newest first; its filters combine with AND, and --limit defaults to 20 (server cap 200). To read every task, keep paging with --offset until a page comes back empty. --status takes any of the five statuses, case-insensitively, and repeats; v0.22.0 refused backlog here, so parked tasks need v0.22.1 to filter by. mine is described below. tree shows a task and its children with status, owner, assignee and any open alarms.

  • list filters. Every filter ANDs with the rest; --status repeats as an alternative (--status PENDING --status STARTED lists both). --tag matches one tag; --tag-any (at least one) and --tag-all (every one) repeat, and a comma is part of a tag, not a separator. --source matches the exact value, never a prefix. --text is 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). --overdue lists tasks whose start-by has passed that are not started, not ended and not backlog — backlog is never overdue, and --overdue=false lists all other tasks; it is a filter, not an alarm. The date ranges (--created-after and --created-before, --started-after and --started-before, --finished-after and --finished-before) take RFC 3339 times, with Z or 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 --text join --team's conflict list: the team view combines with --status, --text, --tree and --stale-over only, every other filter — and --limit / --offset — is refused alongside it (exit 2), and --tree / --stale-over work only with --team. --text still 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 is task list --assignee worker:<bound worker> --status PENDING --status STARTED, run in the bound worker's App, and it prints what list prints, human or --json. With --json an 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, --parent or --tag, so a flag like that is refused as unknown. Only --limit and --offset remain, with list'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 for list.

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, verdict and ready write; readiness reads. 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 and hadron team events --type before 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. --head and the freeze argument 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 one schedule. --verdict is APPROVE, CHANGES_REQUESTED, PASS, FAIL, CARRY or REFUSED.
  • 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. --node and --receipt are 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. --json is {"task":{"id","handle","status"},"action":{"code","state","taskLoc","taskUrn"}}; a missing taskLoc or taskUrn is null in JSON and a dash in text.
  • Output of readiness. READY or NOT READY and the head, then a table of SLOT, CURRENT SEAT, STATE, VERDICT, HEAD and COUNTS. --json is {"ready","head","slots":[{"slot","currentTaskId","state","verdict","head","counts"}]}. NOT READY is a successful answer (exit 0). A task you cannot read is not found (exit 4), the same as a missing one.
  • Refusals. The server's code is kept (serverCode in --json). Protocol conflicts exit 5. A refused ready names the slots that do not count in the text and in error.slots in --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.

  • roster prints one row per worker that isn't retired: state, role, model family, whether its session is live or quiet, 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. The HELD BY and SINCE columns show who holds the worker's name and since when (heldBy and heldAt; v0.35.0 help); see holder fields and visibility for when they are withheld. worker get's heldByUserId and heldAt are Worker fields, not a WorkerHolder object.
  • events reads oldest first, from the beginning of the App. --since keeps events strictly after a time; to page, pass --after the last event id you read. When a page comes back full, the output names the exact --after that continues it. --alarms keeps alarm events only, and the ACK column shows whether each has been acknowledged. --limit defaults to 20 and takes 1 to 200, and a larger value is refused locally (exit 2) rather than silently clamped.
  • Who acted. The ACTOR column 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 reads run <id>, the run's server id, which is what hadron run get <id> takes. --json adds actorRunId to every event: the run's id, or null when no run acted. It's additive, and the other fields keep their shape. The value is the server's actorRunId as 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 ack and the alarm counts in team task tree read the same events, but tree still 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 TASK cell reads worker <name> (<reason>), where the reason is overdue (the worker is overdue checking) or wake-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 exact alarm.dark-worker type 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 is team delivery-settings.
  • Coordinator-cadence alarms. alarm.coordinator-cadence also has no task; it is about a coordinator. Its TASK cell reads coordinator <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 exact alarm.coordinator-cadence type gets this. If the server sends no subject, the cell keeps the — and the alarm ack receipt has no on clause, 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 on hadron-cli main at 34f026ef and first shipped in release v0.37.0. On v0.35.0 or earlier, such a row shows — as before.
  • alarm ack stops 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 bare app. also returns the platform's app.properties-changed, app.credential-act and app.manager-act. Omitting the flag leaves the read unchanged. (Release v0.37.0 onward; 1e050c37 is 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.

  • get lists every worker and model-family record, with its reason, its until, and whether it is in effect now. A worker or family with no record is available. A record whose until has passed reads AVAILABLE (lapsed at <time>) once the server records the lapse.
  • set --worker takes the worker's id, URN or name; a name needs the App. --reason is required with unavailable and refused with available; --until must be in the future.
  • set --family takes the family token, such as claude or codex, 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. get shows the effective values, defaults included, and when the App last changed them. Anyone taking part in the App can read it.
  • Changing. set changes only the flags you pass, and needs at least one (exit 2 otherwise). default returns 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.lost once. When the host checks in again, its registration is live again and host.registered is 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.

  • list shows 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. ops lists the operations, newest first, with who issued each and, once reported, its result or failure reason. --limit is 1 to 200; --after takes the endCursor of the previous page. Whoever reads the App's tasks and events may read both.
  • issue issues 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.create takes repo, baseBranch, branchName and label, where repo must match a key under the host configuration's repos exactly; worktree.remove takes worktree, the tree's full name token (api/dara-2 for the example below, not dara-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-person issues it as you.
  • run is the host poller and status checks its configuration, key and registration without changing anything. Both authenticate with the host:operate key read from the configuration's key_file, never from HADRON_TOKEN or 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

hadron team composition (uses --app or the binding)

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; --json preserves 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.
  • --seq is a provenance label only: it posts and marks nothing in chat. Prefer --message-file for sensitive text, since --text has 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 (alias ls) lists every stop signal the server shows this caller, oldest set first, page by page to the end. --worker narrows to the signals covering that worker now (a team signal on a head also covers each worker in the reporting tree under it); --include-ended adds 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.
  • set sets one signal. --scope worker and --scope team need --worker (a team is named by its head worker); --scope host takes --host (a host key may omit it, and the server takes its own host). --until is 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, a halt on 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; --json keeps the original. Whoever manages the App may lift any signal; a host key, a halt on its own host.

ticker apply-templates — give a worker its Agent's tickers

hadron ticker apply-templates --worker <id-or-URN>

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 are FORBIDDEN, WORKER_NOT_FOUND and WORKER_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. --json is {created: [{ticker, template, effectiveCadenceSeconds}], alreadyPresent: [{id, name}]}.
hadron ticker apply-templates --worker hrn:worker:acme.com:ops:iris

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 --config host YAML and the same 0600 key_file as team host run. The host key is never an argument or an environment variable. Orca comes from delivery.orca_bin when that is set, otherwise from PATH.
  • 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 --config the 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-timeout overrides that. A read that runs out of time says terminal status timed out after <duration>, exits 1 and writes nothing.
  • Only codes and times leave the host. Screen text, the local detail line 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. --interval is required, in whole minutes of at least 1m. Cron needs one that divides an hour or a day evenly, such as 5m, 15m, 1h or 6h. 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. install refuses (exit 2) when neither delivery.orca_bin in the host config nor that PATH resolves orca, because the sweep could only fail unattended. The host key is never written into the entry.
  • Installing again changes nothing. A new --interval updates the entry. There is one entry per user: another --config is refused until team health uninstall.
  • --bin is the absolute path of hadron to run (default: the one on PATH).
  • Exit 2 for a bad flag, path or interval, or when no scheduler is supported (nothing is written). Exit 1 when a scheduler call fails, naming the files written, which uninstall removes.

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. Its stateDir holds 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).

  • loop repeats 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 (--json prints one object per such poll). SIGINT and SIGTERM stop 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, and config-loaded.json records the loaded config's fingerprint and time without changing the adopted token.
  • status shows 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 accounts lists 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 is accounts: [] and complete: 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: false prints "not configured"; an empty configured list prints "none". APP_NOT_FOUND passes through. A server that lacks the field exits 1 with "too old" and the server's own message.
  • team usage project prints the server's token-burn projection. Each window shows lowPctAtReset..highPctAtReset and a confidence of LOW, MEDIUM or HIGH; runsOutAt appears only when the server returns one; status is PROJECTED, INSUFFICIENT_DATA or UNKNOWN. Without --account it projects every account the server lists, one call each, and complete is present only then. With --account it projects that one account. --account given empty or blank exits 2 before any call. A what-if needs --account and exactly one of --add-workers or --move-worker. -m or --config without --account exits 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.

hadron orca terminal status (<worker|terminal-id> | --all) [--json]

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.

hadron orca terminal status example-worker --json
hadron orca terminal status --all --json

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 00 under a feature (msg:010:00), feature 000 under a module (msg:000), and — when the numbering starts with a product — module gen under a product (api:gen). Creating a root with --new-product / --new-module / --new-feature / --new-path scaffolds that tier's contract alongside it unless --no-contract is passed, and allocation wires each new spec's edge to it; spec new … --contract adds one to a tier that lacks it. Existing siblings are not back-wired, and lint does not report the missing edge: link each one that should be bound with spec link <sibling> <contract> --label "inherits the shared contract (general provisions)". Outside the numbering, pass --inherit <loc> to spec 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; spec never writes the register node. Use spec register --check to 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 (and spec extract and spec supersede) fail loudly — exit 1 — when a required table-of-contents, cross-ref, or inheritance edge can't be wired, instead of reporting ✓ created on 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 with hadron edge add. spec supersede --json reports each edge's status (created / failed / skipped). This is the same partial-writes contract as node import --with-edges.
  • spec find is 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 supersede requires --yes when 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; matchedOn records 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; --all returns 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:

  1. the router's outgoing edge, labelled to <action> — what preflight list and preflight lint read;
  2. 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-edge to skip);
  3. the routing line in the router's body — - **"<symptom>"** → [[<loc>]] — <description> — which is what a human or an agent reading preflight top 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:

  • --description is 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.

hadron ai-config ls [--app <id-or-urn>] [--agent <id-or-urn>] [--json]
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 --agent contributes — sibling agents installed in the same App are not consulted.
  • Output is masked. It never carries key material — only hasApiKey and the short apiKeyPreview. --json emits the full masked record: id, name, ownerType, ownerId, provider, model, hasApiKey, apiKeyPreview, params, enabled, createdAt, updatedAt.
  • --app defaults to the configured App context (hadron app use or the global --app flag); --agent narrows to one agent. Both accept an ID or a URN.
  • You must be a member of the App, and — when --agent is 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]
  • create needs 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-64 chars, [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 record ls returns (hasApiKey + apiKeyPreview only). 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); --param replaces the file's params wholesale. 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-key keeps it. --param k=v (repeatable) replaces the whole params object. --enabled=false disables the config.
  • rm <id> requires --yes when 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

hadron ai-config get <id>
hadron ai-config endpoints <provider>
  • ai-config get <id> shows one config by id. endpoint is the stored override and effectiveEndpoint is the destination the server resolves; a null endpoint uses the provider default. The full key is never returned. An unknown id reports AI service config "<id>" was not found.
  • ai-config endpoints <provider> shows the server's endpoint suggestions for one provider, as URL, LABEL, DEFAULT and NOTE columns (--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.
hadron ai-config get cfg_123 --json
hadron ai-config endpoints anthropic

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 (alias ls) lists the calendars you can see on the connection: each calendar's ID (pass it as --calendar elsewhere), name, time zone, whether it is the primary calendar and whether you can edit it.
  • calendar events lists events, optionally between --from and --to, or matching --query (non-empty text). You get one list of at most --top events (default 25, 1 to 100) with no next page, so narrow the window or the query to see more. --from and --to are RFC 3339 date-times with a UTC offset, for example 2026-10-30T00:00:00-07:00; a bare date is refused. Without --calendar the provider's default calendar is used.
  • calendar event get <eventId> reads one event by the id that calendar events returned. Add --calendar when the event is not on the provider's default calendar.
  • calendar freebusy shows the busy windows between --from and --to (both required, with a UTC offset). Titles and attendees are not returned. Repeat --schedule for each calendar ID or email address; without it the provider's default calendar is used. A calendar that is not shared with you has an error message 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 (alias ls) lists files, or narrows them with --folder (a folder ID from drive 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 a nextPageToken; run the same command again with the same filters plus --page-token <that token>. The last page has a null token.
  • drive get <fileId> shows one file's details (name, kind, MIME type, size, parent folders, times and web link), not its text. size is in bytes and is null, 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). --format is MARKDOWN, TEXT or HTML (any letter case); without it the server picks the default for that file type. With --json you get an object with the file's details, the format, the MIME type and the text in content. 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

hadron web-poll list --org <ref>
hadron web-poll cancel <job-id> --org <ref> --yes

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.

hadron ha list [--org <ref>] [--limit 1..200] [--offset N]
hadron ha get <id>
hadron ha ops <id>

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 (alias ls) lists instances sorted by slug, optionally only those of one organization (--org, an ID or hrn:org:<slug>). Each row has the instance ID that ha get and ha ops take. You get one page of --limit rows (1 to 200, default 20); when more exist, stderr says which --offset to use next. --json prints a plain array.
  • ha get <id> (alias show) 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 a RUN-TOOL-NAME of the form ha__<slug>__<op>, which an author lists in a node's data.tools to 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.

hadron ha list --org hrn:org:acme.com
hadron ha ops <instance-id> --json

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. --type still filters; --org/--visibility don'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 (--surface replaces the set).
  • agent rm <id> requires --yes when 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> (...) and team 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>; --clear clears 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 refused BOOT_PROMPT_POINTER_SESSION_REFUSED (exit 8). Exits: _NOT_COMPILED, _WRONG_ROLE, _WRONG_MEMORY exit 2; _NOT_FOUND exits 4 (a missing, deleted or unreadable node alike); FORBIDDEN exits 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] and team 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. --json is { "compiledNodeRef", "revision", "contentHash", "pointerSet", "approvalIssued" }. A compile writes a revision even for unchanged text and never approves: approvalIssued: false is not the revision's approval status, so read that with node 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, or CONFLICT 5; 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 with node get before compiling again.
  • --as-worker sends 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.approve grant names. It never sets a pointer (pointerSet is false whatever --no-set-pointer says) and never creates a node.
    • On node approve the 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 approve the flag sends the worker session with each of its per-worker approvals. Each is an approval of an existing compiled revision, as for node 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 (see team worker approve).
  • 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 new PERSONAL-draft Agent with its own copy of the system memory and copies its links and imports. Linked memories stay links, not copied knowledge. --to is required and must be an organization (id or URN); without --name the clone carries the source's name, and the server decides both defaults. It prints the new Agent's URN; --json returns 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: run hadron agent list --org <org> --visibility PERSONAL before cloning again. A clone does not install anything. The new Agent records where it came from in clonedFromAgentRef. 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, a PUBLIC Agent 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 with CLONE_BASE_UNUSABLE or CLONE_IMPORT_UNUSABLE, as it is for any other Agent the target cannot use.

    Copied: the name, description, type, surfaces, usesTasks, registerDefaults, installationPolicy, memoryProvisioning and 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 as error.extensions.code with --json. Reason codes with their exit codes:

    Reason code Exit Cause
    AGENT_URN_TAKEN 5 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 --name or --slug.
    AGENT_NOT_FOUND 4 The source does not exist, or you cannot see it.
    ORGANIZATION_NOT_FOUND 4 --to is not an organization you can see.
    FORBIDDEN 8 You do not administer the target organization.

    The remaining refusals, with the exit code the CLI gives them:

    Reason code Exit Cause
    AGENT_NOT_PUBLIC 8 The source is not PUBLIC and you do not manage it in its own organization.
    CLONE_BASE_UNUSABLE, CLONE_IMPORT_UNUSABLE 8 The source's base, or one of its imports, cannot be used by the target organization (see above). The refusal's blockers list has one blocker per reason code, and its subjects are the bases or imports that failed: each carries a name only if you can read it, and always a position, the server's number for that subject, printed as received (position 2).
    CLONE_LINKED_MEMORY_UNREADABLE 8 A memory linked to the source is not readable for the clone.
    CLONE_LINKED_MEMORY_ENCRYPTED 2 A linked memory is encrypted.
    CLONE_ENCRYPTED_CONTENT 2 The source holds encrypted content.
    CLONE_TARGET_UNSUPPORTED 2 --to names a user; clone into an organization.
    CONFLICT with reason AGENT_CLONE_SOURCE_CHANGED 5 The source kept changing during the clone. The server marks it retryable; the CLI never retries for you, so run the command again.

    AGENT_RETIRED is 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_FOUND exits 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"
    
  • agent tasks list <agentRef> (alias ls) 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, and INHERITED FROM (the base Agent a task comes through, blank for the Agent's own). A task can appear with a blank TRIGGER: that is a task with no index edge listing it.

  • agent processes list <agentRef> (alias ls) lists the Agent's effective process list, own plus inherited, deduped by the server. Columns: TRIGGER, KIND, NAME, URN and INHERITED FROM. KIND is starts (the process is listed in the Agent's own processes index) or involved (the process has a stage edge to one of the Agent's tasks). The text table prints it in lowercase; --json carries it as STARTS or INVOLVED. TRIGGER is the index edge's name for starts rows and blank for involved rows.

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

hadron agent boot-prompt <agent> [--app <app>] [--model <m>] [--json]

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 (and app get) show chatbotAiConfigId, the server-returned chatbotAiConfigName and chatbotAiConfigListed. In JSON, chatbotAiConfigListed is false when 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), and null when the read of the choices failed, so membership is unknown. If the App does not exist, get exits 4. The explicit get fails on a server that lacks the field; app get still works there. The name comes from the choices list, never from the Agent, Org or Host.
  • list shows the narrow set of choices the server returns: the App's own enabled configs plus a default marker, which is not a config and has no id. JSON is an array of {value,name,isDefault,isAppChatbotConfig,provider,model}. It is not ai-config list.
  • set matches 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 word default is never matched by name (set a config that is named default by its id). default, an ambiguous name and an empty value exit 2 with no mutation.
  • clear sends 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 uninstall deleted the App. A script that ran app uninstall --yes to delete now uninstalls instead, which is the reversible outcome and which the output says. To keep deleting, change the command to app delete (or app rm). app uninstall no longer has the rm alias. Release note.
  • Confirmation. app delete and app uninstall ask on a terminal and need --yes otherwise (exit 2 without it). app reinstall does not ask.
  • Refs. An id or URN is sent to the server unchanged, with no preflight. For uninstall and reinstall, a URN names the installed App holding it, else the one uninstalled App with it. For delete, 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.
  • --json prints {"app": "<ref>", "status": "deleted" | "uninstalled" | "installed"}, where status is the resulting state. The error envelope carries the server's code as serverCode.
  • Repeats. uninstall and reinstall answer a repeat as they do a real change, so a repeat prints the same thing. A repeat app delete by id is refused APP_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 stays null in --json and 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, --description and --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-description clears 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 --app or the active App. The reasons are AGENT_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) and TEAM_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. The WRITE (ADVISORY) column says whether you may create nodes there: yes, no, or inherited for 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 --offset page the list, ordered by memory URN, and stderr says how to fetch the next page. --json prints { "items", "total" }; each source adds agentName and each row adds writeTarget. 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 (alias ls) shows the members you can see. An empty list means "no members visible to you", never "no members".
  • add is 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 --yes to skip the prompt; a non-interactive caller without it is refused before anything is sent.
  • remove (alias rm) 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; --yes skips the prompt.
  • roles prints the roles the App offers, which are the values add --role accepts: the union of its installed Agents' member roles, primary Agent first. Text is one role per line; --json is an array of strings. Change an Agent's roles with hadron 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. --json is { "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, use node 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

hadron app key scope revoke <key-id> <scope> [--instruction <kind>:<ref>]

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 grant and memory-grant add.
  • An admitted instructed list is not record-free: every call, so every page, records one app.credential-act event. 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 (--json serverCode).

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]
  • trigger starts 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-tokens and --budget-actions cap this run's LLM tokens and actions (see Per-trigger token and action limits). --wait polls 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.
  • list is the audit surface — status, trigger kind, and run id. Scope with --app or --org (mutually exclusive); filter with --status (one of PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, TIMED_OUT).
  • get shows one run in full: status, budgets, policy, and the failure payload when present.
  • cancel is the kill switch — transitions a live run to CANCELLED. Prompts on a TTY; requires --yes non-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-tokens and --budget-actions mean what they do on schedule create; --disabled previews switched-off timing. --as-self runs the preview as you, the authenticated person; an App key cannot use it. Empty timing flags are refused before any request. --name, --scope and --policy are 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; --json keeps the server's values.
  • CANNOT_BE_ADOPTED exits 5 with only a reason: MEMORY_UNREADABLE or OTHER. 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.
  • --json is { "outcome", "hash", "reason", "summary" }. For CANNOT_BE_ADOPTED, hash and summary are null; for ADOPTABLE, reason is null. Summary lists are arrays, empty ones included.
  • Exits. 0 ADOPTABLE; 5 CANNOT_BE_ADOPTED; 2 usage errors, before any request; server refusals keep create'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 create checks. --name, --scope and --policy are not read by the hash or the summary, and preview validates neither policy nor scope. create can still refuse them, or anything else it checks, after an ADOPTABLE preview.
  • Who may preview. Preview needs the same authority create does, 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 an ADOPTABLE result grants nothing.
  • Who may create. Authority is create's: an organization admin or a platform admin, with create'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. --action takes one or more action names — an exact action (memory.clone), a wildcard prefix (memory.*), or * for all. --expires sets an optional expiry. The grantee must be a live member; a grant dies with the membership.
  • ls defaults to your own grants; narrow with --org and/or --user (seeing another user's grants needs org-audit visibility).
  • revoke soft-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]
  • list lists organizations; --mine keeps only those you are a member of.
  • set-active (alias use) stores your active organization in ~/.config/hadron/config.toml. It is what search --scope global searches: without one, a global search 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 a global search would silently return nothing for a non-member. --no-verify skips both checks. "" clears it.
  • create requires --name and --urn (e.g. acme.com). update changes only the fields you pass; --visible=false hides the org from listings. rm requires --yes when non-interactive.
  • Members. member ls lists the org's members (user id, name, email, role). member add and member set-role take --user <id> and a --role of OWNER, ADMIN, CONTRIBUTOR, or READER (case-insensitive). member rm removes a user and requires --yes non-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 are owner, writer, or reader; a member is part of the memory's team and may be an owner.
  • memory share — a per-user grant on a personal-class memory only (private is owner-only; knowledge/group use org membership or team members instead). Roles are writer or reader — 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 member for the owning team (symmetric access, may include owners); use share to grant one user read or write access without adding them to the team. The role vocabularies differ accordingly — owner|writer|reader for members, writer|reader for shares.
  • member ls / share ls list the rows (user id, name, email, role). member rm and share rm are destructive and require --yes when 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.

hadron access check <user> <resource> [--json]
  • <user> — id, email, or handle (a leading @ sigil is accepted, e.g. @alice). Resolved to a User ID via searchUsers, 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 — a hrn:user: wrapper is unwrapped client-side.
  • <resource> — a fully-qualified URN: hrn:mem:…, hrn:node:…, hrn:app:…, or hrn:agent:…; or a bare AiServiceConfig id (the one URN-less kind). An under-qualified shorthand like acme.com:kb (no hrn: 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 returns FORBIDDEN (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.

  • --since and --until bound the window by creation time. --since is inclusive and --until is exclusive: you get events with since <= created < until. Either may be left out. Each is an ISO date-time with a Z or 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 --since is not before --until. Note that hadron team events --since is the opposite: it is exclusive.
  • --memory is a memory ID or URN. --loc is an exact node loc, including hierarchical ones such as notes:ideas. --type is an exact event type. An empty value is refused; leave a flag out for no filter.
  • A token count shown as unknown was not recorded. A - under MEMORY ID, LOC, PROVIDER or MODEL means the event has none.
  • --json prints an array of event objects ([] when empty), with the cost as the string costMicroCents. 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 prices lists 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, --model or --tier (the number in each row's tier column). Rates are micro-cents per million tokens, input and output separately: 300000000 is 3 USD per million tokens. markupBasisPoints is a markup in hundredths of a percent (100 = 1%); when it is null the 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 as 250000000 micro-cents (organization <id>). Requires org ADMIN. <org> is an organization ID or hrn: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 --limit the whole ledger is listed; --limit and --offset ask for one page. prices behaves 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, set HADRON_ALLOW_HTTP=1 — the escape hatch is explicit and scoped to http (it never admits a non-http scheme). A loopback host (127.0.0.1, localhost) is always allowed without the flag.
  • Failures are loud, not silent. A corrupt auth.json fails 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, login warns 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}.

hadron server-info --json

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:

  • version is 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.
  • url is where the query was sent; baseUrl is what the server calls itself. A mismatch between them is worth noticing — it usually means a proxy or a stale --server / hadron config set server value.

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