⚠️ EARLY ALPHA — experimental. Use goggles. DO NOT use for production.

create-armadillo

A separately publishable Oclif CLI for standalone Armadillo applications. Node 22.19+ and npm 11.6+ are required. The CLI has no Armadillo or Alchemy runtime dependency.

After publication:

npm create [email protected] my-app -- --template typed --install
cd my-app
npm run check
npm run dev

Before publication, install artifacts/create-armadillo-0.1.0-alpha.tgz in a temporary tool project and run its local binary. Install the library tarball in the generated application. Root npm run release:verify automates this exact test.

Commands:

| Command | Behavior | | --- | --- | | create <directory> | Create a new project; existing directories are rejected | | init [directory] | Add missing application files; reject conflicts before writing | | doctor [directory] | Check application files, installed library compatibility, and Alchemy availability | | dev [directory] | Run the application's installed Alchemy in local mode | | plan [directory] --stage preview | Run Alchemy's infrastructure plan | | deploy [directory] --stage preview | Run Alchemy deployment with its normal approval workflow |

create and init accept --template minimal|typed, --install, and --json. Without --install, files are generated without network access. Installation failures leave a complete project; run npm install inside it to retry. Help and scaffolding work before the target application has Armadillo installed. doctor --json is useful in scripts; run the application's npm run check for type and declaration validation.

Existing package metadata and unrelated scripts/dependencies are preserved. Conflicting template scripts/dependencies are rejected, as are existing authoring files. No repository is reset. The CLI never downloads remote source for execution.

This CLI accepts Armadillo >=1.0.0 <2.0.0; it reads the target application's installed package, rather than assuming its own version matches. A future incompatible library requires an updated compatibility range and tests. The reference examples are the only maintained templates; npm run build snapshots them for distribution.

From the repository root:

npm --prefix cli ci
npm --prefix cli run build
npm --prefix cli test
npm --prefix cli pack

Registry lookup currently returns not found for create-armadillo; that is not a reservation or proof of publication rights. Do not publish until the release gates in ../docs/release.md pass and the owner authorizes publication. MIT licensed.

Application run scripts

The package also exposes the armadillo binary. Add "dev": "armadillo run dev", "deploy": "armadillo run deploy", "plan": "armadillo run plan", "list": "armadillo run list", "stages": "armadillo run stages", and "logs": "armadillo run logs" to the application scripts.

Use npm run deploy -- dev, npm run deploy -- <stageName>, or npm run deploy -- prod. Deployment requires an explicit stage. Plan, resource listing, and logs default to cloud dev. dev always uses local mode and stage local; list local reads the separate local stack. local cannot be deployed. No workflow bypasses Alchemy's normal deployment approval.

doctor and all workflows prefer armadillo.config.ts and retain compatibility with alchemy.run.ts. Put your Alchemy stack declaration in that config. For list and stages, set package.json's armadillo.stack to the stack name (Block Party uses ArmadilloBlockParty). Listing reads existing Alchemy state; it does not deploy resources. Pass --env-file .env.prod for stage-specific configuration, or --dry-run to print the exact invocation without importing the config or contacting a provider. The run command also accepts --directory for scripting across projects.

Known alpha limitations

• Scaffolded templates reference the core as "armadillo": "file:../.." (the local-checkout flow). The bare armadillo name on the npm registry belongs to an unrelated package, so the core is NOT yet installable from the registry — that is a later milestone, not this alpha.