Installation

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

npm ci
npx gspot install
npx gspot check

pnpm

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

Yarn

yarn install --immutable
yarn exec gspot install
yarn exec gspot check

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

Bun

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

mise

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.

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.