Installer Internals

Installer internals

CoderClaw ships three installer scripts, served from coderclaw.ai.

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

Quick commands

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

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

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

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

```powershell iwr -useb https://coderclaw.ai/install.ps1 | iex ```

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

If install succeeds but `coderclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).

install.sh

Recommended for most interactive installs on macOS/Linux/WSL.

Flow (install.sh)

Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing. Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum). Installs Git if missing. - `npm` method (default): global npm install - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/coderclaw` - Runs `coderclaw 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 CoderClaw 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)

```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --no-onboard ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --install-method git ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --dry-run ```

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: `~/coderclaw`). 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`)

Variable	Description
`CODERCLAW_INSTALL_METHOD=git\|npm`	Install method
`CODERCLAW_VERSION=latest\|next\|<semver>`	npm version or dist-tag
`CODERCLAW_BETA=0\|1`	Use beta if available
`CODERCLAW_GIT_DIR=<path>`	Checkout directory
`CODERCLAW_GIT_UPDATE=0\|1`	Toggle git updates
`CODERCLAW_NO_PROMPT=1`	Disable prompts
`CODERCLAW_NO_ONBOARD=1`	Skip onboarding
`CODERCLAW_DRY_RUN=1`	Dry run mode
`CODERCLAW_VERBOSE=1`	Debug mode
`CODERCLAW_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 `~/.coderclaw`) and no system Node dependency.

Flow (install-cli.sh)

Downloads Node tarball (default `22.22.0`) to `/tools/node-v` and verifies SHA-256. If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS. Installs with npm using `--prefix `, then writes wrapper to `/bin/coderclaw`.

Examples (install-cli.sh)

```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install-cli.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install-cli.sh | bash -s -- --prefix /opt/coderclaw --version latest ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/coderclaw ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install-cli.sh | bash -s -- --onboard ```

Flag	Description
`--prefix <path>`	Install prefix (default: `~/.coderclaw`)
`--version <ver>`	CoderClaw version or dist-tag (default: `latest`)
`--node-version <ver>`	Node version (default: `22.22.0`)
`--json`	Emit NDJSON events
`--onboard`	Run `coderclaw 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`)

Variable	Description
`CODERCLAW_PREFIX=<path>`	Install prefix
`CODERCLAW_VERSION=<ver>`	CoderClaw version or dist-tag
`CODERCLAW_NODE_VERSION=<ver>`	Node version
`CODERCLAW_NO_ONBOARD=1`	Skip onboarding
`CODERCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`CODERCLAW_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)

Requires PowerShell 5+. If missing, attempts install via winget, then Chocolatey, then Scoop. - `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\coderclaw.cmd` Adds needed bin directory to user PATH when possible, then runs `coderclaw doctor --non-interactive` on upgrades and git installs (best effort).

Examples (install.ps1)

```powershell iwr -useb https://coderclaw.ai/install.ps1 | iex ``` ```powershell & ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -InstallMethod git ``` ```powershell & ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\coderclaw" ``` ```powershell & ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -DryRun ``` ```powershell # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ```

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

Variable	Description
`CODERCLAW_INSTALL_METHOD=git\|npm`	Install method
`CODERCLAW_GIT_DIR=<path>`	Checkout directory
`CODERCLAW_NO_ONBOARD=1`	Skip onboarding
`CODERCLAW_GIT_UPDATE=0`	Disable git pull
`CODERCLAW_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.

```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard ``` ```bash CODERCLAW_INSTALL_METHOD=git CODERCLAW_NO_PROMPT=1 \ curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/coderclaw ``` ```powershell & ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -NoOnboard ```

Troubleshooting

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. 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). The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:

```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash
```

Install Git for Windows, reopen PowerShell, rerun installer. Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell. `install.ps1` does not currently expose a `-Verbose` switch. Use PowerShell tracing for script-level diagnostics:

```powershell
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```

Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).