Source: https://docs.datzi.ai/install/installer

Installer internals

Datzi ships three installer scripts, served from datzi.ai.

Script	Platform	What it does
`install.sh`	macOS / Linux / WSL	Installs Node if needed, installs Datzi via npm (default) or git, and can run onboarding.
`install-cli.sh`	macOS / Linux / WSL	Installs Node + Datzi into a local prefix (`~/.datzi`). No root required.
`install.ps1`	Windows (PowerShell)	Installs Node if needed, installs Datzi 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://datzi.ai/install.sh | bash

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

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

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

iwr -useb https://datzi.ai/install.ps1 | iex

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

If install succeeds but datzi 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 Datzi

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

Post-install tasks

Runs datzi 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 Datzi 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

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

curl -fsSL --proto --tlsv1.2 https://datzi.ai/install.sh |

bash -s -- --no-onboard ```
</Tab>

<Tab title="Git install">
```bash curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh |
bash -s -- --install-method git ```
</Tab>

<Tab title="Dry run">
  ```bash
  curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/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: `~/datzi`). 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
`DATZI_INSTALL_METHOD=git\|npm`	Install method
`DATZI_VERSION=latest\|next\|<semver>`	npm version or dist-tag
`DATZI_BETA=0\|1`	Use beta if available
`DATZI_GIT_DIR=<path>`	Checkout directory
`DATZI_GIT_UPDATE=0\|1`	Toggle git updates
`DATZI_NO_PROMPT=1`	Disable prompts
`DATZI_NO_ONBOARD=1`	Skip onboarding
`DATZI_DRY_RUN=1`	Dry run mode
`DATZI_VERBOSE=1`	Debug mode
`DATZI_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 ~/.datzi) 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 Datzi under prefix

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

Examples (install-cli.sh)

Default
Custom prefix + version

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

curl -fsSL --proto --tlsv1.2 https://datzi.ai/install-cli.sh

| bash -s -- --prefix /opt/datzi --version latest ```
</Tab>

<Tab title="Automation JSON output">
```bash curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh
| bash -s -- --json --prefix /opt/datzi ```
</Tab>

<Tab title="Run onboarding">
  ```bash
  curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh | bash -s -- --onboard

Flags reference

Flag	Description
`--prefix <path>`	Install prefix (default: `~/.datzi`)
`--version <ver>`	Datzi version or dist-tag (default: `latest`)
`--node-version <ver>`	Node version (default: `22.22.0`)
`--json`	Emit NDJSON events
`--onboard`	Run `datzi 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
`DATZI_PREFIX=<path>`	Install prefix
`DATZI_VERSION=<ver>`	Datzi version or dist-tag
`DATZI_NODE_VERSION=<ver>`	Node version
`DATZI_NO_ONBOARD=1`	Skip onboarding
`DATZI_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`DATZI_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 Datzi

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\datzi.cmd

Post-install tasks

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

Examples (install.ps1)

Default
Git install

iwr -useb https://datzi.ai/install.ps1 | iex

& ([scriptblock]::Create((iwr -useb

https://datzi.ai/install.ps1))) -InstallMethod git ```
</Tab>

<Tab title="Custom git directory">
```powershell & ([scriptblock]::Create((iwr -useb
https://datzi.ai/install.ps1))) -InstallMethod git -GitDir "C:\datzi" ```
</Tab>

<Tab title="Dry run">
```powershell & ([scriptblock]::Create((iwr -useb
https://datzi.ai/install.ps1))) -DryRun ```
</Tab>

<Tab title="Debug trace">
  ```powershell
  # install.ps1 has no dedicated -Verbose flag yet.
  Set-PSDebug -Trace 1
  & ([scriptblock]::Create((iwr -useb https://datzi.ai/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%\datzi`)
`-NoOnboard`	Skip onboarding
`-NoGitUpdate`	Skip `git pull`
`-DryRun`	Print actions only

Environment variables reference

Variable	Description
`DATZI_INSTALL_METHOD=git\|npm`	Install method
`DATZI_GIT_DIR=<path>`	Checkout directory
`DATZI_NO_ONBOARD=1`	Skip onboarding
`DATZI_GIT_UPDATE=0`	Disable git pull
`DATZI_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)

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

DATZI_INSTALL_METHOD=git DATZI_NO_PROMPT=1 \ curl -fsSL --proto

'=https' --tlsv1.2 https://datzi.ai/install.sh | bash ```
</Tab>

<Tab title="install-cli.sh (JSON)">
```bash curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh
| bash -s -- --json --prefix /opt/datzi ```
</Tab>

<Tab title="install.ps1 (skip onboarding)">
  ```powershell
  & ([scriptblock]::Create((iwr -useb https://datzi.ai/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://datzi.ai/install.sh | bash

Windows: "npm error spawn git / ENOENT"

Install Git for Windows, reopen PowerShell, rerun installer.

Windows: "datzi is not recognized"

Run npm config get prefix, append \bin, add that directory to user PATH, 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://datzi.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

datzi not found after install

Usually a PATH issue. See Node.js troubleshooting.

Getting Started

Channels

Gateway

Automation

Concepts

Tools

Platforms

Install

Nodes

Reference

Help

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

Getting Started

Channels

Gateway

Automation

Concepts

Tools

Platforms

Install

Nodes

Reference

Help

​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