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.

Why not run the tools directly?

Installing a tool and running yamllint . yourself is fine for one tool on one machine. Once a project leans on a dozen, the same three chores repeat for each, and repomatic run takes care of all of them:

  • Configuration stays in pyproject.toml, one reviewed file rather than a dotfile per tool. Even tools that can’t read pyproject.toml themselves get their [tool.X] table translated to a temporary native config at run time, following the precedence chain below.

  • Installation is automatic: binaries come from GitHub Releases and are checksum-verified, PyPI tools run through uvx, and tools that import your code (mypy, Nuitka) run inside the project virtualenv.

  • Versions are pinned and re-verified on each use, so a check behaves the same on your laptop and in CI instead of drifting with whatever each machine happens to have installed.

See also

The tools repomatic bridges have standing upstream requests to read [tool.X] from pyproject.toml natively, all still unshipped: actionlint#623, biome#9239, gitleaks#2066, Nuitka#3909, zizmor#322. The same request for shfmt (sh#1268) was declined.

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
╭─────────────────┬─────────┬─────────────────────────────────╮
│ Tool            │ Version │ Config source                   │
├─────────────────┼─────────┼─────────────────────────────────┤
│ actionlint      │ 1.7.12  │ (bare)                          │
│ autopep8        │ 2.3.2   │ (bare)                          │
│ biome           │ 2.4.15  │ (bare)                          │
│ bump-my-version │ 1.2.7   │ (bare)                          │
│ gitleaks        │ 8.30.1  │ (bare)                          │
│ labelmaker      │ 0.6.4   │ (bare)                          │
│ lychee          │ 0.24.2  │ [tool.lychee] in pyproject.toml │
│ mdformat        │ 1.0.0   │ bundled default                 │
│ mypy            │ 1.19.1  │ [tool.mypy] in pyproject.toml   │
│ nuitka          │ 4.1     │ [tool.nuitka] in pyproject.toml │
│ pyproject-fmt   │ 2.16.2  │ (bare)                          │
│ ruff            │ 0.15.5  │ [tool.ruff] in pyproject.toml   │
│ shfmt           │ 3.13.1  │ (bare)                          │
│ typos           │ 1.46.2  │ [tool.typos] in pyproject.toml  │
│ yamllint        │ 1.38.0  │ bundled default                 │
│ zizmor          │ 1.23.0  │ bundled default                 │
╰─────────────────┴─────────┴─────────────────────────────────╯

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

Binary

biome.json, biome.jsonc

bump-my-version

1.2.7

PyPI

[tool.bump-my-version] in pyproject.toml

Gitleaks

8.30.1

Binary

.gitleaks.toml, .github/gitleaks.toml

labelmaker

0.6.4

Binary

CLI flags only

Lychee

0.24.2

Binary

lychee.toml, [tool.lychee] in pyproject.toml

mdformat

1.0.0

PyPI

.mdformat.toml, [tool.mdformat] in pyproject.toml

mypy

1.19.1

PyPI (venv)

[tool.mypy] in pyproject.toml

Nuitka

4.1

PyPI (venv)

[tool.nuitka] 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.46.2

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.

        flowchart TD
    run([repomatic run TOOL]) --> l1{native config file?}
    l1 -->|yes| u1[Level 1. Use the in-repo config file]
    l1 -->|no| l2{tool.X in pyproject.toml?}
    l2 -->|yes| u2[Level 2. Use tool.X, translate if needed]
    l2 -->|no| l3{bundled default?}
    l3 -->|yes| u3[Level 3. repomatic bundled baseline]
    l3 -->|no| u4[Level 4. Bare invocation, tool defaults]

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]

Native

mdformat

Markdown formatting options

[tool.mdformat]

Native (via mdformat-pyproject)

mypy

Static type checking

[tool.mypy]

Native

nuitka

Standalone binary compilation

[tool.nuitka]

repomatic bridge → CLI flags (native support: Nuitka#3909)

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
╭─────────────────┬─────────┬─────────────────────────────────╮
│ Tool            │ Version │ Config source                   │
├─────────────────┼─────────┼─────────────────────────────────┤
│ actionlint      │ 1.7.12  │ (bare)                          │
│ autopep8        │ 2.3.2   │ (bare)                          │
│ biome           │ 2.4.15  │ (bare)                          │
│ bump-my-version │ 1.2.7   │ (bare)                          │
│ gitleaks        │ 8.30.1  │ (bare)                          │
│ labelmaker      │ 0.6.4   │ (bare)                          │
│ lychee          │ 0.24.2  │ [tool.lychee] in pyproject.toml │
│ mdformat        │ 1.0.0   │ bundled default                 │
│ mypy            │ 1.19.1  │ [tool.mypy] in pyproject.toml   │
│ nuitka          │ 4.1     │ [tool.nuitka] in pyproject.toml │
│ pyproject-fmt   │ 2.16.2  │ (bare)                          │
│ ruff            │ 0.15.5  │ [tool.ruff] in pyproject.toml   │
│ shfmt           │ 3.13.1  │ (bare)                          │
│ typos           │ 1.46.2  │ [tool.typos] in pyproject.toml  │
│ yamllint        │ 1.38.0  │ bundled default                 │
│ zizmor          │ 1.23.0  │ bundled default                 │
╰─────────────────┴─────────┴─────────────────────────────────╯

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

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

$ repomatic init --delete-unmodified

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

Try it:

$ repomatic run actionlint

Minimal [tool.actionlint]:

[tool.actionlint.self-hosted-runner]
labels = ["my-linux-runner"]

With no arguments actionlint lints every workflow under .github/workflows. The [tool.actionlint] section is bridged to a temporary YAML config: declaring self-hosted runner labels stops custom runs-on: values being flagged as unknown.

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

Try it:

$ repomatic run autopep8 -- .

autopep8 takes its configuration from CLI flags only. repomatic passes --recursive --in-place --max-line-length 88 --select E501 by default; append more flags after --.

Biome

Installed version: 2.4.15

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

Try it:

$ repomatic run biome -- check .

Minimal [tool.biome]:

[tool.biome.formatter]
indentStyle = "space"

biome check reports formatting and lint issues; add --write after -- to apply fixes. The [tool.biome] section is bridged to a temporary biome.json, so keys keep Biome’s camelCase spelling.

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

Try it:

$ repomatic run bump-my-version -- show-bump

Minimal [tool.bumpversion]:

[tool.bumpversion]
current_version = "1.2.3"

The configuration table is [tool.bumpversion], not [tool.bump-my-version]: the section name predates the project’s rename. show-bump previews the next versions without writing; repomatic run bump-my-version -- bump minor performs the bump.

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

Try it:

$ repomatic run gitleaks -- dir .

Minimal [tool.gitleaks]:

[tool.gitleaks.extend]
useDefault = true

[tool.gitleaks.allowlist]
paths = ['''\.env\.sample$''']

gitleaks dir . scans the working tree; gitleaks git scans history instead. The [tool.gitleaks] section is bridged to a temporary .gitleaks.toml: keep extend.useDefault = true, or a custom config silently replaces the built-in rule set.

labelmaker

Installed version: 0.6.4

Installation method: Binary (downloaded from GitHub Releases)

Config: CLI flags only

Source | CLI usage

labelmaker syncs a repository’s issue and PR labels from a label-definition file, so unlike the linters it needs a target repository and a GITHUB_TOKEN, not a path in the working tree. There is no [tool.labelmaker] section: the label file is the configuration. See the upstream usage docs for its flags and file schema.

Lychee

Installed version: 0.24.2

Installation method: Binary (downloaded from GitHub Releases)

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

Source | Config reference | CLI usage

Try it:

$ repomatic run lychee -- .

Minimal [tool.lychee]:

[tool.lychee]
max_redirects = 5

lychee checks links found in the given path. Since v0.24 it reads [tool.lychee] from pyproject.toml natively, so repomatic does not translate it.

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

Try it:

$ repomatic run mdformat -- .

Minimal [tool.mdformat]:

[tool.mdformat]
wrap = "no"

mdformat rewrites Markdown in place. repomatic bundles a plugin set (GFM, MyST, front-matter, and others) and a baseline mdformat.toml; [tool.mdformat] in your pyproject.toml overrides it.

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

Try it:

$ repomatic run mypy -- .

Minimal [tool.mypy]:

[tool.mypy]
strict = true

mypy runs inside the project virtualenv (via uv run) so it can import your dependencies. repomatic derives --python-version from requires-python, so the check matches your lowest supported interpreter.

Nuitka

Installed version: 4.1

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

Config: [tool.nuitka] in pyproject.toml (translated to CLI flags)

Default flags: --mode=onefile --assume-yes-for-downloads

Source | Config reference | CLI usage

Try it:

$ repomatic run nuitka -- my_app/__main__.py

Minimal [tool.nuitka]:

[tool.nuitka]
onefile = true
output-dir = "build"

repomatic reads every key from [tool.nuitka] and forwards it as a CLI flag: true becomes a bare --flag, a string or number becomes --key=value, and a list repeats the flag once per item. Nuitka does not read [tool.nuitka] natively yet (Nuitka#3909); repomatic’s bridge fills the gap until it does.

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

Try it:

$ repomatic run pyproject-fmt -- pyproject.toml

Minimal [tool.pyproject-fmt]:

[tool.pyproject-fmt]
indent = 4

pyproject-fmt normalizes and reorders pyproject.toml in place. It reads its own [tool.pyproject-fmt] section natively.

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

Try it:

$ repomatic run ruff -- check .

Minimal [tool.ruff]:

[tool.ruff]
line-length = 100

ruff check . lints; ruff format . reformats. Both read [tool.ruff] natively. With no project config, repomatic falls back to its bundled ruff.toml baseline.

shfmt

Installed version: 3.13.1

Installation method: Binary (downloaded from GitHub Releases)

Config files: .editorconfig

Default flags: --write

Source | Config reference | CLI usage

Try it:

$ repomatic run shfmt -- .

shfmt formats shell scripts in place. It has no [tool.shfmt] section: indentation and style come from .editorconfig (indent_size, shell_variant, and the shfmt-specific keys).

typos

Installed version: 1.46.2

Installation method: Binary (downloaded from GitHub Releases)

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

Default flags: --write-changes

Source | Config reference | CLI usage

Try it:

$ repomatic run typos -- .

Minimal [tool.typos]:

[tool.typos.files]
extend-exclude = ["*.lock"]

typos scans the tree and, with repomatic’s default --write-changes, fixes what it finds. It reads [tool.typos] natively; use [tool.typos.default.extend-words] to map project-specific terms to their intended spelling.

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

Try it:

$ repomatic run yamllint -- .

Minimal [tool.yamllint]:

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

yamllint has no native pyproject.toml support, so repomatic bridges [tool.yamllint] to a temporary YAML config passed via --config-file. With no project config it uses repomatic’s strict bundled yamllint.yaml.

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

Try it:

$ repomatic run zizmor -- .

zizmor audits GitHub Actions workflows for security issues, offline by default. repomatic bridges [tool.zizmor] to a temporary YAML config (passed via --config); with none, it uses the bundled zizmor.yaml. See the configuration reference for available keys.

Comparison

Tool

Stars

Last release

Last commit

Commits

Dependencies

Language

License

actionlint

Stars

Last release

Last commit

Commits

Dependencies

Language

License

autopep8

Stars

Last release

Last commit

Commits

Dependencies

Language

License

Biome

Stars

Last release

Last commit

Commits

Dependencies

Language

License

bump-my-version

Stars

Last release

Last commit

Commits

Dependencies

Language

License

Gitleaks

Stars

Last release

Last commit

Commits

Dependencies

Language

License

labelmaker

Stars

Last release

Last commit

Commits

Dependencies

Language

License

Lychee

Stars

Last release

Last commit

Commits

Dependencies

Language

License

mdformat

Stars

Last release

Last commit

Commits

Dependencies

Language

License

mypy

Stars

Last release

Last commit

Commits

Dependencies

Language

License

Nuitka

Stars

Last release

Last commit

Commits

Dependencies

Language

License

pyproject-fmt

Stars

Last release

Last commit

Commits

Dependencies

Language

License

Ruff

Stars

Last release

Last commit

Commits

Dependencies

Language

License

shfmt

Stars

Last release

Last commit

Commits

Dependencies

Language

License

typos

Stars

Last release

Last commit

Commits

Dependencies

Language

License

yamllint

Stars

Last release

Last commit

Commits

Dependencies

Language

License

zizmor

Stars

Last release

Last commit

Commits

Dependencies

Language

License