Installation

This page collects every supported way to get the native sideshow CLI onto your machine. After install, jump back to Getting Started for an end‑to‑end example.

Release assets use the naming pattern sideshow-<version>-<os>-<arch>.<ext> and publish a SHA256SUMS file you can verify before running anything.

Linux archives are statically linked (musl). macOS builds target the stock platform ABI.

Repo wrapper scripts (sideshowx)

Copy the Gradle-style wrappers from the repository root alongside your project (or vendor them once for your org).

Acquire from GitHub (main) — run the line for your OS in an empty project directory (change main in the URL to a tag or commit SHA to pin the launcher revision):

curl -fsSL https://raw.githubusercontent.com/sideshowdb/sideshowdb/main/sideshowx -o sideshowx && chmod +x sideshowx

macOS / Linux / Git Bash — use the curl command above.

Windows (PowerShell 5.1+ or pwsh; fetches sideshowx.ps1 and sideshowx.cmd):

$b='https://raw.githubusercontent.com/sideshowdb/sideshowdb/main'; iwr "$b/sideshowx.ps1" -OutFile sideshowx.ps1; iwr "$b/sideshowx.cmd" -OutFile sideshowx.cmd

The Unix script is Bash-based (#!/usr/bin/env bash). It downloads a release if needed, verifies SHA256SUMS, caches the binary, and execs the real CLI so stdout stays clean for piping.

Pin the CLI version (first match wins):

1. -V / --cli-version (both wrappers).
2. Environment SIDESHOWDB_CLI_VERSION (same accepted values).
3. Project pin file next to the script: .sideshowdb-version or sideshowdb.version (first non-empty line).
4. Otherwise latest (GitHub releases/latest JSON; Python 3 required on Unix to parse it).

Other useful switches: --install-only, --force / -f, --print-path, -- before CLI args, --verbose / -v, --quiet / -q, --trace (shell trace / Set-PSDebug). Wrapper diagnostics go to stderr; help and --print-path use stdout.

# Examples (Unix wrapper)
chmod +x ./sideshowx

./sideshowx --help
./sideshowx -V 0.1.2 --install-only --verbose

# Pin for everyone committing the wrapper
echo '0.1.2' > .sideshowdb-version

# One-off cache location
SIDESHOWDB_HOME=/srv/cache/sideshowdb ./sideshowx --print-path

# Windows examples
.\sideshowx.ps1 --help

$env:SIDESHOWDB_HOME = 'D:\caches\sideshowdb'
.\sideshowx.ps1 -V latest --install-only -v

Windows CLI artifacts: wrappers expect sideshow-<version>-windows-<arch>.zip files on GitHub Releases. The release workflow currently builds Linux and macOS CLI archives first; add a Windows publish job (or attach matching zips) before relying on sideshowx.ps1 in production.

Cache and install paths (SIDESHOWDB_HOME)

Downloaded binaries are stored under SIDESHOWDB_HOME. Override it when you want a shared cache or a non-default drive.

Normalized release version (no leading v) appears as <version> in paths.

Default locations (no override)

With SIDESHOWDB_HOME set

Same path shape; only the prefix changes—for example /var/cache/ssdb on Linux yields /var/cache/ssdb/cli/0.4.2/dist/sideshow, and D:\\caches\\ssdb on Windows yields D:\\caches\\ssdb\\cli\\0.4.2\\dist\\sideshow.exe.

Each version directory also keeps a .ready marker and a copy of SHA256SUMS.

Rare defaults (missing home dir)

If HOME and USERPROFILE are both unset, the Bash wrapper uses TMPDIR when set, otherwise /tmp, and appends /sideshowdb-wrapper to build the cache root. If USERPROFILE is empty on Windows, wrappers use a sideshowdb-wrapper directory under the temp folder (the usual literal is %TEMP%\sideshowdb-wrapper in cmd.exe).

Package / version managers (mise, etc.)

Tagged releases match the github backend naming convention:

mise use github:sideshowdb/sideshowdb@latest

# Pin a semver tag from GitHub Releases
mise use github:sideshowdb/sideshowdb@v0.1.0

Manual download from GitHub Releases

Grab the tarball or zip that matches your OS/arch from the Releases page :

• Linux/macOS archives are .tar.gz.
• Windows ships as .zip when published.

Unpack, verify against SHA256SUMS, then put sideshow (or sideshow.exe) somewhere on PATH (or invoke it by full path).

Build from source

Use this path when hacking on Zig/WASM/site sources.

git clone https://github.com/sideshowdb/sideshowdb.git
cd sideshowdb
zig build              # zig-out/bin/sideshow
zig build wasm        # zig-out/wasm/sideshowdb.wasm
zig build js:install  # repo-root Bun deps
zig build site:dev    # local docs/playground via SvelteKit

Related

• Getting Started — hands-on CLI walk-through after install.