Installation — SpellCraft

What SpellCraft needs, how to get it, and how to confirm it works before you write anything real.

SpellCraft is a Node package. There is no daemon, no agent, and no account to create.

Requirements


Node.js	18 or newer
A C++ toolchain	Jsonnet is compiled from source on install
Terraform	Only if you use the `terraform` node of `@c6fc/spellcraft-plugins`, which downloads its own binary

The toolchain requirement comes from @hanazuki/node-jsonnet, which builds the Jsonnet interpreter natively. If installation fails with a wall of node-gyp output, this is almost always why.

Debian, Ubuntu:

sudo apt-get install -y build-essential cmake

Fedora, RHEL, Amazon Linux:

sudo dnf install -y gcc-c++ make cmake

Alpine:

sudo apk add build-base cmake

Starting a new project

The fastest path is the generator, which scaffolds a working project and installs everything:

npm init spellcraft my-infra
cd my-infra
npm run gen

That renders manifest.jsonnet into render/. If you see render/app.json appear, everything works.

Adding SpellCraft to an existing project

npm install --save @c6fc/spellcraft

The spellcraft binary is then available through npx spellcraft or from an npm script. SpellCraft has no global install step: it resolves plugins from the dependencies of the project you run it in, so a global copy would find nothing.

Why local only

Plugins are discovered by walking your project's dependency tree for packages flagged "spellcraft": true. A globally installed SpellCraft has no project to walk, which is why the CLI is always run through your project.

Confirming the install

npx spellcraft --help

You should see the built-in commands — generate and doc — plus any commands contributed by plugins you have installed. That last part is the useful signal: if you installed a plugin and its commands are missing, the plugin is not being loaded, and the plugin contract chapter explains what SpellCraft looks for.