CLI¶
Tip
Each [tool.repomatic] config option maps to CLI behavior. See the configuration reference for project-level defaults.
Help screen¶
$ repomatic --help
Usage: repomatic [OPTIONS] COMMAND [ARGS]...
Options:
--time / --no-time Measure and print elapsed execution time.
[default: no-time]
--config CONFIG_PATH Location of the configuration file. Supports
local path with glob patterns or remote URL.
[default: ~/.config/repomatic/{*.toml,*.yaml,*.ym
l,*.json,*.ini,pyproject.toml}]
--no-config Ignore all configuration files and only use
command line parameters and environment
variables.
--validate-config FILE Validate the configuration file and exit.
--export-config FORMAT Export the configuration in the selected format
to <stdout>, then exit.
--accessible Accessibility mode: disable colors and render
tables in a plain, screen-reader-friendly format.
--color [auto|always|never] Colorize the output. A bare --color is the same
as --color=always. [default: auto]
--no-color Disable colorization (alias of --color=never).
--progress / --no-progress Show progress indicators during long operations.
Disabled for non-interactive output (pipes, dumb
terminals, CI) and by --accessible. [default:
progress]
--theme [dark|dracula|light|manpage|monokai|nord|solarized_dark]
Color theme used for help screens. [default:
dark]
--params Show all CLI parameters, their provenance,
defaults and value, then exit.
--table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Rendering style of tables. [default: rounded-
outline]
--verbosity LEVEL Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
[default: WARNING]
-v, --verbose Increase the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
-q, --quiet Decrease the default WARNING verbosity by one
level for each additional repetition of the
option. [default: 0]
--tree Show the tree of nested subcommands and exit.
--man Show the command's man page (roff) and exit.
--version Show the version and exit.
--jobs [auto|max|INTEGER] Number of parallel jobs. Accepts an integer,
'auto' (one fewer than the host's logical CPUs)
or 'max' (all logical CPUs). 0 runs sequentially.
[default: auto]
-h, --help Show this message and exit.
GitHub issues & PRs:
apply-labels Label an issue or PR from its content and changed files
broken-links Manage broken links issue lifecycle
ci-status Report which CI jobs are red, and which of them gate a
merge
sync-runner-images Move runner images forward as GitHub retires and
supersedes them
job-timings Measure how long each runner image takes, from finished
runs
cancel-runs Cancel in-progress workflow runs for a branch
lock-threads Lock closed, inactive issues and PRs
pr-body Generate PR body with workflow metadata
pr-sync Create, refresh or retire an automation PR
setup-guide Manage setup guide issue lifecycle
sponsor-label Label issues/PRs from GitHub sponsors
unsubscribe-threads Unsubscribe from closed, inactive notification threads
Linting & checks:
audit Report (and optionally fix) vulnerable dependencies
cache Manage the download cache
fix-awesome-toc Remove the ToC entries awesome-lint forbids
lint-anchors Check same-page doc links against the built site
lint-changelog Check changelog dates against release dates
lint-deps Check dependencies resolve from the public index
lint-repo Run repository consistency checks
cloudflare-pages Reconcile the Cloudflare Pages project
run Run an external tool with managed config
verify-binary Verify binary architecture and OS floor
Release & versioning:
changelog Maintain a Markdown-formatted changelog
close-stale-bump-pr Close a stale version-bump PR
git-commit-push Commit files and push, rebasing on rejection
git-tag Create and push a Git tag
pack-attestation Name an attestation bundle after the asset it attests
pack-binaries Pack compiled binaries and their versionless aliases
pack-plugin Pack the skills and agents as a Claude Code plugin
prepare-release Prepare files for a release
scan-virustotal Upload release binaries to VirusTotal
sync-binaries Regenerate the binaries catalog page
Forge sampling:
sample-metrics Record what forges say about the repositories this
project tracks
Project setup:
update-dep-graph Generate dependency graph from uv lockfile
format-images Format images with lossless optimization
init Bootstrap a repository to use reusable workflows
list-skills List available Claude Code skills
metadata Output project metadata
show-config Print [tool.repomatic] configuration reference
show-test-matrix Render the CI test matrix as a grid
update-checksums Recompute SHA-256 checksums for the binary tool registry
update-docs Regenerate Sphinx API docs and dynamic content
workflow Lint downstream workflow caller files
Sync:
sync-action-pins Bump SHA-pinned GitHub Actions to their latest release
sync-bumpversion Sync bumpversion config from bundled template
sync-dep-sources Swap git-tracked dependencies to their released versions
sync-deps Update dependencies, all or a named subset
sync-dev-release Sync rolling dev pre-release on GitHub
sync-github-releases Sync GitHub release notes from changelog
sync-gitignore Sync .gitignore from gitignore.io templates
sync-labels Sync repository labels via labelmaker
sync-mailmap Sync Git's .mailmap file with missing contributors
sync-tool-versions Bump registry tool versions from upstream releases
sync-uv-lock Re-lock dependencies and roll cooldown overrides forward
sync-workflow-pins Bump npm/PyPI version literals in workflow YAML
Other commands:
help Show help for a command.
repomatic apply-labels¶
$ repomatic apply-labels --help
Usage: repomatic apply-labels [OPTIONS]
Label a freshly opened issue or pull request from the project's rules.
Two rule families, both tables under `[tool.repomatic.labels]` mapping a label
to the patterns that apply it, overlaid on the bundled defaults:
content-rules keywords or /regex/flags matched against the title and
body, of an issue or a pull request alike
file-rules globs matched against the paths a pull request changes
Additive only. A label already on the thread stays, and none is ever removed,
so a classification made by hand survives every later run.
This pre-labels for the maintainer's first pass and never replaces it, so the
rules are tuned for precision: a missing label costs one click, a wrong one is
noise on every issue that trips it.
Requires the gh CLI to be authenticated.
Examples:
# Preview what the current event's issue or PR would earn
repomatic apply-labels
# Apply them, as the labeller job does
repomatic apply-labels --live
# Manual invocation against one pull request
repomatic apply-labels --live --pr --number 42
Options:
--number INTEGER RANGE Issue or PR number. Defaults to the number in
$GITHUB_EVENT_PATH. [2m[[0m[36m[2mx>=1[0m[2m][0m
--pr / --issue Specify issue or pull request. Auto-detected from
$GITHUB_EVENT_PATH.
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
--dry-run / --live Report what would be done without making changes.
[default: dry-run]
-h, --help Show this message and exit.
repomatic audit¶
$ repomatic audit --help
Usage: repomatic audit [OPTIONS]
Scan locked dependencies for known security vulnerabilities.
Read-only by default: queries every advisory database enabled in
[tool.repomatic] vulnerable-deps.sources (default: uv-audit and
github-advisories), unions and deduplicates the results, and prints
them. The table respects the global --table-format option (github,
json, csv, etc.), so --table-format json yields a machine-readable
report. Report mode exits 1 when any vulnerability is found (use
--exit-zero to override), so it can gate CI.
With --fix, upgrades each fixable package with uv lock --upgrade-package
and:
- bypasses the exclude-newer cooldown for security fixes
- persists exclude-newer-package entries in pyproject.toml
- prints a markdown report of vulnerabilities and version changes
Examples:
# Report known vulnerabilities (read-only)
repomatic audit
# Machine-readable output
repomatic --table-format json audit
# Upgrade fixable packages (mutates uv.lock and pyproject.toml)
repomatic audit --fix
# CI autofix job: write the [35m[1mmarkdown[0m report as a step output
repomatic audit --fix --repo owner/name \
--output "$GITHUB_OUTPUT" --output-format github-actions
Options:
--lockfile FILE Path to the uv.lock file. [default: uv.lock]
--repo TEXT Repository in OWNER/NAME format. Enables the
GitHub Advisory Database source. Defaults to
GITHUB_REPOSITORY when set. [default:
(dynamic)]
--fix / --no-fix Upgrade fixable packages and persist cooldown
exemptions (mutates uv.lock and pyproject.toml).
Default: report only. [default: no-fix]
--exit-zero / --no-exit-zero In report mode, exit 0 even when vulnerabilities
are found. [default: no-exit-zero]
--output FILE Write a markdown report to this file.
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
--sort-by [package|version|advisory|fixed|sources]
Sort table by this column. Repeat to set
priority. [default: package]
-h, --help Show this message and exit.
repomatic broken-links¶
$ repomatic broken-links --help
Usage: repomatic broken-links [OPTIONS]
Manage the broken links issue lifecycle.
Combines Lychee and Sphinx linkcheck results into a single "Broken links"
issue. Creates, updates, or closes the issue based on results.
Requires the gh CLI to be authenticated.
In GitHub Actions, most options are auto-detected:
- --repo-name defaults to $GITHUB_REPOSITORY name component.
- --body-file defaults to ./lychee/out.md when --lychee-exit-code is set.
- --output-json defaults to ./docs/_linkcheck/output.json if it exists.
- --source-url is composed from $GITHUB_SERVER_URL, $GITHUB_REPOSITORY,
and $GITHUB_SHA when --output-json is set.
Examples:
# In GitHub Actions (auto-detection)
repomatic broken-links --lychee-exit-code 2
# Explicit options
repomatic broken-links \
--lychee-exit-code 2 \
--body-file ./lychee/out.md \
--repo-name "my-repo"
Options:
--lychee-exit-code INTEGER Exit code from lychee (0=no broken links, 2=broken
links found).
--body-file FILE Path to the issue body file (lychee output).
--output-json FILE Path to Sphinx linkcheck output.json file.
--source-url TEXT Base URL for linking filenames and line numbers in
the Sphinx report. Example:
https://github.com/owner/repo/blob/<sha>/docs
--repo-name TEXT Repository name (for label selection). Defaults to
$GITHUB_REPOSITORY name component.
-h, --help Show this message and exit.
repomatic cache¶
$ repomatic cache --help
Usage: repomatic cache [OPTIONS] COMMAND [ARGS]...
Manage the local download cache.
Binary tools and HTTP API responses are cached to avoid redundant downloads.
This group provides subcommands to inspect, clean, and locate the cache.
Options:
-h, --help Show this message and exit.
Commands:
clean Remove cached entries
help Show help for a command.
path Print the cache directory path
show List cached entries
repomatic cache clean¶
$ repomatic cache clean --help
Usage: repomatic cache clean [OPTIONS]
Remove cached binaries, tool configs and HTTP responses.
Without options, removes everything. Use --tool to target a specific binary
tool and its cached config, --namespace for a specific HTTP namespace, or
--max-age for entries older than a threshold.
Examples:
repomatic cache clean
repomatic cache clean --tool ruff
repomatic cache clean --namespace pypi
repomatic cache clean --max-age 7
Options:
--tool TEXT Only remove the binary and config entries for this tool.
--namespace TEXT Only remove HTTP entries in this namespace (e.g., pypi,
github-releases).
--max-age INTEGER Only remove entries older than this many days.
-h, --help Show this message and exit.
repomatic cache help¶
$ repomatic cache help --help
Usage: repomatic cache help [OPTIONS] [COMMAND_PATH]...
Show help for a command.
Options:
--search TEXT Search all subcommands for matching options or descriptions.
-h, --help Show this message and exit.
repomatic cache path¶
$ repomatic cache path --help
Usage: repomatic cache path [OPTIONS]
Print the absolute path to the cache directory.
Useful for CI integration with actions/cache or similar tools.
Options:
-h, --help Show this message and exit.
repomatic cache show¶
$ repomatic cache show --help
Usage: repomatic cache show [OPTIONS]
List all cached binaries and HTTP responses.
Options:
--sort-by [type|name|detail|size|age]
Sort table by this column. Repeat to set priority. [default:
name]
-h, --help Show this message and exit.
repomatic cancel-runs¶
$ repomatic cancel-runs --help
Usage: repomatic cancel-runs [OPTIONS]
Cancel the in-progress and queued workflow runs of a branch.
Fired when a pull request closes: GitHub does not cancel PR-triggered runs on
close, so the branch's live runs would burn CI minutes to completion. The
repository is resolved by the gh CLI from GH_REPO or the current checkout.
Examples:
# From the [97m[1mcancel-runs[0m workflow, sparing its own run
repomatic cancel-runs --branch "$BRANCH"
Options:
--branch TEXT Head branch whose in-progress and queued runs to
cancel. [required]
--current-run-id TEXT Run ID to spare (the cancelling run itself). Defaults
to $GITHUB_RUN_ID. [default: ""]
-h, --help Show this message and exit.
repomatic changelog¶
$ repomatic changelog --help
Usage: repomatic changelog [OPTIONS] [CHANGELOG_PATH]
Stamp the changelog with the current version's release header.
Options:
--source FILE Changelog source file. Defaults to the configured
changelog.location.
--default-branch TEXT Branch name the unreleased comparison URL points at.
[default: main]
-h, --help Show this message and exit.
repomatic ci-status¶
$ repomatic ci-status --help
Usage: repomatic ci-status [OPTIONS]
Report the latest CI run of each workflow, and what is actually broken.
Reads jobs rather than runs, so a crashed allowed-failure probe cannot hide
inside a green run conclusion and a run still reading "queued" cannot hide the
dozen jobs of it that already finished.
A job whose name carries the unstable glyph anywhere is allowed to fail and
never affects the exit code. Every other job is required, including the non-
matrix ones that carry no glyph at all.
Examples:
# What is red on main right now
repomatic ci-status
# One [35m[1mworkflow[0m, without failing the shell
repomatic ci-status --workflow tests.yaml --no-fatal
Options:
--branch TEXT Branch whose latest run of each workflow to read.
[default: main]
--workflow TEXT Workflow file to read, repeatable. Defaults to every
workflow a push can start, derived from
.github/workflows/.
--fatal / --no-fatal Exit non-zero when a required job failed. [default:
fatal]
--sort-by [workflow|commit|run-status|verdict]
Sort table by this column. Repeat to set priority.
[default: workflow]
-h, --help Show this message and exit.
repomatic close-stale-bump-pr¶
$ repomatic close-stale-bump-pr --help
Usage: repomatic close-stale-bump-pr [OPTIONS]
Close the minor/major version-increment PR when a bump is no longer allowed.
The changelog workflow's bump-version job opens a draft PR on the
"<part>-version-increment" branch whenever a bump is allowed. A scheduled run
that started before a competing push can open this PR against a main branch
that has already advanced past the target, leaving an orphan that subsequent
scheduled runs cannot refresh.
This command reconciles that state: it re-evaluates the gate against the
current checkout and, when the bump is no longer allowed, closes any open PR
on the matching branch (deleting the branch). When the bump is still allowed,
it leaves the PR alone so the standard bump flow can update it.
Idempotent: a no-op when no open PR exists on the target branch.
Examples:
repomatic close-stale-bump-pr --part minor
repomatic close-stale-bump-pr --part major
Options:
--part [minor|major] The version part whose bump PR should be reconciled.
[required]
-h, --help Show this message and exit.
repomatic cloudflare-pages¶
$ repomatic cloudflare-pages --help
Usage: repomatic cloudflare-pages [OPTIONS]
Reconcile the Cloudflare Pages project against the declared state.
A Direct Upload project's live settings (compatibility date, Smart Placement,
build image, attached source) exist only server-side, where they drift with
nothing watching. This command diffs them against the `[tool.repomatic]
site.*` declarations, enforces them, and warns when the API token is within a
month of its expiry, which Cloudflare itself never signals.
Credentials come from CLOUDFLARE_API_TOKEN, falling back to the OAuth token a
local `wrangler login` stored. The account is derived from the credential at
run time, never declared beside it.
Examples:
# In CI: fail the job when the live project drifted
repomatic cloudflare-pages --check
# Write the declared compatibility date and placement back
repomatic cloudflare-pages --apply
# Rebuild from nothing: create the project if missing, then configure
# it. An existing project is reconciled, not re-created.
repomatic cloudflare-pages --create --project my-site
# Serve the project at a custom domain, DNS record included
repomatic cloudflare-pages --attach-domain example.com
Options:
--project TEXT Cloudflare Pages project to reconcile. Defaults to
[tool.repomatic] site.cloudflare-project, then to the
repository name.
--check Diff the live project against the declared state; exit
1 on drift.
--apply Write the declared values back to the live project.
--dump Print the live project state as JSON, secrets
redacted.
--create Create the Direct Upload project when missing, then
apply the declared values: the rebuild-from-nothing
verb. An existing project is reused and reconciled, so
re-running is safe.
--attach-domain DOMAIN Serve the project at DOMAIN, creating the proxied
CNAME it needs. The API attaches a hostname without
any DNS, unlike the dashboard, leaving the domain
pending forever; this does both.
-h, --help Show this message and exit.
repomatic fix-awesome-toc¶
$ repomatic fix-awesome-toc --help
Usage: repomatic fix-awesome-toc [OPTIONS]
Remove the table-of-contents entries awesome-lint forbids.
Deletes the Contents, Contributing, Footnotes and Related Lists entries from
the mdformat-toc block of readme.md and of every readme.{lang}.md translation
beside it.
A translation names those sections in its own language, so they are
matched by their position in the heading sequence of readme.md rather
than by name.
Run it right after mdformat regenerates the ToC: mdformat-toc lists every
heading it finds and has no way to leave one out.
Example:
repomatic fix-awesome-toc
Options:
-h, --help Show this message and exit.
repomatic format-images¶
$ repomatic format-images --help
Usage: repomatic format-images [OPTIONS]
Format images by losslessly optimizing them with external CLI tools.
Discovers PNG and JPEG files and compresses them losslessly in-place using
oxipng and jpegoptim. Produces a markdown summary table showing before/after
sizes and savings.
Only lossless optimizers are used so that results are idempotent: running the
command twice produces no further changes.
Required tools:
oxipng is downloaded and checksum-verified from the pinned tool
registry, once per run. jpegoptim has to be on $PATH:
sudo apt-get install jpegoptim
Examples:
# Format images and print summary
repomatic format-images
# CI: write as a GitHub Actions step output
repomatic format-images \
--output "$GITHUB_OUTPUT" --output-format github-actions
# Use a 10% minimum savings threshold
repomatic format-images --min-savings 10
Options:
--min-savings FLOAT RANGE Minimum percentage savings to keep an optimized
file. [default: 5; 0<=x<=100]
--min-savings-bytes INTEGER RANGE
Minimum absolute byte savings to keep an optimized
file. [default: 1024; x>=0]
--output FILE Output file path. Defaults to stdout. [default: -]
--output-format [markdown|github-actions]
Format for --output. github-actions produces format
for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic git-commit-push¶
$ repomatic git-commit-push --help
Usage: repomatic git-commit-push [OPTIONS] [PATHS]...
Commit the given files and push them to a remote branch.
Idempotent: exits successfully without creating a commit when the files are
unchanged. A rejected push (something else pushed meanwhile) is retried after
rebasing onto the fresh remote tip, so release jobs can publish generated
files to the default branch without racing other pushes. Works from a detached
HEAD.
With --all-changes, everything the working tree carries is staged rather than
a named list. Reserved for a job whose writers are the steps right before it
and whose output paths only its configuration knows.
Examples:
repomatic git-commit-push --message "Record v1.2.3 binaries" \
docs/binaries.md docs/assets/virustotal-scans.csv
repomatic git-commit-push --message "Sample star counts" --all-changes
Options:
--message TEXT Commit message. [required]
--remote TEXT Remote to push to. [default: origin]
--branch TEXT Remote branch to push to. [default: main]
--all-changes / --no-all-changes
Stage every change in the working tree instead of named files,
for a job whose output paths come from configuration.
[default: no-all-changes]
-h, --help Show this message and exit.
repomatic git-tag¶
$ repomatic git-tag --help
Usage: repomatic git-tag [OPTIONS]
Create and optionally push a Git tag.
This command is idempotent: if the tag already exists and --skip-existing is
used, it exits successfully without making changes. This allows safe re-runs
of workflows interrupted after tag creation.
Examples:
# Create and push a tag
repomatic git-tag --tag v1.2.3
# Tag a specific commit
repomatic git-tag --tag v1.2.3 --commit abc123def
# Create tag without pushing
repomatic git-tag --tag v1.2.3 --no-push
# Fail if tag exists
repomatic git-tag --tag v1.2.3 --error-existing
# Output result for GitHub Actions
repomatic git-tag --tag v1.2.3 --output "$GITHUB_OUTPUT"
Options:
--tag TEXT Tag name to create (e.g., v1.2.3). [required]
--commit TEXT Commit to tag. Defaults to HEAD.
--push / --no-push Push the tag to remote after creation. [default: push]
--skip-existing / --error-existing
Skip silently if tag exists, or fail with an error.
[default: skip-existing]
-o, --output FILE Output file for created=true/false (e.g., $GITHUB_OUTPUT).
-h, --help Show this message and exit.
repomatic help¶
$ repomatic help --help
Usage: repomatic help [OPTIONS] [COMMAND_PATH]...
Show help for a command.
Options:
--search TEXT Search all subcommands for matching options or descriptions.
-h, --help Show this message and exit.
repomatic init¶
$ repomatic init --help
Usage: repomatic init [OPTIONS] [COMPONENT[/FILE]]...
Bootstrap a repository to use reusable workflows from kdeldycke/repomatic.
With no arguments, generates thin-caller workflow files, exports configuration
files (labels), and creates a minimal changelog. Specify COMPONENTS to
initialize only selected parts.
Scope restrictions (awesome-only, non-awesome) and [tool.repomatic] exclude
entries only apply during bare init (no arguments). Explicitly naming a
component bypasses scope, allowing workflows to materialize out-of-scope
configs at runtime.
Selectors use the same syntax as the exclude config in [tool.repomatic]: bare
names select an entire component, qualified component/file entries select a
single file.
The derived upstream pin honors the [tool.repomatic] minimum-release-age
cooldown when it would adopt a release newer than the one already pinned in
this repository: if the running repomatic version is still inside that window,
the workflow pin steps back to the newest release that has cleared it, and
never below the pin already on disk. Re-running init at the pinned version
leaves it untouched. Pass --no-cooldown to pin the running version
immediately, or --version to pin an exact tag.
Components:
labels Label definitions for labelmaker (labels.toml)
publish-pypi-action Composite action that publishes to PyPI via Trusted Publishing (.github/actions/publish-pypi/)
subagents Agent subagent definitions (.claude/agents/)
skills Claude Code skill definitions (.claude/skills/)
workflows Thin-caller workflow files
awesome-template Boilerplate for awesome-* repositories
changelog Minimal changelog.md
plugin Claude Code plugin marketplace wiring (.claude/settings.json)
agent Audience-tagged sections of the agent instructions file
uv uv resolver pin and dependency cooldown policy
lychee Lychee link checker configuration
ruff Ruff linter/formatter configuration
pytest Pytest test configuration
coverage Coverage.py measurement and reporting configuration
mypy Mypy type checking configuration
mdformat mdformat Markdown formatter configuration
bumpversion bump-my-version configuration
typos Typos spell checker configuration
File-level selectors (labels, publish-pypi-action, subagents, skills, workflows):
workflows/autofix.yaml A single workflow
skills/repomatic-topics A single skill
labels/labels.toml A single label config file
Examples:
# Full bootstrap (workflows + labels + changelog)
repomatic init
# Pin to a specific version
repomatic init --version v5.9.1
# Adopt the running version now, skipping the release-age cooldown
repomatic init --no-cooldown
# Install a single skill
repomatic init skills/repomatic-topics
# One workflow + all labels
repomatic init workflows/autofix.yaml labels
# Only merge ruff config into pyproject.toml
repomatic init ruff
# Multiple components
repomatic init ruff bumpversion
Options:
--version TEXT Version pin for upstream workflows (e.g.,
v5.10.0). Defaults to the latest release derived
from the package version.
--cooldown / --no-cooldown When adopting a repomatic release newer than the
one this repository already pins, hold the
upstream pin back to the newest release past the
[tool.repomatic] minimum-release-age window. Never
moves a pin at or above the running version. --no-
cooldown pins the running repomatic version
immediately. Ignored when --version is set.
[default: cooldown]
--upstream-repo TEXT Upstream repository containing reusable workflows.
[default: kdeldycke/repomatic]
--output-dir DIRECTORY Root directory of the target repository.
[default: .]
--delete-excluded Delete files that are excluded by config but still
on disk.
--delete-unmodified Delete config files identical to bundled defaults.
--keep-removed Keep orphaned files of assets repomatic no longer
ships (report them instead of auto-pruning).
--delete-removed-modified Also delete orphaned files of removed assets that
were modified locally (normally reported for
manual review, never deleted).
-h, --help Show this message and exit.
repomatic job-timings¶
$ repomatic job-timings --help
Usage: repomatic job-timings [OPTIONS]
Report median whole-job wall-clock per runner image.
Runner choice is supposed to rest on measurement, and the measurement that
matters is whole-job: this repository once kept a lean image for years on a
benchmark that timed only the tool pass, where it looked near-parity, while
end to end it was 20-56% slower. The jobs API reports start and end
timestamps, so what this reads is whole-job by construction.
Only successful runs are sampled, because a failed run's jobs stop early and
time where the failure landed rather than what the image costs. The figure is
a median across several runs, which is what turns a queue stall into noise
instead of a verdict.
Examples:
# Which image is holding the matrix up
repomatic job-timings
# A wider sample, written out for documentation
repomatic job-timings --limit 10 --output timings.md
Options:
--workflow TEXT Workflow file whose runs to sample. [default: tests.yaml]
--branch TEXT Branch whose runs to sample. [default: main]
--limit INTEGER How many recent successful runs to sample. [default: 5]
--output FILE Write the report as a Markdown table to this file, for
documentation.
--sort-by [runner|jobs|median|slowest-job|slowest]
Sort table by this column. Repeat to set priority. [default:
median]
-h, --help Show this message and exit.
repomatic lint-anchors¶
$ repomatic lint-anchors --help
Usage: repomatic lint-anchors [OPTIONS]
Check every same-page link resolves to an anchor the build produced.
A literal (#fragment) link is copied into the HTML untouched, so a fragment
naming a slug that was never generated ships as a link that looks fine and
lands nowhere. Sphinx cannot catch it, having nothing to resolve, and a
Markdown link checker has to guess the slug rather than read it, which is a
different answer often enough to be useless.
Only fragments written in the Markdown sources are checked, so a theme's own
footnote backrefs and header permalinks are never mistaken for something an
author asked for.
Run it against a site that has just been built: an out-of-date build directory
answers for the pages it was made from.
Examples:
# Defaults, straight after a Sphinx build
repomatic lint-anchors
# A tree built elsewhere
repomatic lint-anchors --docs-dir ./docs --build-dir /tmp/site
Options:
--docs-dir DIRECTORY Root of the documentation sources to read links from.
[default: docs]
--build-dir DIRECTORY Root of the rendered site to resolve those links
against. [default: docs/_build]
-h, --help Show this message and exit.
repomatic lint-changelog¶
$ repomatic lint-changelog --help
Usage: repomatic lint-changelog [OPTIONS]
Verify that changelog release dates match canonical release dates.
Uses PyPI upload dates as the canonical reference when the project is
published to PyPI. Falls back to git tag dates for non-PyPI projects.
PyPI timestamps are immutable and reflect the actual publication date, making
them more reliable than git tags which can be recreated.
Also detects orphaned versions: versions that exist as git tags, GitHub
releases, or PyPI packages but have no corresponding changelog entry. Orphans
cause a non-zero exit code.
Reads pypi-package-history from [tool.repomatic] to fetch releases published
under former package names (for renamed projects).
Reads abandoned-versions from [tool.repomatic] to skip "not found on PyPI"
warnings for releases that were frozen but never published (skip-and-move-
forward releases).
Reads changelog.bullet-word-threshold from [tool.repomatic] to warn, non-
fatally, about unreleased changelog bullets longer than that many words. A
changelog entry is a release note, not a commit message.
Warns, non-fatally, about a released section holding no entry: a published
release heading with nothing under it reads as broken to anyone scanning the
notes for that version.
Output symbols:
✓ Dates match
⚠ Version not found on reference source (warning, non-fatal)
✗ Date mismatch (error, fatal)
With --fix, the command also:
- Corrects mismatched dates to match the canonical source.
- Adds a PyPI link admonition under each released version.
- Adds a CAUTION admonition for yanked releases.
- Adds a WARNING admonition for versions not on PyPI.
- Inserts placeholder sections for orphaned versions.
Exit codes:
0 All dates match, or --fix corrected the file.
1 Date mismatch or orphan detected without --fix.
2 Sanity gate refused to rewrite: upstream lookup (PyPI or
GitHub Releases) looks unhealthy and the existing changelog
has substantial coverage that would be silently stripped.
Re-run when the API is reachable.
Examples:
# Check the default changelog.md (auto-detects PyPI package)
repomatic lint-changelog
# Fix dates and add admonitions
repomatic lint-changelog --fix
# Explicit package name
repomatic lint-changelog --package repomatic
Options:
--changelog FILE Path to the changelog file. Defaults to the configured
changelog.location.
--package TEXT PyPI package name for date lookups. Auto-detected from
pyproject.toml.
--fix Fix date mismatches and add PyPI admonitions to the
changelog.
-h, --help Show this message and exit.
repomatic lint-deps¶
$ repomatic lint-deps --help
Usage: repomatic lint-deps [OPTIONS]
Check that every dependency resolves from the index users install from.
A dependency is shippable when whoever installs the published artifact gets
the same code the release was tested against. A git branch, a local path, a
fork, a direct URL or a private index all break that, and most of them break
it silently: a `[tool.uv.sources]` override never reaches the published
metadata, so the wheel builds and uploads exactly as it would have, and only
the install fails.
Runs entirely offline, reading pyproject.toml and uv.lock. The lockfile pass
is what catches a source override on a package no table names, since it
records the resolved origin of the whole tree.
Reads lint-deps.allow from [tool.repomatic] for packages exempted by name,
each mapped to the reason it is safe, and lint-deps.comment-word-threshold for
the length a floor comment may run to.
Output symbols:
✗ Blocks a release
⚠ Warning, does not block
ℹ Covered by lint-deps.allow
Exit codes:
0 Nothing blocks a release, or --no-fatal was passed.
1 At least one finding blocks a release.
Examples:
# Check the current project
repomatic lint-deps
# Report without failing, for an ordinary CI push
repomatic lint-deps --no-fatal
# Emit a [35m[1mmarkdown[0m report for a PR body
repomatic lint-deps --no-fatal --output report.md
Options:
--pyproject FILE Path to the pyproject.toml file. [default:
pyproject.toml]
--lockfile FILE Path to the uv.lock file. [default: uv.lock]
--fatal / --no-fatal Exit non-zero when a finding blocks a release. Pass
--no-fatal to report without failing, for continuous
visibility on ordinary pushes. [default: fatal]
--policy / --no-policy Also report declarations departing from the project's
version policy: upper bounds, missing floors, unsorted
lists, misplaced type stubs, uncommented and over-long
floor comments. Never blocks a release. [default:
policy]
--output FILE Write a markdown report of the blocking findings to
this file.
--output-format [markdown|github-actions]
Format for --output. github-actions produces format
for PR template consumption in workflows. [default:
markdown]
--sort-by [package|kind|location|verdict]
Sort table by this column. Repeat to set priority.
[default: package]
-h, --help Show this message and exit.
repomatic lint-repo¶
$ repomatic lint-repo --help
Usage: repomatic lint-repo [OPTIONS]
Run consistency checks on repository metadata.
Reads package_name, is_sphinx, and project_description from pyproject.toml in
the current directory.
Checks:
- Package name vs repository name (warning).
- Website field set for Sphinx projects, and matching the documentation
URL declared in [project.urls] (warning).
- Repository description matches project description (error).
- Inline upstream pins match the version the uses: refs name (error).
- Inline upstream pins resolving under a cooldown carry their
--exclude-newer-package exemption (error).
- Workflows only ask repomatic metadata for keys it still emits (error).
- Every astral-sh/setup-uv step pins one uv version (warning).
- GitHub topics subset of pyproject.toml keywords (warning).
- Funding file present when owner has GitHub Sponsors (warning).
- Stale draft releases (non-.dev0 drafts) (warning).
- Install guide download URLs resolve to real release assets (warning).
- Repository-local PR body templates sit in .github/pr-templates/
and carry valid frontmatter (warning).
- Fork PR workflow approval policy strict enough (warning).
- VIRUSTOTAL_API_KEY secret missing when Nuitka is active (warning).
- REPOMATIC_NOTIFICATIONS_PAT secret missing when the unsubscribe
workflow is enabled (warning).
- CLOUDFLARE_API_TOKEN secret missing when site.deploy targets
Cloudflare Pages (warning).
- Legacy github.io URLs still redirect, for a project that moved its
site to Cloudflare Pages (warning).
- Committed _redirects files survive the Cloudflare Pages engine:
no dropped rules, no silent budget abort (error).
- wrangler.toml agrees with the declared Cloudflare project name and
compatibility date (warning).
When a PAT is detected, additional capability checks are run:
- Contents permission (error).
- Issues permission (error).
- Pull requests permission (error).
- Dependabot alerts permission and alerts enabled (error).
- Workflows permission (error).
Examples:
# In GitHub Actions (reads pyproject.toml automatically)
repomatic lint-repo --repo-name my-package
# Local run (derives repo from $GITHUB_REPOSITORY or [36m[1m--repo[0m)
repomatic lint-repo --repo owner/repo
# With PAT capability checks
repomatic lint-repo --has-pat
Options:
--repo-name TEXT Repository name. Defaults to $GITHUB_REPOSITORY
name component.
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
--has-cloudflare-api-token Whether CLOUDFLARE_API_TOKEN is configured.
--has-notifications-pat Whether REPOMATIC_NOTIFICATIONS_PAT is configured.
--has-pat / --no-has-pat Whether REPOMATIC_PAT is configured, enabling the
PAT capability checks. Auto-detected from the
REPOMATIC_PAT environment variable when omitted.
[default: (dynamic)]
--has-virustotal-key Whether VIRUSTOTAL_API_KEY is configured.
-h, --help Show this message and exit.
repomatic list-skills¶
$ repomatic list-skills --help
Usage: repomatic list-skills [OPTIONS]
List all bundled Claude Code skills grouped by lifecycle phase.
Reads skill definitions from the bundled data files and displays them in a
table grouped by phase: Setup, Development, Quality, and Release.
Options:
-h, --help Show this message and exit.
repomatic lock-threads¶
$ repomatic lock-threads --help
Usage: repomatic lock-threads [OPTIONS]
Lock closed issues and pull requests left inactive too long.
Keeps spam and necro-posting off threads whose discussion is over, without
touching anything still moving: the clock counts from a thread's last update,
so a closed issue people are still replying to keeps resetting it.
Locking is one-way here. Nothing unlocks a thread on a schedule, and a thread
already locked never reappears in the search, so re-running the command right
after a run finds nothing left to do.
Issues repomatic maintains itself are excluded by default: they are meant to
reopen when their condition recurs, which a lock would block.
Requires the gh CLI to be authenticated.
Examples:
# Preview what a run would lock
repomatic lock-threads
# Lock them, as the autolock workflow does
repomatic lock-threads --live
# Lock silently after six months, sparing triaged threads
repomatic lock-threads --live --inactive-days 180 \
--issue-comment "" --exclude-label "🚧 needs triage"
Options:
--inactive-days INTEGER RANGE Days without activity before a closed thread is
locked. [default: 90; x>=1]
--issue-comment TEXT Comment posted on an issue before locking it.
Empty to post none. [default: This issue has
been automatically locked since there has not
been any recent activity after it was closed.
Please open a new issue for related bugs.]
--pr-comment TEXT Comment posted on a pull request before locking
it. Empty to post none. [default: This pull
request has been automatically locked since
there has not been any recent activity after it
was closed. Please open a new issue for related
bugs.]
--exclude-label TEXT Leave threads carrying this label unlocked.
Repeatable. [default: 🤖 ci]
--limit INTEGER RANGE Maximum number of threads to examine in one
run. [default: 200; 1<=x<=1000]
--reason [off_topic|resolved|spam|too_heated]
Reason recorded with the lock. [default:
resolved]
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
--dry-run / --live Report what would be done without making
changes. [default: dry-run]
-h, --help Show this message and exit.
repomatic metadata¶
$ repomatic metadata --help
Usage: repomatic metadata [OPTIONS] [KEYS]...
Dump project metadata to a file.
Prints all metadata keys to stdout by default. Use --output to write to a
file. Pass key names as arguments to filter output.
Examples:
repomatic metadata current_version is_python_project
repomatic metadata --list-keys
repomatic metadata --format github-json --output "$GITHUB_OUTPUT" \
current_version is_python_project
Options:
--format [github|github-json|json]
Rendering format of the metadata. [default:
github]
--overwrite, --force, --replace / --no-overwrite, --no-force, --no-replace
Overwrite output file if it already exists.
[default: overwrite]
-o, --output FILE Output file path. Defaults to stdout. [default:
-]
--list-keys List all available metadata keys with
descriptions and exit.
--sort-by [key|description] Sort table by this column. Repeat to set
priority. [default: key]
-h, --help Show this message and exit.
repomatic pack-attestation¶
$ repomatic pack-attestation --help
Usage: repomatic pack-attestation [OPTIONS]
Rename an attestation bundle after its subject, print the upload list.
actions/attest writes every bundle to the same `attestation.json` basename, so
a release attaching several would keep only the last. This reads back the
subjects the bundle actually attests, names it after them, and prints every
file the release upload step should attach: the assets and their bundle, one
path per line.
A bundle covering several assets has no single name to take, so pass --name to
name the set instead.
Idempotent: re-running copies the same bytes over the same name.
Examples:
# Single asset, named papaya.tar.gz.attestation.json
repomatic pack-attestation --bundle "${BUNDLE_PATH}"
# A glob's worth of assets, all covered by one bundle
repomatic pack-attestation --bundle b.json --dir dist --name papaya-set
Options:
--bundle FILE Attestation bundle written by actions/attest. [required]
--dir DIRECTORY Directory holding the attested assets, and where the bundle
lands. [default: .]
--name TEXT Stem naming the set, for a bundle attesting more than one
asset.
-h, --help Show this message and exit.
repomatic pack-binaries¶
$ repomatic pack-binaries --help
Usage: repomatic pack-binaries [OPTIONS]
Materialize versionless binary aliases and print the upload list.
Copies each versioned binary (`repomatic-1.2.3-linux-arm64.bin`) to its
versionless alias (`repomatic-linux-arm64.bin`) so the stable
releases/latest/download URLs always resolve, then prints every file the
release upload step should attach, one path per line. Python distributions
(.tar.gz, .whl) are skipped: create-release already uploaded them.
Idempotent: re-running overwrites the same aliases with the same bytes.
Examples:
repomatic pack-binaries --version 1.2.3 --dir ./compile-assets
Options:
--version TEXT Release version whose binaries earn versionless aliases.
[required]
--dir DIRECTORY Directory holding the compiled binaries and attestation
bundles. [required]
-h, --help Show this message and exit.
repomatic pack-plugin¶
$ repomatic pack-plugin --help
Usage: repomatic pack-plugin [OPTIONS]
Pack the bundled skills and agents into a Claude Code plugin archive.
Assembles `.claude-plugin/plugin.json` and every skill and agent the component
registry declares into a zip holding a single top-level folder, which the
release lane attaches to each GitHub release. The archive is byte-
deterministic, so re-packing an unchanged tree produces an identical file.
Examples:
# Pack into the default ./repomatic-claude-plugin.zip
repomatic pack-plugin
# Install the packed plugin locally, without a marketplace
repomatic pack-plugin --output /tmp/repomatic-claude-plugin.zip
unzip /tmp/repomatic-claude-plugin.zip -d /tmp/plugin
claude --plugin-dir /tmp/plugin/repomatic
Options:
--output FILE Destination path of the plugin archive. [default: ./repomatic-
claude-plugin.zip]
-h, --help Show this message and exit.
repomatic pr-body¶
$ repomatic pr-body --help
Usage: repomatic pr-body [OPTIONS]
Generate a PR body with a collapsible workflow metadata block.
Reads GITHUB_* environment variables to produce a <details> block listing the
workflow metadata (documentation, trigger, actor, ref, commit, job, workflow,
run).
The prefix can be set via --template (built-in templates), --prefix (arbitrary
content, also via GHA_PR_BODY_PREFIX env var) or --prefix-file (the same
content read from a file, also via GHA_PR_BODY_PREFIX_FILE). If a template and
a prefix are both given, the prefix is prepended before the rendered template
content.
Examples:
# Preview metadata block locally
repomatic pr-body
# CI: write as GitHub Actions step outputs
repomatic pr-body --output "$GITHUB_OUTPUT" \
--output-format github-actions
# Use a built-in template
repomatic pr-body --template bump-version \
--version 1.2.0 --part minor
# Use a downstream-shipped template with custom variables
repomatic pr-body --template-file path/to/template.md \
--template-arg fruit=mango --template-arg crate=10
# With a prefix via environment variable
GHA_PR_BODY_PREFIX="Fix formatting" repomatic pr-body
Options:
--prefix TEXT Content to prepend before the metadata details
block. Can also be set via the
GHA_PR_BODY_PREFIX environment variable.
[default: ""]
--prefix-file FILE Read the prefix from a file instead of --prefix,
for a report too large to travel in an
environment variable. Can also be set via the
GHA_PR_BODY_PREFIX_FILE environment variable.
Wins over --prefix when both are given.
--template [available-admonition|broken-links-issue|bump-version|detect-squash-merge|development-warning|fix-changelog|fix-typos|fix-vulnerable-deps|format-images|format-json|format-markdown|format-pyproject|format-python|format-shell|generated-footer|github-releases|immutable-releases|pr-metadata|prepare-release|refresh-tip|release-notes|release-sync-report|setup-guide|setup-guide-branch-ruleset|setup-guide-cloudflare-pages|setup-guide-dependabot|setup-guide-fork-pr-approval|setup-guide-notifications-pat|setup-guide-pages-source|setup-guide-pypi-trusted-publisher|setup-guide-sha-pinning-required|setup-guide-token|setup-guide-verify|setup-guide-virustotal|sync-action-pins|sync-bumpversion|sync-dep-sources|sync-gitignore|sync-mailmap|sync-repomatic|sync-runner-images|sync-tool-versions|sync-uv-lock|sync-workflow-pins|unavailable-admonition|unsubscribe-phase1|unsubscribe-phase2|update-dep-graph|update-docs|yanked-admonition]
Use a built-in prefix template instead of
--prefix.
--template-file FILE Use an external template file (markdown with
optional YAML frontmatter). Mutually exclusive
with --template. Lets downstream repos ship
project-specific PR templates without modifying
repomatic. Templates should set 'footer: false'
in their frontmatter to avoid duplicating the
attribution footer that ships with the metadata
block.
--template-arg KEY=VALUE Pass an arbitrary key/value pair to the
template. Repeat to provide multiple. Use this
to feed template variables not covered by the
dedicated --version / --part / --pr-ref flags.
Example: --template-arg channel=Nix.
--template-arg-file KEY=PATH Read a template value from a file. Repeat to
provide multiple. Use this for a value with no
ceiling on its size, like a generated table: a
report travels as a path rather than inline.
Example: --template-arg-file
summary=proposal.md.
--version TEXT Version string passed to the template (e.g.
1.2.0).
--part TEXT Version part passed to the bump-version template
(e.g. minor, major).
--pr-ref TEXT PR reference passed to detect-squash-merge
template (e.g. #2316).
--output FILE Output file path. Defaults to stdout. [default:
-]
--output-format [markdown|github-actions]
Format for --output. 'github-actions' wraps
body, title, and commit_message as step output
variables. [default: markdown]
-h, --help Show this message and exit.
repomatic pr-sync¶
$ repomatic pr-sync --help
Usage: repomatic pr-sync [OPTIONS]
Converge a branch and its PR onto whatever the working tree holds.
Opens the pull request when the tree carries changes, refreshes it when those
changes moved, does nothing at all when the branch already matches, and closes
the PR (deleting the branch) once the changes are gone.
Idempotent: re-running with an unchanged tree performs no write, so a workflow
re-run never churns the PR or re-triggers its checks.
With --template, the title, body and commit message are rendered internally
and the branch, labels and draft state come from the template and its
frontmatter, so the whole operation is one flag. Without one, pass --title,
--body and --commit-message explicitly.
Works from a detached HEAD: the base falls back to the repository default
branch read from the CI event payload, and any commits the job made itself are
carried through.
Commits the whole tree unless --add-path narrows it. A job that installs its
own linter into the checkout, or runs a package manager that rewrites a lock
file on the way past, wants the narrow form: those writes are not what the
pull request is for.
Examples:
repomatic pr-sync --template format-python
repomatic pr-sync --template bump-version --part minor \
--branch minor-version-increment
repomatic pr-sync --branch my-fix --title "Fix" --body "…" \
--commit-message "Fix the thing"
Options:
--template [available-admonition|broken-links-issue|bump-version|detect-squash-merge|development-warning|fix-changelog|fix-typos|fix-vulnerable-deps|format-images|format-json|format-markdown|format-pyproject|format-python|format-shell|generated-footer|github-releases|immutable-releases|pr-metadata|prepare-release|refresh-tip|release-notes|release-sync-report|setup-guide|setup-guide-branch-ruleset|setup-guide-cloudflare-pages|setup-guide-dependabot|setup-guide-fork-pr-approval|setup-guide-notifications-pat|setup-guide-pages-source|setup-guide-pypi-trusted-publisher|setup-guide-sha-pinning-required|setup-guide-token|setup-guide-verify|setup-guide-virustotal|sync-action-pins|sync-bumpversion|sync-dep-sources|sync-gitignore|sync-mailmap|sync-repomatic|sync-runner-images|sync-tool-versions|sync-uv-lock|sync-workflow-pins|unavailable-admonition|unsubscribe-phase1|unsubscribe-phase2|update-dep-graph|update-docs|yanked-admonition]
Render title, body and commit message from a
built-in template, and derive the branch, labels
and draft state from it: the branch defaults to
the template name, labels and draft to its
frontmatter.
--template-file FILE Use an external template file instead of
--template, for project-specific PRs. Same
derivations, with the branch defaulting to the
file's stem.
--template-arg KEY=VALUE Pass an arbitrary key/value pair to the
template. Repeat to provide multiple. Use this
to feed template variables not covered by the
dedicated --version / --part / --pr-ref flags.
Example: --template-arg channel=Nix.
--template-arg-file KEY=PATH Read a template value from a file. Repeat to
provide multiple. Use this for a value with no
ceiling on its size, like a generated table: a
report travels as a path rather than inline.
Example: --template-arg-file
summary=proposal.md.
--version TEXT Version string passed to the template (e.g.
1.2.0).
--part TEXT Version part passed to the bump-version template
(e.g. minor, major).
--branch TEXT Head branch to create, update or retire. By
convention the job ID; defaults to the template
name when a template is given.
--title TEXT Pull-request title, when not using a template.
Can also be set via the GHA_PR_TITLE environment
variable.
--body TEXT Rendered markdown body, when not using a
template. Can also be set via the GHA_PR_BODY
environment variable.
--commit-message TEXT Commit message, when not using a template. Can
also be set via the GHA_PR_COMMIT_MESSAGE
environment variable.
--base TEXT Base branch. Defaults to the currently checked-
out branch, or to the repository default branch
when the checkout is detached in CI.
--label TEXT Label to attach, overriding the template's
frontmatter labels. Repeat to provide multiple.
Best-effort: a label GitHub refuses warns
instead of failing the command.
--assignee TEXT Assignee to attach. Repeat to provide multiple.
Defaults to the workflow actor via the ambient
GITHUB_ACTOR variable. Best-effort: github-
actions[bot] cannot be assigned and only warns.
--draft / --no-draft Hold the pull request in draft, overriding the
template's frontmatter. Re-applied on every
update, not just at creation, so a PR marked
ready-for-review goes back to draft on the next
sync.
--add-path TEXT Git pathspec limiting what the pull request
commits. Repeat to provide multiple. Defaults to
the whole tree, which is right when a job's only
writes are the ones it means to publish; narrow
it when the job also provisions tooling into the
checkout, so an installed package or a rewritten
lock file cannot ride along.
-h, --help Show this message and exit.
repomatic prepare-release¶
$ repomatic prepare-release --help
Usage: repomatic prepare-release [OPTIONS]
Prepare files for a release or post-release version bump.
This command consolidates all release preparation steps:
- Set release date in changelog (replaces "(unreleased)" with today's date).
- Set release date in citation.cff.
- Update changelog comparison URL from "...main" to "...v{version}".
- Remove the "[!WARNING]" development warning block from changelog.
- Optionally update workflow URLs to use versioned tag.
When running in GitHub Actions, --update-workflows is auto-detected:
it defaults to True when $GITHUB_REPOSITORY matches the canonical
workflows repository (kdeldycke/repomatic).
For post-release (after the release commit), use --post-release to retarget
workflow URLs back to the default branch.
Examples:
# Prepare release (changelog + citation)
repomatic prepare-release
# Post-release: retarget workflows to main branch
repomatic prepare-release --post-release
Options:
--changelog FILE Path to the changelog file. Defaults to the
configured changelog.location.
--citation FILE Path to the citation file. [default: citation.cff]
--workflow-dir DIRECTORY Path to the GitHub workflows directory. [default:
.github/workflows]
--default-branch TEXT Name of the default branch for workflow URL updates.
[default: main]
--update-workflows / --no-update-workflows
Update workflow URLs to use versioned tag instead of
default branch. Defaults to True when
$GITHUB_REPOSITORY is the canonical workflows repo.
--post-release Run post-release steps (retarget workflow URLs to
default branch).
-h, --help Show this message and exit.
repomatic run¶
$ repomatic run --help
Usage: repomatic run [OPTIONS] [TOOL_NAME] [EXTRA_ARGS]...
Run an external tool with managed configuration.
Installs the tool at a pinned version, resolves config through a 4-level
precedence chain (native config file, [tool.X] in pyproject.toml, bundled
default, bare invocation), and invokes the tool.
Binary tools are cached locally to avoid re-downloading on repeated runs. Use
--no-cache to force a fresh download. See repomatic cache for cache
management.
Pass extra arguments to the tool after --:
repomatic run yamllint -- --strict .
repomatic run zizmor -- --offline .
Report what a formatter would rewrite, leaving the tree alone:
repomatic run mdformat --verify -- changelog.md
Override the pinned version:
repomatic run shfmt --version 3.14.0 --skip-checksum -- .
List all managed tools and their resolved config source:
repomatic run --list
Options:
--list List all managed tools.
--verify Report which targets the tool would rewrite, without touching
them. Runs the write path against throwaway copies, so the
answer holds even for a tool whose own --check mode is
unreliable.
--version TEXT Override the pinned version of the tool.
--checksum TEXT Override the SHA-256 checksum for the current platform.
--skip-checksum Skip SHA-256 verification of binary downloads.
--no-cache Bypass the binary cache (download fresh every time).
--sort-by [tool|version|config-source]
Sort table by this column. Repeat to set priority. [default:
tool]
-h, --help Show this message and exit.
repomatic sample-metrics¶
$ repomatic sample-metrics --help
Usage: repomatic sample-metrics [OPTIONS]
Record what forges say about the repositories this project tracks.
Reads every subject through whichever API its host speaks (GitHub, GitLab or
Forgejo) and appends one row per subject, metric and date. A counter like the
star count accrues, so its curve can be charted; an attribute like the date of
the newest commit keeps a single row, restamped only when it moves.
GitHub restricted its stargazer endpoints to a repository's own admins in
2026, which left every third-party star chart on the web rendering an error
card. The aggregate count stayed public, so this snapshots it on a schedule
and commits the result: a history that accrues locally cannot be revoked.
Each reading records where it came from, since the curves are not all measured
the same way. A GitHub repository the token administers is reconstructed
exactly from the timestamp of every star it still holds; the rest are sampled
forward, and backfilled from archived pages or from a star-history.com export.
Examples:
repomatic sample-metrics
repomatic sample-metrics --no-reconstruct --backfill-wayback
repomatic sample-metrics --import-csv star-history-export.csv
Options:
--store FILE CSV store to accumulate into. Defaults to
[tool.repomatic.metrics] store.
--forward / --no-forward Read every subject's current metrics from its own
forge. [default: forward]
--reconstruct / --no-reconstruct
Rebuild exact star curves from per-star timestamps,
for GitHub repositories the token administers.
[default: reconstruct]
--backfill-wayback Mine contemporaneous star counts from archived
GitHub pages. Slow, and a one-off: the scheduled job
never runs it.
--import-csv FILE Import a star-history.com calendar export.
Repeatable.
--render / --no-render Redraw the configured charts from the stored
history. [default: render]
-h, --help Show this message and exit.
repomatic scan-virustotal¶
$ repomatic scan-virustotal --help
Usage: repomatic scan-virustotal [OPTIONS]
Upload release binaries to VirusTotal.
Scans all .bin and .exe files in the given directory and uploads them to
VirusTotal, seeding antivirus vendor databases with the signatures of the
freshly built binaries.
With --poll, waits for the analyses to complete and reports each binary's
flagged / total verdict counts. With --records, the polled snapshots are
merged into a JSON history file, which sync-binaries renders into the binaries
catalog page.
Examples:
repomatic scan-virustotal --tag v1.2.3 --binaries-dir ./binaries
repomatic scan-virustotal --tag v1.2.3 --binaries-dir ./binaries \
--poll --records docs/assets/virustotal-scans.csv
Options:
--tag TEXT Release tag the binaries belong to (e.g.,
v1.2.3). [required]
--api-key TEXT VirusTotal API key. [required]
--binaries-dir DIRECTORY Directory containing binary files to upload.
[required]
--rate-limit INTEGER RANGE Maximum VirusTotal API requests per minute.
[default: 4; 1<=x<=60]
--poll / --no-poll Poll for detection statistics after uploading.
[default: no-poll]
--poll-timeout INTEGER RANGE Maximum seconds to wait for analysis completion
when polling. [default: 600; 60<=x<=3600]
--records FILE JSON scan history file to record detection
snapshots in (requires --poll).
-h, --help Show this message and exit.
repomatic setup-guide¶
$ repomatic setup-guide --help
Usage: repomatic setup-guide [OPTIONS]
Manage the setup guide issue lifecycle.
Each setup step is shown as a collapsible section with a status indicator:
incomplete steps are expanded with a warning emoji, completed steps are
collapsed with a checkmark.
PAT availability is auto-detected from the REPOMATIC_PAT environment variable
when --has-pat/--no-has-pat is not specified.
When a PAT is detected and --repo is provided, the command runs granular PAT
permission checks and repository settings checks. The issue closes only when
all verifiable steps pass.
Requires the gh CLI to be authenticated.
Examples:
# No secret: create or reopen the setup issue
repomatic setup-guide
# Secret configured: close the issue if all checks pass
repomatic setup-guide --has-pat
Options:
--has-cloudflare-api-token Whether CLOUDFLARE_API_TOKEN is configured.
--has-notifications-pat Whether REPOMATIC_NOTIFICATIONS_PAT is configured.
--has-pat / --no-has-pat Whether REPOMATIC_PAT is configured, enabling the
PAT capability checks. Auto-detected from the
REPOMATIC_PAT environment variable when omitted.
[default: (dynamic)]
--has-virustotal-key Whether VIRUSTOTAL_API_KEY is configured.
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
-h, --help Show this message and exit.
repomatic show-config¶
$ repomatic show-config --help
Usage: repomatic show-config [OPTIONS]
Print the [tool.repomatic] configuration reference table.
Renders a table of all available options, their types, defaults, and
descriptions, generated from the Config dataclass docstrings. Respects the
global --table-format and --sort-by options.
Options:
--sort-by [option|type|default|description]
Sort table by this column. Repeat to set priority. [default:
option]
-h, --help Show this message and exit.
repomatic show-test-matrix¶
$ repomatic show-test-matrix --help
Usage: repomatic show-test-matrix [OPTIONS] [full|pr]
Render the computed CI test matrix as a Python-version by OS grid.
Each cell shows whether that combination runs as a stable or unstable
(continue-on-error) job, or is absent from the matrix. Pass "full" for the
push and schedule matrix (the default), or "pr" for the reduced pull-request
matrix. Respects the global --table-format option.
Examples:
repomatic show-test-matrix
repomatic show-test-matrix pr --no-emoji
repomatic --table-format github show-test-matrix full
Options:
--emoji / --no-emoji Decorate cells with a status emoji. Use --no-emoji for
plain words. [default: emoji]
-h, --help Show this message and exit.
repomatic sponsor-label¶
$ repomatic sponsor-label --help
Usage: repomatic sponsor-label [OPTIONS]
Add a label to issues or PRs from GitHub sponsors.
Checks if the author of an issue or PR is a sponsor of the repository owner.
If they are, adds the specified label.
This command requires the gh CLI to be authenticated.
When run in GitHub Actions, all parameters are auto-detected from environment
variables ($GITHUB_REPOSITORY_OWNER, $GITHUB_REPOSITORY) and the event payload
($GITHUB_EVENT_PATH). You can override any auto-detected value by passing it
explicitly.
Examples:
# In GitHub Actions (all defaults auto-detected)
repomatic sponsor-label
# Override specific values
repomatic sponsor-label --label "sponsor"
# Manual invocation with all values
repomatic sponsor-label --owner kdeldycke --author some-user \
--repo kdeldycke/repomatic --number 123 --issue
Options:
--owner TEXT GitHub username or organization to check sponsorship
for. Defaults to $GITHUB_REPOSITORY_OWNER.
--author TEXT GitHub username of the issue/PR author to check.
Defaults to author from $GITHUB_EVENT_PATH.
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
--number INTEGER RANGE Issue or PR number. Defaults to number from
$GITHUB_EVENT_PATH. [2m[[0m[36m[2mx>=1[0m[2m][0m
--label TEXT Label to add if author is a sponsor. [default: 💖
sponsor]
--pr / --issue Specify issue or pull request. Auto-detected from
$GITHUB_EVENT_PATH.
-h, --help Show this message and exit.
repomatic sync-action-pins¶
$ repomatic sync-action-pins --help
Usage: repomatic sync-action-pins [OPTIONS]
Bump SHA-pinned GitHub Actions across `.github/` to their latest release.
Scans workflow and composite-action files for
`uses: owner/repo@<sha> # vX.Y.Z` pins, resolves each action's latest
release passing the [tool.repomatic] minimum-release-age cooldown to its
commit SHA, and rewrites the SHA and version comment. repomatic's own
reusable-workflow refs are left to `repomatic init`.
Example:
repomatic sync-action-pins
Options:
--output FILE Write a markdown report (version table) to this
file.
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the minimum-
release-age cooldown. [default: held-back]
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic sync-binaries¶
$ repomatic sync-binaries --help
Usage: repomatic sync-binaries [OPTIONS]
Regenerate the binaries catalog from the GitHub Releases API.
Writes the catalog data to assets/binaries.csv next to the page, one row per
released binary: download link, size, SHA-256 checksum linking to the
VirusTotal analysis, and the detection snapshot when a scan history file is
given. The page renders the CSV through a csv-table directive and is created
from a default template when missing; only its chart region is rewritten
afterwards, so the prose can be edited per repository.
With --backfill-records, detection snapshots are first recovered from the
VirusTotal tables that release notes carried before the history file existed,
and merged into the records file. Release notes are immutable, so the backfill
converges and is safe to leave enabled.
Examples:
repomatic sync-binaries --repo owner/repo
repomatic sync-binaries --repo owner/repo \
--records docs/assets/virustotal-scans.csv --backfill-records
Options:
--repo TEXT Repository in owner/repo format. [required]
--page FILE Markdown page to create or refresh. [default:
docs/binaries.md]
--records FILE JSON scan history file written by scan-virustotal.
--backfill-records / --no-backfill-records
Recover detection snapshots from legacy release-notes tables
into the records file (requires --records). [default: no-
backfill-records]
-h, --help Show this message and exit.
repomatic sync-bumpversion¶
$ repomatic sync-bumpversion --help
Usage: repomatic sync-bumpversion [OPTIONS]
Sync [tool.bumpversion] config in pyproject.toml from the bundled template.
Overwrites the [tool.bumpversion] section with the canonical template bundled
in repomatic. Designed for the sync-bumpversion autofix job. The repomatic
init bumpversion command remains available for interactive bootstrapping.
Options:
-h, --help Show this message and exit.
repomatic sync-dep-sources¶
$ repomatic sync-dep-sources --help
Usage: repomatic sync-dep-sources [OPTIONS]
Swap git-tracked dependencies back to their released versions.
Manages one idiom: a [tool.uv.sources] entry tracking a git branch,
paired with a .dev version floor naming the awaited release (like
'mango>=2.1.0.dev0'). Once a stable release satisfying the floor ships
on PyPI, the swap:
- drops the [tool.uv.sources] override
- tightens the .dev floor to its base release
- freezes the adopted release through the exclude-newer cooldown
(an exclude-newer-package entry the ordinary sync-uv-lock lifecycle
prunes once it ages out)
- re-locks and verifies the adopted version landed
Overrides outside the idiom (path or workspace sources, rev/tag pins,
floor-less branch tracks) are never touched. A resolution conflict or a
lock landing on an unexpected version restores the project untouched.
Examples:
# Swap whatever is ready and show changes
repomatic sync-dep-sources
# CI: write [35m[1mmarkdown[0m report as a GitHub Actions step output
repomatic sync-dep-sources --no-table --release-notes \
--output "$GITHUB_OUTPUT" --output-format github-actions
Options:
--lockfile FILE Path to the uv.lock file. [default: uv.lock]
--table / --no-table Print a summary table of updated packages.
[default: table]
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the exclude-
newer cooldown (runs a second uv resolution).
[default: held-back]
--output FILE Write a markdown report (table + release notes)
to this file.
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic sync-deps¶
$ repomatic sync-deps --help
Usage: repomatic sync-deps [OPTIONS] [sync-dep-sources|sync-uv-lock|sync-action-
pins|sync-workflow-pins|sync-tool-versions]...
Update project dependencies, the whole set or a named subset.
The single entry point for dependency updates. It drives
sync-dep-sources, sync-uv-lock, sync-action-pins, sync-workflow-pins, and
sync-tool-versions: their network discovery runs concurrently (one shared
HTTP cache, one spinner), then the file rewrites apply serially because
three of them touch the same workflow files. Name one or more updaters to
run just those; with none named, every enabled updater runs.
The [tool.repomatic] feature flags are always authoritative: a disabled
updater never runs. With no names, updaters not meaningful in the current
working tree are skipped too (sync-tool-versions outside the repomatic
checkout, the pin updaters without workflow files); naming one runs it
regardless of the working tree.
Each updater still opens its own PR in CI; this is the local one-shot, and
the shared engine the consolidated autofix job drives.
Examples:
# Update everything enabled
repomatic sync-deps
# Only the lockfile and action pins
repomatic sync-deps sync-uv-lock sync-action-pins
# Preview without writing
repomatic sync-deps --dry-run
Options:
--output FILE Write a combined markdown report (one section
per updater) to this file.
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the minimum-
release-age cooldown. [default: held-back]
--dry-run / --live Resolve and preview every update without writing
any change. [default: live]
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic sync-dev-release¶
$ repomatic sync-dev-release --help
Usage: repomatic sync-dev-release [OPTIONS]
Sync a rolling dev pre-release on GitHub.
Maintains a single pre-release that mirrors the unreleased changelog section.
The dev tag is force-updated to point to the latest main commit.
In --delete mode, removes the dev pre-release without recreating it. This is
used during real releases to clean up.
Examples:
# Dry run to preview what would be synced
repomatic sync-dev-release --dry-run
# Create or update the dev pre-release
repomatic sync-dev-release --live
# Create or update with asset upload
repomatic sync-dev-release --live --upload-assets release_assets/
# Delete the dev pre-release (e.g. during a real release)
repomatic sync-dev-release --live --delete
Options:
--dry-run / --live Report what would be done without making changes.
[default: dry-run]
--delete / --no-delete Delete-only mode: remove the dev pre-release
without recreating. [default: no-delete]
--upload-assets DIRECTORY Directory containing assets (binaries, packages) to
upload.
-h, --help Show this message and exit.
repomatic sync-github-releases¶
$ repomatic sync-github-releases --help
Usage: repomatic sync-github-releases [OPTIONS]
Sync GitHub release notes from changelog.md.
Compares each GitHub release body against the corresponding changelog.md
section and updates any that have drifted.
Examples:
# Dry run to preview what would be updated
repomatic sync-github-releases --dry-run
# Update drifted release notes
repomatic sync-github-releases --live
Options:
--dry-run / --live Report what would be done without making changes.
[default: dry-run]
-h, --help Show this message and exit.
repomatic sync-gitignore¶
$ repomatic sync-gitignore --help
Usage: repomatic sync-gitignore [OPTIONS]
Sync a .gitignore file from gitignore.io templates.
Fetches templates for a base set of categories plus any extras from
[tool.repomatic] config, then appends gitignore-extra-content. Writes to the
path specified by gitignore-location (default ./.gitignore).
The generated file is the whole file: nothing is read back from the copy on
disk. A rule added there by hand is therefore dropped on the next sync, so the
write aborts when it would lose one. Move the rule into gitignore-extra-
content to keep it, or pass --drop-orphans to let it go.
Examples:
# Generate .gitignore using config from pyproject.toml
repomatic sync-gitignore
# Write to custom location
repomatic sync-gitignore --output ./custom/.gitignore
# Preview on stdout
repomatic sync-gitignore --output -
Options:
--output FILE Output path. Defaults to gitignore-location from
[tool.repomatic] config.
--drop-orphans / --no-drop-orphans
Overwrite rules found on disk but absent from the generated
file, instead of refusing to drop them. [default: no-drop-
orphans]
-h, --help Show this message and exit.
repomatic sync-labels¶
$ repomatic sync-labels --help
Usage: repomatic sync-labels [OPTIONS]
Sync repository labels from bundled definitions using labelmaker.
Exports label definitions to a scratch directory, then applies them to the
repository using labelmaker. Applies the default profile to all repositories,
plus the awesome profile for awesome-* repos.
Authentication follows the canonical token resolution (REPOMATIC_PAT, then
GH_TOKEN, then GITHUB_TOKEN). Downloads labelmaker automatically via the tool
registry.
Options:
--repo TEXT Repository in 'owner/repo' format. Defaults to
$GITHUB_REPOSITORY.
-h, --help Show this message and exit.
repomatic sync-mailmap¶
$ repomatic sync-mailmap --help
Usage: repomatic sync-mailmap [OPTIONS] [DESTINATION_MAILMAP]
Update .mailmap with missing contributors from Git history.
Reads the existing .mailmap as a reference for grouped identities, then
appends any contributors not already covered. Results are sorted but not
regrouped: manual editing may be needed.
The destination defaults to the source file (in-place update). Pass - to print
to stdout instead.
Options:
--source FILE Mailmap source file to use as reference for contributors
identities that are already grouped. [default: .mailmap]
--create-if-missing / --skip-if-missing
If not found, either create the missing destination mailmap
file, or skip the update process entirely. This option is
ignored if the destination is to print the result to <stdout>.
[default: create-if-missing]
-h, --help Show this message and exit.
repomatic sync-runner-images¶
$ repomatic sync-runner-images --help
Usage: repomatic sync-runner-images [OPTIONS]
Move retiring runner images forward, and probe superseding ones.
Every label this repository runs is looked up in GitHub's available-images
table. A **retirement** rewrites each literal `runs-on:` naming a deprecated
image onto its successor, because those jobs carry an end date. An **upgrade**
adds a strictly newer *version* to the full test matrix as a `continue-on-
error` probe rather than migrating onto it: nothing is bet on it, but the
suite starts exercising it at once, which surfaces a dependency breaking there
while there is runway to report it upstream.
Strictly newer by version is what separates an upgrade from a flavour. A same-
version variant carrying a different toolchain is not a newer image and is
never proposed as one.
Merging is the decision; the CI run this triggers is the evidence for it. To
decline a proposal for good, name the label in `[tool.repomatic.sync-runner-
images] ignore`: closing the pull request alone brings it back on the next
run.
Examples:
# What would change, without touching the tree
repomatic sync-runner-images --dry-run
Options:
--dry-run / --no-dry-run Report the changes without writing them. [default:
no-dry-run]
--output FILE Write the proposal as a Markdown table to this file,
for feeding a pull request body through `pr-sync
--template-arg-file`.
-h, --help Show this message and exit.
repomatic sync-tool-versions¶
$ repomatic sync-tool-versions --help
Usage: repomatic sync-tool-versions [OPTIONS]
Bump every `repomatic run` tool to its latest eligible release.
For each registry tool, finds the highest version that has cleared the
[tool.repomatic] minimum-release-age cooldown (GitHub releases for binary
tools, PyPI otherwise), writes it into tool_registry.py, recomputes binary
checksums in the same pass, and keeps the actionlint matcher URL in
lint.yaml in lockstep.
Upstream-only: it rewrites repomatic's own package source, so invoke it with
`uv run` (editable), never `uvx` (whose isolated wheel is discarded).
Examples:
repomatic sync-tool-versions
# CI: write a [35m[1mmarkdown[0m report as a GitHub Actions step output
repomatic sync-tool-versions \
--output "$GITHUB_OUTPUT" --output-format github-actions
Options:
--output FILE Write a markdown report (version table) to this
file.
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the minimum-
release-age cooldown. [default: held-back]
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic sync-uv-lock¶
$ repomatic sync-uv-lock --help
Usage: repomatic sync-uv-lock [OPTIONS]
Upgrade all dependencies and clean up stale cooldown overrides.
Wraps uv lock --upgrade and:
- syncs the repomatic-owned [tool.uv] policy pins (required-version,
exclude-newer) in pyproject.toml from the bundled template, so every
machine resolves the lockfile against the same uv floor and cooldown
- prunes exclude-newer-package entries from pyproject.toml whose held
version has aged past the exclude-newer cutoff, then freezes the
survivors at their locked version (a fixed date) so the upgrade
holds them instead of tracking newer releases
- prints a table of updated packages with upload dates
- reports the cooldown-bypass lifecycle: entries pruned or frozen by
the run, and each active freeze with the date it expires
- optionally fetches release notes from GitHub (markdown)
- optionally reports newer releases held back by the cooldown, with the
date each ages out of the exclude-newer window (--held-back)
The table respects the global --table-format option (github, json,
csv, etc.). Release notes are always rendered as markdown.
Examples:
# Upgrade and show changes
repomatic sync-uv-lock
# With release notes
repomatic sync-uv-lock --release-notes
# Machine-readable formats
repomatic --table-format github sync-uv-lock
repomatic --table-format json sync-uv-lock
# CI: write [35m[1mmarkdown[0m report as a GitHub Actions step output
repomatic sync-uv-lock --no-table --release-notes \
--output "$GITHUB_OUTPUT" --output-format github-actions
Options:
--lockfile FILE Path to the uv.lock file. [default: uv.lock]
--table / --no-table Print a summary table of updated packages.
[default: table]
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the exclude-
newer cooldown (runs a second uv resolution).
[default: held-back]
--output FILE Write a markdown report (table + release notes)
to this file.
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic sync-workflow-pins¶
$ repomatic sync-workflow-pins --help
Usage: repomatic sync-workflow-pins [OPTIONS]
Bump npm and PyPI version literals embedded in workflow YAML.
Scans workflow and composite-action files for `npm install pkg@x` and
`uvx '<pkg>==x'` pins, resolves each to its latest release passing the
[tool.repomatic] minimum-release-age cooldown, and rewrites the literal.
Example:
repomatic sync-workflow-pins
Options:
--output FILE Write a markdown report (version table) to this
file.
--release-notes / --no-release-notes
Fetch release notes from GitHub (markdown,
appended after the table). [default: no-
release-notes]
--held-back / --no-held-back Report newer releases withheld by the minimum-
release-age cooldown. [default: held-back]
--output-format [markdown|github-actions]
Format for --output. github-actions produces
format for PR template consumption in workflows.
[default: markdown]
-h, --help Show this message and exit.
repomatic unsubscribe-threads¶
$ repomatic unsubscribe-threads --help
Usage: repomatic unsubscribe-threads [OPTIONS]
Unsubscribe from closed, inactive GitHub notification threads.
Processes notifications in two phases:
Phase 1, REST notification threads:
Fetches Issue/PullRequest notification threads, inspects each for
closed + stale status, and unsubscribes via DELETE + PATCH.
Phase 2, GraphQL threadless subscriptions:
Searches for closed issues/PRs the user is involved in and
unsubscribes via the updateSubscription mutation.
Examples:
# Dry run to preview what would be unsubscribed
repomatic unsubscribe-threads --dry-run
# Unsubscribe from threads inactive for 6+ months
repomatic unsubscribe-threads --months 6
# Process at most 50 threads per phase
repomatic unsubscribe-threads --batch-size 50
Options:
--months INTEGER RANGE Inactivity threshold in months. Threads updated
more recently are kept. [default: 3; x>=1]
--batch-size INTEGER RANGE Maximum number of threads/items to process per
phase. [default: 200; x>=1]
--dry-run / --live Report what would be done without making changes.
[default: dry-run]
-h, --help Show this message and exit.
repomatic update-checksums¶
$ repomatic update-checksums --help
Usage: repomatic update-checksums [OPTIONS]
Recompute SHA-256 checksums for the binary tool registry.
Downloads each binary-distributed tool in the `repomatic run` registry at its
pinned version, computes the SHA-256, and rewrites any stale hash (and its
version stamp) in tool_registry.py.
A repair path for a manual version edit: sync-tool-versions already
refreshes checksums when it bumps a version.
Example:
repomatic update-checksums
Options:
-h, --help Show this message and exit.
repomatic update-dep-graph¶
$ repomatic update-dep-graph --help
Usage: repomatic update-dep-graph [OPTIONS]
Generate a Mermaid dependency graph from the project's uv lockfile.
Parses the CycloneDX SBOM export from uv and renders it as a Mermaid flowchart
for documentation. Version specifiers from uv.lock are shown as edge labels.
Examples:
# Generate Mermaid graph
repomatic update-dep-graph
# Include test dependencies
repomatic update-dep-graph --group test
# Include all groups and extras
repomatic update-dep-graph --all-groups --all-extras
# Include all groups except typing
repomatic update-dep-graph --all-groups --no-group typing
# Include all extras except one
repomatic update-dep-graph --all-extras --no-extra json5
# Show only test group dependencies (no main deps)
repomatic update-dep-graph --only-group test
# Show only a specific extra's dependencies
repomatic update-dep-graph --only-extra xml
# Focus on a specific package
repomatic update-dep-graph --package click-extra
# Limit graph depth to 2 levels
repomatic update-dep-graph --level 2
# Save to file
repomatic update-dep-graph --output ./docs/assets/dependencies.mmd
Group filtering:
-g, --group TEXT Include dependencies from the specified group (e.g., test,
typing). Can be repeated.
--all-groups Include all dependency groups from pyproject.toml.
--no-group TEXT Exclude the specified group. Takes precedence over --all-
groups and --group. Can be repeated.
--only-group TEXT Only include dependencies from the specified group,
excluding main dependencies. Can be repeated.
Extra filtering:
-e, --extra TEXT Include dependencies from the specified extra (e.g., xml,
json5). Can be repeated.
--all-extras Include all optional extras from pyproject.toml.
--no-extra TEXT Exclude the specified extra, if --all-extras is supplied.
Can be repeated.
--only-extra TEXT Only include dependencies from the specified extra,
excluding main dependencies. Can be repeated.
Other options:
-p, --package TEXT Focus on a specific package's dependency tree.
--frozen / --no-frozen Use --frozen to skip lock file updates. [default:
frozen]
-l, --level INTEGER RANGE Maximum depth of the dependency graph. 1 =
directly-declared deps only, 2 = adds their deps,
etc. [x>=1]
-o, --output FILE Output file path. Defaults to [tool.repomatic]
config or stdout.
-h, --help Show this message and exit.
repomatic update-docs¶
$ repomatic update-docs --help
Usage: repomatic update-docs [OPTIONS]
Regenerate Sphinx autodoc stubs and run the project's update script.
Orchestrates four phases:
1. Run `sphinx-apidoc` to generate RST stubs for all modules. 2. If MyST-
Parser is detected, convert the RST stubs to MyST markdown with ``{eval-
rst}`` blocks. 3. Run the project-specific `docs/docs_update.py` script (if
present) to generate dynamic content. 4. Refresh self-updating blocks
(``{matrix}`` compatibility tables and `python:render` `:mirror:` regions)
found in `docs/` pages and `readme.md`, via `click-extra refresh-
directives`.
With ``--check``, phases 1-2 are skipped and phases 3-4 run in their own check
modes to report drift without writing (the update script must accept a
``--check`` flag to participate).
Configuration is read from `[tool.repomatic]` in `pyproject.toml`.
Options:
--check Report out-of-date self-updating content and exit non-zero,
without writing anything. For CI drift detection.
-h, --help Show this message and exit.
repomatic verify-binary¶
$ repomatic verify-binary --help
Usage: repomatic verify-binary [OPTIONS]
Verify a compiled binary's architecture and minimum-OS floor.
Parses the executable headers natively (ELF, Mach-O, PE), with no external
tool: the architecture is checked on every platform, then the glibc floor on
Linux and the deployment target on macOS are measured over the binary plus the
Nuitka dist directories whose content its onefile payload repacks.
Examples:
# Verify a Linux ARM64 binary
repomatic verify-binary --target linux-arm64 --binary ./mpm-linux-arm64.bin
# Verify a Windows x64 binary
repomatic verify-binary --target windows-x64 --binary ./mpm-windows-x64.exe
Options:
--target [linux-arm64|linux-x64|macos-arm64|macos-x64|windows-arm64|windows-x64]
Target platform. [required]
--binary FILE Path to the binary file to verify. [required]
--dist-dir DIRECTORY Nuitka dist directory to include in the OS floor scan.
Repeatable. Defaults to every *.dist directory in the
working directory.
-h, --help Show this message and exit.
repomatic workflow¶
$ repomatic workflow --help
Usage: repomatic workflow [OPTIONS] COMMAND [ARGS]...
Lint downstream workflow caller files.
Check thin caller workflows that delegate to the canonical reusable workflows
in kdeldycke/repomatic. Use repomatic init workflows to generate or sync
workflow files.
Options:
-h, --help Show this message and exit.
Commands:
help Show help for a command.
lint Lint workflow files for common issues
repomatic workflow help¶
$ repomatic workflow help --help
Usage: repomatic workflow help [OPTIONS] [COMMAND_PATH]...
Show help for a command.
Options:
--search TEXT Search all subcommands for matching options or descriptions.
-h, --help Show this message and exit.
repomatic workflow lint¶
$ repomatic workflow lint --help
Usage: repomatic workflow lint [OPTIONS]
Lint workflow files for common issues.
Checks all YAML files in the workflow directory for:
- Standalone workflows missing the workflow_dispatch trigger.
- Thin callers using @main instead of a version tag.
- Thin callers with triggers that diverge from the canonical workflow
(missing or extra entries).
- Thin callers missing required secrets.
Examples:
# Lint workflows in default location
repomatic workflow lint
# Lint with fatal mode (exit 1 on issues)
repomatic workflow lint --fatal
# Lint a custom directory
repomatic workflow lint --workflow-dir ./my-workflows
Options:
--workflow-dir DIRECTORY Directory containing workflow YAML files. [default:
.github/workflows]
--upstream-repo TEXT Upstream repository to match thin callers against.
[default: kdeldycke/repomatic]
--fatal / --warning Exit with code 1 if issues are found (default:
warning only). [default: warning]
-h, --help Show this message and exit.
Command |
Description |
|---|---|
Label an issue or PR from its content and changed files |
|
Report (and optionally fix) vulnerable dependencies |
|
Manage broken links issue lifecycle |
|
Manage the download cache |
|
Remove cached entries |
|
Show help for a command |
|
Print the cache directory path |
|
List cached entries |
|
Cancel in-progress workflow runs for a branch |
|
Maintain a Markdown-formatted changelog |
|
Report which CI jobs are red, and which of them gate a merge |
|
Close a stale version-bump PR |
|
Reconcile the Cloudflare Pages project |
|
Remove the ToC entries awesome-lint forbids |
|
Format images with lossless optimization |
|
Commit files and push, rebasing on rejection |
|
Create and push a Git tag |
|
Show help for a command |
|
Bootstrap a repository to use reusable workflows |
|
Measure how long each runner image takes, from finished runs |
|
Check same-page doc links against the built site |
|
Check changelog dates against release dates |
|
Check dependencies resolve from the public index |
|
Run repository consistency checks |
|
List available Claude Code skills |
|
Lock closed, inactive issues and PRs |
|
Output project metadata |
|
Name an attestation bundle after the asset it attests |
|
Pack compiled binaries and their versionless aliases |
|
Pack the skills and agents as a Claude Code plugin |
|
Generate PR body with workflow metadata |
|
Create, refresh or retire an automation PR |
|
Prepare files for a release |
|
Run an external tool with managed config |
|
Record what forges say about the repositories this project tracks |
|
Upload release binaries to VirusTotal |
|
Manage setup guide issue lifecycle |
|
Print [tool.repomatic] configuration reference |
|
Render the CI test matrix as a grid |
|
Label issues/PRs from GitHub sponsors |
|
Bump SHA-pinned GitHub Actions to their latest release |
|
Regenerate the binaries catalog page |
|
Sync bumpversion config from bundled template |
|
Swap git-tracked dependencies to their released versions |
|
Update dependencies, all or a named subset |
|
Sync rolling dev pre-release on GitHub |
|
Sync GitHub release notes from changelog |
|
Sync .gitignore from gitignore.io templates |
|
Sync repository labels via labelmaker |
|
Sync Git’s .mailmap file with missing contributors |
|
Move runner images forward as GitHub retires and supersedes them |
|
Bump registry tool versions from upstream releases |
|
Re-lock dependencies and roll cooldown overrides forward |
|
Bump npm/PyPI version literals in workflow YAML |
|
Unsubscribe from closed, inactive notification threads |
|
Recompute SHA-256 checksums for the binary tool registry |
|
Generate dependency graph from uv lockfile |
|
Regenerate Sphinx API docs and dynamic content |
|
Verify binary architecture and OS floor |
|
Lint downstream workflow caller files |
|
Show help for a command |
|
Lint workflow files for common issues |
repomatic.cli API¶
classDiagram
ParamType <|-- ComponentSelector
- repomatic.cli.exit_if_disabled(ctx, enabled, key)[source]¶
Exit successfully when a
[tool.repomatic]feature flag is off.The shared guard of every sync command: a disabled feature is a normal, configured state, so the command logs the flag and exits
0instead of failing the workflow that invoked it.
- repomatic.cli.log_output_target(subject, output)[source]¶
Log where a command is about to write subject.
Every command that honors an
--outputpath narrates the destination the same way, distinguishing the stdout case (-) so the log names the stream instead of a literal dash.
- class repomatic.cli.ComponentSelector[source]¶
Bases:
ParamTypeAccepts bare component names or qualified
component/fileselectors.Bare names (e.g.,
skills) select an entire component. Qualified entries (e.g.,skills/repomatic-topics) select a single file within a component. Validation delegates toparse_component_entries(), the same code path theexcludeandincludeconfig options go through, so the CLI and config agree on syntax and error messages.- get_metavar(param, ctx)[source]¶
Returns the metavar default for this param if it provides one.
- Return type:
- convert(value, param, ctx)[source]¶
Convert the value to the correct type. This is not called if the value is
None(the missing value).This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.
The
paramandctxarguments may beNonein certain situations, such as when converting prompt input.If the value cannot be converted, call
fail()with a descriptive message.
- shell_complete(ctx, param, incomplete)[source]¶
Return a list of
CompletionItemobjects for the incomplete value. Most types do not provide completions, but some do, and this allows custom types to provide custom completions as well.- Parameters:
Added in version 8.0.
- Return type:
- repomatic.cli.TEST_MATRIX_STATE_DISPLAY = {'stable': '✅ stable', 'unstable': '⁉️ unstable'}¶
Emoji-decorated labels for job states in the
show-test-matrixgrid.The same two glyphs the workflow templates stamp onto each matrix job’s name, and that
repomatic.github.ci_status.JobStatus.required()reads back off it, so the grid and the CI verdict cannot come to disagree about which mark means “allowed to fail”.