Docs/Get Started/Setup & Channels

Setup & Channels

A deeper look at how to install and run spec-init on each channel - npx vs a global install on npm, pipx vs pip on Python - plus version pinning, updates, and per-channel troubleshooting.

New in 1.2.0Every scaffold command on this page uses the create-app shorthand: spec-init my-app now implies init. Read the full 1.2.0 notes on the Changelog.

The two channels are interchangeable. They expose the same commands and flags and ship one source-of-truth template payload, verified byte-for-byte on every release, so a project scaffolded from npm is identical to one scaffolded from PyPI. Choose by the runtime you already have.

Which channel should I use?

You have Node.js ≥ 18Use npm. The npx form needs zero install and always runs the latest release - the simplest possible path.

You have Python ≥ 3.10Use PyPI. pipx gives you an isolated, always-available spec-init command.

You have bothPick either - they are functionally identical. Node users tend to prefer npx for its zero-install ergonomics.

npm: npx vs global install

npx downloads and runs the newest published version on demand, leaving nothing behind. It is ideal for one-off scaffolds and CI:

# always the latest release, nothing installed
npx spec-init my-app

# pin an exact version for a reproducible scaffold
npx spec-init@1.2.0 my-app

A global install puts a persistent spec-init on your PATH - better if you scaffold often or work offline:

npm install -g spec-init      # latest
npm install -g spec-init@1.2.0  # exact version

spec-init --version           # → spec-init 1.2.0

Python: pipx vs pip

pipx installs the CLI into a dedicated virtualenv, so it never conflicts with a project environment. This is the recommended path:

pipx install spec-init          # latest
pipx install spec-init==1.2.0   # exact version

spec-init --version             # → spec-init 1.2.0

Plain pip works when you want the CLI inside a specific environment (for example a project venv):

python -m venv .venv && source .venv/bin/activate
pip install spec-init==1.2.0
spec-init --version

Avoid a bare global pip installInstalling into your system Python with sudo pip can clash with OS-managed packages. Prefer pipx, or a virtualenv, so spec-init stays isolated.

Verify and pin

After installing, confirm the version, then let doctor validate a scaffold. Pinning an exact version (shown above) keeps CI reproducible:

spec-init --version   # → spec-init 1.2.0

spec-init my-app
cd my-app
spec-init doctor      # ✓ required files, template-version, spec.config.js

Keep the CLI updated

# npm global install
npm update -g spec-init

# pipx
pipx upgrade spec-init

# pip (in the target environment)
pip install --upgrade spec-init

Updating the CLI is not the same as upgrading a projectThese commands update the spec-init tool. To pull a newer template into an existing scaffold, run spec-init upgrade inside that project - it three-way-merges the new payload and advances the template version, never silently overwriting your edits.

Per-channel troubleshooting

command not found: spec-initFor a global npm install, ensure npm’s global bin is on PATH (npm bin -g). For pipx, run pipx ensurepath and reopen the shell.

npx keeps running an old versionnpx caches. Force the latest with npx spec-init@latest, or clear it with npm cache clean --force.

pip install works but spec-init is missingThe environment’s Scripts/bin directory is not on PATH, or you installed into a different interpreter. Prefer pipx, or activate the venv you installed into.

Windows PowerShellBoth channels work. If a global bin is not found, restart the terminal so PATH changes take effect; WSL behaves like Linux.

Uninstall

npm uninstall -g spec-init   # npm global
pipx uninstall spec-init     # pipx
pip uninstall spec-init      # pip

Quickstart

Empty folder to first shipped feature, end to end.

CLI Reference

Every command and flag, identical on both channels.