# Commands

> Every gspot command, its options, and its exit codes.

Run gspot from any folder in the repository; it finds the nearest `gspot.toml`. Start each command the way your repository runs gspot, such as `npx gspot` or `mise exec -- gspot`. See [Install](/start/install/#choose-how-to-install). Commands that change settings write generated files too.

| Command                             | What it does                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| [`gspot init`](#gspot-init)         | Find what this repository needs, then write gspot.toml and the generated files |
| [`gspot install`](#gspot-install)   | Install the tools and turn on the Git hooks in this clone                      |
| [`gspot apply`](#gspot-apply)       | Write the generated files again from gspot.toml                                |
| [`gspot check`](#gspot-check)       | Run the checks and print the findings                                          |
| [`gspot add`](#gspot-add)           | Select configurations                                                          |
| [`gspot remove`](#gspot-remove)     | Stop using configurations                                                      |
| [`gspot set`](#gspot-set)           | Change a setting                                                               |
| [`gspot unset`](#gspot-unset)       | Delete your value, so the default applies again                                |
| [`gspot ignore`](#gspot-ignore)     | Turn off a check, or one lint rule, with a reason                              |
| [`gspot unignore`](#gspot-unignore) | Turn an ignored check on again                                                 |
| [`gspot list`](#gspot-list)         | List the configurations or the settings                                        |
| [`gspot explain`](#gspot-explain)   | Explain a check, lint rule, configuration, setting, or file                    |
| [`gspot doctor`](#gspot-doctor)     | Find setup problems and print the command that fixes each one                  |
| [`gspot export`](#gspot-export)     | Write gspot.toml as a template for other repositories                          |

## gspot init

Find the configurations this repository needs and print a plan. When you accept the plan, gspot writes `gspot.toml`, the tool files, the rules for coding agents, the Git hooks, and the CI workflow. init deletes the tool files that gspot replaces. Git keeps their old content. init installs no tools and runs no checks. Run `gspot install` next.

```shell
gspot init [options]
```

| Option                        | What it does                                                                                 |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| `--yes`                       | Accept the plan without a question (needed without a terminal).                              |
| `--dry-run`                   | Print the plan and write nothing.                                                            |
| `--from <template>`           | Start from a template: a file path, an HTTPS URL, or `github:owner/repository[/path][@ref]`. |
| `--configurations <names...>` | Use these configurations at the root instead of the detected ones.                           |
| `--no-configurations`         | Select no configurations at the root.                                                        |
| `--json`                      | Print the result as JSON. Needs `--yes` or `--dry-run`.                                      |

| Exit code | Meaning                                             |
| --------- | --------------------------------------------------- |
| `0`       | The plan was written, printed, or declined.         |
| `2`       | An argument is not valid, or init could not finish. |

For example:

```shell
gspot init --dry-run
```

## gspot install

Install the tools that `gspot.toml` needs, at the pinned versions:

* npm tools into `.gspot/node_modules`, from `.gspot/package-lock.json`
* Python tools into `.gspot/.venv`, from `.gspot/uv.lock`
* programs with mise, from `.gspot/mise.toml` (gspot runs `mise trust` for this file)

install writes each missing or outdated lockfile. Commit the lockfiles. install also sets the Git setting `core.hooksPath` to `.gspot/hooks`, or removes it when you set `hooks.enabled` to false. Without mise, install names the programs that you must install yourself.

```shell
gspot install [options]
```

| Option   | What it does              |
| -------- | ------------------------- |
| `--json` | Print the result as JSON. |

| Exit code  | Meaning                                                         |
| ---------- | --------------------------------------------------------------- |
| `0`        | The tools are installed, or the missing programs are named.     |
| `2`        | install could not finish. The error names the step that failed. |
| `130, 143` | Installation stopped because of Ctrl-C or SIGTERM.              |

For example:

```shell
gspot install
```

## gspot apply

Write the tool files, the rules, the Git hooks, and the CI workflow again from `gspot.toml`. apply replaces the generated files that gspot owns. apply sets the version pin in `.gspot/version` to the gspot version that runs. apply does not change `gspot.toml` and installs no tools. Run `gspot install` when apply says the tools changed.

```shell
gspot apply [options]
```

| Option      | What it does                                                                            |
| ----------- | --------------------------------------------------------------------------------------- |
| `--dry-run` | Print the generated files that would change, with their differences, and write nothing. |
| `--json`    | Print the result as JSON.                                                               |

| Exit code | Meaning                                             |
| --------- | --------------------------------------------------- |
| `0`       | The files were written, or the dry run finished.    |
| `2`       | gspot.toml is not valid, or apply could not finish. |

For example:

```shell
gspot apply --dry-run
```

## gspot check

Run the checks and print each finding with its file, line, lint rule, and help. Without options, gspot runs the commit and push checks on the working tree. Commit message checks run with `--hook commit-msg`. Manual checks run only when `--only` names them.

```shell
gspot check [options] [paths...]
```

| Argument | What it is                                                           |
| -------- | -------------------------------------------------------------------- |
| `paths`  | Files or folders to check (default: the whole repository). Optional. |

| Option               | What it does                                                                                                                                                                |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--only <checks...>` | Run only these checks, such as `python/ruff`.                                                                                                                               |
| `--staged`           | Check the staged content of the staged files.                                                                                                                               |
| `--changed [ref]`    | Check the files changed since ref (default: the upstream branch, else the default branch).                                                                                  |
| `--fix`              | Run the fixers, then run the checks on the fixed files.                                                                                                                     |
| `--dry-run`          | With `--fix`: print the changes the fixers would make, and write nothing.                                                                                                   |
| `--hook <hook>`      | Run as the Git hook runs: `pre-commit`, `pre-push`, or `commit-msg`. Put the arguments that Git gives the hook after `--`. Choices: `pre-commit`, `pre-push`, `commit-msg`. |
| `--verbose`          | Also print the passed and skipped checks, each command, and each ignore.                                                                                                    |
| `--json`             | Print the report as JSON.                                                                                                                                                   |

| Exit code  | Meaning                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `0`        | Every check that ran passed.                                                                      |
| `1`        | Findings remain.                                                                                  |
| `2`        | A check could not run (a tool is missing or failed), a fixer failed, or an argument is not valid. |
| `130, 143` | The run stopped because of Ctrl-C or SIGTERM.                                                     |

For example:

```shell
gspot check --staged
```

## gspot add

Select configurations in `gspot.toml`, then write the generated files again. gspot also selects the configurations that they need, but `gspot.toml` lists only the names you give. Run `gspot install` next when the configurations need new tools.

```shell
gspot add [options] <configuration...>
```

| Argument        | What it is                                                                     |
| --------------- | ------------------------------------------------------------------------------ |
| `configuration` | Configuration names, such as `pytest`. Run `gspot list` to see them. Required. |

| Option           | What it does                                        |
| ---------------- | --------------------------------------------------- |
| `--scope <path>` | Select them in this scope only (default: the root). |
| `--json`         | Print the result as JSON.                           |

| Exit code | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `0`       | The configurations were added, or they were already selected. |
| `2`       | An argument is not valid, or add could not finish.            |

For example:

```shell
gspot add pytest --scope services/api
```

## gspot remove

Stop using configurations, then write the generated files again. `gspot.toml` records the removal, so detection does not select them again. `gspot add` undoes it. gspot refuses to remove a configuration that another selected configuration needs.

```shell
gspot remove [options] <configuration...>
```

| Argument        | What it is                     |
| --------------- | ------------------------------ |
| `configuration` | Configuration names. Required. |

| Option           | What it does                                          |
| ---------------- | ----------------------------------------------------- |
| `--scope <path>` | Remove them from this scope only (default: the root). |
| `--json`         | Print the result as JSON.                             |

| Exit code | Meaning                                                        |
| --------- | -------------------------------------------------------------- |
| `0`       | The configurations were removed, or none of them was selected. |
| `2`       | An argument is not valid, or remove could not finish.          |

For example:

```shell
gspot remove nextjs --scope apps/web
```

## gspot set

Change one setting in `gspot.toml`, then write the generated files again. gspot checks the value first. For a list, gspot adds the values. For a table, give one TOML inline table, and gspot adds its entries. Write `[[...]]` records, such as `[[command_check]]`, by hand.

```shell
gspot set [options] <setting> <values...>
```

| Argument  | What it is                                                                                      |
| --------- | ----------------------------------------------------------------------------------------------- |
| `setting` | The setting name, such as `limits.file_lines`. Run `gspot list settings` to see them. Required. |
| `values`  | The new value, or the items or table entries to add. Required.                                  |

| Option            | What it does                                                    |
| ----------------- | --------------------------------------------------------------- |
| `--reason <text>` | Why you change it. Needed when the change makes a check weaker. |
| `--scope <path>`  | Change it in this scope only (default: the root).               |
| `--json`          | Print the result as JSON.                                       |

| Exit code | Meaning                                                         |
| --------- | --------------------------------------------------------------- |
| `0`       | The setting was written.                                        |
| `2`       | The setting or the value is not valid, or set could not finish. |

For example:

```shell
gspot set level all
```

## gspot unset

Delete your value of a setting from `gspot.toml`, then write the generated files again. The root value or the default applies again. With items, delete only those list items or table entries.

```shell
gspot unset [options] <setting> [items...]
```

| Argument  | What it is                                                                      |
| --------- | ------------------------------------------------------------------------------- |
| `setting` | The setting name, such as `naming.banned_words`. Required.                      |
| `items`   | List items or table entry names to delete (default: the whole value). Optional. |

| Option           | What it does                                      |
| ---------------- | ------------------------------------------------- |
| `--scope <path>` | Change it in this scope only (default: the root). |
| `--json`         | Print the result as JSON.                         |

| Exit code | Meaning                                                 |
| --------- | ------------------------------------------------------- |
| `0`       | The value was deleted, or there was no value to delete. |
| `2`       | The setting is not valid, or unset could not finish.    |

For example:

```shell
gspot unset level
```

## gspot ignore

Turn off a check, or one of its lint rules, everywhere or for some paths. gspot writes the ignore and your reason to `gspot.toml`, then writes the generated files again. Each report counts the ignores. `gspot check --verbose` prints them with their reasons.

```shell
gspot ignore [options] <check>
```

| Argument | What it is                                  |
| -------- | ------------------------------------------- |
| `check`  | The check, such as `python/ruff`. Required. |

| Option              | What it does                                            |
| ------------------- | ------------------------------------------------------- |
| `--reason <text>`   | Why you turn it off (required).                         |
| `--rule <rule>`     | Turn off only this lint rule.                           |
| `--paths <glob...>` | Turn it off only for these paths (default: every path). |
| `--until <date>`    | Turn it on again on this date, YYYY-MM-DD (UTC).        |
| `--json`            | Print the result as JSON.                               |

| Exit code | Meaning                                               |
| --------- | ----------------------------------------------------- |
| `0`       | The ignore was written.                               |
| `2`       | An argument is not valid, or ignore could not finish. |

For example:

```shell
gspot ignore javascript/eslint --rule no-console --paths "scripts/**" --reason "Scripts print their results."
```

## gspot unignore

Delete the ignores of a check from `gspot.toml`, then write the generated files again. With `--rule`, delete only the ignores of that lint rule. With `--paths`, take those paths out of the ignores. An ignore without paths covers every path, so `--paths` cannot narrow it. unignore keeps that ignore and says so.

```shell
gspot unignore [options] <check>
```

| Argument | What it is                                  |
| -------- | ------------------------------------------- |
| `check`  | The check, such as `python/ruff`. Required. |

| Option              | What it does                               |
| ------------------- | ------------------------------------------ |
| `--rule <rule>`     | Delete only the ignores of this lint rule. |
| `--paths <glob...>` | Take only these paths out of the ignores.  |
| `--json`            | Print the result as JSON.                  |

| Exit code | Meaning                                                    |
| --------- | ---------------------------------------------------------- |
| `0`       | The ignores were deleted or changed, or no ignore matched. |
| `2`       | An argument is not valid, or unignore could not finish.    |

For example:

```shell
gspot unignore javascript/eslint --rule no-console
```

## gspot list

List the selected and the available configurations, with the state of each check in each scope. gspot list settings lists each setting, its value, and where the value comes from. list changes nothing.

```shell
gspot list [options] [configurations|settings]
```

| Argument | What it is                                                                                  |
| -------- | ------------------------------------------------------------------------------------------- |
| `what`   | What to list. Optional. Choices: `configurations`, `settings`. Default: `"configurations"`. |

| Option   | What it does                                        |
| -------- | --------------------------------------------------- |
| `--json` | Print the result as JSON, with long values in full. |

| Exit code | Meaning                                            |
| --------- | -------------------------------------------------- |
| `0`       | The list was printed.                              |
| `2`       | gspot.toml is not valid, or list could not finish. |

For example:

```shell
gspot list settings
```

## gspot explain

Explain one thing: what it means, its state in this repository, and the commands that change it. explain changes nothing.

```shell
gspot explain [options] <subject>
```

| Argument  | What it is                                                                                                                                                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject` | A check (`python/ruff`), a lint rule (`eslint/no-console`), a configuration (`python`), a setting (`limits.file_lines`), or a file (`./src/app.ts`). Required. |

| Option   | What it does              |
| -------- | ------------------------- |
| `--json` | Print the result as JSON. |

| Exit code | Meaning                                |
| --------- | -------------------------------------- |
| `0`       | The explanation was printed.           |
| `2`       | gspot knows no subject with this name. |

For example:

```shell
gspot explain python/ruff
```

## gspot doctor

Find setup problems: missing or wrong tool versions, Git hooks that do not run, and configurations that the repository needs but does not select. Each problem line shows the command that fixes it. doctor changes nothing.

```shell
gspot doctor [options]
```

| Option   | What it does                                                  |
| -------- | ------------------------------------------------------------- |
| `--json` | Print the full report as JSON, with the tools that are ready. |

| Exit code | Meaning                            |
| --------- | ---------------------------------- |
| `0`       | No problem found.                  |
| `1`       | A tool or a Git hook is not ready. |
| `2`       | doctor could not finish.           |

For example:

```shell
gspot doctor
```

## gspot export

Write `gspot.toml` as a template that other repositories can start from with `gspot init --from`. The template leaves out the scopes. If a command check runs a script from this repository, copy the script too. export does not change `gspot.toml`.

```shell
gspot export [options] <file>
```

| Argument | What it is                                                           |
| -------- | -------------------------------------------------------------------- |
| `file`   | The template file to write, such as `gspot.template.toml`. Required. |

| Option   | What it does              |
| -------- | ------------------------- |
| `--json` | Print the result as JSON. |

| Exit code | Meaning                                                 |
| --------- | ------------------------------------------------------- |
| `0`       | The template was written.                               |
| `2`       | The file name is not valid, or export could not finish. |

For example:

```shell
gspot export gspot.template.toml
```

## Global options

| Option      | What it does       |
| ----------- | ------------------ |
| `--version` | Print the version. |
| `--help`    | Print help.        |

## Exit codes

Every command exits with one of these codes.

| Exit code  | Meaning                                                    |
| ---------- | ---------------------------------------------------------- |
| `0`        | The command finished. For check: no findings remain.       |
| `1`        | check found findings, or doctor found a setup problem.     |
| `2`        | The command could not finish, or an argument is not valid. |
| `130, 143` | check or install stopped because of Ctrl-C or SIGTERM.     |

## Environment variables

| Variable       | What it does                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| `GITHUB_TOKEN` | Lets gspot read a template from a private GitHub repository. mise also reads it for tool downloads from GitHub. |
| `NO_COLOR`     | Any nonempty value turns color off.                                                                             |