Installer internals

FluffBuzz ships three installer scripts, served from fluffbuzz.com.

Script	Platform	What it does
`install.sh`	macOS / Linux / WSL	Installs Node if needed, installs FluffBuzz via npm (default) or git, and can run onboarding.
`install-cli.sh`	macOS / Linux / WSL	Installs Node + FluffBuzz into a local prefix (`~/.fluffbuzz`). No root required.
`install.ps1`	Windows (PowerShell)	Installs Node if needed, installs FluffBuzz via npm (default) or git, and can run onboarding.

Quick commands

install.sh
install-cli.sh
install.ps1

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash -s -- --help

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash -s -- --help

iwr -useb https://fluffbuzz.com/install.ps1 | iex

& ([scriptblock]::Create((iwr -useb https://fluffbuzz.com/install.ps1))) -Tag beta -NoOnboard -DryRun

If install succeeds but fluffbuzz 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 22+

Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum).

Ensure Git

Installs Git if missing.

Install FluffBuzz

npm method (default): global npm install
git method: clone/update repo, install deps with pnpm, build, then install wrapper at ~/.local/bin/fluffbuzz

Post-install tasks

Runs fluffbuzz doctor --non-interactive on 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 FluffBuzz 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
Skip onboarding
Git install
Dry run

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash -s -- --no-onboard

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash -s -- --install-method git

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.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>`	npm version or dist-tag (default: `latest`)
`--beta`	Use beta dist-tag if available, else fallback to `latest`
`--git-dir <path>`	Checkout directory (default: `~/fluffbuzz`). 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
`FLUFFBUZZ_INSTALL_METHOD=git\|npm`	Install method
`FLUFFBUZZ_VERSION=latest\|next\|<semver>`	npm version or dist-tag
`FLUFFBUZZ_BETA=0\|1`	Use beta if available
`FLUFFBUZZ_GIT_DIR=<path>`	Checkout directory
`FLUFFBUZZ_GIT_UPDATE=0\|1`	Toggle git updates
`FLUFFBUZZ_NO_PROMPT=1`	Disable prompts
`FLUFFBUZZ_NO_ONBOARD=1`	Skip onboarding
`FLUFFBUZZ_DRY_RUN=1`	Dry run mode
`FLUFFBUZZ_VERBOSE=1`	Debug mode
`FLUFFBUZZ_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 ~/.fluffbuzz) and no system Node dependency.

Flow (install-cli.sh)

Install local Node runtime

Downloads Node tarball (default 22.22.0) 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 FluffBuzz under prefix

Installs with npm using --prefix <prefix>, then writes wrapper to <prefix>/bin/fluffbuzz.

Examples (install-cli.sh)

Default
Custom prefix + version
Automation JSON output
Run onboarding

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash -s -- --prefix /opt/fluffbuzz --version latest

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash -s -- --json --prefix /opt/fluffbuzz

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash -s -- --onboard

Flags reference

Flag	Description
`--prefix <path>`	Install prefix (default: `~/.fluffbuzz`)
`--version <ver>`	FluffBuzz version or dist-tag (default: `latest`)
`--node-version <ver>`	Node version (default: `22.22.0`)
`--json`	Emit NDJSON events
`--onboard`	Run `fluffbuzz 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
`FLUFFBUZZ_PREFIX=<path>`	Install prefix
`FLUFFBUZZ_VERSION=<ver>`	FluffBuzz version or dist-tag
`FLUFFBUZZ_NODE_VERSION=<ver>`	Node version
`FLUFFBUZZ_NO_ONBOARD=1`	Skip onboarding
`FLUFFBUZZ_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`FLUFFBUZZ_GIT_DIR=<path>`	Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout)
`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 22+

If missing, attempts install via winget, then Chocolatey, then Scoop.

Install FluffBuzz

npm method (default): global npm install using selected -Tag
git method: clone/update repo, install/build with pnpm, and install wrapper at %USERPROFILE%\.local\bin\fluffbuzz.cmd

Post-install tasks

Adds needed bin directory to user PATH when possible, then runs fluffbuzz doctor --non-interactive on upgrades and git installs (best effort).

Examples (install.ps1)

Default
Git install
Custom git directory
Dry run
Debug trace

iwr -useb https://fluffbuzz.com/install.ps1 | iex

& ([scriptblock]::Create((iwr -useb https://fluffbuzz.com/install.ps1))) -InstallMethod git

& ([scriptblock]::Create((iwr -useb https://fluffbuzz.com/install.ps1))) -InstallMethod git -GitDir "C:\fluffbuzz"

& ([scriptblock]::Create((iwr -useb https://fluffbuzz.com/install.ps1))) -DryRun

# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://fluffbuzz.com/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

Flags reference

Flag	Description
`-InstallMethod npm\|git`	Install method (default: `npm`)
`-Tag <tag>`	npm dist-tag (default: `latest`)
`-GitDir <path>`	Checkout directory (default: `%USERPROFILE%\fluffbuzz`)
`-NoOnboard`	Skip onboarding
`-NoGitUpdate`	Skip `git pull`
`-DryRun`	Print actions only

Environment variables reference

Variable	Description
`FLUFFBUZZ_INSTALL_METHOD=git\|npm`	Install method
`FLUFFBUZZ_GIT_DIR=<path>`	Checkout directory
`FLUFFBUZZ_NO_ONBOARD=1`	Skip onboarding
`FLUFFBUZZ_GIT_UPDATE=0`	Disable git pull
`FLUFFBUZZ_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)
install.sh (non-interactive git)
install-cli.sh (JSON)
install.ps1 (skip onboarding)

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash -s -- --no-prompt --no-onboard

FLUFFBUZZ_INSTALL_METHOD=git FLUFFBUZZ_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://fluffbuzz.com/install-cli.sh | bash -s -- --json --prefix /opt/fluffbuzz

& ([scriptblock]::Create((iwr -useb https://fluffbuzz.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://fluffbuzz.com/install.sh | bash

Windows: "npm error spawn git / ENOENT"

Install Git for Windows, reopen PowerShell, rerun installer.

Windows: "fluffbuzz is not recognized"

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://fluffbuzz.com/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

fluffbuzz not found after install

Usually a PATH issue. See Node.js troubleshooting.

Install overview

Other install methods

Maintenance

Hosting and deployment

Advanced

Installer Internals

Installer internals

Quick commands

install.sh

Flow (install.sh)

Source checkout detection

Examples (install.sh)

install-cli.sh

Flow (install-cli.sh)

Examples (install-cli.sh)

install.ps1

Flow (install.ps1)

Examples (install.ps1)

CI and automation

Troubleshooting

Install overview

Other install methods

Maintenance

Hosting and deployment

Advanced

​Installer internals

​Quick commands

​install.sh

​Flow (install.sh)

​Source checkout detection

​Examples (install.sh)

​install-cli.sh

​Flow (install-cli.sh)

​Examples (install-cli.sh)

​install.ps1

​Flow (install.ps1)

​Examples (install.ps1)

​CI and automation

​Troubleshooting

Installer internals

Quick commands

install.sh

Flow (install.sh)

Source checkout detection

Examples (install.sh)

install-cli.sh

Flow (install-cli.sh)

Examples (install-cli.sh)

install.ps1

Flow (install.ps1)

Examples (install.ps1)

CI and automation

Troubleshooting