CLI Commands

Headbox is a command-line product. These are its units of interaction: 23 shipped and 9 planned. Every shipped signature below is parsed straight out of printHelp(), so it cannot drift from the binary.

Shipped

Planned

Total

Shipped

Commands that exist in cli/headbox.js today and run against a real workspace. Signatures are parsed from the CLI's own help output at build time.

🎮

headbox help Shipped

Prints the entire command surface. The only command that runs without HEADBOX_HOME set.

cli/headbox.js:1735

Signature

headbox help | --help | -h

📊

headbox status Shipped

Spec version, plugin count and whether the runtime is installed here. Add --target to ask about another project.

cli/headbox.js: printHelp()

Signature

headbox status [--target PATH] [--json]

▶️

headbox session-start Shipped

What an agent runs when it opens the project: pulls automation findings, owner notifications, sticky notes and next actions.

cli/headbox.js: printHelp()

Signature

headbox session-start [--target PATH] [--json]

❤️

headbox health Shipped

Rolls every known project up into active / stale / missing, with the issues that caused each verdict.

cli/headbox.js: printHelp()

Signature

headbox health [--root PATH] [--stale-minutes N] [--json]

🗂️

headbox project Shipped

The multi-tool: status, detail, plugins, sync, init-team, link and plugin-set against one project id.

cli/headbox.js: printHelp()

Signature

headbox project --id ID --action status|detail|plugins|sync|init-team [--json]
headbox project --id ID --action link --to OTHER_ID_OR_NAME [--type related|parent|child|temporary-workspace] [--json]
headbox project --id ID --action plugin-set --plugin NAME --state active|paused|available [--json]

💾

headbox artifacts Shipped

Lists all artifacts with their access rule, or reads and writes one. Honours proposal-required by routing to --propose.

cli/headbox.js: printHelp()

Signature

headbox artifacts [--id ID] [--read] [--content TEXT|--from-file PATH] [--propose] [--json]

✅

headbox validate Shipped

Integrity check across every plugin in the workspace.

cli/headbox.js: printHelp()

Signature

headbox validate [--json]

🩺

headbox doctor Shipped

Diagnostic pass. Currently prints the same plugin check as validate.

cli/headbox.js: printHelp()

Signature

headbox doctor [--json]

📦

headbox build-dist Shipped

Verifies the distributable install protocol. --check is the only supported mode today.

cli/headbox.js: printHelp()

Signature

headbox build-dist --check [--json]

🚀

headbox init Shipped

Scaffolds Headbox into a project: detects vendor files, writes the block, optionally sets up team + sidecar.

cli/headbox.js: printHelp()

Signature

headbox init [--target PATH] [--team] [--sidecar PATH] [--yes] [--no-claude] [--no-agents] [--no-hooks] [--json]

♻️

headbox refresh Shipped

Re-emits the managed instruction blocks from headbox-main.md into every vendor file. The propagation path: change the rules once, refresh, and every agent file is rewritten.

cli/headbox.js: printHelp()

Signature

headbox refresh [--target PATH] [--json]        Re-emit managed blocks from headbox-main.md

🪝

headbox install-hooks Shipped

Installs the deterministic adherence hooks. The rules stop depending on an agent choosing to read them. The harness enforces them. --reinforce strengthens existing hooks; --no-guards skips the guard rails.

cli/headbox.js: printHelp()

Signature

headbox install-hooks [--target PATH] [--reinforce] [--no-guards] [--json]

🔄

headbox sync Shipped

Reconciles a project against its shared sidecar.

cli/headbox.js: printHelp()

Signature

headbox sync [--target PATH] [--sidecar PATH] [--json]

💓

headbox heartbeat Shipped

Records that work happened, with an optional summary. The signal staleness detection reads.

cli/headbox.js: printHelp()

Signature

headbox heartbeat [--target PATH] [--summary TEXT] [--json]

📝

headbox propose Shipped

Files a change proposal instead of editing a governed artifact directly.

cli/headbox.js: printHelp()

Signature

headbox propose --title TEXT [--reason TEXT] [--risk low|medium|high] [--json]

⚖️

headbox decide Shipped

Resolves a proposal: approved, rejected, superseded or needs-info.

cli/headbox.js: printHelp()

Signature

headbox decide --id PROPOSAL_ID --decision approved|rejected|superseded|needs-info [--json]

📥

headbox inbox Shipped

Lists pending proposals awaiting a decision.

cli/headbox.js: printHelp()

Signature

headbox inbox [--status pending|all] [--json]

🔔

headbox notifications Shipped

Owner notification queue; also acknowledges or dismisses by id.

cli/headbox.js: printHelp()

Signature

headbox notifications [--status unresolved|acknowledged|dismissed|all] [--id ID --decision acknowledged|dismissed|unresolved] [--json]

👥

headbox roster Shipped

Prints the team roster artifact. Who holds which approval scope.

cli/headbox.js: printHelp()

Signature

headbox roster [--json]

📋

headbox execution Shipped

The execution ledger: whether work was planned, unplanned or drifted from its plan.

cli/headbox.js: printHelp()

Signature

headbox execution [--add] [--title TEXT] [--state planned|unplanned|drifted] [--json]

🔍

headbox review-agent Shipped

Findings raised by the Review Agent for triage.

cli/headbox.js: printHelp()

Signature

headbox review-agent [--json]

🤖

headbox automation Shipped

Automation findings, with --notify-stale to raise them to the owner.

cli/headbox.js: printHelp()

Signature

headbox automation [--notify-stale] [--json]

⚙️

headbox daemon Shipped

The headboxd service layer. --once is a single deterministic tick; long-running mode watches git state and writes heartbeats.

cli/headbox.js: printHelp()

Signature

headbox daemon [--target PATH] [--sidecar PATH] [--interval-minutes N] [--once] [--json]

Planned

Named in the roadmap's CLI Automation Layer but not implemented. They are listed so the surface is complete, and tagged so nobody mistakes them for shipped.

🔎

headbox scan Planned

Survey a project and report what Headbox would install before it installs it.