Install / Install overview
Installer internals
Genesis ships three installer scripts, served from genesis.pixelzx.com.
| Script | Platform | What it does |
|---|---|---|
install.sh |
macOS / Linux / WSL | Installs Node if needed, installs Genesis via npm (default) or git, and can run onboarding. |
install-cli.sh |
macOS / Linux / WSL | Installs Node + Genesis into a local prefix (~/.genesis) with npm or git checkout modes. No root required. |
install.ps1 |
Windows (PowerShell) | Installs Node if needed, installs Genesis via npm (default) or git, and can run onboarding. |
Quick commands
install.sh
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --help
install-cli.sh
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --help
install.ps1
iwr -useb https://genesis.pixelzx.com/install.ps1 | iex
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -Tag beta -NoOnboard -DryRun
If install succeeds but genesis is not found in a new terminal, see Node.js troubleshooting.
install.sh
Recommended for most interactive installs on macOS/Linux/WSL.
Flow (install.sh)
Detect OS
Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
Ensure Node.js 24 by default
Checks Node version and installs Node 24 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). Genesis still supports Node 22 LTS, currently 22.14+, for compatibility.
Ensure Git
Installs Git if missing.
Install Genesis
npmmethod (default): global npm installgitmethod: clone/update repo, install deps with pnpm, build, then install wrapper at~/.local/bin/genesis
Post-install tasks
- Refreshes a loaded gateway service best-effort (
genesis gateway install --force, then restart) - Runs
genesis doctor --non-interactiveon upgrades and git installs (best effort) - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass)
- Defaults
SHARP_IGNORE_GLOBAL_LIBVIPS=1
Source checkout detection
If run inside an Genesis checkout (package.json + pnpm-workspace.yaml), the script offers:
- use checkout (
git), or - use global install (
npm)
If no TTY is available and no install method is set, it defaults to npm and warns.
The script exits with code 2 for invalid method selection or invalid --install-method values.
Examples (install.sh)
Default
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash
Skip onboarding
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --no-onboard
Git install
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --install-method git
GitHub main via npm
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --version main
Dry run
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --dry-run
Flags reference
| Flag | Description |
|---|---|
--install-method npm|git |
Choose install method (default: npm). Alias: --method |
--npm |
Shortcut for npm method |
--git |
Shortcut for git method. Alias: --github |
--version <version|dist-tag|spec> |
npm version, dist-tag, or package spec (default: latest) |
--beta |
Use beta dist-tag if available, else fallback to latest |
--git-dir <path> |
Checkout directory (default: ~/genesis). Alias: --dir |
--no-git-update |
Skip git pull for existing checkout |
--no-prompt |
Disable prompts |
--no-onboard |
Skip onboarding |
--onboard |
Enable onboarding |
--dry-run |
Print actions without applying changes |
--verbose |
Enable debug output (set -x, npm notice-level logs) |
--help |
Show usage (-h) |
Environment variables reference
| Variable | Description |
|---|---|
GENESIS_INSTALL_METHOD=git|npm |
Install method |
GENESIS_VERSION=latest|next|main|<semver>|<spec> |
npm version, dist-tag, or package spec |
GENESIS_BETA=0|1 |
Use beta if available |
GENESIS_GIT_DIR=<path> |
Checkout directory |
GENESIS_GIT_UPDATE=0|1 |
Toggle git updates |
GENESIS_NO_PROMPT=1 |
Disable prompts |
GENESIS_NO_ONBOARD=1 |
Skip onboarding |
GENESIS_DRY_RUN=1 |
Dry run mode |
GENESIS_VERBOSE=1 |
Debug mode |
GENESIS_NPM_LOGLEVEL=error|warn|notice |
npm log level |
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 |
Control sharp/libvips behavior (default: 1) |
install-cli.sh
Designed for environments where you want everything under a local prefix
(default ~/.genesis) and no system Node dependency. Supports npm installs
by default, plus git-checkout installs under the same prefix flow.
Flow (install-cli.sh)
Install local Node runtime
Downloads a pinned supported Node LTS tarball (the version is embedded in the script and updated independently) to <prefix>/tools/node-v<version> and verifies SHA-256.
Ensure Git
If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
Install Genesis under prefix
npmmethod (default): installs under the prefix with npm, then writes wrapper to<prefix>/bin/genesisgitmethod: clones/updates a checkout (default~/genesis) and still writes the wrapper to<prefix>/bin/genesis
Refresh loaded gateway service
If a gateway service is already loaded from that same prefix, the script runs
genesis gateway install --force, then genesis gateway restart, and
probes gateway health best-effort.
Examples (install-cli.sh)
Default
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash
Custom prefix + version
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --prefix /opt/genesis --version latest
Git install
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --install-method git --git-dir ~/genesis
Automation JSON output
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --json --prefix /opt/genesis
Run onboarding
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --onboard
Flags reference
| Flag | Description |
|---|---|
--prefix <path> |
Install prefix (default: ~/.genesis) |
--install-method npm|git |
Choose install method (default: npm). Alias: --method |
--npm |
Shortcut for npm method |
--git, --github |
Shortcut for git method |
--git-dir <path> |
Git checkout directory (default: ~/genesis). Alias: --dir |
--version <ver> |
Genesis version or dist-tag (default: latest) |
--node-version <ver> |
Node version (default: 22.22.0) |
--json |
Emit NDJSON events |
--onboard |
Run genesis onboard after install |
--no-onboard |
Skip onboarding (default) |
--set-npm-prefix |
On Linux, force npm prefix to ~/.npm-global if current prefix is not writable |
--help |
Show usage (-h) |
Environment variables reference
| Variable | Description |
|---|---|
GENESIS_PREFIX=<path> |
Install prefix |
GENESIS_INSTALL_METHOD=git|npm |
Install method |
GENESIS_VERSION=<ver> |
Genesis version or dist-tag |
GENESIS_NODE_VERSION=<ver> |
Node version |
GENESIS_GIT_DIR=<path> |
Git checkout directory for git installs |
GENESIS_GIT_UPDATE=0|1 |
Toggle git updates for existing checkouts |
GENESIS_NO_ONBOARD=1 |
Skip onboarding |
GENESIS_NPM_LOGLEVEL=error|warn|notice |
npm log level |
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 |
Control sharp/libvips behavior (default: 1) |
install.ps1
Flow (install.ps1)
Ensure PowerShell + Windows environment
Requires PowerShell 5+.
Ensure Node.js 24 by default
If missing, attempts install via winget, then Chocolatey, then Scoop. Node 22 LTS, currently 22.14+, remains supported for compatibility.
Install Genesis
npmmethod (default): global npm install using selected-Taggitmethod: clone/update repo, install/build with pnpm, and install wrapper at%USERPROFILE%\.local\bin\genesis.cmd
Post-install tasks
- Adds needed bin directory to user PATH when possible
- Refreshes a loaded gateway service best-effort (
genesis gateway install --force, then restart) - Runs
genesis doctor --non-interactiveon upgrades and git installs (best effort)
Examples (install.ps1)
Default
iwr -useb https://genesis.pixelzx.com/install.ps1 | iex
Git install
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -InstallMethod git
GitHub main via npm
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -Tag main
Custom git directory
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -InstallMethod git -GitDir "C:\genesis"
Dry run
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -DryRun
Debug trace
# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
Flags reference
| Flag | Description |
|---|---|
-InstallMethod npm|git |
Install method (default: npm) |
-Tag <tag|version|spec> |
npm dist-tag, version, or package spec (default: latest) |
-GitDir <path> |
Checkout directory (default: %USERPROFILE%\genesis) |
-NoOnboard |
Skip onboarding |
-NoGitUpdate |
Skip git pull |
-DryRun |
Print actions only |
Environment variables reference
| Variable | Description |
|---|---|
GENESIS_INSTALL_METHOD=git|npm |
Install method |
GENESIS_GIT_DIR=<path> |
Checkout directory |
GENESIS_NO_ONBOARD=1 |
Skip onboarding |
GENESIS_GIT_UPDATE=0 |
Disable git pull |
GENESIS_DRY_RUN=1 |
Dry run mode |
If -InstallMethod git is used and Git is missing, the script exits and prints the Git for Windows link.
CI and automation
Use non-interactive flags/env vars for predictable runs.
install.sh (non-interactive npm)
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash -s -- --no-prompt --no-onboard
install.sh (non-interactive git)
GENESIS_INSTALL_METHOD=git GENESIS_NO_PROMPT=1 \
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash
install-cli.sh (JSON)
curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install-cli.sh | bash -s -- --json --prefix /opt/genesis
install.ps1 (skip onboarding)
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -NoOnboard
Troubleshooting
Why is Git required?
Git is required for git install method. For npm installs, Git is still checked/installed to avoid spawn git ENOENT failures when dependencies use git URLs.
Why does npm hit EACCES on Linux?
Some Linux setups point npm global prefix to root-owned paths. install.sh can switch prefix to ~/.npm-global and append PATH exports to shell rc files (when those files exist).
sharp/libvips issues
The scripts default SHARP_IGNORE_GLOBAL_LIBVIPS=1 to avoid sharp building against system libvips. To override:
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://genesis.pixelzx.com/install.sh | bash
Accordion
Install Git for Windows, reopen PowerShell, rerun installer.
Accordion
Run npm config get prefix and add that directory to your user PATH (no \bin suffix needed on Windows), then reopen PowerShell.
Windows: how to get verbose installer output
install.ps1 does not currently expose a -Verbose switch.
Use PowerShell tracing for script-level diagnostics:
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://genesis.pixelzx.com/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
genesis not found after install
Usually a PATH issue. See Node.js troubleshooting.