Get started

Installation

Install Pi-Bolt with one command. The installer downloads the release for your system, checks its checksum and signature, and puts pi-bolt on your PATH. It does not change your Pi installation.

Requirements#

macOS 13 or later on Apple silicon. There is no build for Intel Macs.
Linux on x86-64 with glibc 2.17 or later. musl distributions such as Alpine are not supported.
Windows 10 (1809) or later, or Windows 11, on x64.

Pi-Bolt does not need Node.js, Bun or Pi. npm is only needed if you install with npm.

Install#

$ curl -fsSL https://pi-bolt.opensec.in/install.sh | sh

$ curl -fsSL https://pi-bolt.opensec.in/install.sh | sh

irm https://pi-bolt.opensec.in/install.ps1 | iex

powershell -c "irm https://pi-bolt.opensec.in/install.ps1 | iex"

On an older Windows 10 whose PowerShell only offers TLS 1.0, run these two lines in PowerShell instead:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072
irm https://pi-bolt.opensec.in/install.ps1 | iex

$ npm install -g --allow-scripts=pi-bolt pi-bolt

--allow-scripts=pi-bolt lets npm run the package's install script, which puts the Windows executable in place. On macOS and Linux, the first run of pi-bolt downloads the release that matches the package's version.

The installer:

Downloads the release for your platform and CPU, from the npm registry's CDN with GitHub as a fallback.
Checks it against the release's SHA256SUMS, and checks the Ed25519 signature of SHA256SUMS against Pi-Bolt's release key. A download that does not verify is not installed. (On macOS and Linux, the signature check needs OpenSSL 3 or an earlier Pi-Bolt; without either, the installer checks the checksums only and says so.)
Installs it to ~/.pi-bolt and links pi-bolt into ~/.local/bin. On Windows, it installs to %USERPROFILE%\.pi-bolt and asks before adding it to your PATH. It needs no administrator rights.
Offers two optional extensions by OpenSec, and installs them only if you say yes. See OpenSec extensions.

Then run pi-bolt in a project. Continue with the Quickstart.

pi-bolt: command not found? ~/.local/bin is not on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new terminal.

Builds#

Each platform has a default build and a JIT build. The installer picks the default build for your CPU. To choose another, set PIBOLT_VARIANT. See Choose a build for when the JIT build is the better choice.

Platform	`PIBOLT_VARIANT`	Build
macOS	`arm64`	Default
macOS	`arm64-jit`	JIT on, for heavy run-time extensions
Linux	`x64`	Default, for CPUs with AVX2 (Intel Haswell, AMD Zen and later)
Linux	`x64-baseline`	Any x86-64 CPU. Picked automatically when the CPU has no AVX2.
Linux	`x64-jit`	JIT on
Windows	`x64`	Default. Runs compiled code on CPUs with AVX2, and bytecode on others.
Windows	`x64-jit`	JIT on

$ curl -fsSL https://pi-bolt.opensec.in/install.sh | PIBOLT_VARIANT=arm64-jit sh

$ curl -fsSL https://pi-bolt.opensec.in/install.sh | PIBOLT_VARIANT=x64-jit sh

$env:PIBOLT_VARIANT = "x64-jit"
powershell -c "irm https://pi-bolt.opensec.in/install.ps1 | iex"

# ~/.zshrc or ~/.bashrc; use x64-jit on Linux
export PIBOLT_VARIANT=arm64-jit

On macOS and Linux, the npm package reads PIBOLT_VARIANT every time it runs, so keep it set in your shell profile. If it is unset later, the next run switches back to the default build.

On Windows, the npm package picks the build when it is installed or updated. Set the variable first, then install:

$env:PIBOLT_VARIANT = "x64-jit"
npm install -g --allow-scripts=pi-bolt pi-bolt

To change builds later, set or clear PIBOLT_VARIANT and run the install again.

pi-bolt update keeps the build you chose.

Verify the installation#

$ pi-bolt --version
1.1.0 (Pi-Bolt 0.8.0, darwin-arm64, JIT off)

The first number is the Pi release this build is made from. The rest is the Pi-Bolt release, the platform, and whether the JIT is on. To check that Pi runs its compiled code, see Check the compiled code.

Update#

$ pi-bolt update          # Pi-Bolt only
$ pi-bolt update --all    # Pi-Bolt and your extensions

With npm, run npm update -g pi-bolt; the next run downloads the new release. Running the installer again also updates.

Uninstall#

Run the installer again and choose uninstall. It removes the Pi-Bolt builds from ~/.pi-bolt and the pi-bolt link. With npm, run npm uninstall -g pi-bolt, then delete ~/.pi-bolt/npm, where the npm package keeps the release it downloaded.

Your Pi configuration in ~/.pi/agent belongs to Pi and is not removed.

Manual download#

Download a build from the latest release, check it against SHA256SUMS, unpack it, and run ./pi (on Windows, pi-bolt.exe). Keep the unpacked folder together: the executable uses the files around it for themes, HTML export and image tools. Link to the executable rather than copying it.

Download	For
`pi-bolt-darwin-arm64.tar.xz`	macOS on Apple silicon
`pi-bolt-linux-x64.tar.xz`	Linux, CPUs with AVX2
`pi-bolt-linux-x64-baseline.tar.xz`	Linux, any x86-64 CPU
`pi-bolt-win32-x64.zip`	Windows x64

The JIT builds are pi-bolt-darwin-arm64-jit.tar.xz, pi-bolt-linux-x64-jit.tar.xz and pi-bolt-win32-x64-jit.zip. To check a download:

$ sha256sum -c --ignore-missing SHA256SUMS

macOS: downloaded with a browser A browser marks downloads as quarantined, and macOS then refuses Pi-Bolt's ad-hoc signed executable (zsh: killed, or "cannot verify the developer"). Install with the installer or npm, which do not quarantine, or remove the attribute from the unpacked folder: xattr -dr com.apple.quarantine pi-bolt-darwin-arm64.

Installer options#

Set these in the environment of the installer: curl ... | NAME=value sh on macOS and Linux, $env:NAME = "value" before the command on Windows.

Variable	Effect
`PIBOLT_VARIANT`	The build to install (see Builds).
`PIBOLT_VERSION`	A release tag such as `bolt-v0.8.0`. Default: the latest release.
`PIBOLT_INSTALL`	Where to install. Default: `~/.pi-bolt` (Windows: `%USERPROFILE%\.pi-bolt`).
`PIBOLT_BIN_DIR`	macOS and Linux: where to link `pi-bolt`. Default: `~/.local/bin`.
`PIBOLT_NO_PATH=1`	Windows: do not add Pi-Bolt to your PATH.
`PIBOLT_YES=1`	Do not ask: take the default action, install no extensions, and do not offer to start Pi-Bolt.
`PIBOLT_EXTENSIONS`	`yes` or `no`: whether to install OpenSec's optional extensions without asking.
`PIBOLT_SOURCE`	Where to download the executable from: `auto` (npm, then GitHub; the default), `npm` or `github`. Checksums and signatures always come from the GitHub release.
`PIBOLT_NPM_REGISTRY`	An npm registry or mirror. Default: `https://registry.npmjs.org`.
`PIBOLT_CONNECTIONS`	macOS and Linux: connections to download over at once. Default: 4.