@decantr/cli

Support status: core-supported
Release channel: stable

Decantr’s main local operator surface for scaffolding, auditing, inspecting, and maintaining Decantr projects.

Install

npm install -D @decantr/cli

Or run it without installing:

npx @decantr/cli new my-app --blueprint=agent-marketplace

Use decantr new for a greenfield workspace in a fresh directory. With a blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass --adoption=decantr-css. Use decantr analyze first when you already have an app and want Decantr governance without adopting a blueprint. Use decantr init to attach Decantr contract/context files to an existing project or to create a contract-only workspace.

Current starter adapter availability:

• react-vite is the runnable bootstrap adapter in this wave
• next-app is the runnable Next.js App Router adapter
• other contract targets use the generic-web contract-only adapter until their runnable adapters land

Explicit workflow/adoption flags:

decantr init --workflow=greenfield --adoption=contract-only
decantr init --existing --adoption=contract-only
decantr init --existing --adoption=style-bridge
decantr init --existing --adoption=decantr-css
decantr init --project=apps/web --yes
decantr init --assistant-bridge=preview
decantr rules apply

Adoption modes:

• contract-only writes Decantr essence/context/governance files without Decantr CSS files or @decantr/css dependency guidance.
• style-bridge writes bridge tokens/files that map Decantr intent onto an existing style system without requiring @decantr/css.
• decantr-css writes the full Decantr CSS files and runtime guidance.

Monorepos store both workspaceRoot and appRoot. In non-interactive workspace-root runs with multiple app candidates, pass --project=<path> so Decantr attaches to the intended app.

Assistant rule integration is preview-first: --assistant-bridge=preview writes .decantr/context/assistant-bridge.md, while --assistant-bridge=apply or decantr rules apply mutates supported rule files with idempotent marked blocks.

What It Does

• scaffolds Decantr projects from blueprints, archetypes, or prompts
• supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
• generates execution-pack context files for AI coding assistants
• audits projects against Decantr contracts
• searches the registry and showcase benchmark corpus
• validates, refreshes, and maintains decantr.essence.json

Common Commands

decantr new my-app --blueprint=agent-marketplace
decantr analyze
decantr init --existing --yes --adoption=contract-only
decantr init --existing --blueprint=agent-marketplace
decantr init --workflow=greenfield --adoption=contract-only
decantr rules apply
decantr magic "AI-native analytics workspace"
decantr audit
decantr check
decantr registry summary --namespace @official --json
decantr showcase verification --json

Greenfield Certification

Use the built-in certification harness before releases when you want to prove that representative blueprints still scaffold into runnable starter projects:

pnpm --filter @decantr/cli certify:blueprints

By default it certifies portfolio, producer-studio, and agent-marketplace by:

• running decantr new in fresh temp directories
• seeding offline content from DECANTR_CONTENT_DIR or a sibling decantr-content checkout
• verifying the starter runtime files and router mode match the generated essence
• running npm run build in each scaffolded project

Override the matrix or emit JSON when needed:

pnpm --filter @decantr/cli certify:blueprints -- --blueprints=portfolio,legal-research --json

Offline blueprint scaffolding expects a real local content source:

DECANTR_CONTENT_DIR=/path/to/decantr-content decantr new my-app --blueprint=agent-marketplace --offline

If a requested offline blueprint, archetype, or theme cannot be resolved from local cache/custom content or DECANTR_CONTENT_DIR, the CLI now stops explicitly instead of silently falling back to the default scaffold.

Workflow Certification

The broader workflow matrix now has its own certification entrypoint:

pnpm --filter @decantr/cli certify:workflows

It covers:

• greenfield blueprint bootstrap
• greenfield contract-only
• brownfield analyze -> init --existing
• direct brownfield init
• adoption modes (contract-only, style-bridge, decantr-css)
• offline contract-only and offline blueprint flows
• unsupported target contract-only fallback
• monorepo --project handling
• Next.js App Router adapter
• hybrid follow-up composition via Decantr mutation commands

Generated Context

Scaffolded projects include compiled execution packs under .decantr/context/, including:

• scaffold-pack.md / scaffold-pack.json
• section-*-pack.md / section-*-pack.json
• page-*-pack.md / page-*-pack.json
• review-pack.md / review-pack.json
• pack-manifest.json

Those files are the compact task contracts meant for AI assistants and downstream tooling.

Recommended read order for AI-assisted scaffolding:

1. DECANTR.md for the design spec, CSS approach, and guard rules
2. .decantr/context/scaffold-pack.md as the primary compiled shell, theme, feature, and route contract
3. .decantr/context/scaffold.md as the broader app overview and topology guide
4. matching section-*-pack.md and section-*.md files before section work
5. matching page-*-pack.md files before route work

Treat the compiled execution packs as the source of truth. Use the narrative docs as secondary explanation, start with the shell and route structure first, and run decantr check plus decantr audit after implementation.

For cold-start harness or certification runs, use only the scaffolded workspace files as the contract. If local scaffold files disagree, stop and report the mismatch rather than relying on repo-global Decantr assumptions.

Related Packages

• @decantr/essence-spec for schema and guard validation
• @decantr/registry for registry contracts and API access
• @decantr/verifier for audit and critique

Docs

• Decantr root README
• Package support matrix

License

MIT