> ## Documentation Index
> Fetch the complete documentation index at: https://ancplua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installer internals

# Installer internals

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

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

## Quick commands

<Tabs>
  <Tab title="install.sh">
    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | bash
    ```

    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install-cli.sh">
    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh | bash
    ```

    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install.ps1">
    ```powershell theme={null}
    iwr -useb https://datzi.ai/install.ps1 | iex
    ```

    ```powershell theme={null}
    & ([scriptblock]::Create((iwr -useb https://datzi.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
    ```
  </Tab>
</Tabs>

<Note>
  If install succeeds but `datzi` is not found in a new terminal, see [Node.js
  troubleshooting](/datzi/install/index).
</Note>

***

## install.sh

<Tip>Recommended for most interactive installs on macOS/Linux/WSL.</Tip>

### Flow (install.sh)

<Steps>
  <Step title="Detect OS">
    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
  </Step>

  <Step title="Ensure Node.js 22+">
    Checks Node version and installs Node 22 if needed (Homebrew on macOS,
    NodeSource setup scripts on Linux apt/dnf/yum).
  </Step>

  <Step title="Ensure Git">Installs Git if missing.</Step>

  <Step title="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`
  </Step>

  <Step title="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`
  </Step>
</Steps>

### 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)

<Tabs>
  <Tab title="Default">
    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Skip onboarding">
    ````bash curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | theme={null}
    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
    ````
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="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`)                                         |
  </Accordion>

  <Accordion title="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`) |
  </Accordion>
</AccordionGroup>

***

## install-cli.sh

<Info>
  Designed for environments where you want everything under a local prefix
  (default `~/.datzi`) and no system Node dependency.
</Info>

### Flow (install-cli.sh)

<Steps>
  <Step title="Install local Node runtime">
    Downloads Node tarball (default `22.22.0`) to `<prefix>/tools/node-v<version>` and verifies SHA-256.
  </Step>

  <Step title="Ensure Git">
    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on
    macOS.
  </Step>

  <Step title="Install Datzi under prefix">
    Installs with npm using `--prefix <prefix>`, then writes wrapper to `<prefix>/bin/datzi`.
  </Step>
</Steps>

### Examples (install-cli.sh)

<Tabs>
  <Tab title="Default">
    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh | bash
    ```
  </Tab>

  <Tab title="Custom prefix + version">
    ````bash curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install-cli.sh theme={null}
    | 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
    ````
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="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`)                                                               |
  </Accordion>

  <Accordion title="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`)                                     |
  </Accordion>
</AccordionGroup>

***

## install.ps1

### Flow (install.ps1)

<Steps>
  <Step title="Ensure PowerShell + Windows environment">
    Requires PowerShell 5+.
  </Step>

  <Step title="Ensure Node.js 22+">
    If missing, attempts install via winget, then Chocolatey, then Scoop.
  </Step>

  <Step title="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`
  </Step>

  <Step title="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).
  </Step>
</Steps>

### Examples (install.ps1)

<Tabs>
  <Tab title="Default">
    ```powershell theme={null}
    iwr -useb https://datzi.ai/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Git install">
    ````powershell & ([scriptblock]::Create((iwr -useb theme={null}
    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
    ````
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="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                                  |
  </Accordion>

  <Accordion title="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       |
  </Accordion>
</AccordionGroup>

<Note>
  If `-InstallMethod git` is used and Git is missing, the script exits and
  prints the Git for Windows link.
</Note>

***

## CI and automation

Use non-interactive flags/env vars for predictable runs.

<Tabs>
  <Tab title="install.sh (non-interactive npm)">
    ```bash theme={null}
    curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | bash -s -- --no-prompt --no-onboard
    ```
  </Tab>

  <Tab title="install.sh (non-interactive git)">
    ````bash DATZI_INSTALL_METHOD=git DATZI_NO_PROMPT=1 \ curl -fsSL --proto theme={null}
    '=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
    ````
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="sharp/libvips issues">
    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:

    ```bash theme={null}
    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://datzi.ai/install.sh | bash
    ```
  </Accordion>

  <Accordion title="Windows: &#x22;npm error spawn git / ENOENT&#x22;">
    Install Git for Windows, reopen PowerShell, rerun installer.
  </Accordion>

  <Accordion title="Windows: &#x22;datzi is not recognized&#x22;">
    Run `npm config get prefix`, append `\bin`, add that directory to user PATH,
    then reopen PowerShell.
  </Accordion>

  <Accordion title="Windows: how to get verbose installer output">
    `install.ps1` does not currently expose a `-Verbose` switch.
    Use PowerShell tracing for script-level diagnostics:

    ```powershell theme={null}
    Set-PSDebug -Trace 1
    & ([scriptblock]::Create((iwr -useb https://datzi.ai/install.ps1))) -NoOnboard
    Set-PSDebug -Trace 0
    ```
  </Accordion>

  <Accordion title="datzi not found after install">
    Usually a PATH issue. See [Node.js troubleshooting](/datzi/install/index).
  </Accordion>
</AccordionGroup>