URL: /install

---
title: "Install"
icon: "download"
description: "Every way to install the squirrelscan CLI, what the installer does to your machine, and how to verify, update or remove it."
---

<Tip>Rather have your coding agent do the whole setup? See [Agent setup](/agent-setup). New here? The [Quickstart](/quickstart) gets you to a first audit in two minutes.</Tip>

<Tabs>
  <Tab title="macOS / Linux">
    ```bash
    curl -fsSL --connect-timeout 10 --max-time 120 https://install.squirrelscan.com | bash
    ```
  </Tab>
  <Tab title="Windows">
    ```powershell
    iwr -useb https://install.squirrelscan.com/install.ps1 | iex
    ```
  </Tab>
  <Tab title="Homebrew (macOS)">
    ```bash
    brew install --cask squirrelscan/tap/squirrel
    ```
    The cask is macOS only. `brew upgrade` does nothing for the CLI: update it with `squirrel self update`. See [Homebrew](#homebrew) below for how this install updates and uninstalls.
  </Tab>
  <Tab title="npm">
    ```bash
    npm install -g squirrelscan
    ```
  </Tab>
</Tabs>

The x64 binaries (macOS Intel, Linux and Windows) are built for the baseline x86-64 instruction set, so they run on CPUs without AVX. Apple Silicon and Linux arm64 have their own builds. Baseline builds can be slightly slower than an AVX-tuned one; that is the trade for running everywhere.

This downloads the binary and links it into a directory on your PATH. With Homebrew, that happens on the first run, when the launcher runs the regular installer. See [How the installer sets up your PATH](#how-the-installer-sets-up-your-path).

## After installing

Check the install, then run setup once.

```bash
squirrel self doctor
```

Setup signs you in (optional), installs the agent skills for Claude Code, Codex, Cursor and more, turns on auto-update, and ends by offering to audit a site:

```bash
squirrel setup
```

Then audit a site: `squirrel audit https://your-site.com`. The [Quickstart](/quickstart) walks through the first run and the report.

<Tip>Run `squirrel` on its own any time to see every command and a quick start.</Tip>

<Note>
**Alpine / musl Linux:** the binary needs the `libstdc++` runtime library. The installer adds it automatically when run as root; otherwise install it first with `apk add libstdc++` (or `sudo apk add libstdc++`).
</Note>

## Install options

Set any of these before running the installer.

| Variable | What it does |
| --- | --- |
| `SQUIRREL_VERSION` | Install a specific release instead of the newest one, for example `v0.0.94`. |
| `SQUIRREL_CHANNEL` | `stable` (default) or `beta`. |
| `SQUIRREL_BIN_DIR` | Where to put the `squirrel` symlink. Defaults to the first writable directory on your PATH, falling back to `~/.local/bin`. The installer refuses a value that is only whitespace and any path that names `/` once `.` and `..` are resolved by name (`/`, `//`, `/.`, `/..`, `/usr/..`; a symlink to `/` is not followed); an empty value is read as not set. |
| `SQUIRREL_NO_MODIFY_PATH` | Any value but empty, `0` or `false` stops the installer editing your shell profile or user PATH. It prints the line to add instead. See below. |
| `SQUIRREL_FORCE_MIRROR` | Download from squirrelscan's mirror instead of GitHub. See below. |
| `NO_TELEMETRY` | Any defined value, including an empty value, `0`, or `false`, turns off the anonymous failure report the installer sends when it fails. `DO_NOT_TRACK=1` (or `true`) does too. |

## What the installer protects

- **Permissions.** It runs with the umask tightened to at least `022`, so the directories and the binary it creates are never group or world writable, whatever umask it inherited. A stricter umask (`077`) is kept.
- **Size and checksum.** The release manifest records each binary's size. A download of a different size fails with a size mismatch, before the checksum, so a cut-short download reads as that and not as a bad hash.
- **Provenance.** The checksum comes from a manifest served next to the binary, so on its own it cannot tell a compromised download origin from a good one. Every release binary and the manifest also carry a GitHub build attestation, signed by the release workflow. When the GitHub CLI (`gh`) is installed and logged in, the installer runs `gh attestation verify <file> --repo squirrelscan/squirrelscan --cert-identity <release workflow on main> --deny-self-hosted-runners` on the download and stops with nothing installed if it does not match. See [Verifying a release](#verifying-a-release).
- **Ctrl-C.** An interrupt, `SIGTERM` or `SIGHUP` during the install (including one sent to the installer alone, mid-download) removes the temporary directory, ends the download and exits with 130, 143 or 129. Stopping the install is not a failure, so no failure report is sent.
- **No `HOME`.** If `HOME` is unset or empty it stops at once and tells you to set it. The installer keeps its state under `$HOME/.squirrel`, so it needs `HOME` even when `SQUIRREL_BIN_DIR` is set.
- **A `noexec` temp directory.** The binary is first run from your temp directory. If it cannot be run there (a `noexec` mount, whatever language the system's messages are in), the installer retries from `~/.squirrel/tmp`. If that fails too it says a `noexec` mount is the likely cause and tells you to set `TMPDIR` to a directory on a filesystem that can run programs; if `~/.squirrel/tmp` cannot even be created it says that instead.

## How the installer sets up your PATH

`SQUIRREL_BIN_DIR` wins. Otherwise the installer uses the first of `~/.local/bin`, `~/bin`, `/usr/local/bin` or `/opt/homebrew/bin` that is already on your PATH and writable.

If none is, it uses `~/.local/bin` and appends one marked line to the file your shell reads at startup, then tells you which file it changed. It never rewrites existing content, creates the file if it is missing, and adds nothing when the file already puts `~/.local/bin` on your PATH (a `PATH` or `fish_add_path` line) or carries the `# squirrel` marker, so running the installer again is safe.

| Shell | File | Line |
| --- | --- | --- |
| zsh | `$ZDOTDIR/.zshrc`, or `~/.zshrc` | `export PATH="$HOME/.local/bin:$PATH"` |
| bash on macOS | `~/.bash_profile` | same |
| bash on Linux | `~/.bashrc` | same |
| fish | `~/.config/fish/conf.d/squirrel.fish` | `fish_add_path $HOME/.local/bin` |
| sh or anything else | `~/.profile` | same as zsh |

On Linux a login shell (an SSH session, some terminals) may read `~/.profile` or `~/.bash_profile` and never `~/.bashrc`; if `squirrel` is not found there, add the same line to the file your login shell reads. An open terminal does not see the change. The closing message then tells you to open a new terminal or run `source ~/.zshrc` (your file), and gives a command that works right now, such as `~/.local/bin/squirrel audit https://your-site.com`.

Set `SQUIRREL_NO_MODIFY_PATH=1` to keep the installer away from your profile: it prints the line to add instead. In CI (`CI` set) it never edits a profile; when `GITHUB_PATH` is set, it appends the directory to that file so later steps find `squirrel`.

On Windows, the installer adds `%LOCALAPPDATA%\squirrel\bin` to your user `Path` (never the machine `Path`) and to the current session, once, and a new terminal picks it up. `SQUIRREL_NO_MODIFY_PATH` and CI behave the same way.

The one-time install registration reports what happened as `path_setup` (`on_path`, `added`, `opted_out`, `ci` or `failed`). It carries no path and nothing about you, and it is not sent when telemetry is off.

## What the installer host records

`install.squirrelscan.com` counts each fetch of the install script: which script (shell or PowerShell), a coarse class of the client (curl, wget, PowerShell, browser, coding-agent sandbox, other) taken from its User-Agent, and an optional `?source=` tag such as `?source=agent`. The count carries no IP address and no location, and nothing that identifies you. (Cloudflare serves the host and handles requests the way any CDN does; that is outside this count.) A tag is lowercase letters, digits and `-` (up to 32 characters) or it is ignored. The server records the fetch before your shell sees anything, so `NO_TELEMETRY` cannot turn it off.

## If GitHub is blocked on your network

Release binaries live on GitHub, and a GitHub download redirects to `release-assets.githubusercontent.com`. Some networks cannot reach it, most commonly in mainland China. The installer handles this on its own: when a GitHub download fails it retries the same file from `install.squirrelscan.com`, which serves the identical bytes through squirrelscan's own infrastructure. The checksum from the release manifest is verified either way, so the mirror is not a shortcut around the integrity check.

To skip GitHub from the start rather than waiting for it to time out:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash
    curl -fsSL https://install.squirrelscan.com | SQUIRREL_FORCE_MIRROR=1 bash
    ```
    The variable has to reach the shell that runs the script, so it goes on the right of the pipe.
  </Tab>
  <Tab title="Windows">
    ```powershell
    $env:SQUIRREL_FORCE_MIRROR='1'; iwr -useb https://install.squirrelscan.com/install.ps1 | iex
    ```
  </Tab>
</Tabs>

If both hosts are unreachable, the installer prints the two URLs it tried. Allowlist either `github.com` or `install.squirrelscan.com`, or download the binary on a machine that can reach one of them and move it into place yourself. A host that answers with a sign-in page instead of the release files, which is what a captive portal or an intercepting proxy does, counts as unreachable and the installer moves on to the other one.

`SQUIRREL_DOWNLOAD_ENDPOINT` points the fallback at a different host if you mirror the releases yourself. A custom endpoint's address never appears in the installer's anonymous failure report: when a request to it fails, the report says `custom` where it would name the host, so neither the name nor a token in a URL's userinfo, query or fragment leaves your machine. After a failed request to squirrelscan or GitHub, the installer makes one short, bounded request to that same host, ignoring proxy settings, only to read which IP family the connection used (reported as `v4`, `v6` or `unknown`). It runs after the install has already failed, in the background, and sends nothing but the request itself. A failed request to a custom endpoint is never probed.

## Verifying a release

Each release binary (and `manifest.json`) has a build attestation made by the release workflow in `squirrelscan/squirrelscan`. The trust root is GitHub's attestation service (Sigstore), not the origin you downloaded from, so it holds even if that origin or the mirror were compromised. The SHA-256 checksum stays in place; the attestation is a second check on top of it.

What the installers and `squirrel self update` do:

| Situation | Result |
|---|---|
| `gh` is installed and logged in, and the attestation matches | Continues, and prints `Attestation verified` |
| `gh` is installed and logged in, and the attestation does **not** match | Fails. Nothing is installed or run, and `gh`'s own output is shown. For `self update`, the current version stays in place |
| `gh` is not installed, is too old to have `gh attestation`, is not logged in, or a `gh` probe (`--help`, `auth status`) takes longer than 15 seconds | Prints a warning and relies on the SHA-256 checksum alone |
| `gh attestation verify` itself takes longer than 120 seconds | Fails with `gh attestation verify timed out after 120s, nothing was installed.` |

`gh attestation verify` needs a logged-in `gh`, so run `gh auth login` once to turn the check on. A `gh` that is not logged in cannot verify anything, so it is treated like a missing one, with the warning, and never as a pass.

To verify a binary by hand, download it from the [releases page](https://github.com/squirrelscan/squirrelscan/releases) and run:

```bash
gh attestation verify ./squirrel-<version>-<platform> \
  --repo squirrelscan/squirrelscan \
  --cert-identity https://github.com/squirrelscan/squirrelscan/.github/workflows/release.yml@refs/heads/main \
  --deny-self-hosted-runners
```

The same command works on `manifest.json`. Releases published before attestations were added have none, so pinning one of them with a logged-in `gh` fails this check. A mismatch means the file was not built by the squirrelscan release workflow: delete it and do not run it. The same applies on Windows with `squirrel-<version>-windows-x64.exe`.

## Homebrew

```bash
brew install --cask squirrelscan/tap/squirrel
```

The cask is macOS only (Linuxbrew is not supported; on Linux use the install script). It puts a small `squirrel` launcher on your PATH. The first time you run it, it runs the regular installer and then your command. The CLI lands in `~/.squirrel/releases` with a `squirrel` link in `~/.local/bin`, the same layout as the install script.

From then on it is an ordinary managed install. `squirrel self update` and auto-update keep it current, and `brew upgrade` leaves the CLI alone. Homebrew only owns the launcher.

To uninstall:

```bash
brew uninstall --cask squirrel
```

This removes the launcher and runs `squirrel self uninstall --yes`. That removes the link and the release binaries, and keeps your settings, credentials and audit data in `~/.squirrel`. To remove `~/.squirrel` as well:

```bash
brew uninstall --zap --cask squirrel
```

## Uninstall

Whichever way you installed, `squirrel self uninstall` removes the link and the release binaries. It asks before deleting anything. Add `--purge` to remove settings, credentials and audit data too. See [self uninstall](/cli/self#uninstall) for exactly what it removes.

## If the install is killed at the last step

On a machine with very little free memory the kernel can kill `squirrel self install` before it finishes, which used to leave nothing installed. The installer now finishes the job itself: it lays the release out, links the binary, and runs it once to confirm it works. If even that run is killed, the machine cannot execute the binary at all, and the installer says so and points at the [cloud dashboard](https://app.squirrelscan.com) as the way to audit without a local binary.
