CLI Commands

Commands you run directly in the terminal via npx hatch3r.

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
--quick, --default	—	off	Aliases for --yes (headless mode)
--yes	—	off	Skip all prompts (headless mode)
--preset	minimal, standard, full	full	Content profile preset
--project-type	greenfield, brownfield	auto-detected	Project type context
--team-size	solo, team	solo	Team size context
--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 init flow asks:

1. Platform -- GitHub, Azure DevOps, or GitLab (auto-detected from git remote)
2. Repo identity -- owner/org and repo name
3. Default branch -- for checkout, PR base, and release
4. Project type -- greenfield (new project) or brownfield (existing codebase)
5. Team size -- solo developer or team collaboration
6. Content profile -- Minimal, Standard (recommended), Full, or Custom
7. Tools -- select from 15 supported coding tools
8. Features -- agents, skills, rules, commands, prompts, MCP, hooks, GitHub agents
9. MCP servers -- optionally configure up to 10 MCP servers

Only the content matching your profile and context is copied to .agents/. Use hatch3r config to add or remove items later.

With --yes, init auto-detects greenfield/brownfield, defaults to solo + standard preset, and skips all prompts.

hatch3r config

Interactive reconfiguration of your hatch3r setup.

npx hatch3r config

• Change platform, tools, features, and MCP servers
• Add or remove individual content items (agents, skills, rules, commands)
• 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

hatch3r sync

Re-generates tool-specific files from the canonical .agents/ source.

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 Preflight integrity check (1.6.0) Since 1.6.0, sync runs verifyIntegrity() before executing. If drift is detected, the command halts with HatchError INTEGRITY_ERROR. Use --force to override and proceed. :::

:::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 manually editing canonical files 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 cascades content from the workspace .agents/ into each sub-repo, applying per-repo overrides from workspace.json. Sub-repos receive independent copies (not symlinks).

hatch3r update

Pulls the latest hatch3r templates and merges them with your canonical source.

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	Override the preflight integrity check and proceed despite drift
--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

:::info Preflight integrity check (1.6.0) Like sync, update runs verifyIntegrity() before executing. Use --force to override on drift. :::

hatch3r status

Checks sync status between canonical .agents/ and generated tool files.

npx hatch3r status
npx hatch3r status --verbose   # detailed per-file status
npx hatch3r status --deep      # byte-for-byte comparison

Flags:

Flag	Description
--verbose	Show detailed per-file status information
--deep	Regenerate every adapter's output in-memory to compare byte-for-byte (slower; default uses integrity-manifest fast 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 the .agents/ directory structure and file contents.

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.json manifest
• Frontmatter integrity (opening/closing ---, required id and type fields)
• 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/pkg invocations and @latest tags as supply-chain risk (per OWASP ASI 2026)

hatch3r verify

Verifies file integrity by comparing canonical files against stored checksums.

npx hatch3r verify
npx hatch3r verify --fix                        # auto-fix via update regenerate cycle
npx hatch3r verify --fix --max-fix-attempts 3   # raise the default 2-cycle cap

Requires .agents/.integrity.json (generated by init and update). Reports each file as PASS, MODIFIED, MISSING, NEW, or TAMPERED. Exit code 1 if any integrity issues are found.

Flags:

Flag	Description
--fix	Auto-fix integrity issues by running hatch3r update (regenerate path only, no npm fetch)
--max-fix-attempts <n>	Maximum verify-fix cycles (default: 2, max: 5)

Recovery:

• Modified/Tampered: Run hatch3r update to restore originals
• Missing: Run hatch3r update to 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 .agents/, all generated tool files, and archive directories. Optionally offers to reinitialize after cleanup.

hatch3r worktree-setup

Sets up gitignored files (.env.mcp, .agents/.integrity.json, etc.) in a new git worktree.

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 (/tmp mounts, 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-cleanup removes 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.