Agent-first CLI — make any project AI-agent compatible.

Anvil installs, projects, and maintains AI agent components (skills, recipes, hooks, agents) in each agent's native format. Write once, deploy to Copilot, Claude, or Cursor — then promote recipes to autonomous GitHub Agentic Workflows.

Components are loaded from the official marketplace (synced on first use) and optional external marketplaces.

Quick Start

npm install -g @fr-nan-ai/anvil

# Initialize a project for GitHub Copilot
anvil init --agent copilot

# Or with a bundle (installs a curated set of components)
anvil init --agent copilot --preset full-stack

# Install components from the catalog
anvil install skill coding-principles
anvil install skill test-driven-development
anvil install hook pre-commit-check

# Customize a component for your team
anvil customize skill coding-principles
# Edit .anvil/state/local/skills/coding-principles/index.md
anvil generate

# Create a brand new local component
anvil create skill my-team-guidelines

# Promote a recipe to an autonomous GitHub workflow
anvil promote recipe my-workflow --target gh-aw

# Validate project integrity
anvil validate

# Check what's installed
anvil status

Supported Targets

| Target | Surface | |--------|---------| | copilot | .github/copilot-instructions.md, .github/instructions/, .github/prompts/ | | claude | AGENTS.md, .claude/skills/ | | cursor | .cursor/rules/*.mdc | | gh-aw (promotion) | .github/workflows/*.md + .github/workflows/*.lock.yml |

How It Works

Anvil follows a state-then-project architecture with a copy-on-customize model:

catalog (official + external marketplaces)
    │
    ▼  anvil install
    │
.anvil/state/framework/     ← installed components (read-only)
    │
    ├── anvil customize ──► .anvil/state/local/  ← editable copies
    │
    ▼  anvil generate
    │
.github/instructions/        ← Copilot surface
.claude/skills/              ← Claude surface
.cursor/rules/               ← Cursor surface

1. anvil install copies a component from the catalog into .anvil/state/framework/
2. anvil customize copies it to .anvil/state/local/ for editing
3. anvil generate projects state into the agent's native surface (auto-selects local or framework)
4. anvil update merges upstream changes into customized components (3-way merge with backup)
5. anvil promote compiles a recipe into a GitHub Agentic Workflow (.md + .lock.yml)
6. Components are tracked with SHA-256 hashes for version detection

Commands

| Command | Description | |---------|-------------| | anvil init --agent <target> | Initialize a project for an AI agent | | anvil install <type> <name> | Install a component from the catalog | | anvil remove <type> <name> | Remove an installed component | | anvil customize <type> <name> | Copy a component to local for editing | | anvil uncustomize <type> <name> | Restore the framework version | | anvil create <type> <name> | Scaffold a new local component | | anvil status | Show installed components and their state | | anvil generate | Re-project state to agent surface files | | anvil catalog | Browse available components | | anvil inspect <type> <name> | Show component details before installing | | anvil diff | Compare installed components with source | | anvil update <type> <name> | Update a component from source | | anvil update <type> <name> --preview | Preview changes without applying | | anvil update <type> <name> --restore | Restore from backup after a bad merge | | anvil marketplace list | List configured marketplace sources | | anvil marketplace add <name> | Add an external marketplace | | anvil marketplace remove <name> | Remove a marketplace source | | anvil marketplace sync | Sync marketplace catalogs | | anvil marketplace enable <name> | Enable a marketplace | | anvil marketplace disable <name> | Disable a marketplace | | anvil marketplace init <path> | Scaffold a new marketplace repository | | anvil promote recipe <name> --target gh-aw | Promote a recipe to a GitHub Agentic Workflow | | anvil promote --recompile <name> | Recompile a promoted workflow after recipe update | | anvil validate | Validate project integrity (config, state, promotions) | | anvil doctor | Diagnose installation health | | anvil onboard complete | Mark project as onboarded |

Global Flags

| Flag | Description | |------|-------------| | --json | Output as structured JSON | | --yes | Skip confirmation prompts (also ANVIL_YES=1) | | --verbose | Verbose output | | --quiet | Suppress non-essential output | | --force | Force operation (skip guards) | | --from <marketplace> | Specify source marketplace | | --all | Apply to all components | | --preset <name> | Use a preset during init | | --preview | Dry-run for update (show diff without writing) | | --restore | Restore last backup after update | | --target <target> | Promotion target (currently gh-aw) | | --trigger <event> | Trigger event for promoted workflow | | --recompile | Recompile a promoted workflow | | --dry-run | Simulate promotion without writing files | | --help | Show help | | --version | Show version |

Customization

Anvil uses a copy-on-customize model: framework components are read-only, and customization creates an editable local copy.

# Customize a framework component
anvil customize skill coding-principles

# Edit the local copy
# .anvil/state/local/skills/coding-principles/index.md

# Re-project to surface
anvil generate

# When upstream updates are available
anvil update skill coding-principles --preview   # preview the diff
anvil update skill coding-principles             # merge with auto-backup
anvil update skill coding-principles --restore   # undo if merge was bad

# Revert to the framework version
anvil uncustomize skill coding-principles

Creating Local Components

# Create a brand new skill (not from catalog)
anvil create skill my-guidelines

# Create a recipe
anvil create recipe my-workflow

# Local components are stored in .anvil/state/local/
# and projected to the active surface automatically

Promotion (GitHub Agentic Workflows)

Recipes with interactions and providers can be promoted to autonomous GitHub Agentic Workflows. Promotion compiles a recipe (with its dependent skills inlined) into a .md workflow and a .lock.yml lockfile.

# Promote a recipe to GitHub Agentic Workflow
anvil promote recipe us-to-pr --target gh-aw

# Preview what would be generated (dry-run)
anvil promote recipe us-to-pr --target gh-aw --dry-run

# Specify a custom trigger event
anvil promote recipe us-to-pr --target gh-aw --trigger "issues:labeled:ready"

# After updating a promoted recipe, recompile the workflow
anvil update recipe us-to-pr
# ⚠ Warning: promoted workflow is stale
anvil promote --recompile us-to-pr

Generated files:

• .github/workflows/<name>.md — workflow with frontmatter (trigger, tools, permissions) + recipe content + inlined skills
• .github/workflows/<name>.lock.yml — lockfile with recipe hash, compiled timestamp, interaction mappings

Interactions & Providers

Recipes can declare interactions (human-in-the-loop points) and providers (external integrations) in component.yaml:

interactions:
  - id: validate-approach
    phase: analysis
    mode: interactive
    fallback: comment
providers:
  - type: ticket
    name: ticket-source
    required: true

These are visible via anvil inspect recipe <name> and compiled into the workflow during promotion.

Hooks Runtime

Hooks with a script field in component.yaml execute shell scripts in response to events:

name: post-install-check
type: hook
event: post.install
script: scripts/check.sh
timeout: 5000

Supported events: session.start, session.end, prompt.submitted, tool.pre, tool.post.success, tool.post.failure, post.install, post.remove, post.generate.

Scripts run sandboxed via execFile (not shell) with environment variables: ANVIL_EVENT, ANVIL_PROJECT_ROOT, ANVIL_COMPONENT_NAME.

Validation

# Full project integrity check
anvil validate

Validates: catalog schema, config consistency, component state, hash integrity, surface projections, promotion consistency (workflow + lockfile exist, stale detection), and orphan components.

Marketplaces

Anvil supports multiple component sources. The official marketplace is fetched from GitHub and cached locally. You can add external sources via git or local path.

# Add a team marketplace from a git repo
anvil marketplace add myteam --git https://github.com/org/anvil-components.git

# Add a local marketplace (useful for development)
anvil marketplace add local-dev --local /path/to/components

# Sync all marketplaces
anvil marketplace sync

# Browse the unified catalog (all sources)
anvil catalog

# Install from a specific marketplace
anvil install skill my-skill --from myteam

# Scaffold a new marketplace repository
anvil marketplace init ./my-marketplace

When a component name exists in multiple marketplaces, anvil requires --from to disambiguate.

Bundles (Presets)

Bundles are curated sets of components for common use cases, hosted in the marketplace:

anvil init --agent copilot --preset full-stack

Available bundles: full-stack, tech-lead. Browse them with anvil catalog --type bundle.

Component Lifecycle

# Inspect before installing
anvil inspect skill coding-principles

# Install
anvil install skill coding-principles

# Customize for your team
anvil customize skill coding-principles

# Check for updates
anvil diff

# Update with 3-way merge (auto-backup)
anvil update skill coding-principles

# Preview update without writing
anvil update skill coding-principles --preview

# Restore backup if merge was bad
anvil update skill coding-principles --restore

# Update all non-customized components
anvil update --all

# Revert customization
anvil uncustomize skill coding-principles

# Remove (with dependency guard)
anvil remove skill coding-principles

Project Structure

After anvil init --agent copilot, your project will have:

.anvil/
  config.json          ← project config (v2 schema)
  state/
    framework/
      official/        ← official catalog components
      external/        ← external marketplace components
    local/             ← customized + created components
  backups/             ← automatic backups before merges
  cache/
    marketplaces/      ← synced marketplace catalogs
  docs/                ← project documentation for agents
  .gitignore

Component Types

| Type | Description | Copilot | Claude | Cursor | |------|-------------|---------|--------|--------| | skill | Reusable guidance | .github/instructions/*.instructions.md | .claude/skills/*.md | .cursor/rules/*.mdc | | hook | Event-driven instructions | .github/instructions/*-hook.instructions.md | .claude/skills/*-hook.md | .cursor/rules/*-hook.mdc | | agent | Specialized AI agents | .github/instructions/*.instructions.md | .claude/skills/*.md | .cursor/rules/*.mdc | | recipe | Multi-step workflows | .github/prompts/*.prompt.md | .claude/skills/*.md | .cursor/rules/*.mdc |

Component Format

Each component lives in its own directory with:

skills/coding-principles/
  component.yaml       ← metadata (type, name, version, targets, depends)
  index.md             ← content

Configuration

.anvil/config.json uses a v2 schema:

{
  "version": 2,
  "agent": "copilot",
  "marketplaces": {
    "official": { "kind": "git", "enabled": true, "priority": 0, "remote": "https://github.com/FR-NAN-AI/anvil-marketplace.git", "ref": "main" },
    "myteam": { "kind": "git", "enabled": true, "priority": 10, "remote": "..." }
  },
  "components": {
    "skills": {
      "coding-principles": {
        "marketplace": "official",
        "hash": "...",
        "customized": false,
        "frameworkHash": null
      }
    }
  },
  "promotions": {
    "us-to-pr": {
      "target": "gh-aw",
      "recipeHash": "...",
      "promotedAt": "...",
      "trigger": "issues:labeled:agent-ready",
      "workflowPath": ".github/workflows/us-to-pr.md",
      "lockfilePath": ".github/workflows/us-to-pr.lock.yml",
      "stale": false
    }
  },
  "onboarded": false
}

Doctor

anvil doctor runs comprehensive health checks:

• Node.js version (>= 18)
• .anvil/ structure integrity
• Component state consistency (config ↔ state ↔ surface)
• SHA-256 hash integrity (detects manual edits)
• Orphan components (state without config entry)
• Orphan projections (surface files without matching component)
• Customized components with outdated upstream
• Stale backups (> 30 days)
• Marketplace cache status

Versioning

• 0.1.x: Copilot target, official catalog
• 0.2.x: Multi-target (Claude, Cursor), external marketplaces, presets
• 0.3.x: Customization (copy-on-customize), create, 3-way merge, backups
• 0.4.x: Promotion (gh-aw), validate, hooks runtime, interactions/providers
• 0.5.x: Remote official marketplace, educational onboarding, improved adapters
• v1.0.0: Stable API, production ready

Development

# Run E2E tests
node test/e2e-phase1.js    # 42 tests — core commands
node test/e2e-phase2.js    # 57 tests — marketplaces, adapters, lifecycle
node test/e2e-phase3.js    # 62 tests — customization, create, merge, backups
node test/e2e-phase4.js    # 49 tests — promotion, validate, hooks runtime

# Test manually
node bin/anvil --help
node bin/anvil --version

Architecture

bin/anvil                    ← entry point
lib/
  cli/
    parse-args.js            ← argument parser (Node 18+ util.parseArgs)
    output.js                ← structured output (JSON/text)
  core/
    config.js                ← .anvil/config.json v2
    state-store.js           ← .anvil/state/ management
    hash.js                  ← SHA-256 component tracking
    catalog.js               ← catalog reader + multi-source merge
    marketplace.js           ← marketplace registry (add/remove/enable)
    marketplace-sync.js      ← git clone + cache management
    marketplace-cmd.js       ← anvil marketplace CLI handler (+ init)
    preset.js                ← preset loading + apply
    dependencies.js          ← dependency graph + remove guard
    init.js                  ← anvil init (+ preset support)
    install.js               ← anvil install (multi-source)
    remove.js                ← anvil remove (with dependency check)
    customize.js             ← anvil customize + uncustomize
    create.js                ← anvil create (scaffold local component)
    backup.js                ← automatic backups before merge
    merge.js                 ← 3-way merge engine
    status.js                ← anvil status
    generate.js              ← anvil generate
    inspect.js               ← anvil inspect
    diff.js                  ← anvil diff
    update.js                ← anvil update (+ merge, --preview, --restore)
    promote.js               ← anvil promote (recipe → gh-aw workflow)
    validate.js              ← anvil validate (project integrity)
    hooks-runtime.js         ← hooks script execution (sandboxed)
    doctor.js                ← anvil doctor (hash integrity, orphans)
    onboard.js               ← anvil onboard
  adapters/
    shared.js                ← adapter interface contract
    index.js                 ← adapter registry
    copilot/transform.js     ← Copilot adapter (.github/)
    claude/transform.js      ← Claude adapter (AGENTS.md, .claude/)
    cursor/transform.js      ← Cursor adapter (.cursor/rules/)
    gh-aw/transform.js       ← GitHub Agentic Workflow adapter (promotion)
skills/
  onboarding/                ← embedded fallback (auto-installed on init)
  anvil-cli-reference/       ← embedded fallback (auto-installed on init)
  catalog-browser/           ← embedded fallback (auto-installed on init)

License

MIT — see LICENSE