Docs/Get Started/Install

Install

Throughspec ships on two channels from a single source-of-truth template tree, so the trees never drift byte-for-byte.

New in 1.2.0spec-init my-app now scaffolds directly - the create-app shorthand means you no longer need to type the init subcommand. See the full 1.2.0 notes on the Changelog.

Pick either channel - the Node and Python CLIs expose an identical command surface and ship the same template payload, verified byte-for-byte on every release. Use whichever runtime you already have.

npm (Node.js ≥ 18)

Distributed as ESM. The fastest path is npx, which downloads and runs the latest published version without a global install:

# one-off scaffold - no install, always the latest version
npx spec-init my-app

Prefer a persistent command on your PATH? Install it globally instead:

# install globally, then call spec-init anywhere
npm install -g spec-init
spec-init my-app

PyPI (Python ≥ 3.10)

Distributed as a pure-Python wheel. pipx is recommended - it installs the CLI into its own isolated virtualenv so it never collides with your project dependencies:

# recommended: isolated install via pipx
pipx install spec-init
spec-init my-app

If you do not use pipx, a plain pip install into the active environment works too:

# alternative: install into the current environment
pip install spec-init
spec-init my-app

npm and pip side by side

Every command maps one-to-one across the two channels. If a snippet elsewhere in these docs shows only the npx form, the pip equivalent is exactly the same after the runner prefix.

Run without installingnpm: npx spec-init my-app · pip: (install first, pipx/pip have no npx-style runner)

Global installnpm: npm install -g spec-init · pip: pipx install spec-init

Scaffold a projectBoth: spec-init my-app (create-app shorthand, new in 1.2.0)

Check the versionBoth: spec-init --version → spec-init 1.2.0

Update the CLInpm: npm update -g spec-init · pip: pipx upgrade spec-init

Flags

--persona <name>vibe | student | engineer | team - pre-tunes CLAUDE.md and the learning map.

--integrations <csv>graphify,obsidian - activates the relevant integration blocks and drops in their config files.

--forceRequired to overwrite an existing project. init refuses otherwise.

--dry-runPrints the file plan without writing anything.

--versionPrints the installed CLI version (spec-init 1.2.0) and exits.

Verify the install

Confirm the CLI is on your PATH and reports 1.2.0, then let doctor validate a scaffolded project has all required files, a template-version in CLAUDE.md, and a valid spec.config.js:

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

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

Update the CLI

npx always fetches the latest release, so there is nothing to update on that path. For a global install, upgrade in place:

# npm global install
npm update -g spec-init

# pipx
pipx upgrade spec-init

CLI version vs template versionspec-init --version reports the installed CLI (1.2.0). That is separate from the template version stamped into a scaffolded CLAUDE.md, which spec-init upgrade advances. Upgrading the CLI does not touch existing projects; run spec-init upgrade inside a project to pull a newer template.

Uninstall

# npm global install
npm uninstall -g spec-init

# pipx
pipx uninstall spec-init

# plain pip
pip uninstall spec-init

No native binariesNothing compiled is required at install time. The Node CLI is pure JS; the Python CLI is pure Python. macOS, Linux, and Windows (PowerShell + WSL) are all supported.

Setup & Channels

npx vs global vs pipx vs pip, per-channel troubleshooting, and version pinning.

Quickstart

Empty folder to first shipped feature, end to end.