Troubleshooting — Installation

sdtk: command not found after install

npm's global bin directory isn't on your PATH.

npm prefix -g          # where npm installs globals
npm bin -g 2>/dev/null || echo "$(npm prefix -g)/bin"

Add that directory to your PATH (shell profile on macOS/Linux; Environment Variables on Windows), open a new terminal, and retry sdtk --version.

If you use a Node version manager (nvm, fnm, volta), make sure the shell you're testing in has the same Node active as the one you installed with.

Node version errors

SDTK requires Node.js ≥ 18.13.

node --version

Upgrade Node (or switch versions with your version manager) and reinstall sdtk-kit if the CLIs were installed under an old Node.

PowerShell not found (exit code 2)

The spec/ops/code runtime assets need PowerShell — Windows PowerShell 5.1+ or pwsh (PowerShell 7) on macOS/Linux.

pwsh --version    # macOS/Linux

Install PowerShell 7 from Microsoft's releases, then re-run the failing command. sdtk-spec exits with code 2 for exactly this dependency error.

sdtk-spec atlas build fails: Python missing

sdtk-spec atlas needs Python 3.8+ on PATH. Two fixes:

• Install Python 3.8+ (python3 --version to check), or
• Use the wiki atlas instead — sdtk-wiki atlas build is native Node and needs no Python.

Permission errors on npm install -g

Don't sudo npm install. Either use a Node version manager (nvm/fnm — recommended), or point npm's prefix at a user-writable directory:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

sdtk init fails partway through the kits

sdtk init chains six kit setups and stops at the first failure by default. To see detail and continue past a failing kit:

sdtk init --runtime claude --force --keep-going --verbose

Then fix the failing kit individually (its own init / runtime install) and re-run.

Versions look stale after updating

sdtk update --check-only   # what's outdated?
sdtk update                # update kits
sdtk init --runtime claude --force   # refresh each project's runtime assets

Installed skills are per-project (or per-user for Codex default scope) — updating the npm packages does not refresh them; the --force re-init does.

Pro command exits with an entitlement error

sdtk-spec project … and sdtk-wiki ask fail closed without a Pro license:

sdtk activate --license SDTK-XXXX-YYYY
sdtk-spec entitlement status
sdtk-spec entitlement sync    # if status looks stale after activating

Still stuck?

Run the built-in diagnostics and open an issue with their output:

sdtk-code doctor
sdtk-spec runtime status

Issues: github.com/codexsdtk/sdtk-toolkit