Node.js

OpenSoul requires Node 22 or newer. The installer script will detect and install Node automatically — this page is for when you want to set up Node yourself and make sure everything is wired up correctly (versions, PATH, global installs).

Check your version

node -v

If this prints v22.x.x or higher, you're good. If Node isn't installed or the version is too old, pick an install method below.

Install Node

macOS

Homebrew (recommended):

brew install node

Or download the macOS installer from nodejs.org.

Linux

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / RHEL:

sudo dnf install nodejs

Or use a version manager (see below).

Windows

winget (recommended):

winget install OpenJS.NodeJS.LTS

Chocolatey:

choco install nodejs-lts

Or download the Windows installer from nodejs.org.

Using a version manager (nvm, fnm, mise, asdf)

Version managers let you switch between Node versions easily. Popular options:

• fnm — fast, cross-platform
• nvm — widely used on macOS/Linux
• mise — polyglot (Node, Python, Ruby, etc.)

Example with fnm:

fnm install 22
fnm use 22

Warning Make sure your version manager is initialized in your shell startup file (~/.zshrc or ~/.bashrc). If it isn't, opensoul may not be found in new terminal sessions because the PATH won't include Node's bin directory.

Troubleshooting

opensoul: command not found

This almost always means npm's global bin directory isn't on your PATH.

1. Find your global npm prefix

   npm prefix -g

2. Check if it's on your PATH

   echo "$PATH"

   Look for <npm-prefix>/bin (macOS/Linux) or <npm-prefix> (Windows) in the output.

3. Add it to your shell startup file

   macOS / Linux

   Add to ~/.zshrc or ~/.bashrc:

   export PATH="$(npm prefix -g)/bin:$PATH"

   Then open a new terminal (or run rehash in zsh / hash -r in bash).

   Windows

   Add the output of npm prefix -g to your system PATH via Settings → System → Environment Variables.

Permission errors on npm install -g (Linux)

If you see EACCES errors, switch npm's global prefix to a user-writable directory:

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

Add the export PATH=... line to your ~/.bashrc or ~/.zshrc to make it permanent.