CLI Commands
Commands you run directly in the terminal via npx hatch3r.
Standard flags (2.0.0)
Every non-stub command and subcommand accepts:
| Flag | Description |
|---|---|
--format <human|json> | human (default) or json. JSON mode emits exactly one JSON document on stdout (envelope: status, command payload fields, command, hatch3rVersion, timestamp); diagnostics and spinners go to stderr. An invalid value, or --format json on an invocation that would prompt (e.g. mcp setup, bare cli-tools, interactive flows without --yes), is an exit-2 usage error |
--quiet | Suppress stdout chrome (banner, spinners, boxes, next steps); stderr diagnostics still emit |
Mutating commands additionally accept --dry-run (preview without writing): init, sync, update, config, clean, rollback, worktree-setup, worktree-cleanup, mcp setup/remove, cli-tools, learn capture. --verbose is registered only on commands that have detail output wired. The per-command tables below list command-specific flags; the standard flags are not repeated.
hatch3r init
Interactive setup that initializes hatch3r in your repository.
npx hatch3r init
npx hatch3r init --tools cursor,claude
npx hatch3r init --yes # headless mode (standard preset, auto-detected context)
npx hatch3r init --preset full --project-type brownfield --team-size team --yes
Flags:
| Flag | Values | Default | Description |
|---|---|---|---|
--tools | comma-separated tool names | auto-detected | Which coding tools to configure (Claude Code, Cursor, Copilot) |
--quick, --default | — | off | Aliases for --yes (headless mode) |
--yes | — | off | Skip all prompts (headless mode) |
--preset | minimal, standard, full, web-app, api-service, cli-tool, monorepo, legacy, security, or a comma-list to compose | standard | Content profile preset |
--project-type | greenfield, brownfield | auto-detected | Project type context |
--team-size | solo, team | git-inferred | Team size context |
--maturity | solo, team, scaleup, enterprise | solo | Investment-depth dial — calibrates how deeply agents build (see Maturity Tiers). Does not filter content; every tier installs the full corpus |
--cli-tools, --no-cli-tools | tier1, all, or comma-separated ids | picker / smart default | Resolve the CLI-tools selection up front (skips the picker); --no-cli-tools skips CLI tools entirely |
--mcp, --no-mcp | — | off | Opt in to MCP servers (interactive init does not prompt for MCP); --no-mcp force-disables even with --mcp |
--dry-run | — | off | Preview what init would create or change without writing files |
--workspace | — | off | Force workspace mode for multi-repo directories |
When CWD is a non-git directory containing git subdirectories, init auto-detects a workspace layout and suggests workspace mode. Use --workspace to force workspace mode without the prompt.
The interactive flow asks (default branch, project type, and team size are inferred, not prompted):
- Platform -- GitHub, Azure DevOps, or GitLab (auto-detected from git remote)
- Repo identity -- owner/org and repo name (auto-filled from the remote where possible)
- Content profile -- Minimal, Standard (recommended), Full, or Custom
- Maturity tier -- solo, team, scaleup, or enterprise (seeded at the git-inferred default);
--maturity <tier>skips this prompt. The tier is an investment-depth dial, not a content gate -- every tier installs the full corpus (see Maturity Tiers) - Custom content items -- only when Custom is selected at step 3
- Tools -- select from the 3 supported adapters (Claude Code, Cursor, GitHub Copilot)
- CLI tools -- tier-grouped picker (tier-1 + trigger-matched tier-2 pre-checked; enter-through equals the
--yessmart default). There is no MCP prompt — opt in with--mcpornpx hatch3r mcp setuplater
The common (non-custom) path is 6 prompts; the custom-content multi-select adds a 7th only when Custom is chosen at step 3.
Only the content matching your profile and context is generated into your adapter outputs (canonical content is read from the bundled npm package, not copied into your repo). Use hatch3r config to add or remove items later.
With --yes, init auto-detects greenfield/brownfield, defaults to solo + standard preset, selects tier-1 + triggered tier-2 CLI tools, and skips all prompts.
hatch3r setup
Added in 2.1.0. Scaffolds a fresh project directory and then chains into the hatch3r init prompts inside it. The happy path needs only Node 22+ and git.
npx hatch3r setup my-app
npx hatch3r setup my-app --remote
npx hatch3r setup demo --yes --tools claude
npx hatch3r setup my-app --dry-run # preview the scaffold without writing
Flags:
| Flag | Values | Default | Description |
|---|---|---|---|
--remote | — | off | Create a private GitHub remote via gh repo create after git init. Acts only when gh is installed and authenticated (gh auth status exits 0); otherwise it prints a warning and continues the local scaffold |
--tools | comma-separated tool names | auto-detected | Forwarded to init — which coding tools to configure (Claude Code, Cursor, Copilot) |
--preset | minimal, standard, full, or any init preset value | standard | Forwarded to init — content profile preset |
--maturity | solo, team, scaleup, enterprise | git-inferred | Forwarded to init — investment-depth tier; supplying it skips the maturity prompt |
--yes | — | off | Forwarded to init — skip all prompts (headless mode) |
--format <human|json> | human, json | human | Forwarded to init. --format json without --yes is an exit-2 usage error |
--quiet | — | off | Forwarded to init — suppress stdout chrome |
--dry-run | — | off | Preview the scaffold plan (directory, git init, remote, then init) and write nothing; init is not run |
--verbose | — | off | Forwarded to init — verbose per-step output |
What it does, in order:
- Resolves the target directory from the positional
[dir]argument; when omitted it uses the current directory if empty, otherwise prompts for a directory name. An existing target with content beyond a lone.gitis refused with an actionableFS_ERROR(exit 74) - Creates the directory (skipped when it already exists empty)
- Runs
git init— idempotent, skipped when a.gitis already present - With
--remote, creates the private GitHub remote (warns and continues whenghis missing/unauthenticated, or ifgh repo createfails) - Changes into the new directory and runs the
hatch3r initprompts (see above);initemits the single terminal outcome box / JSON envelope
hatch3r config
Interactive reconfiguration of your hatch3r setup. Also accepts scalar forms: config maturity=<tier>, config get <key>, config set <key> <value>.
npx hatch3r config
npx hatch3r config --dry-run # preview the change without writing
npx hatch3r config maturity=team # scalar form, no prompts
- Change platform, tools, features, and MCP servers
- Add or remove individual content items (agents, skills, rules, commands) — manifest-only bookkeeping: the selection is written to
.hatch3r/hatch.jsonand adapter outputs are regenerated from the bundled canonical content (no.agents/materialization). Removing an item rescues its hand-authored.customize.*overrides into the archive - Enable/disable worktree file isolation for parallel agent sessions
- Manage workspace repos (add/remove sub-repos, toggle sync, change sync strategy)
- Archives removed tool outputs to
.hatch3r-archive/ - Re-syncs all adapters after changes
Command-specific flags: --dry-run (preview without writing), --verbose.
hatch3r sync
Re-generates tool-specific files from the bundled canonical content plus your .hatch3r/overrides/.
npx hatch3r sync
npx hatch3r sync --repos frontend backend # sync specific sub-repos only
npx hatch3r sync --dry-run # preview without writing
npx hatch3r sync --force # overwrite even if unchanged
Flags:
| Flag | Values | Default | Description |
|---|---|---|---|
--repos | space-separated paths | all repos | Sync only the listed sub-repos |
--dry-run | — | off | Show what would be synced without writing files |
--force | — | off | Overwrite target files even if unchanged |
--diff | — | off | Show a before/after diff summary for each generated file |
--minimal | — | off | Generate stripped-down output (no comments, minimal formatting) to reduce token usage |
--strict-budget | — | off | Fail sync if any adapter's generated output exceeds its context budget (default: warn) |
--verbose | — | off | Show detailed output for each file processed |
:::info Drift gate
There is no integrity-checksum preflight (the .agents/-scoped integrity manifest was removed in the Wave 7 bundled-content model). Drift is detected by regenerating each adapter output and diffing it against the on-disk copy. --force overwrites target files even when unchanged.
:::
:::info Orphan cleanup (1.6.0)
Since 1.6.0, sync unlinks files previously emitted by hatch3r but no longer produced, tracked per-adapter via managedFilesByAdapter in hatch.json. Four safety refusals prevent accidental deletion: user-wrapped content, paths outside adapter roots, non-hatch3r- basenames, and no-history first-run.
:::
Run after editing anything under .hatch3r/overrides/, upgrading hatch3r, or when generated files get out of sync. Preserves content outside managed blocks in markdown files. Warns if project specs in docs/specs/ are stale (>7 days without update).
In a workspace, sync generates tool-specific files in each sub-repo from the bundled canonical content plus the workspace-level selection and any per-repo overrides from workspace.json. Sub-repos receive independent copies (not symlinks).
hatch3r update
Pulls the latest hatch3r package and regenerates adapter outputs from the updated bundled content, safe-merging into your customizations.
npx hatch3r update
Uses the safe merge system: managed blocks are updated, your customizations are preserved.
Flags:
| Flag | Description |
|---|---|
--yes | Skip interactive prompts, use defaults |
--diff | Show a before/after diff summary for each generated file |
--force | Overwrite generated outputs even when unchanged |
--offline, --skip-fetch | Skip the package fetch step; regenerate only from already-installed canonical content |
--dry-run | Preview what would change (added/modified/unchanged per adapter) without writing files |
hatch3r status
Checks sync status by regenerating each adapter output from the bundled canonical content (plus your overrides) and diffing it against the generated tool files on disk.
npx hatch3r status
npx hatch3r status --verbose # detailed per-file status
npx hatch3r status --diff # before/after diff summary per generated file
Flags:
| Flag | Description |
|---|---|
--verbose | Show detailed per-file status information |
--diff | Show a before/after diff summary for each generated file (same box hatch3r sync --diff emits) |
Status compares only the hatch3r-managed block (HATCH3R:BEGIN/END) against a fresh regeneration; content you author outside the markers is never reported here. (The former --deep flag was removed — regeneration is the only drift path.)
Reports synced, drifted, and missing files for each configured tool. When a workspace.json manifest exists, also displays workspace topology -- listing each sub-repo, its sync status, and any per-repo overrides.
hatch3r validate
Validates content structure and file contents — bundled canonical content plus your .hatch3r/overrides/.
npx hatch3r validate
npx hatch3r validate --verbose # detailed validation output
Flags:
| Flag | Description |
|---|---|
--verbose | Show detailed validation output for each check |
Checks for:
- Required directories (
agents/,skills/,rules/) - Valid
hatch.jsonmanifest - Frontmatter integrity (opening/closing
---, requiredidandtypefields) - Valid MCP JSON configuration
- Managed file presence and naming conventions
- Content consistency — manifest items vs. files on disk
- Orphaned customization files in
.hatch3r/ - Cross-reference integrity — verifies
hatch3r-*references between content items resolve to existing IDs - Orchestration dependencies — warns if pipeline-critical agents (researcher, implementer, reviewer, test-writer, security-auditor) are missing from the content selection
- MCP version-pin check — flags unpinned
npx @scope/pkginvocations and@latesttags as supply-chain risk (per OWASP ASI 2026)
hatch3r verify
A thin drift-detection wrapper over status: it regenerates each adapter output from the bundled canonical content and diffs it against the on-disk copy, then exits non-zero if any output is drifted or missing. There is no .integrity.json checksum file — drift is computed by regeneration, not stored hashes.
npx hatch3r verify
npx hatch3r verify --fix # auto-repair drift by regenerating output
npx hatch3r verify --fix --max-fix-attempts 3 # raise the default 2-cycle cap
Reports each adapter output as synced, drifted, or missing. Exits 73 (INTEGRITY_ERROR) if any drift remains — see Exit Codes.
Flags:
| Flag | Description |
|---|---|
--fix | Auto-repair drifted/missing output by regenerating it (the same in-memory regeneration hatch3r sync performs), re-checking drift after each pass |
--max-fix-attempts <n> | Maximum regenerate-then-recheck cycles (default: 2, clamped to 1–5) |
--verbose | Show the per-tool / per-file drift breakdown before the PASS/FAIL summary |
--diff | Show a before/after diff summary for each generated file |
Recovery:
- Drifted: Run
hatch3r verify --fix(orhatch3r sync) to regenerate the on-disk output - Missing: Run
hatch3r syncto regenerate
hatch3r clean
Remove all hatch3r artifacts from the current repository.
npx hatch3r clean
npx hatch3r clean --yes # skip confirmation (no reinit)
npx hatch3r clean --dry-run # preview without modifying files
Flags:
| Flag | Description |
|---|---|
--yes | Skip confirmation prompts (cleans without reinit) |
--dry-run | Show what would be removed without modifying files |
Removes .hatch3r/hatch.json, all generated tool files, and archive directories (.hatch3r-archive/). Keeps the rest of .hatch3r/ — learnings, handoffs, overrides, mcp, and .customize.yaml files. Optionally offers to reinitialize after cleanup.
hatch3r worktree-setup
Sets up gitignored files (.env.mcp and other .env.*, plus the shared .hatch3r/ state) in a new git worktree, per the patterns in .worktreeinclude.
npx hatch3r worktree-setup [worktree-path]
Flags:
| Flag | Description |
|---|---|
--from <path> | Main repo path (auto-detected by default) |
--dry-run | Show what would be done without changes |
--force | Overwrite existing files in the worktree |
--yes | Skip the secret-propagation confirmation prompt |
Automatically triggered by the Claude adapter's PostToolUse hook when git worktree add is detected. Can also be run manually after creating a worktree.
Secret propagation (blast radius)
.env.mcp and other .env.* files are copied (not symlinked) into each worktree so MCP servers can start without reaching outside the worktree root. This duplicates plaintext credentials and aligns with CWE-552 (Files or Directories Accessible to External Parties).
Before running worktree-setup, consider the blast radius:
- Worktree paths on shared locations (
/tmpmounts, network drives, devcontainer volumes) expose the copied secrets to every user with read access. - Ephemeral worktree farms (per-branch CI sandboxes, parallel AI agent scratch dirs) multiply the exposure surface — N worktrees equals N plaintext credential copies.
hatch3r worktree-cleanupremoves symlinks and unmodified copies; run it as soon as a worktree is no longer needed.
When .env.mcp is present, worktree-setup prints a highlighted warning box and, on an interactive terminal, asks for confirmation before continuing. Use --yes to skip the prompt in automation (for example, the Claude adapter's PostToolUse hook).
hatch3r worktree-cleanup
Remove symlinks and copied files created by worktree-setup in the current worktree.
npx hatch3r worktree-cleanup
npx hatch3r worktree-cleanup --dry-run # preview without changes
Flags:
| Flag | Description |
|---|---|
--dry-run | Show what would be done without changes |
hatch3r add
Install community content packs (coming soon).
npx hatch3r add <pack>
This command will allow installing community-contributed agent packs, rule sets, and workflow recipes. Follow hatch3r on GitHub for updates.
hatch3r cli-tools
Added in 1.7.5. Manage the agentic CLI-tools selection (ripgrep, fd, jq, gh, ast-grep, and 25 others across three tiers). The CLI-tooling pivot positions OS-native CLI tools as the default token-efficient agent-tooling surface; MCP is opt-in.
npx hatch3r cli-tools # open the tier-grouped picker
npx hatch3r cli-tools list # show current selection + install status
npx hatch3r cli-tools detect # read-only detection report
npx hatch3r cli-tools install # re-run the installer offer for missing tools
Detection uses POSIX command -v / Windows where with a 2-second timeout and fail-open semantics. The installer never executes — it prints copy-paste commands grouped per package manager (brew, apt, dnf, winget, scoop, with cargo / pipx / npm fallback). After every flow that touches CLI-tool selection, a warning-style box surfaces any selected-but-not-installed tools alongside a one-liner that chains installable tools through their shared package manager.
The bare command also accepts --dry-run (show the resulting selection without writing the manifest). --format json is accepted on list and detect; the bare picker and install can prompt, so JSON is rejected there (exit 2).
See the CLI Tools getting-started guide for the full tier catalog.
hatch3r mcp
Added in 1.7.5. Manage MCP server configuration. MCP is pure opt-in since 2.0.0: interactive init does not prompt for it, and no init path configures it without --mcp. mcp setup is the primary opt-in surface; setup and remove keep the manifest's features.mcp flag consistent (true only while at least one server remains selected).
npx hatch3r mcp setup # open the MCP server picker (writes manifest + .env.mcp)
npx hatch3r mcp list # show current MCP configuration
npx hatch3r mcp remove <id> # delete a single MCP server
npx hatch3r mcp env-check # audit .env.mcp for missing required env vars
setup and remove accept --dry-run (show the resulting server list + features.mcp without writing). --format json is accepted on the headless subcommands (list, remove, env-check); setup always prompts, so JSON is rejected there (exit 2).
See MCP setup for server reference and security model.