Tool runner

repomatic run is a unified entry point for running external linters, formatters, and security scanners. It installs each tool at a pinned version, resolves configuration through a strict precedence chain, and invokes the tool: no manual setup, no dotfile sprawl.

Quick start

Run a tool against your project:

$ repomatic run yamllint -- .

The -- separates repomatic’s own options from the arguments forwarded to the tool. Everything after -- is passed through verbatim.

List all managed tools and their resolved config source:

$ repomatic run --list

Available tools

Tool	Version	Type	Config discovery
actionlint	1.7.12	Binary	.github/actionlint.yaml
autopep8	2.3.2	PyPI	CLI flags only
biome	2.4.5	Binary	biome.json, biome.jsonc
bump-my-version	1.2.7	PyPI	[tool.bumpversion] in pyproject.toml
gitleaks	8.30.1	Binary	.gitleaks.toml, .github/gitleaks.toml
labelmaker	0.6.4	Binary	CLI flags only
lychee	0.23.0	Binary	lychee.toml
mdformat	1.0.0	PyPI	.mdformat.toml, [tool.mdformat] in pyproject.toml
mypy	1.19.1	PyPI (venv)	[tool.mypy] in pyproject.toml
pyproject-fmt	2.16.2	PyPI	[tool.pyproject-fmt] in pyproject.toml
ruff	0.15.5	PyPI	ruff.toml, .ruff.toml, [tool.ruff] in pyproject.toml
shfmt	3.13.1	Binary	.editorconfig
typos	1.44.0	Binary	[tool.typos] in pyproject.toml
yamllint	1.38.0	PyPI	.yamllint.yaml, .yamllint.yml, .yamllint
zizmor	1.23.0	PyPI	zizmor.yaml

• Binary: downloaded as platform-specific executables from GitHub Releases.

• PyPI: installed via uvx.

• PyPI (venv): run inside the project virtualenv via uv run because they need to import project code.

Config resolution

When repomatic run <tool> is invoked, configuration is resolved through a 4-level precedence chain. The first match wins: no merging across levels.

Tip

Run repomatic --verbosity INFO run <tool> to see which config level was selected and the exact command line being executed. This is useful for debugging unexpected behavior. For full detail (config file contents, environment, caching), use --verbosity DEBUG.

Level 1: native config file

If the tool’s own config file exists in the repo (like ruff.toml or .yamllint.yaml), repomatic defers to it entirely. Your repo stays in control.

$ ls ruff.toml
ruff.toml
$ repomatic run ruff -- check .
# Uses ruff.toml directly — repomatic does nothing special.

Level 2: [tool.X] in pyproject.toml

If no native config file is found but your pyproject.toml has a [tool.<name>] section, repomatic uses it. For tools that read pyproject.toml natively (ruff, mypy, bump-my-version, etc.), this just works. For tools that don’t, repomatic translates the section into the tool’s native format and passes it via a temporary config file.

# pyproject.toml
[tool.yamllint.rules.line-length]
max = 120

[tool.yamllint.rules.truthy]
check-keys = false

$ repomatic run yamllint -- .
# Translates [tool.yamllint] to YAML, passes via --config-file.

All tools that support [tool.X] sections in pyproject.toml, whether natively or via repomatic’s translation bridge:

Tool	Customizes	Section	Support
actionlint	Workflow linting rules	[tool.actionlint]	repomatic bridge → YAML
biome	JSON/JS formatting and linting	[tool.biome]	repomatic bridge → JSON
bump-my-version	Version bump patterns and files	[tool.bumpversion]	Native
coverage.py	Code coverage reporting	[tool.coverage.*]	Native
gitleaks	Secret detection rules	[tool.gitleaks]	repomatic bridge → TOML
lychee	Link checking rules	[tool.lychee]	repomatic bridge → TOML
mdformat	Markdown formatting options	[tool.mdformat]	Native (via mdformat-pyproject)
mypy	Static type checking	[tool.mypy]	Native
pyproject-fmt	pyproject.toml formatting	[tool.pyproject-fmt]	Native
pytest	Test runner options	[tool.pytest]	Native
ruff	Linting and formatting rules	[tool.ruff]	Native
typos	Spell-checking exceptions	[tool.typos]	Native
uv	Package resolution and build config	[tool.uv]	Native
yamllint	YAML linting rules	[tool.yamllint]	repomatic bridge → YAML
zizmor	Workflow security scanning	[tool.zizmor]	repomatic bridge → YAML

See Click Extra’s inventory of pyproject.toml-aware tools for a broader list.

Level 3: bundled default

If the repo has no config at all, repomatic falls back to its own bundled defaults (stored in repomatic/data/). These provide sensible baseline rules so that tools produce useful results even without any project-specific configuration.

Tools with bundled defaults: mdformat, ruff, yamllint, zizmor.

Level 4: bare invocation

If none of the above applies (no config file, no [tool.X], no bundled default), the tool runs with its own built-in defaults. Tools like autopep8 and pyproject-fmt work this way: all behavior is controlled through CLI flags.

Checking the active config source

To see which precedence level is active for each tool in your repo:

$ repomatic run --list

The “Config source” column shows whether the tool is using a native config file (level 1), [tool.X] (level 2), a bundled default (level 3), or bare invocation (level 4).

Tutorial: adding yamllint to your project

This walkthrough covers a common scenario: running yamllint on a project that has no YAML linting configured.

Step 1: run with defaults

With no config file and no [tool.yamllint] section in pyproject.toml, repomatic uses its bundled default:

$ repomatic run yamllint -- .

The bundled config enforces strict YAML rules. If that produces too many warnings, customize it.

Step 2: customize via pyproject.toml

Instead of creating a .yamllint.yaml file, add a section to your pyproject.toml:

[tool.yamllint.rules.line-length]
max = 120

[tool.yamllint.rules.truthy]
check-keys = false

Now repomatic run yamllint -- . translates this to YAML, passes it via --config-file, and cleans up the temporary file afterward.

Step 3: graduate to a native config file

If your yamllint config grows complex, create a .yamllint.yaml directly. Once that file exists, repomatic defers to it (level 1 takes precedence) and the [tool.yamllint] section in pyproject.toml is ignored.

Cleaning up redundant configs

If you previously ran repomatic init and have a native config file that is identical to the bundled default, repomatic init --clean-redundant-configs removes it:

$ repomatic init --clean-redundant-configs

Overriding tool versions

To test a newer version of a tool before the registry is updated:

$ repomatic run shfmt --version 3.14.0 --skip-checksum -- .

--skip-checksum is required because the registry only stores checksums for the pinned version. For binary tools, --checksum lets you provide the correct SHA-256 for the new version instead of skipping verification entirely:

$ repomatic run shfmt --version 3.14.0 --checksum abc123... -- .

Binary caching

repomatic run downloads platform-specific binaries (actionlint, biome, gitleaks, labelmaker, lychee, etc.) from GitHub Releases. To avoid re-downloading on every invocation, binaries are cached under a platform-appropriate user cache directory:

Platform	Default cache path
Linux	$XDG_CACHE_HOME/repomatic or ~/.cache/repomatic
macOS	~/Library/Caches/repomatic
Windows	%LOCALAPPDATA%\repomatic\Cache

Cached binaries are re-verified against their registry SHA-256 checksum on every use. Entries older than 30 days are auto-purged.

Both settings are configurable via [tool.repomatic] (see cache.dir and cache.max-age) or environment variables. The env var takes precedence over the config.

Environment variable	Config key	Default	Description
REPOMATIC_CACHE_DIR	cache.dir	(platform-specific)	Override the cache directory path.
REPOMATIC_CACHE_MAX_AGE	cache.max-age	30	Auto-purge entries older than this many days. 0 disables.

Cache management commands:

$ repomatic cache show
$ repomatic cache clean
$ repomatic cache clean --tool ruff --max-age 7
$ repomatic cache path

Use --no-cache on repomatic run to bypass the cache entirely.

Passing extra arguments

Everything after -- is forwarded to the tool:

$ repomatic run ruff -- check --fix .
$ repomatic run zizmor -- --offline .github/workflows/
$ repomatic run biome -- format --write src/

For tools with subcommands (ruff, biome, gitleaks), the subcommand goes after -- as the first argument.

Tool details

actionlint

Installed version: 1.7.12

Installation method: Binary (downloaded from GitHub Releases)

Config files: .github/actionlint.yaml

Default flags: -color

Source | Config reference | CLI usage

autopep8

Installed version: 2.3.2

Installation method: PyPI, installed via uvx

Config: CLI flags only

Default flags: --recursive --in-place --max-line-length 88 --select E501

Source | CLI usage

Biome

Installed version: 2.4.5

Installation method: Binary (downloaded from GitHub Releases)

Config files: biome.json, biome.jsonc

[tool.biome] bridge: repomatic translates to JSON and passes via --config-path.

Source | Config reference | CLI usage

bump-my-version

Installed version: 1.2.7

Installation method: PyPI, installed via uvx

Config: [tool.bump-my-version] in pyproject.toml (native)

Source | Config reference | CLI usage

Gitleaks

Installed version: 8.30.1

Installation method: Binary (downloaded from GitHub Releases)

Config files: .gitleaks.toml, .github/gitleaks.toml

[tool.gitleaks] bridge: repomatic translates to TOML and passes via --config.

Source | Config reference | CLI usage

labelmaker

Installed version: 0.6.4

Installation method: Binary (downloaded from GitHub Releases)

Config: CLI flags only

Source | CLI usage

Lychee

Installed version: 0.23.0

Installation method: Binary (downloaded from GitHub Releases)

Config files: lychee.toml

[tool.lychee] bridge: repomatic translates to TOML and passes via --config.

Source | Config reference | CLI usage

mdformat

Installed version: 1.0.0

Installation method: PyPI, installed via uvx

Config files: .mdformat.toml and [tool.mdformat] in pyproject.toml (native)

Default flags: --strict-front-matter

Bundled default: mdformat.toml

Plugins:

• mdformat_admon

• mdformat-config

• mdformat_deflist

• mdformat_footnote

• mdformat-front-matters

• mdformat-gfm

• mdformat_gfm_alerts

• mdformat_myst

• mdformat-pelican

• mdformat_pyproject

• mdformat-recover-urls

• mdformat-ruff

• mdformat-shfmt

• mdformat_simple_breaks

• mdformat-toc

• mdformat-web

• ruff

Source | Config reference | CLI usage

mypy

Installed version: 1.19.1

Installation method: PyPI, runs in project virtualenv via uv run

Config: [tool.mypy] in pyproject.toml (native)

Default flags: --color-output

Source | Config reference | CLI usage

pyproject-fmt

Installed version: 2.16.2

Installation method: PyPI, installed via uvx

Config: [tool.pyproject-fmt] in pyproject.toml (native)

Default flags: --expand-tables project.entry-points,project.optional-dependencies,project.urls,project.scripts

Source | Config reference | CLI usage

Ruff

Installed version: 0.15.5

Installation method: PyPI, installed via uvx

Config files: ruff.toml, .ruff.toml and [tool.ruff] in pyproject.toml (native)

Bundled default: ruff.toml

Source | Config reference | CLI usage

shfmt

Installed version: 3.13.1

Installation method: Binary (downloaded from GitHub Releases)

Config files: .editorconfig

Default flags: --write

Source | Config reference | CLI usage

typos

Installed version: 1.44.0

Installation method: Binary (downloaded from GitHub Releases)

Config: [tool.typos] in pyproject.toml (native)

Default flags: --write-changes

Source | Config reference | CLI usage

yamllint

Installed version: 1.38.0

Installation method: PyPI, installed via uvx

Config files: .yamllint.yaml, .yamllint.yml, .yamllint

[tool.yamllint] bridge: repomatic translates to YAML and passes via --config-file.

Default flags: --strict

CI flags: --format github

Bundled default: yamllint.yaml

Source | Config reference | CLI usage

zizmor

Installed version: 1.23.0

Installation method: PyPI, installed via uvx

Config files: zizmor.yaml

[tool.zizmor] bridge: repomatic translates to YAML and passes via --config.

Default flags: --offline

CI flags: --format github

Bundled default: zizmor.yaml

Source | Config reference | CLI usage

Comparison

Tool	Stars	Last release	Last commit	Commits	Dependencies	Language	License
actionlint
autopep8
Biome
bump-my-version
Gitleaks
labelmaker
Lychee
mdformat
mypy
pyproject-fmt
Ruff
shfmt
typos
yamllint
zizmor