Installation

Prerequisites, platforms, and troubleshooting.

Prerequisites

Node.js 20+ — check with node --version
npm — ships with Node.js. Check with npm --version

Node version managers

We recommend using nvm or fnm to manage your Node.js installation. This avoids permission issues and makes upgrading easy.

Install

Install Franklin globally via npm:

bash

npm install -g @blockrun/franklin

This adds the franklin command to your PATH.

Verify

Confirm the installation succeeded:

bash

franklin --version

You should see the version number (e.g., 0.1.0). If you see "command not found", check the troubleshooting section below.

Platforms

macOS

Fully supported on Apple Silicon (M1/M2/M3/M4) and Intel Macs. Works with the default Terminal, iTerm2, Warp, or any terminal emulator.

Linux

Fully supported on x86_64 and ARM64 distributions. Tested on Ubuntu 22.04+, Debian 12+, Fedora 38+, and Arch Linux.

Windows (WSL2)

Franklin runs inside WSL2 (Windows Subsystem for Linux). Install Node.js inside your WSL2 distribution, not on the Windows side.

bash

# Inside WSL2
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
npm install -g @blockrun/franklin

Windows native not supported

Running Franklin directly on Windows (outside WSL2) is not supported. File system operations and shell integration require a Unix-like environment.

Troubleshooting

EACCES permission error

If you see EACCES: permission denied when installing globally, do not use sudo. Instead, fix your npm prefix:

bash

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @blockrun/franklin

Or, better yet, switch to a Node version manager like nvm which handles this automatically.

Command not found after install

If franklin --versionreturns "command not found", the npm global bin directory is not in your PATH. Find it and add it:

bash

# Find where npm installs global binaries
npm config get prefix

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$(npm config get prefix)/bin:$PATH"

Node.js version too old

Franklin requires Node.js 20 or later. If you're on an older version, upgrade with your version manager:

bash

nvm install 22
nvm use 22