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.

Why not run the tools directly?¶

Once a project leans on a dozen tools, 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, tools that import your code (mypy, Nuitka) run inside the project virtualenv, and npm tools install from the npm registry (Node.js required).
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.

Todo

Drop the [tool.X] translation layer for each tool that grows native pyproject.toml support, as lychee already has. The standing upstream requests, all still unshipped: actionlint#623, biome#9239, gitleaks#2066, zizmor#322. The same request for shfmt (sh#1268) was declined. Nuitka#3909 shipped in 4.2, but only for --project builds, which take their entry points from the project configuration. repomatic names a main module on the command line, so the nuitka bridge stays.

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  │ [tool.actionlint] in pyproject.toml (replaces bundled default) │
│ autopep8        │ 2.3.2   │ (bare)                                                         │
│ awesome-lint    │ 2.3.0   │ (bare)                                                         │
│ biome           │ 2.5.14  │ (bare)                                                         │
│ bump-my-version │ 1.5.1   │ (bare)                                                         │
│ gh              │ 2.101.0 │ (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            │ 2.3.1   │ [tool.mypy] in pyproject.toml                                  │
│ nuitka          │ 4.2.2   │ [tool.nuitka] in pyproject.toml                                │
│ oxipng          │ 10.2.1  │ (bare)                                                         │
│ pyproject-fmt   │ 2.29.4  │ (bare)                                                         │
│ ruff            │ 0.16.8  │ [tool.ruff] in pyproject.toml (replaces bundled default)       │
│ shfmt           │ 3.14.1  │ (bare)                                                         │
│ typos           │ 1.50.2  │ [tool.typos] in pyproject.toml                                 │
│ yamllint        │ 1.38.0  │ bundled default                                                │
│ zizmor          │ 1.30.1  │ bundled default                                                │
╰─────────────────┴─────────┴────────────────────────────────────────────────────────────────╯

Available tools¶

Tool	Version	Type	Config discovery
actionlint	`1.7.12`	Binary	`.github/actionlint.yaml`, `.github/actionlint.yml`
autopep8	`2.3.2`	PyPI	`[tool.autopep8]` in `pyproject.toml`
awesome-lint	`2.3.0`	npm	CLI flags only
Biome	`2.5.14`	Binary	`biome.json`, `biome.jsonc`, `.biome.json`, `.biome.jsonc`
bump-my-version	`1.5.1`	PyPI	`.bumpversion.toml`, `[tool.bump-my-version]` in `pyproject.toml`
GitHub CLI	`2.101.0`	Binary	CLI flags only
Gitleaks	`8.30.1`	Binary	`.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	`2.3.1`	PyPI (venv)	`[tool.mypy]` in `pyproject.toml`
Nuitka	`4.2.2`	PyPI (venv)	`[tool.nuitka]` in `pyproject.toml`
Oxipng	`10.2.1`	Binary	CLI flags only
pyproject-fmt	`2.29.4`	PyPI	`pyproject-fmt.toml`, `[tool.pyproject-fmt]` in `pyproject.toml`
Ruff	`0.16.8`	PyPI	`.ruff.toml`, `ruff.toml`, `[tool.ruff]` in `pyproject.toml`
shfmt	`3.14.1`	Binary	`.editorconfig`
typos	`1.50.2`	Binary	`typos.toml`, `_typos.toml`, `.typos.toml`, `[tool.typos]` in `pyproject.toml`
yamllint	`1.38.0`	PyPI	`.yamllint`, `.yamllint.yaml`, `.yamllint.yml`
zizmor	`1.30.1`	PyPI	`.github/zizmor.yml`, `.github/zizmor.yaml`, `zizmor.yml`, `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.
npm: installed from the npm registry into a throwaway prefix and run via node_modules/.bin. The one backend that needs a foreign runtime (Node.js and npm on PATH); integrity is npm’s own per-tarball verification, with no repomatic-pinned checksum.

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. Tools that read pyproject.toml natively (ruff, mypy, bump-my-version, etc.) read the section themselves. For tools that don’t, repomatic translates the section into the tool’s native format and passes it via a temporary config file.

Note

When the tool’s native format is also TOML (like gitleaks), the translation keeps the comments from your [tool.X] section and only drops the [tool.X] prefix. Translations to another format (YAML, JSON) carry the values only: a TOML comment has no equivalent to map onto.

# 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
autopep8	Python code formatting	`[tool.autopep8]`	Native
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 is `--project`-only: 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: actionlint, 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 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  │ [tool.actionlint] in pyproject.toml (replaces bundled default) │
│ autopep8        │ 2.3.2   │ (bare)                                                         │
│ awesome-lint    │ 2.3.0   │ (bare)                                                         │
│ biome           │ 2.5.14  │ (bare)                                                         │
│ bump-my-version │ 1.5.1   │ (bare)                                                         │
│ gh              │ 2.101.0 │ (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            │ 2.3.1   │ [tool.mypy] in pyproject.toml                                  │
│ nuitka          │ 4.2.2   │ [tool.nuitka] in pyproject.toml                                │
│ oxipng          │ 10.2.1  │ (bare)                                                         │
│ pyproject-fmt   │ 2.29.4  │ (bare)                                                         │
│ ruff            │ 0.16.8  │ [tool.ruff] in pyproject.toml (replaces bundled default)       │
│ shfmt           │ 3.14.1  │ (bare)                                                         │
│ typos           │ 1.50.2  │ [tool.typos] in pyproject.toml                                 │
│ yamllint        │ 1.38.0  │ bundled default                                                │
│ zizmor          │ 1.30.1  │ 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 run a tool at a version the registry does not pin:

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

Running with no arguments¶

Some tools declare the arguments and target files CI would pass on their behalf, so repomatic run <tool> with nothing after it runs the same invocation:

$ repomatic run yamllint
$ repomatic run mdformat

The first resolves to repomatic run yamllint -- .; the second walks every Markdown file in the repository and formats each one in turn, matching what the format-markdown job runs. A tool with no declared defaults runs bare, exactly as before.

Note

This only fires on a bare invocation. Passing any argument after -- suppresses the tool’s default arguments and paths, handing the command line to you. Splicing repomatic’s defaults into a caller-driven command could otherwise build something like biome format … check ., which is not a command anyone meant to run.

Managed configuration is not suppressed with them. A tool’s default flags and its resolved config file are still applied on top of whatever you pass, so repeating one yourself produces a duplicate the tool then rejects: repomatic run zizmor -- --offline . fails because --offline is already a zizmor default flag.

When a tool’s defaults are file-driven and the repository holds no matching file, the tool is skipped rather than invoked with no path: a formatter handed zero paths does not no-op, it walks the entire tree in write mode.

Passing extra arguments¶

Everything after -- is forwarded to the tool:

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

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

Verifying without writing¶

--verify reports which targets a tool would rewrite, without touching the working tree:

$ repomatic run mdformat --verify -- changelog.md

It runs the write path against throwaway copies of the targets and diffs the results, rather than trusting the tool’s own --check or --dry-run mode. That distinction matters for a tool whose check mode relies on a repomatic post-processing step that only runs after an actual write: for those, --check can report drift the write path would reconcile, or miss drift the write path would introduce. --verify is the authoritative answer either way.

With no arguments after the tool name, --verify resolves the same defaults a bare repomatic run <tool> would, so repomatic run mdformat --verify checks every Markdown file in the repository.

A known mdformat defect¶

mdformat deletes the content of a backtick code span inside the alt-text of a Markdown image. It keeps the words around it and leaves a double space:

![A pear's `ripen` stage in a crate](pear.svg)

becomes:

![A pear's  stage in a crate](pear.svg)

The same code span in ordinary link text is kept, so the defect belongs to the image-alt path alone.

This is mdformat itself, not a plugin that repomatic bundles: it occurs with a bare mdformat and no plugins loaded. repomatic run mdformat therefore cannot prevent it, and the format-markdown job carries it into every consuming repository. The loss is silent, it applies to prose that is already committed, and no check reports it.

mdformat tracks the defect as hukkin/mdformat#414, where the maintainer records that a proper fix needs markdown-it-py synced with markdown-it 14.0.0. It is still present in mdformat 1.0.0.

Write image alt-text without code spans until mdformat corrects this. Removing the backticks is the stable repair: a restored code span is deleted again by the next format-markdown run.

Tool details¶

actionlint ¶

Stars Last release

Installed version: 1.7.12

Installation method: Binary (downloaded from GitHub Releases)

Config files: .github/actionlint.yaml, .github/actionlint.yml

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

Default flags: -color

Bundled default: actionlint.yaml

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 ¶

Stars Last release

Installed version: 2.3.2

Installation method: PyPI, installed via uvx

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

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

awesome-lint ¶

Last release

Installed version: 2.3.0

Installation method: npm registry, run via node_modules/.bin

Config: CLI flags only

CLI usage

Biome ¶

Stars Last release

Installed version: 2.5.14

Installation method: Binary (downloaded from GitHub Releases)

Config files: biome.json, biome.jsonc, .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 ¶

Stars Last release

Installed version: 1.5.1

Installation method: PyPI, installed via uvx

Config files: .bumpversion.toml and [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.

GitHub CLI ¶

Stars Last release

Installed version: 2.101.0

Installation method: Binary (downloaded from GitHub Releases)

Config: CLI flags only

Source | CLI usage

Try it:

$ repomatic run gh -- --version

Pinned so the release lane gets the same gh everywhere. The manylinux container the Linux binaries compile in ships no gh, and the runner images that do ship one leave its version to the image. gh reads no project configuration: it authenticates from GH_TOKEN in the environment.

Gitleaks ¶

Stars Last release

Installed version: 8.30.1

Installation method: Binary (downloaded from GitHub Releases)

Config files: .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 ¶

Stars Last release

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 ¶

Stars Last release

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 ¶

Stars Last release

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-shfmt
mdformat_simple_breaks
mdformat-toc
mdformat-web

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 ¶

Stars Last release

Installed version: 2.3.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. In a repository without a uv.lock there is no project virtualenv to freeze, so mypy runs in an isolated environment instead and only resolves the standard library: fine for standalone scripts, but dependency imports then report import-not-found.

uv run provisions only the default dependency groups, so a module that imports a dep declared solely in a non-default group (docs, typing, …) sees it as missing and mypy reports import-not-found. Either move the stub/dependency somewhere mypy resolves, or silence it with an override:

[[tool.mypy.overrides]]
module = "the_docs_only_package.*"
ignore_missing_imports = true

Nuitka ¶

Stars Last release

Installed version: 4.2.2

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 4.2 reads the section itself, but only under --project (Nuitka#3909). That mode takes its entry points from the project configuration, not from the command line, so repomatic keeps its own bridge.

Binaries skip tkinter by default, via the nuitka.nofollow-imports setting of [tool.repomatic]: set it to [] to bundle Tcl/Tk in a GUI project.

Oxipng ¶

Stars Last release

Installed version: 10.2.1

Installation method: Binary (downloaded from GitHub Releases)

Config: CLI flags only

Source | CLI usage

Try it:

$ repomatic run oxipng -- --opt 4 --strip safe image.png

Lossless PNG optimizer. repomatic format-images reaches it through repomatic.tooling.tool_runner.ensure_binary(), so the pinned, checksum-verified build is used instead of whatever the runner image or the distro archive supplies.

pyproject-fmt ¶

Stars Last release

Installed version: 2.29.4

Installation method: PyPI, installed via uvx

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

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 ¶

Stars Last release

Installed version: 0.16.8

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 ¶

Stars Last release

Installed version: 3.14.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 ¶

Stars Last release

Installed version: 1.50.2

Installation method: Binary (downloaded from GitHub Releases)

Config files: typos.toml, _typos.toml, .typos.toml and [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.

Because the fix-typos workflow job ships whatever typos rewrites as an unattended pull request, guard content where a “correction” is a corruption with [tool.typos.default.extend-ignore-re] patterns. The two known traps are encoded hashes, whose random letter runs typos happily respells (a Guix (base32 "...") source hash losing its value to an an-to-and fix), and intentional-typo examples that docs or tests exercise on purpose:

[tool.typos.default]
extend-ignore-re = [
  'base32 "[0-9a-z]{52}"',
  "\\{query\\}",
]

yamllint ¶

Stars Last release

Installed version: 1.38.0

Installation method: PyPI, installed via uvx

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

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

Stars Last release

Installed version: 1.30.1

Installation method: PyPI, installed via uvx

Config files: .github/zizmor.yml, .github/zizmor.yaml, zizmor.yml, 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.

The runner’s own API is documented on the repomatic.tooling.tool_runner page.

Tool runner¶

Why not run the tools directly?¶

Quick start¶

Available tools¶

Config resolution¶

Level 1: native config file¶

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

Level 3: bundled default¶

Level 4: bare invocation¶

Checking the active config source¶

Tutorial: adding yamllint to your project¶

Step 1: run with defaults¶

Step 2: customize via pyproject.toml¶

Step 3: graduate to a native config file¶

Cleaning up unmodified configs¶

Overriding tool versions¶

Binary caching¶

Running with no arguments¶

Passing extra arguments¶

Verifying without writing¶

A known mdformat defect¶

Tool details¶

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

Step 2: customize via `pyproject.toml`¶