CLI Domain

The CLI domain covers the punks and dp command surface, scaffold lifecycle, repo detection, pack resolution, managed update behavior, baseline content, and generated AI operating context.

This domain is about CLI mechanics: what the executable writes, how it resolves scaffold content, where shared app/package boundaries sit, and what guarantees an operator can expect from setup and update commands. Harness methodology lives under /docs/harness; the CLI distributes and refreshes that operating context but does not duplicate the methodology articles here.

Command Surface

The executable has ten root commands:

check      ensure      init        operator    report
scaffold   skills      tools       update      upgrade

Six nested paths extend that graph:

operator status      operator install
operator update      operator migrate
skills rename        tools ensure

hi init prepares the docs-onboarding gate, records provider and backlog destination settings, and seeds the target wiki tree. hi scaffold runs repo-aware detection, pack resolution, confirmation, and managed file generation. Neither command is nested below scaffold.

ensure and init require interaction and support interactive or redirected plain output. scaffold and update may interact and also support non-interactive JSON. Every other registered command supports interactive, plain, and JSON modes.

Agents should activate $hi-cli before following generated .devpunks handoffs. hi init creates docs-onboarding, requirements/backlog/spec skills, and an initial wiki root, then asks the next agent to activate $docs-onboarding immediately to inspect code, existing docs, and backlog context before reconstructing evidence-backed specs. hi scaffold creates repo-aware managed output that still needs final reconciliation with the real repo layout.

Boundaries

• apps/cli owns local repo mutation, terminal interaction, scaffold rendering, baseline resolution, and update/diff behavior.
• packages/scaffold owns shared scaffold schemas and types, not runtime writing behavior.
• packages/contract owns shared Effect HTTP API contracts used by the CLI and API.
• apps/api can provide typed control-plane baseline metadata, but the CLI keeps GitHub stable and bundled fallback behavior.
• apps/wiki owns the private routed knowledge base that this page belongs to.