Standalone Animus extraction CLI — one-shot builds and artifact emission
for any build system. animus build drives the same extraction session the
bundler plugins use and publishes a deterministic, fixed-path artifact set
for CI gates, non-JS orchestrators, and tooling.
If you are on a supported bundler, you want a transform driver instead:
@animus-ui/vite-plugin,
@animus-ui/next-plugin, or
@animus-ui/unplugin (rollup/esbuild/rspack/webpack). The
CLI's artifacts do not transform your sources — see the
standalone extraction contract
for why the transform is mandatory.
npm install --save-dev @animus-ui/cliRequires Node >=22.12.0. Native engine binaries ship for darwin-arm64,
linux-x64-gnu, and linux-arm64-gnu; the CLI exits 3 with remediation text
on unsupported platforms.
animus build --root . --system ./src/ds.ts --strict
animus watch --root . --system ./src/ds.ts
animus print-config --root . --system ./src/ds.tsConfiguration lives in animus.config.{json,mjs,js,ts} (probed in that
order; .ts needs Node >= 23.6 native type stripping — older runtimes get
a guided error naming the .mjs/.json remedy). Flags override file
values; --exclude merges. animus print-config prints the fully resolved
configuration as JSON on stdout with per-key provenance.
Stream discipline is a contract: stdout carries machine output only; every human-facing line goes to stderr.
| Code | Meaning |
|---|---|
| 0 | Success — artifact set published and self-consistent |
| 1 | Extraction failure (error diagnostics, --strict escalation, zero files, structural emptiness) |
| 2 | Config/usage error (unknown key, unresolvable system path, lock conflict) |
| 3 | Engine/environment failure (native engine load, consistency-check failure) |
animus watch adds: 130 on SIGINT, 143 on SIGTERM (lock released,
last-good artifacts kept), and 3 under --fail-on-degraded when any root
cannot be watched. Watch readiness is an explicit stderr event: wait for
the watch ready line before starting dependent steps.
Silent-empty success is impossible: system-load failure, zero discovered files, and structural emptiness are fatal in every mode.
animus build publishes to --out-dir (default <root>/.animus/ —
.gitignore it) at fixed paths: styles.css, system-props.js,
manifest.json, and commit.json — written last, carrying a content hash
per payload, so one read verifies set completeness and freshness. Bytes are
deterministic and identity-free; lock.json is a single-writer advisory
lock that fails loud. The full contract, including the consistency-check
recipe for non-JS orchestrators, is in the
standalone extraction contract.
MIT