<!-- Source: https://docs.squirro.com/en/latest/technical/cli/installation.html -->
# Installation

Squirro CLI runs as a Docker container. A small wrapper script places a `squirro` command on your system path and runs the container for you, so the tool behaves as though it were installed natively.

Before starting, see the [Squirro CLI](index.md#squirro-cli) page for what the tool does and how it is meant to be used.

## Prerequisites

- **A Squirro ID with Squirro Registry access**

  Squirro CLI is published to the [Squirro Registry](https://registry.squirro.com), which requires a Squirro ID. If you do not have one, see the [How to Register for a Squirro ID](../../getting/self-service/how-to/how-register-id.md#how-register-id) page. Access to Squirro CLI is granted to selected customers and partners, so request it early: visit the [Squirro Support website](https://go.squirro.com/support) and submit a technical support request for Squirro Registry access.
- **Docker**

  Install Docker for your operating system from the [Docker](https://docs.docker.com/engine/install/) website. Docker must be running before any `squirro` command works.
- **An internet connection**

  Required to authenticate with the Squirro Registry and to download the image on first use.
- **A Squirro instance URL and API token**

  Take the API token from the user menu of the instance web interface. The instance must run version 3.16.4 or later.

## Log In to the Squirro Registry

Authenticate with the Squirro Registry.

```bash
docker login registry.squirro.com
```

Docker prompts for a username and a password. Use the Registry username associated with your Squirro ID, and your Registry CLI secret as the password. Both are shown in your user profile after you log in to the [Squirro Registry](https://registry.squirro.com) website.

You only need to do that once, because Docker stores the credentials locally.

## Install the squirro Command

Squirro CLI is a client. Install it on the machine you work from, such as your own workstation or a build agent, and not on a Squirro server. It reaches the instance over HTTPS using the cluster URL and token that the active profile carries, so it needs no access to the machines the platform runs on.

The wrapper script goes in `/usr/local/bin/`, which requires `sudo` access. If you do not have `sudo` access, ask your system administrator to install it for you.

On Linux and macOS, run the following commands.

```bash
sudo curl -fsSL https://mirror.squirro.net/extras/squirro-cli-docker.sh -o /usr/local/bin/squirro
sudo chmod +x /usr/local/bin/squirro
```

The script mounts two paths into the container:

- `~/.squirro`, which holds your user-scoped profiles.
- The directory you run the command from.

> **Important**
>
> The container sees only the directory you ran the command from. Run any command that touches configuration files, such as `config pull`, `config apply`, and `config validate`, from inside your configuration directory. Run them elsewhere and Squirro CLI has no access to those files.

## Verify the Installation

```bash
squirro --help
```

The first run downloads the image, which takes a few minutes depending on your connection speed. A list of command groups confirms that the installation works.

```text
Commands:
  api          Universal access to Squirro API endpoints.
  chat         Chat with Squirro AI agents.
  config       Manage Squirro configuration.
  connection   Test connection to all configured platforms (GenAI and...
  init         Initialize a new unified Squirro project.
  load         Load a local FILE into a file-based source.
  logs         Fetch logs from Squirro Studio log_files plugin.
  permissions  Manage Squirro permissions and access control.
  profile      Manage Squirro connection profiles.
  project      Manage Squirro projects.
  search       Search functionality commands.
  secret       Manage secrets for the current profile.
  test         Test Squirro configurations and connections.
  ui           Build and deploy custom Squirro UI (forwards to the neo-ui...
```

`squirro --help` lists the global options above that. Adding a group name describes that one group and the subcommands it holds.

```bash
squirro config --help
```

```text
Usage: squirro config [OPTIONS] COMMAND [ARGS]...

  Manage Squirro configuration.

Options:
  --help  Show this message and exit.

Commands:
  apply     Apply configuration from file(s).
  list      List all supported configuration types.
  pull      Pull configuration from Squirro to file(s).
  schema    Generate JSON schema for configuration files.
  validate  Validate configuration, showing the changes an apply would make.
```

For what each group does, and which of them carry less than their name suggests, see the [Main Commands](commands.md#squirro-cli-commands) page.

The following command reports which build you are running and the minimum instance version it supports.

```bash
squirro --version
```

That prints the build tag and the minimum version.

```text
squirro-cli 0.2026.09.08.68 (squirro >= 3.16.4)
```

## Move to a New Build

The image is cached locally and does not update on its own, so you decide when to move to a newer build.

```bash
squirro self update
```

That command is handled by the wrapper script rather than by the CLI. It refreshes the script itself from `mirror.squirro.net`, logs in to the Squirro Registry, then pulls the current image.

It can therefore ask for two different passwords, so read which one is being requested:

- Updating the script may need elevated permissions, in which case `sudo` shows a `Password:` prompt. That one wants your computer login password.
- The Registry login is usually silent, because Docker has stored your credentials. It prompts for `Username:` and `Password:` only when those credentials have gone, after a rotated Registry CLI secret for example. That one wants your Squirro Registry username and CLI secret, and the update stops there if it fails.

You can also pull the image without touching the wrapper script.

```bash
docker pull registry.squirro.com/squirro-cli/squirro-cli:latest
```

The wrapper script does not change. It uses the newly pulled image the next time you run a command.

A new build can ship newer assistant assets and a newer configuration schema, so run the following command once in each configuration directory you keep.

```bash
squirro init --update
```

That refreshes the bundled `CLAUDE.md`, skills, and tool definitions, and applies any pending schema migrations. It leaves your profiles, your configuration, and `README.md` alone, and keeps any skills and tools you added yourself, so review the result with `git diff` before committing. For more information, see the [Configuration Directory](configuration-directory.md#squirro-cli-configuration-directory) page.

### Pull a Specific Build

Every build receives two tags. The `latest` tag points at the most recent build, and a calendar version tag points at that one build permanently.

```text
0.<year>.<month>.<day>.<build>
```

The calendar version is also what `squirro --version` reports, so that command tells you which build you are on. To browse the available builds, log in to the [Squirro Registry](https://registry.squirro.com) website and open the Squirro CLI repository.

```bash
docker pull registry.squirro.com/squirro-cli/squirro-cli:0.2026.09.08.68
```

Docker stores each tagged image separately, so pulling a build-tagged image leaves your `latest` image untouched. The wrapper script always uses `latest`, so to run a specific build, call `docker run` directly.

```bash
docker run --rm \
  -it \
  --user "$UID:$(id -g)" \
  --env "HOME=$HOME" \
  -v "${HOME}/.squirro:${HOME}/.squirro" \
  -v "$(pwd):$(pwd)" \
  -w "$(pwd)" \
  registry.squirro.com/squirro-cli/squirro-cli:0.2026.09.08.68 \
  [command]
```

## Next Steps

With the CLI installed, create a configuration directory and connect it to your instance. For more information, see the [Configuration Directory](configuration-directory.md#squirro-cli-configuration-directory) page.