# Installation

> Choose an installation method for your repository and prepare its checks.

## What you need

Git and Node.js 24.15 or newer. The tools that your checks run need these:

| Tools                                                    | What you need                                                                                                                                                                                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tools from npm                                           | Node.js and the npm, pnpm, Yarn, or Bun package manager of the project. gspot uses the package manager that `package.json` names in `packageManager` or `devEngines.packageManager`, else the one whose lockfile it finds, else npm. |
| Tools from PyPI                                          | uv; gspot installs its pinned Python version when needed.                                                                                                                                                                            |
| Other programs                                           | mise, or the exact pinned tools on `PATH`. `gspot doctor` lists missing tools.                                                                                                                                                       |
| Your project’s own commands, such as its tests and build | Your project’s runtime, dependencies, and build tools.                                                                                                                                                                               |

`gspot init --dry-run` shows the configurations that gspot picks. After init, `gspot doctor` lists the missing tools.

### Systems

gspot runs on macOS, Linux, and Windows. Some checks need more:

| Checks                                                                  | Need                                         |
| ----------------------------------------------------------------------- | -------------------------------------------- |
| Swift checks                                                            | The Swift toolchain                          |
| SwiftLint, SwiftFormat, and Swift package builds                        | macOS or Linux                               |
| `xcode/plutil`, Periphery, the SwiftLint analyzer, Xcode project builds | macOS, with Xcode selected by `xcode-select` |
| Some container checks                                                   | A running Docker daemon                      |
| Some scans                                                              | Network access                               |

Each [check page](/reference/checks/) lists its systems.

## Choose how to install

Install gspot with the package manager of your repository. A repository without `package.json`, such as a Python or Swift project, uses mise, which pins gspot in `mise.toml`. The guides show commands as `gspot ...`; start them as the last column shows.

| Package manager | Add gspot                                                                        | Start later commands with |
| --------------- | -------------------------------------------------------------------------------- | ------------------------- |
| npm             | `npm i -D -E @gspothq/cli`                                                       | `npx gspot`               |
| pnpm            | `pnpm add -D -E @gspothq/cli`                                                    | `pnpm exec gspot`         |
| Yarn            | `yarn add -D -E @gspothq/cli`                                                    | `yarn exec gspot`         |
| Bun             | `bun add -d -E @gspothq/cli`                                                     | `bunx gspot`              |
| mise            | `mise use --pin node@24 --tool-option allow_low_downloads=true npm:@gspothq/cli` | `mise exec -- gspot`      |

Then run `gspot init` and `gspot install`, as the [Quickstart](/start/quickstart/) shows. With mise, `--pin` writes exact Node.js and gspot versions to `mise.toml`. mise requires approval for a new npm package or one with few downloads; `allow_low_downloads=true` approves gspot.

Caution

Install `@gspothq/cli` before you run `npx gspot`. npm has no package named `gspot`, so without the install, npx stops with a 404 error.

## Set up a clone

Install the dependencies from the committed lockfile first; it pins the gspot version of the repository. Without `package.json`, `mise.toml` pins it. When the versions differ, gspot stops with `This repository pins gspot <version>` and prints the install command. `gspot init` refuses to run where `gspot.toml` exists, so run `gspot install` instead.

* npm

  ```shell
  npm ci
  npx gspot install
  npx gspot check
  ```

* pnpm

  ```shell
  pnpm install --frozen-lockfile
  pnpm exec gspot install
  pnpm exec gspot check
  ```

* Yarn

  ```shell
  yarn install --immutable
  yarn exec gspot install
  yarn exec gspot check
  ```

  Yarn Classic installs with `yarn install --frozen-lockfile`.

* Bun

  ```shell
  bun install --frozen-lockfile
  bunx gspot install
  bunx gspot check
  ```

* mise

  ```shell
  mise exec -- gspot install
  mise exec -- gspot check
  ```

`gspot install` installs the tools and turns on hooks in this clone. If it changes a lockfile under `.gspot/`, commit that file.

## Private registries

The npm, pnpm, Yarn, and Bun installs of gspot use the registry settings of your repository and your environment. uv reads Python package indexes from `uv.toml` or `[tool.uv]` in `pyproject.toml`.

Keep credentials in environment variables or your user settings, never in `gspot.toml` or a lockfile.

## Uninstall gspot

To stop checking one language or framework instead, see [gspot.toml](/configure/gspot-toml/#choose-configurations).

gspot has no uninstall command. Commit first, so you can go back.

1. Copy the list under “Generated files” in the gspot section of `AGENTS.md`. It names every file gspot writes outside `.gspot/` and each key it sets in your files.
2. Run `gspot set rules.enabled false`, `gspot set ci.enabled false`, and `gspot set hooks.enabled false`, then `gspot install`. gspot deletes the rules, its `AGENTS.md` section, the CI workflow, and the hook scripts, and `gspot install` removes `core.hooksPath`. If Husky, Lefthook, or your own hooks run gspot, delete those lines.
3. Restore your earlier tool files from Git, such as `git show <commit>:.eslintrc.json`, or set up the tools you want.
4. Delete the files and keys from step 1, the gspot sections in `.gitignore` and `.gitattributes`, `gspot.toml`, and `.gspot/`.
5. Remove the package: `npm uninstall @gspothq/cli`, the remove command of your package manager, or `mise unuse npm:@gspothq/cli`.

Review the diff. To undo, go back to the first commit and run `gspot install`.