CLI reference¶
Discover every command and its schemas with hz --command-tree (JSON). Every operation accepts --json. Commands marked (expert) run like any other but are listed in help and completion only in expert mode: hz system expert on.
Usage:
$ hz [OPTIONS] COMMAND [ARGS]...
Options:
--command-tree: Print every command, argument, option and operation schema as JSON, including expert commands.-V, --version: Show the version and repository, Python, platform, installation and plugins, then exit.--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--help: Show this message and exit.
Commands:
ai: (expert) How hz reaches AI, and what it...chat: Chat with the agent runner in this...graph: Show your team's promises: who keeps which...heinzel: Your Heinzelmännchen: durable agents that...join: Join a team from its invite line: finds...org: Your profile, and the team, org and...report: Telemetry: log what a Heinzelmännchen did,...setup: Set up what is still missing, wizard...system: Inspect, configure, diagnose and update...team: Your team's repository: create one (`hz...ui: Open the web app in your browser, served...
hz ai¶
(expert) How hz reaches AI, and what it spends: tokens and cost per run.
Usage:
$ hz ai [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
access: (expert) Pick how hz reaches AI: Claude...models: (expert) List the models and efforts of...usage: (expert) Show the tokens and cost of AI...
hz ai access¶
(expert) Pick how hz reaches AI: Claude Code, your company's gateway, or an option a plugin adds.
Usage:
$ hz ai access [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the AI access options, the...login: (expert) Sign in to ChatGPT in your...test: (expert) Run one cheap live check of an AI...use: (expert) Use an AI access option: sets...
hz ai access list¶
(expert) List the AI access options, the one in use, whether each is signed in, and what runs each use.
Usage:
$ hz ai access list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ai access login¶
(expert) Sign in to ChatGPT in your browser, so the chatgpt option uses your plan instead of an API key.
Usage:
$ hz ai access login [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ai access test¶
(expert) Run one cheap live check of an AI access option and keep the result; this may cost a little.
Usage:
$ hz ai access test [OPTIONS]
Options:
--name <str>: The option to test, e.g.gateway; the one in use when not given.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ai access use¶
(expert) Use an AI access option: sets capabilities.ai_access, and agent_runner if the option names one.
Usage:
$ hz ai access use [OPTIONS] {name}
Arguments:
name: The AI access to use, onehz ai access listshows, e.g.claude-code. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ai models¶
(expert) List the models and efforts of the AI access in use, for the chat's model and effort picker.
Usage:
$ hz ai models [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ai usage¶
(expert) Show the tokens and cost of AI runs today and this week, by access, model, Heinzelmännchen or cause.
Usage:
$ hz ai usage [OPTIONS]
Options:
--period <today|week>:today(since local midnight) orweek(the last seven days). [default: today]--by <access|model|heinzel|cause>: Break down byaccess,model,heinzelorcause. [default: model]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat¶
Chat with the agent runner in this terminal: it reads with hz's operations and asks you before it changes anything. /exit or Ctrl-D leaves; hz chat --continue comes back.
Usage:
$ hz chat [OPTIONS] COMMAND [ARGS]...
Options:
-c, --continue: Continue the most recent chat instead of opening one.--session <str>: Continue this chat session (hz chat list).--context <str>: What a new chat is about:route:/contracts,contract:weekly,draft:<id>,event:<id>.--detail <str>: What you know about it, in words.--help: Show this message and exit.
Commands:
authorize-for-mcp: Authorize one reviewed schedule action for...confirm: Run an action the agent proposed, with...decline: Decline an action the agent proposed; it...list: List chat sessions, most recent first;...open: Open a chat session, optionally about a...open-check-in: Open a runner chat bound to this owner's...propose-agent-contract: Stage current agent contract terms for...propose-agent-notification: Stage one exact notification draft for a...propose-agent-schedule-review: Stage the exact current agent schedule for...propose-connected-read-review: Stage current connected-read terms for an...propose-model-policy: Stage the exact current model policy for...propose-schedule-control: Stage a schedule action for review in...recover: Check an interrupted confirmation without...remove: (expert) Delete a chat session and...send: Send a message in a chat session and wait...show: (expert) Show a chat session: its context,...
hz chat authorize-for-mcp¶
Authorize one reviewed schedule action for a single MCP run; keep its proof private.
Usage:
$ hz chat authorize-for-mcp [OPTIONS] {session} {action}
Arguments:
session: The chat session's id, fromhz chat list. [required]action: The proposed action's id, e.g.a1. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat confirm¶
Run an action the agent proposed, with exactly the arguments shown; only you can confirm.
Usage:
$ hz chat confirm [OPTIONS] {session} {action}
Arguments:
session: The chat session's id, fromhz chat list. [required]action: The proposed action's id, e.g.a1. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat decline¶
Decline an action the agent proposed; it never runs.
Usage:
$ hz chat decline [OPTIONS] {session} {action}
Arguments:
session: The chat session's id, fromhz chat list. [required]action: The proposed action's id, e.g.a1. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat list¶
List chat sessions, most recent first; they are kept for system.runner.chat.keep_days.
Usage:
$ hz chat list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat open¶
Open a chat session, optionally about a screen, a contract, a draft or a notification event.
Usage:
$ hz chat open [OPTIONS]
Options:
--context <str>: What the chat is about, askind:ref:route:/contracts,contract:weekly,draft:<id>,event:<id>; a bare id is a notification event.--detail <str>: What you know about it, in words, e.g. a notification's text.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat open-check-in¶
Open a runner chat bound to this owner's durable session and current conversation history.
Usage:
$ hz chat open-check-in [OPTIONS] {session_id} {request_id} {timezone}
Arguments:
session_id: The durable personal session id fromhz heinzel sessionsor the personal Heinzel page. [required]request_id: A stable id for opening or resuming this scoped chat. [required]timezone: The IANA time zone to use for this schedule preview. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-agent-contract¶
Stage current agent contract terms for human review.
Usage:
$ hz chat propose-agent-contract [OPTIONS] {durable_session} {request_id}
Arguments:
durable_session: The personal agent session. [required]request_id: The contract proposal request id. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-agent-notification¶
Stage one exact notification draft for a human decision; no notice is sent.
Usage:
$ hz chat propose-agent-notification [OPTIONS] {durable_session} {request_id}
Arguments:
durable_session: The personal agent session. [required]request_id: The notification draft request id. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-agent-schedule-review¶
Stage the exact current agent schedule for human review; no schedule is approved yet.
Usage:
$ hz chat propose-agent-schedule-review [OPTIONS] {durable_session} {request_id}
Arguments:
durable_session: The personal agent session. [required]request_id: The schedule proposal request id. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-connected-read-review¶
Stage current connected-read terms for an explicit human decision.
Usage:
$ hz chat propose-connected-read-review [OPTIONS] {durable_session} {request_id}
Arguments:
durable_session: The personal agent session. [required]request_id: The connected read proposal request id. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-model-policy¶
Stage the exact current model policy for human review; no grant or model call is made.
Usage:
$ hz chat propose-model-policy [OPTIONS] {durable_session} {request_id}
Arguments:
durable_session: The personal agent session. [required]request_id: The policy proposal request id. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat propose-schedule-control¶
Stage a schedule action for review in chat; creating the proposal never changes or activates it.
Usage:
$ hz chat propose-schedule-control [OPTIONS] {durable_session} {request_id} {expected_revision} {action}:<activate|resume> {expected_contract_version} {expected_preview_hash}
Arguments:
durable_session: The personal Heinzel whose schedule you read. [required]request_id: A stable id for this schedule action. [required]expected_revision: The schedule revision you inspected. [required]action:<activate|resume>: The exact schedule change to review. [required]expected_contract_version: The contract version shown in the preview. [required]expected_preview_hash: The preview hash shown in the schedule details. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat recover¶
Check an interrupted confirmation without running it again; unresolved outcomes stay blocked.
Usage:
$ hz chat recover [OPTIONS] {session} {action}
Arguments:
session: The chat session's id, fromhz chat list. [required]action: The proposed action's id, e.g.a1. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat remove¶
(expert) Delete a chat session and everything it holds; returns the sessions left.
Usage:
$ hz chat remove [OPTIONS] {session}
Arguments:
session: The chat session's id, fromhz chat list. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat send¶
Send a message in a chat session and wait for the answer; this may cost money.
Usage:
$ hz chat send [OPTIONS] {session} {message}
Arguments:
session: The chat session's id, fromhz chat list. [required]message: What to say. [required]
Options:
--budget-usd <float>: Most this answer may cost in US dollars, within the per-message and session caps.--model <str>: The model this chat uses from now on, onehz ai modelslists, e.g.sonnet; empty goes back to the default.--effort <|low|medium|high|xhigh|max>: The effort this chat uses from now on: low, medium, high, xhigh or max; empty: the default.--request-id <str>: Stable id for a safe exact-message retry.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz chat show¶
(expert) Show a chat session: its context, messages, actions and costs.
Usage:
$ hz chat show [OPTIONS] {session}
Arguments:
session: The chat session's id, fromhz chat list. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz graph¶
Show your team's promises: who keeps which artifact, how each promise stands, where the flow waits.
Usage:
$ hz graph [OPTIONS]
Options:
--artifact <str>: Only this artifact, its parts and what reads or writes them, by node id.--heinzel <str>: Only this Heinzelmännchen and what it reads and writes, by its id; with --artifact, both.--state <on_time|waiting_for_approval|late|fell_back|offline>: Only nodes in this state: on_time, waiting_for_approval, late, fell_back or offline.--at ISO-8601: The graph as of this time, ISO 8601 with offset; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel¶
Your Heinzelmännchen: durable agents that keep your team's documents true.
Usage:
$ hz heinzel [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
abandon-chat-turn: Explicitly set aside a stopped uncertain...amend-scheduled-agent: Propose revised terms; an independent...answer-chat: Answer one authenticated user's accepted...associate-artifact: Associate a Google file locally; no...chat: Durably queue a message for this Heinzel;...chat-turn-state: Read the recorded turn state; unresolved...check: (expert) Check contracts and list every...discover: (expert) Find candidates for each...drafts: List the drafts runs saved locally, newest...graph: (expert) Show the workflow your contracts...input-snapshot-history: Show recent private exact-result...latest-profile-proposal: Inspect the latest suggested name and...latest-scheduled-agent-proposal: Read the current inert proposal for the...list: List your Heinzelmännchen, one per...new: Write a starter contract, or a playbook's...new-chat: Create a durable personal Heinzel with an...personal-artifacts: List local principal-submitted file...playbooks: (expert) List the playbooks plugins...profile: Save this Heinzel's name or look against...propose-check-in: Propose local five-minute check-ins; the...propose-scheduled-agent: Save an inert agent execution proposal; it...prune: (expert) Delete drafts and records older...schedule-control: Pause a schedule; activation and resume...scheduled-agent-proposal: Inspect the exact inert proposal; a...sent: (expert) Record how much of a draft you...session: Open one durable Heinzel and an ordered...sessions: List your durable personal Heinzels,...show: Show a contract as the daemon runs it:...skill-draft: Read exact private skill draft files and...skill-drafts: List private draft references without file...tool-activity: Show owner-private host-observed tool...wake: Wake a Heinzelmännchen now: fetch its...
hz heinzel abandon-chat-turn¶
Explicitly set aside a stopped uncertain turn; never retry or undo its possible effects.
Usage:
$ hz heinzel abandon-chat-turn [OPTIONS] {session_id} {request_id} {acknowledge_uncertain}
Arguments:
session_id: [required]request_id: [required]acknowledge_uncertain: Confirm the outcome may be unknown and no retry or undo occurs. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel amend-scheduled-agent¶
Propose revised terms; an independent human review and approval is still required.
Usage:
$ hz heinzel amend-scheduled-agent [OPTIONS] {session_id} {request_id} {expected_revision} {contract} {max_usd} {timeout_seconds}
Arguments:
session_id: [required]request_id: [required]expected_revision: The exact proposal revision inspected. [required]contract: Complete replacement instructions. [required]max_usd: Proposed per-turn USD limit; not yet enforced. [required]timeout_seconds: Proposed maximum seconds per turn. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel answer-chat¶
Answer one authenticated user's accepted message; an interrupted request is never silently replayed.
Usage:
$ hz heinzel answer-chat [OPTIONS] {session_id} {request_id}
Arguments:
session_id: [required]request_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel associate-artifact¶
Associate a Google file locally; no access, provider ownership or permission is verified.
Usage:
$ hz heinzel associate-artifact [OPTIONS] {session_id} {request_id} {kind}:<document|spreadsheet|presentation> {ref}
Arguments:
session_id: [required]request_id: [required]kind:<document|spreadsheet|presentation>: The claimed Google file type; not verified with the provider. [required]ref: Canonical Google editor URL. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel chat¶
Durably queue a message for this Heinzel; acceptance is distinct from a completed model answer.
Usage:
$ hz heinzel chat [OPTIONS] {session_id} {request_id} {message}
Arguments:
session_id: [required]request_id: [required]message: Your message to this Heinzel, retained privately. [required]
Options:
--when-busy <follow_up|steer>: Queue a follow-up or request steering at the next safe boundary. [default: follow_up]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel chat-turn-state¶
Read the recorded turn state; unresolved may still be running.
Usage:
$ hz heinzel chat-turn-state [OPTIONS] {session_id} {request_id}
Arguments:
session_id: [required]request_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel check¶
(expert) Check contracts and list every problem with file and line; exits with 1 on errors, so CI can gate.
Usage:
$ hz heinzel check [OPTIONS]
Options:
--path <path>: A contract file, or a directory searched for *.prose.md; every contract found if none.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel discover¶
(expert) Find candidates for each playbook's asset types through the capabilities you have bound; reads only.
Usage:
$ hz heinzel discover [OPTIONS]
Options:
--playbook <str>: Only this module's playbook; every playbook's if omitted.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel drafts¶
List the drafts runs saved locally, newest first, with their paths and records, or show the newest.
Usage:
$ hz heinzel drafts [OPTIONS]
Options:
--name <str>: Only this contract's drafts; every contract's if omitted.--latest / --no-latest: Print the newest draft instead of the list. [default: no-latest]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel graph¶
(expert) Show the workflow your contracts make: what each maintains and reads, cycles, unmaintained inputs.
Usage:
$ hz heinzel graph [OPTIONS]
Options:
--mermaid / --no-mermaid: Print only the Mermaid flowchart, to paste into a document or a pull request. [default: no-mermaid]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel input-snapshot-history¶
Show recent private exact-result comparisons from approved reads, without source contents.
Usage:
$ hz heinzel input-snapshot-history [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--limit <int>: Maximum recent observations to return. [default: 20]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel latest-profile-proposal¶
Inspect the latest suggested name and look; it has not been applied.
Usage:
$ hz heinzel latest-profile-proposal [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel latest-scheduled-agent-proposal¶
Read the current inert proposal for the personal session, if one exists.
Usage:
$ hz heinzel latest-scheduled-agent-proposal [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel list¶
List your Heinzelmännchen, one per contract: owner, schedule, state, last and next run.
Usage:
$ hz heinzel list [OPTIONS]
Options:
--state <scheduled|manual|blocked|broken>: Only Heinzelmännchen in this state: scheduled, manual, blocked, broken.--contract <str>: Only contracts whose name or<namespace>:<name>contains this, e.g.team:orweekly.--artifact <str>: Only those that maintain or read this artifact, e.g.contract:team/weekly-report#report.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel new¶
Write a starter contract, or a playbook's template (--template), into your workflows directory.
Usage:
$ hz heinzel new [OPTIONS] {name}
Arguments:
name: The contract's name: lowercase words joined by dashes, e.g. weekly-digest. [required]
Options:
--team / --no-team: Write it into the team repository's workflows/ instead of your own directory. [default: no-team]--template <str>: Start from a playbook's template contract,<module>:<name>(hz heinzel playbookslists them), instead of the blank starter.--asset <str>: Fill a template's asset placeholder as type=reference, e.g. weekly-report=doc-123 (hz heinzel discoverfinds candidates); repeat for each.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel new-chat¶
Create a durable personal Heinzel with an idempotent request, name and look.
Usage:
$ hz heinzel new-chat [OPTIONS] {request_id}
Arguments:
request_id: [required]
Options:
--name <str>: Your personal display name for this Heinzel. [default: New Heinzel]--appearance JSON: The complete personal appearance overrides; null leaves the current look unchanged.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel personal-artifacts¶
List local principal-submitted file associations without accessing the provider.
Usage:
$ hz heinzel personal-artifacts [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel playbooks¶
(expert) List the playbooks plugins contribute: asset types, template contracts and recommended settings.
Usage:
$ hz heinzel playbooks [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel profile¶
Save this Heinzel's name or look against the exact profile revision you saw.
Usage:
$ hz heinzel profile [OPTIONS] {session_id} {request_id} {expected_revision}
Arguments:
session_id: [required]request_id: [required]expected_revision: The exact profile_revision you last read. [required]
Options:
--name <str>: The new personal display name; null leaves it unchanged.--appearance JSON: The complete personal appearance overrides; null leaves the current look unchanged.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel propose-check-in¶
Propose local five-minute check-ins; the schedule stays inactive until activated.
Usage:
$ hz heinzel propose-check-in [OPTIONS] {session_id} {request_id}
Arguments:
session_id: [required]request_id: [required]
Options:
--timezone <str>: The IANA time zone for the schedule preview. [default: UTC]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel propose-scheduled-agent¶
Save an inert agent execution proposal; it neither approves nor starts a model turn.
Usage:
$ hz heinzel propose-scheduled-agent [OPTIONS] {session_id} {request_id} {contract} {max_usd} {timeout_seconds}
Arguments:
session_id: [required]request_id: [required]contract: Exact instructions to preview for a future agent turn. [required]max_usd: Proposed per-turn USD limit; not yet enforced. [required]timeout_seconds: Proposed maximum seconds per turn. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel prune¶
(expert) Delete drafts and records older than retention_days (default 90); receipts are kept.
Usage:
$ hz heinzel prune [OPTIONS]
Options:
--dry-run / --no-dry-run: Only list what would be deleted; delete nothing. [default: no-dry-run]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel schedule-control¶
Pause a schedule; activation and resume require an exact-intent approval from a trusted issuer.
Usage:
$ hz heinzel schedule-control [OPTIONS] {session_id} {request_id} {expected_revision} {action}:<activate|pause|resume>
Arguments:
session_id: [required]request_id: [required]expected_revision: The schedule revision you last inspected. [required]action:<activate|pause|resume>: Explicitly activate the proposal, pause it, or resume a paused schedule. [required]
Options:
--approval-proof <str>: Human-issued exact-intent proof required to activate or resume; never returned by reads. On CLI, pass-to read it from hidden input or stdin.--expected-contract-version <int>: The contract version in the schedule preview. [default: 1]--expected-preview-hash <str>: The preview hash shown for this exact schedule.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel scheduled-agent-proposal¶
Inspect the exact inert proposal; a separate future human approval is required to run it.
Usage:
$ hz heinzel scheduled-agent-proposal [OPTIONS] {session_id} {request_id}
Arguments:
session_id: [required]request_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel sent¶
(expert) Record how much of a draft you changed before sending it; hz heinzel show reports it.
Usage:
$ hz heinzel sent [OPTIONS] {name}
Arguments:
name: The contract's name, or<namespace>:<name>(team:orme:) when both have it. [required]
Options:
--file <path>: What you finally sent, saved as a text or Markdown file; or give --ref.--ref <str>: The document the approved version lives in, read through the documents capability.--draft <path>: The draft it was edited from; the contract's newest draft if omitted.--edit-minutes <float>: Your own estimate of the minutes you spent editing; optional.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel session¶
Open one durable Heinzel and an ordered page of its accepted messages, even during an active turn.
Usage:
$ hz heinzel session [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--cursor <str>: The opaque next_cursor from this session's previous page.--limit <int>: The most messages returned in this page. [default: 50]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel sessions¶
List your durable personal Heinzels, including new conversations without an approved contract.
Usage:
$ hz heinzel sessions [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel show¶
Show a contract as the daemon runs it: schedule, requirements, adapters, readiness, next steps.
Usage:
$ hz heinzel show [OPTIONS] {name}
Arguments:
name: The contract's name, or<namespace>:<name>(team:orme:) when both have it. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel skill-draft¶
Read exact private skill draft files and requested sharing scope.
Usage:
$ hz heinzel skill-draft [OPTIONS] {session_id} {request_id}
Arguments:
session_id: [required]request_id: [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel skill-drafts¶
List private draft references without file contents.
Usage:
$ hz heinzel skill-drafts [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--cursor <int>: Resume after this session journal position. [default: 0]--limit <int>: The most private draft references returned in this page. [default: 20]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel tool-activity¶
Show owner-private host-observed tool decisions, without their arguments.
Usage:
$ hz heinzel tool-activity [OPTIONS] {session_id}
Arguments:
session_id: [required]
Options:
--limit <int>: Maximum recent recorded tool events to return. [default: 30]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz heinzel wake¶
Wake a Heinzelmännchen now: fetch its inputs, run the agent, save the draft; nothing is published.
Usage:
$ hz heinzel wake [OPTIONS] {name}
Arguments:
name: The contract's name, or<namespace>:<name>(team:orme:) when both have it. [required]
Options:
--dry-run / --no-dry-run: Only fetch the inputs and show the packet; run no agent. [default: no-dry-run]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz join¶
Join a team from its invite line: finds out who you are, joins the team, then sets up what is missing.
Usage:
$ hz join [OPTIONS] {URL}
Arguments:
URL: The team repository's URL, the invite: https, ssh or a local path. [required]
Options:
--yes: Make it your team without asking (when its roster lists you).--propose: When the roster doesn't list you, ask its owners to add you without asking: opens a pull request.--role <str>: Your role, so hz doesn't ask it.--handle, --as <str>: Your handle in the team's roster.--answers <file>: Answer in advance from a TOML file with a table per module, e.g.role = "engineer"in the org table; runs without a terminal, for coding agents and teams. Never put secrets in it.--json: Print what happened as JSON on stdout.--help: Show this message and exit.
hz org¶
Your profile, and the team, org and company you work with.
Usage:
$ hz org [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
agenda: (expert) Show the meeting you are in now...show: Show your profile: who you are, your role,...sync: Show what your team recommends beside what...
hz org agenda¶
(expert) Show the meeting you are in now and your next one, from your calendar, or how to connect one.
Usage:
$ hz org agenda [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz org show¶
Show your profile: who you are, your role, time zone and working hours, and what is still missing.
Usage:
$ hz org show [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz org sync¶
Show what your team recommends beside what you have; apply only what you accept, to your user file.
Usage:
$ hz org sync [OPTIONS]
Options:
--accept <str>: Recommendations to apply, by id and comma-separated (binding:documents), or all.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report¶
Telemetry: log what a Heinzelmännchen did, for your team's graph (hz report published <id> <url>).
Usage:
$ hz report [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
approved: Log that a Heinzelmännchen's draft was...drafted: Log that a Heinzelmännchen put a draft...fell-back: Log that a Heinzelmännchen used a stale...heartbeat: Log that a Heinzelmännchen is alive; one a...published: Log where a Heinzelmännchen published: a...read: Log that a Heinzelmännchen read an...sync: (expert) Copy your Heinzelmännchen's logs...
hz report approved¶
Log that a Heinzelmännchen's draft was approved, by whom; the entry's time is when.
Usage:
$ hz report approved [OPTIONS] {heinzel} {target} {by}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]target: What it acted on: an https URL, an email address, contract:team/<name>#<output> or chat:<channel>. [required]by: Who approved it, by roster handle. [required]
Options:
--description <str>: One line a reader of the team's graph should know; never content or addresses.--contract <str>: The team contract it keeps, team:<name>.--part <str>: The part of the target it concerns, e.g. its row in a tracker.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report drafted¶
Log that a Heinzelmännchen put a draft where it will be approved, and from which contract version.
Usage:
$ hz report drafted [OPTIONS] {heinzel} {target}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]target: What it acted on: an https URL, an email address, contract:team/<name>#<output> or chat:<channel>. [required]
Options:
--contract-version <str>: The contract's version it drafted from.--description <str>: One line a reader of the team's graph should know; never content or addresses.--contract <str>: The team contract it keeps, team:<name>.--part <str>: The part of the target it concerns, e.g. its row in a tracker.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report fell-back¶
Log that a Heinzelmännchen used a stale version of an input to keep its deadline.
Usage:
$ hz report fell-back [OPTIONS] {heinzel} {target} {input}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]target: What it acted on: an https URL, an email address, contract:team/<name>#<output> or chat:<channel>. [required]input: The input whose stale version it used, as a target. [required]
Options:
--description <str>: One line a reader of the team's graph should know; never content or addresses.--contract <str>: The team contract it keeps, team:<name>.--part <str>: The part of the target it concerns, e.g. its row in a tracker.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report heartbeat¶
Log that a Heinzelmännchen is alive; one a day is enough for the team to see it isn't offline.
Usage:
$ hz report heartbeat [OPTIONS] {heinzel}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]
Options:
--contract <str>: The team contract it keeps, team:<name>.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report published¶
Log where a Heinzelmännchen published: a document, an email address, a chat channel.
Usage:
$ hz report published [OPTIONS] {heinzel} {target}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]target: What it acted on: an https URL, an email address, contract:team/<name>#<output> or chat:<channel>. [required]
Options:
--version <str>: The artifact's version, as its source names it.--description <str>: One line a reader of the team's graph should know; never content or addresses.--contract <str>: The team contract it keeps, team:<name>.--part <str>: The part of the target it concerns, e.g. its row in a tracker.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report read¶
Log that a Heinzelmännchen read an artifact, which version, and by when its contract needs it.
Usage:
$ hz report read [OPTIONS] {heinzel} {target}
Arguments:
heinzel: The Heinzelmännchen's id, a slug unique in your team, e.g. costas-tracker. [required]target: What it acted on: an https URL, an email address, contract:team/<name>#<output> or chat:<channel>. [required]
Options:
--version <str>: The artifact's version, as its source names it.--needed-by ISO-8601: By when the reader's contract needs it, ISO 8601 with offset.--description <str>: One line a reader of the team's graph should know; never content or addresses.--contract <str>: The team contract it keeps, team:<name>.--part <str>: The part of the target it concerns, e.g. its row in a tracker.--at ISO-8601: When it happened, ISO 8601 with offset, within the last 30 days; now by default.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz report sync¶
(expert) Copy your Heinzelmännchen's logs into your team repository's checkout, for you to commit and push.
Usage:
$ hz report sync [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz setup¶
Set up what is still missing, wizard style: every step not finished yet, in order; optional steps can be skipped, and a run continues where the last one stopped. With MODULE, set up only that module.
Usage:
$ hz setup [OPTIONS] [MODULE]
Arguments:
MODULE: Set up only this module, by qualified name (hz setup clock); every module when left out.
Options:
--restart: Forget which steps finished and go through every one again.--answers <file>: Answer in advance from a TOML file with a table per module, e.g.role = "engineer"in the org table; runs without a terminal, for coding agents and teams. Never put secrets in it.--print-answers: Print the answers of the steps that finished as an answers file, and run nothing.--json: Print the outcome of every step as JSON on stdout; questions, if any, go to stderr.--help: Show this message and exit.
hz system¶
Inspect, configure, diagnose and update Heinzelmännchen itself.
Usage:
$ hz system [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
agent: (expert) Install the Heinzelmännchen...capability: (expert) Show which adapters serve which...changelog: (expert) Show the installed version's...claude: (expert) See the MCP servers and skills...config: (expert) Show, get, set and initialize...connector: (expert) Show whether each connector is...credential: (expert) Store and check the credentials...daemon: (expert) Run modules' jobs in the...doctor: Run every module's health checks; exits...expert: Expert mode: list every command, or just...info: (expert) Show versions, interpreter,...layer: (expert) Show the layer plugins installed...modules: (expert) List every module and the lets it...notify: (expert) Pop up what deserves your...plugin: (expert) Find, add, remove, enable,...release: (expert) Ask where Heinzelmännchen was...runner: Run bounded agent sessions with Claude...serve: (expert) Serve every operation to coding...skill: (expert) List the skills plugins ship for...sound: (expert) Pick the web app's soundscape:...state: (expert) Note how hz is used on this...theme: (expert) Pick how the web app looks: the...ui: (expert) List what modules add to the web...update: Update Heinzelmännchen and its plugins;...
hz system agent¶
(expert) Install the Heinzelmännchen skills for coding agents.
Usage:
$ hz system agent [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
install: (expert) Copy Heinzelmännchen's skills...skills: (expert) List the Agent Skills that ship...uninstall: (expert) Remove Heinzelmännchen's skills...
hz system agent install¶
(expert) Copy Heinzelmännchen's skills into each configured agent skill directory.
Usage:
$ hz system agent install [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system agent skills¶
(expert) List the Agent Skills that ship with Heinzelmännchen.
Usage:
$ hz system agent skills [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system agent uninstall¶
(expert) Remove Heinzelmännchen's skills from each configured agent skill directory.
Usage:
$ hz system agent uninstall [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system capability¶
(expert) Show which adapters serve which capabilities, and who reads and writes what.
Usage:
$ hz system capability [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List capabilities, their bindings...
hz system capability list¶
(expert) List capabilities, their bindings and adapters, and every requirement with its adapter and hosts.
Usage:
$ hz system capability list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system changelog¶
(expert) Show the installed version's changelog as Markdown, or with --newer what newer releases bring.
Usage:
$ hz system changelog [OPTIONS]
Options:
--newer / --no-newer: Show what the releases newer than the installed version bring instead, newest first; asks GitHub, with GH_TOKEN or GITHUB_TOKEN if set. As JSON: a list of {version, date, notes, url}. [default: no-newer]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system claude¶
(expert) See the MCP servers and skills you already set up for Claude, without using any of them.
Usage:
$ hz system claude [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the MCP servers and skills...summary: (expert) Count the MCP servers and skills...
hz system claude list¶
(expert) List the MCP servers and skills Claude Code and Claude Desktop have; nothing is switched on.
Usage:
$ hz system claude list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system claude summary¶
(expert) Count the MCP servers and skills found in Claude's configuration per source, without their names.
Usage:
$ hz system claude summary [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config¶
(expert) Show, get, set and initialize configuration.
Usage:
$ hz system config [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
get: (expert) Show one setting in effect, with...init: (expert) Write a configuration file with...reveal: (expert) Show a configuration file in...reveal-setting: (expert) Show the file or folder a path...set: (expert) Change a setting in the user or...show: (expert) Show the configuration files...unset: (expert) Remove a setting from the user or...
hz system config get¶
(expert) Show one setting in effect, with its environment variable.
Usage:
$ hz system config get [OPTIONS] {key}
Arguments:
key: Setting as section.key, e.g. hz.log_level or example.greeting. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config init¶
(expert) Write a configuration file with every setting commented out, ready to edit.
Usage:
$ hz system config init [OPTIONS]
Options:
--path <path>: Where to write; defaults to the user configuration file.--force / --no-force: Overwrite an existing file. [default: no-force]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config reveal¶
(expert) Show a configuration file in Finder, Explorer or your desktop's file manager; nothing is created.
Usage:
$ hz system config reveal [OPTIONS] {scope}:<site|user|project>
Arguments:
scope:<site|user|project>: Which configuration file: site, user or project. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config reveal-setting¶
(expert) Show the file or folder a path setting names, such as hz.log_dir, in your file manager.
Usage:
$ hz system config reveal-setting [OPTIONS] {key}
Arguments:
key: Setting as section.key, e.g. hz.log_level or example.greeting. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config set¶
(expert) Change a setting in the user or project configuration file, after validating it.
Usage:
$ hz system config set [OPTIONS] {key} {value}
Arguments:
key: Setting as section.key, e.g. hz.log_level or example.greeting. [required]value: New value; TOML syntax for numbers, booleans and lists. [required]
Options:
--scope <user|project>: Which file to change: user, or the project's hz.toml. [default: user]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config show¶
(expert) Show the configuration files Heinzelmännchen reads and every setting in effect.
Usage:
$ hz system config show [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system config unset¶
(expert) Remove a setting from the user or project configuration file, so its default applies again.
Usage:
$ hz system config unset [OPTIONS] {key}
Arguments:
key: Setting as section.key, e.g. hz.log_level or example.greeting. [required]
Options:
--scope <user|project>: Which file to change: user, or the project's hz.toml. [default: user]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system connector¶
(expert) Show whether each connector is signed in and serves something, and test one live.
Usage:
$ hz system connector [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List connectors with their...test: (expert) Test a connector live: one cheap...
hz system connector list¶
(expert) List connectors with their sign-in, what they serve and their tools; offline.
Usage:
$ hz system connector list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system connector test¶
(expert) Test a connector live: one cheap read-only call through its tool, with a short timeout.
Usage:
$ hz system connector test [OPTIONS] {name}
Arguments:
name: The connector, ashz system connector listnames it, e.g.github. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system credential¶
(expert) Store and check the credentials modules need, in the OS keychain.
Usage:
$ hz system credential [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the credentials modules...remove: (expert) Remove a credential's value from...set: (expert) Store a credential, read from...
hz system credential list¶
(expert) List the credentials modules declare and whether each is stored, never their values.
Usage:
$ hz system credential list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system credential remove¶
(expert) Remove a credential's value from the keychain.
Usage:
$ hz system credential remove [OPTIONS] {name}
Arguments:
name: Name of the credential, ashz system credential listshows it. [required]
Options:
--service <str>: Service it is kept under; needed only when several services declare the name.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system credential set¶
(expert) Store a credential, read from standard input or a hidden prompt, never from the command line.
Usage:
$ hz system credential set [OPTIONS] {name}
Arguments:
name: Name of the credential, ashz system credential listshows it. [required]
Options:
--service <str>: Service it is kept under; needed only when several services declare the name.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon¶
(expert) Run modules' jobs in the background, supervised by launchd or systemd.
Usage:
$ hz system daemon [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
install: (expert) Install and load the launchd...jobs: (expert) List every job with its schedule,...logs: (expert) Show the latest lines of the...pause: (expert) Pause the daemon: ticks run no...restart: (expert) Restart the daemon so it runs...resume: (expert) Resume a paused daemon.status: (expert) Check-ins need a resumed daemon...tick: (expert) Run the jobs that are due and...uninstall: (expert) Unload and remove the daemon's...
hz system daemon install¶
(expert) Install and load the launchd agent or systemd timer that ticks every few minutes.
Usage:
$ hz system daemon install [OPTIONS]
Options:
--interval <str>: Minutes between ticks, dividing an hour: 1m … 30m, or 1h. [default: 5m]--dry-run / --no-dry-run: Only show the unit that would be written. [default: no-dry-run]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon jobs¶
(expert) List every job with its schedule, next slot and last run.
Usage:
$ hz system daemon jobs [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon logs¶
(expert) Show the latest lines of the daemon's log.
Usage:
$ hz system daemon logs [OPTIONS]
Options:
--lines <int>: How many of the latest lines to show. [default: 50]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon pause¶
(expert) Pause the daemon: ticks run no job until resumed.
Usage:
$ hz system daemon pause [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon restart¶
(expert) Restart the daemon so it runs with the installed hz.
Usage:
$ hz system daemon restart [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon resume¶
(expert) Resume a paused daemon.
Usage:
$ hz system daemon resume [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon status¶
(expert) Check-ins need a resumed daemon with 5m ticks and a matching service version.
Usage:
$ hz system daemon status [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon tick¶
(expert) Run the jobs that are due and write a receipt for each; exits with 1 if any job failed.
Usage:
$ hz system daemon tick [OPTIONS]
Options:
--dry-run / --no-dry-run: Only show which jobs are due; run nothing. [default: no-dry-run]--job <str>: Run this job now, as<module>:<job>fromhz system daemon jobs.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system daemon uninstall¶
(expert) Unload and remove the daemon's unit; receipts and logs stay.
Usage:
$ hz system daemon uninstall [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system doctor¶
Run every module's health checks; exits with 1 if anything is down.
Usage:
$ hz system doctor [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system expert¶
Expert mode: list every command, or just the everyday ones.
Usage:
$ hz system expert [OPTIONS] COMMAND [ARGS]...
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
Commands:
off: Turn expert mode off: help, completion and...on: Turn expert mode on: help, completion and...
hz system expert off¶
Turn expert mode off: help, completion and the web app list the everyday commands.
Usage:
$ hz system expert off [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system expert on¶
Turn expert mode on: help, completion and the web app list every command.
Usage:
$ hz system expert on [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system info¶
(expert) Show versions, interpreter, settings, modules and what modules report.
Usage:
$ hz system info [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system layer¶
(expert) Show the layer plugins installed and the stack you are in, general to specific.
Usage:
$ hz system layer [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the installed layer plugins:...show: (expert) Show your stack: company, org and...
hz system layer list¶
(expert) List the installed layer plugins: where each sits, what it brings and what is wrong with the tree.
Usage:
$ hz system layer list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system layer show¶
(expert) Show your stack: company, org and site, team; what the layers bring and the settings they recommend.
Usage:
$ hz system layer show [OPTIONS]
Options:
--layer <str>: Show this layer's stack instead of yours, e.g. acme-payments-checkout.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system modules¶
(expert) List every module and the lets it advertises.
Usage:
$ hz system modules [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system notify¶
(expert) Pop up what deserves your attention: in the web app while it is open, else natively.
Usage:
$ hz system notify [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
ack: (expert) Mark notices as shown, so the...install: (expert) Install the native notifier...list: (expert) Show the latest notices, whether...settings: (expert) Open the system's notification...test: (expert) Record a test notice, report each...
hz system notify ack¶
(expert) Mark notices as shown, so the daemon doesn't pop them up again.
Usage:
$ hz system notify ack [OPTIONS] {ids}
Arguments:
ids: Ids of the notices that were shown, fromlist, separated by commas. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system notify install¶
(expert) Install the native notifier (Heinzel Notifier on macOS) and pop up a test notification now.
Usage:
$ hz system notify install [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system notify list¶
(expert) Show the latest notices, whether each popped up and who showed it, and how they reach you.
Usage:
$ hz system notify list [OPTIONS]
Options:
--limit <int>: How many of the latest notices to show. [default: 50]--before <str>: Only notices older than this id, for the next page.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system notify settings¶
(expert) Open the system's notification settings to allow hz's pop-ups (macOS: System Settings).
Usage:
$ hz system notify settings [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system notify test¶
(expert) Record a test notice, report each way it can reach you, and exit 1 if nothing pops it up.
Usage:
$ hz system notify test [OPTIONS]
Options:
--native / --no-native: Pop it up through the native notifier now too, as the web app's test button does. [default: no-native]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin¶
(expert) Find, add, remove, enable, disable, list and scaffold plugins.
Usage:
$ hz system plugin [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
add: (expert) Show what a plugin would install,...develop: (expert) Add the plugin in a directory on...disable: (expert) Switch a plugin off without...docs: (expert) Document installed plugins: what...enable: (expert) Switch a disabled plugin on again.history: (expert) List plugin changes made on this...list: (expert) List installed plugins, enabled...new: (expert) Scaffold a plugin repository from...operation: (expert) Read the status and result of a...remove: (expert) Remove a plugin.sdk: (expert) Export the versioned plugin view...search: (expert) Find plugins to install:...
hz system plugin add¶
(expert) Show what a plugin would install, then add it with --confirm; adding it again replaces it.
Usage:
$ hz system plugin add [OPTIONS] {spec}
Arguments:
spec: A first-party plugin by name (github,acme), a PyPI package named heinzel-<name> (heinzel-crm==1.2.0), or a git repository over https (git+https://github.com/acme-example/heinzel-crm@v1.0.0); private GitHub repositories use your gh login. Passrequirementfrom an earlier answer to install exactly what it showed. [required]
Options:
--confirm / --no-confirm: Install it. Without it, nothing is installed: the answer shows the source, version and publisher to confirm first, because a plugin runs with your rights. [default: no-confirm]--operation-id <str>: Opaque receipt returned by a preview; confirms that exact candidate only once.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin develop¶
(expert) Add the plugin in a directory on this machine, to try a plugin you are writing.
Usage:
$ hz system plugin develop [OPTIONS] {path}
Arguments:
path: The plugin's checkout, e.g..in a repository scaffolded bynew. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin disable¶
(expert) Switch a plugin off without removing it, in disabled_modules of your user file.
Usage:
$ hz system plugin disable [OPTIONS] {distribution}
Arguments:
distribution: Distribution name, ashz system plugin listshows it. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin docs¶
(expert) Document installed plugins: what each brings, as a model and as Markdown pages.
Usage:
$ hz system plugin docs [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
build: (expert) Write a Markdown page per...show: (expert) Show what each installed plugin...
hz system plugin docs build¶
(expert) Write a Markdown page per installed plugin, with theme swatches and its recordings when they exist.
Usage:
$ hz system plugin docs build [OPTIONS]
Options:
--directory <path>: Where the pages go: one<distribution>/index.mdeach, with anassets/beside it. [default: docs/plugins]--plugin <str>: One plugin, by its short name (clock) or distribution (heinzel-clock); every one if absent.--scenes <path>: Thedocs/scenes.tomldeclaring what to record for the plugin (ADR 0082); when the default doesn't exist, a CLI scene is derived from the operations. [default: docs/scenes.toml]--builtin / --no-builtin: Include Heinzelmännchen's own modules as the pageheinzel. [default: no-builtin]--index / --no-index: Also writeREADME.md, a gallery of the pages built. [default: index]--check / --no-check: Write nothing; report the pages that differ from what would be written, for CI. [default: no-check]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin docs show¶
(expert) Show what each installed plugin brings; --json is the full model its page is built from.
Usage:
$ hz system plugin docs show [OPTIONS]
Options:
--plugin <str>: One plugin, by its short name (clock) or distribution (heinzel-clock); every one if absent.--scenes <path>: Thedocs/scenes.tomldeclaring what to record for the plugin (ADR 0082); when the default doesn't exist, a CLI scene is derived from the operations. [default: docs/scenes.toml]--builtin / --no-builtin: Include Heinzelmännchen's own modules as the pageheinzel. [default: no-builtin]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin enable¶
(expert) Switch a disabled plugin on again.
Usage:
$ hz system plugin enable [OPTIONS] {distribution}
Arguments:
distribution: Distribution name, ashz system plugin listshows it. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin history¶
(expert) List plugin changes made on this machine, oldest first: what was installed, from where, by whom.
Usage:
$ hz system plugin history [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin list¶
(expert) List installed plugins, enabled or not, with their source and the modules and adapters they bring.
Usage:
$ hz system plugin list [OPTIONS]
Options:
--fresh / --no-fresh: Read the installed environment in a fresh interpreter, without reloading this server. [default: no-fresh]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin new¶
(expert) Scaffold a plugin repository from the Heinzelmännchen template, asking for answers not given.
Usage:
$ hz system plugin new [OPTIONS] {destination}
Arguments:
destination: Directory for the new plugin repository. [required]
Options:
--data <str>: Answer a template question as key=value, e.g. plugin_name=crm; repeat for each.--template <str>: Copier template: a git URL, gh:owner/repo or a local path. [default: gh:helmut-hoffer-von-ankershoffen/heinzel]--ref <str>: Template version; defaults to this Heinzelmännchen's release tag.--defaults / --no-defaults: Use template defaults without interactive questions. [default: no-defaults]--layout <standalone|collection>: A standalone repository, or only owning files inside a plugin collection. [default: standalone]--preset <minimal|contributions>: One operation and test, or the complete UI and notification example. [default: minimal]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin operation¶
(expert) Read the status and result of a plugin add without repeating it.
Usage:
$ hz system plugin operation [OPTIONS] {operation_id}
Arguments:
operation_id: Receipt id from a plugin preview. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin remove¶
(expert) Remove a plugin.
Usage:
$ hz system plugin remove [OPTIONS] {distribution}
Arguments:
distribution: Distribution name, ashz system plugin listshows it. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin sdk¶
(expert) Export the versioned plugin view SDK from this installation, without a core checkout.
Usage:
$ hz system plugin sdk [OPTIONS] {destination}
Arguments:
destination: New directory for the installed view SDK and TypeScript definitions. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system plugin search¶
(expert) Find plugins to install: first-party ones, and community ones by querying the GitHub API.
Usage:
$ hz system plugin search [OPTIONS]
Options:
--text <str>: Words that name or describe the plugin, e.g.calendar; sent to GitHub's search. All plugins if omitted.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system release¶
(expert) Ask where Heinzelmännchen was installed from for its latest release, and whether to update.
Usage:
$ hz system release [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system runner¶
Run bounded agent sessions with Claude Code or a configured command.
Usage:
$ hz system runner [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
ask: (expert) Ask the bound agent runner,...
hz system runner ask¶
(expert) Ask the bound agent runner, read-only and within a cost cap; this may cost money.
Usage:
$ hz system runner ask [OPTIONS] {prompt}
Arguments:
prompt: What to ask: a question, or the conversation so far ending with one; nothing is kept between calls. [required]
Options:
--budget-usd <float>: Most this answer may cost in US dollars, at most the setting system.runner.ask_max_usd.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system serve¶
(expert) Serve every operation to coding agents (MCP) or over HTTP (REST), or run the daemon in the foreground.
Usage:
$ hz system serve [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
api: (expert) Serve every operation as a REST...daemon: (expert) Run the daemon's tick in the...mcp: (expert) Serve every operation as an MCP...
hz system serve api¶
(expert) Serve every operation as a REST endpoint; OpenAPI docs at /docs.
Usage:
$ hz system serve api [OPTIONS]
Options:
--host <str>: Interface to listen on. [default: 127.0.0.1]--port <int>: Port to listen on. [default: 8000]--private: Require a server-scoped bearer for private operations.--credential-file <path>: New owner-only file for the private API credential; never put the token in arguments.--help: Show this message and exit.
hz system serve daemon¶
(expert) Run the daemon's tick in the foreground every interval, printing each result as a JSON line.
Usage:
$ hz system serve daemon [OPTIONS]
Options:
--interval DURATION: Time between ticks, e.g. 30s, 5m or 1h. [default: 5m]--help: Show this message and exit.
hz system serve mcp¶
(expert) Serve every operation as an MCP tool, e.g. claude mcp add hz -- hz system serve mcp.
Raises: typer.Exit: With 2 when --chat is given with another transport than stdio.
Usage:
$ hz system serve mcp [OPTIONS]
Options:
--transport <stdio|streamable-http>: stdio for agents that start hz; streamable-http to share. [default: stdio]--host <str>: Interface for streamable-http. [default: 127.0.0.1]--port <int>: Port for streamable-http. [default: 8765]--chat SESSION: Serve the tools of this chat session: reads run, everything else waits for your confirmation in the chat. Started byhz chatfor its agent, over stdio only.--project <path>: Read the configuration as if started in this directory (its hz.toml), as the chat does.--chat-tools <everyday|all|personal-check-in>: With --chat: the everyday operations as tools (cheaper messages), or all of them. [default: everyday]--help: Show this message and exit.
hz system skill¶
(expert) List the skills plugins ship for AI, and hand chosen ones to Claude Code.
Usage:
$ hz system skill [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
export: (expert) Export the skills you name for...list: (expert) List the skills in effect: which...show: (expert) Show a skill: where it comes...unexport: (expert) Remove skills hz exported for...
hz system skill export¶
(expert) Export the skills you name for Claude Code, as heinzel-<name> in each export directory.
Usage:
$ hz system skill export [OPTIONS]
Options:
--name <str>: A skill to export, e.g. explain-heinzel; repeat for each.--all-skills / --no-all-skills: Export every skill in effect but your own. [default: no-all-skills]--sync / --no-sync: Only remove exports whose skill is gone or changed; never add one. [default: no-sync]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system skill list¶
(expert) List the skills in effect: which module offers each, what it hides, and where it is exported.
Usage:
$ hz system skill list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system skill show¶
(expert) Show a skill: where it comes from, its files and hints, and its body.
Usage:
$ hz system skill show [OPTIONS] {name}
Arguments:
name: The skill, onehz system skill listshows, e.g.explain-heinzel. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system skill unexport¶
(expert) Remove skills hz exported for Claude Code; directories hz didn't write are left alone.
Usage:
$ hz system skill unexport [OPTIONS]
Options:
--name <str>: A skill to remove from the export; repeat for each.--all-skills / --no-all-skills: Remove every skill hz exported. [default: no-all-skills]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system sound¶
(expert) Pick the web app's soundscape: off or one an installed plugin offers.
Usage:
$ hz system sound [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the soundscapes of the web...use: (expert) Pick the web app's soundscape,...
hz system sound list¶
(expert) List the soundscapes of the web app, where each comes from, which one is picked and which plays.
Usage:
$ hz system sound list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system sound use¶
(expert) Pick the web app's soundscape, off for none; turns off theme following and saves your choice.
Usage:
$ hz system sound use [OPTIONS] {name}
Arguments:
name: The soundscape to play, onehz system sound listshows, oroff. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system state¶
(expert) Note how hz is used on this machine and push it to your own state repository.
Usage:
$ hz system state [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
push: (expert) Push this machine's new presence...reset: (expert) Start this machine's clone of its...status: (expert) Show where this machine's state...
hz system state push¶
(expert) Push this machine's new presence and adoption lines to your personal state repository now.
Usage:
$ hz system state push [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system state reset¶
(expert) Start this machine's clone of its branch afresh after a refused push; the old one is kept aside.
Usage:
$ hz system state reset [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system state status¶
(expert) Show where this machine's state goes, what is still to push and how the last push went.
Usage:
$ hz system state status [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system theme¶
(expert) Pick how the web app looks: the built-in theme or one a plugin offers.
Usage:
$ hz system theme [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
list: (expert) List the themes of the web app,...signals: (expert) Show the signals themes follow...use: (expert) Use a theme in the web app:...
hz system theme list¶
(expert) List the themes of the web app, with every colour, font and size, and which one is in effect.
Usage:
$ hz system theme list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system theme signals¶
(expert) Show the signals themes follow now: the time of day, and the weather when a plugin publishes it.
Usage:
$ hz system theme signals [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system theme use¶
(expert) Use a theme in the web app: writes name to your configuration file.
Usage:
$ hz system theme use [OPTIONS] {name}
Arguments:
name: The theme to use, onehz system theme listshows, e.g.default. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui¶
(expert) List what modules add to the web app: status items, header actions and Today widgets.
Usage:
$ hz system ui [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
actions: (expert) List the buttons modules add to...hide: (expert) Hide a contribution from a slot...list: (expert) List every contribution to the...navigation: (expert) List active providers' navigation...show: (expert) Show a contribution in a slot of...status: (expert) List the status items modules add...views: (expert) List active installed views,...widgets: (expert) List the widgets modules add to...
hz system ui actions¶
(expert) List the buttons modules add to the web app's header, with what each does and its badge.
Usage:
$ hz system ui actions [OPTIONS]
Options:
--item <str>: Only this one, by id (<module>:<name>), e.g.clock:primary-zone.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui hide¶
(expert) Hide a contribution from a slot of the web app, such as the clock from the footer.
Usage:
$ hz system ui hide [OPTIONS] {item}
Arguments:
item: The contribution, by id (<module>:<name>), e.g.clock:primary-zone. [required]
Options:
--slot <str>: Where:footer,sidebar,headerortoday; needed when it may show in several.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui list¶
(expert) List every contribution to the web app, where it may show and whether it does; nothing runs.
Usage:
$ hz system ui list [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui navigation¶
(expert) List active providers' navigation and owned Settings metadata without running their operations.
Usage:
$ hz system ui navigation [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui show¶
(expert) Show a contribution in a slot of the web app, such as the clock in the sidebar.
Usage:
$ hz system ui show [OPTIONS] {item}
Arguments:
item: The contribution, by id (<module>:<name>), e.g.clock:primary-zone. [required]
Options:
--slot <str>: Where:footer,sidebar,headerortoday; needed when it may show in several.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui status¶
(expert) List the status items modules add to the web app's status bar, with what each shows now.
Usage:
$ hz system ui status [OPTIONS]
Options:
--item <str>: Only this one, by id (<module>:<name>), e.g.clock:primary-zone.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui views¶
(expert) List active installed views, their compatible bundles and read-only operation calls.
Usage:
$ hz system ui views [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system ui widgets¶
(expert) List the widgets modules add to the web app's Today screen, with what each shows now.
Usage:
$ hz system ui widgets [OPTIONS]
Options:
--item <str>: Only this one, by id (<module>:<name>), e.g.clock:primary-zone.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz system update¶
Update Heinzelmännchen and its plugins; see what it brings with hz system changelog --newer.
Usage:
$ hz system update [OPTIONS]
Options:
--source <str>: Install from here instead, e.g. git+https://github.com/org/heinzel@v1.2.0 or a wheel.--channel <release|main>: Followrelease(the default, settingupdate_channel): the newest release, also frommainonce a release is as new as it; ormain: its newest commit.--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz team¶
Your team's repository: create one (hz team new), join one by its URL (hz team join), add people to it.
Usage:
$ hz team [OPTIONS] COMMAND [ARGS]...
Options:
--help: Show this message and exit.
Commands:
add: Add someone to your team's roster, as one...adopt: (expert) Make an existing checkout your...join: Clone a team repository with your own...new: Create a team repository from the...show: Show your team: its repository, checkout...
hz team add¶
Add someone to your team's roster, as one of its owners: a pull request the other owners see.
Usage:
$ hz team add [OPTIONS] {handle}
Arguments:
handle: Their handle: lowercase letters, digits, dashes. [required]
Options:
--login <str>: Their GitHub login; an owner needs one.--role <str>: Their role: one of engineer, principal, engineering-manager, engineering-leadership, product-manager, product-leadership, program-manager. [default: engineer]--owner / --no-owner: Make them an owner: they approve roster changes. [default: no-owner]--by <str>: Your own GitHub login, whenghisn't signed in as you.--yes / --no-yes: Carry out the steps that wait for you: remote changes, and making the team yours. [default: no-yes]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz team adopt¶
(expert) Make an existing checkout your team repository; replaces the deprecated heinzel.team_repository.
Usage:
$ hz team adopt [OPTIONS] {path}
Arguments:
path: A checkout of your team repository you already have. [required]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz team join¶
Clone a team repository with your own access, find you in its roster, and make it your team.
Usage:
$ hz team join [OPTIONS] {url}
Arguments:
url: The team repository's URL, the invite: https, ssh or a local path. [required]
Options:
--propose / --no-propose: When the roster doesn't list you, open a pull request adding you; owners merge it. [default: no-propose]--handle <str>: Your handle: the roster entry that is you when it has no login yet, or the one to propose.--role <str>: Your role when you propose to be added: one of engineer, principal, engineering-manager, engineering-leadership, product-manager, product-leadership, program-manager. [default: engineer]--login <str>: Your GitHub login, whenghisn't signed in; asked ofgh api userotherwise.--yes / --no-yes: Carry out the steps that wait for you: remote changes, and making the team yours. [default: no-yes]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz team new¶
Create a team repository from the template: you its first owner, its roster drafted for review.
Usage:
$ hz team new [OPTIONS] {name}
Arguments:
name: The team's name: lowercase words joined by dashes, e.g. payments. [required]
Options:
--github <str>: Create it on GitHub as this private repository, owner/name; only on this machine if none.--roster <str>: Draft the roster from a GitHub team you can read: github:<org>/<team>, or github:<org>.--role <str>: Your role: one of engineer, principal, engineering-manager, engineering-leadership, product-manager, product-leadership, program-manager. [default: engineering-manager]--handle <str>: Your handle in the team; defaults to your GitHub login.--login <str>: Your GitHub login, whenghisn't signed in; asked ofgh api userotherwise.--yes / --no-yes: Carry out the steps that wait for you: remote changes, and making the team yours. [default: no-yes]--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz team show¶
Show your team: its repository, checkout and members, and what is wrong with them.
Usage:
$ hz team show [OPTIONS]
Options:
--format <text|json>: Output format; defaults to the output_format setting (HZ_OUTPUT_FORMAT), which is text.--json: Shorthand for --format json, for scripts and agents.--help: Show this message and exit.
hz ui¶
Open the web app in your browser, served on localhost; Ctrl-C stops it.
Usage:
$ hz ui [OPTIONS]
Options:
--port <int>: Port on 127.0.0.1; ui_port by default, 0 picks a free one.--browser / --no-browser: Open the default browser at the app; --no-browser prints only its URL. [default: browser]--devices: List the browsers and installed apps paired with hz, then stop.--revoke <str>: Unpair a device by its id from --devices, orall, then stop.--help: Show this message and exit.