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. Commands that change settings write generated files too.
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.
gspotinit [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.
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.
gspotinstall [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.
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.
gspotapply [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.
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.
gspotcheck [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.
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.
gspotadd [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.
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.
gspotremove [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.
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.
gspotset [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.
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.
gspotunset [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.
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.
gspotignore [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:
gspotignorejavascript/eslint--ruleno-console--paths"scripts/**"--reason"Scripts print their results."
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.
gspotunignore [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.
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.
gspotlist [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.
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.
gspotdoctor [options]
Option
What it does
--json
Print the full report as JSON, with the tools that are ready.
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.
gspotexport [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.
