Installation

Requirements

• Node.js 22 or later
• Git
• npm (included with Node.js)

Windows: Windows 10 (build 1803) or later. Git for Windows must be installed (not WSL). Windows Terminal or PowerShell recommended — cmd.exe has limited colour support.

---

1. Install Node.js

If you already have Node.js 22 or later installed, skip this step.

macOS

The recommended approach is nvm (Node Version Manager):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Restart your terminal, then:
nvm install 22
nvm use 22
node --version   # should show v22.x.x

Alternatively, download the installer directly from nodejs.org.

Linux

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Restart your terminal, then:
nvm install 22
nvm use 22
node --version

Or use your distribution's package manager — but verify the version is 22 or later. Many distros ship an older Node.js by default.

Windows

Download and run the Node.js 22 LTS installer from nodejs.org. The installer includes npm.

Verify in PowerShell or Command Prompt:

node --version   # should show v22.x.x
npm --version

PowerShell execution policy

If npm scripts fail with a policy error, run this once in an elevated PowerShell window:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

---

2. Install scd

npm install -g @activemind/scd
scd --version   # verify

Development install

If you have cloned the repository and want to run from source:

cd scd
npm install
npm link

To remove the dev link: npm unlink -g @activemind/scd

---

3. Install git hooks

scd uses git hooks to scan your code automatically — secrets scanning before commits, full OWASP scan before pushes. The hooks are installed globally on your machine, so every git repository you work in is protected automatically.

scd install

Run this once per machine. It sets up the hooks in ~/.scd/hooks/ and configures git to use them globally.

Verify the setup:

scd doctor

To remove the hooks from a machine:

scd uninstall

This removes the global hooks and the git configuration, but preserves your scan history and exceptions in ~/.scd/.

---

4. Register a project

Once the hooks are installed, register each project you want to work with:

cd /path/to/your/project
scd init
scd scan     # run your first scan

scd init creates a per-project config in ~/.scd/repos/ — nothing is written to your repository.

scd install vs scd init

	scd install	scd init
Scope	Machine-wide	Per project
Run	Once per machine	Once per project
What it does	Installs git hooks for all repos	Registers the project, creates config
Touches the repo	No	No

scd install is the global step — without it, hooks do not run. scd init is the per-project step. scd doctor will tell you clearly if either step has been missed.

---

Where scd stores data

All scan history, configuration, and reports are stored outside your repositories:

~/.scd/                          # macOS / Linux
%USERPROFILE%\.scd\              # Windows

  config                         ← central URL, token, timeouts
  repos/
    {repoId}/
      meta.json                  ← repo identity, last scan, timestamps
      config.yml                 ← exceptions and rule configuration
      audit.log                  ← full scan history (append-only)
      last-scan.json             ← latest scan cache
      scans/                     ← one JSON per scan (never overwritten)
      reports/                   ← generated HTML/MD/JSON reports

Uninstalling scd does not remove store data — your scan history is preserved.

---

Troubleshooting

scd not found after install

macOS / Linux: Check where npm puts global binaries:

npm config get prefix

Add the bin subdirectory to your PATH if missing:

# Add to ~/.zshrc or ~/.bash_profile:
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.zshrc

If you use nvm, run nvm use 22 (or nvm alias default 22 to make it permanent) and try again.

Windows: npm may not have added its global bin directory to PATH. Run this in PowerShell, then open a new terminal:

[System.Environment]::SetEnvironmentVariable(
  "PATH",
  $env:PATH + ";$env:APPDATA\npm",
  [System.EnvironmentVariableTarget]::User
)

Permission error on npm install -g (Linux)

Do not use sudo npm install -g. Configure npm to use a user-local prefix instead:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.bashrc too
npm install -g @activemind/scd

scd points to wrong location after switching Node.js versions

Clear your shell's command cache:

hash -r
which scd

If still missing, reinstall for the current Node.js version:

nvm use 22
npm install -g @activemind/scd