badgevet

Find retired and broken status badges in Markdown that link checkers miss.

A retired shields.io badge returns HTTP 200 with a valid SVG whose title reads retired badge, so ordinary link checkers (lychee, markdown-link-check) mark it OK. badgevet fetches each badge and reads the rendered SVG title instead, so it can tell a dead badge from a healthy one.

Install

cargo install badgevet
# or a prebuilt binary, no recompile:
cargo binstall badgevet

Usage

badgevet                    # scan README.md in the current directory
badgevet docs/ README.md    # scan files and directories (dirs recurse for *.md)
badgevet ~/Projects/mine    # one command scans every README under all your local repos
badgevet --only-broken .    # report only permanently broken badges
badgevet | jq .             # JSON when piped

Check every repo you own

Point badgevet at an owner and it checks the canonical published README of each of their repositories - no cloning needed. It reads the same README GitHub shows the world, so it catches badge rot even in repos you rarely touch.

badgevet --github rvben              # all your public, non-fork, non-archived repos
badgevet --github rvben --only-broken

Set GITHUB_TOKEN (or GH_TOKEN) to lift GitHub's unauthenticated rate limit; required for --include-private. Widen the default scope with --include-forks, --include-archived, --include-private.

Example:

STATE        PROVIDER               LOCATION                   BADGE
broken       shields.io             README.md:3                Version
             -> https://vsmarketplacebadges.dev/version/rvben.rumdl.svg

3 checked · 2 ok · 1 broken · 0 unconfirmed

How it classifies

Each badge lands in one of three states:

The distinction is the point. shields.io renders invalid both for a genuinely bad badge and when its upstream API is merely rate-limiting, so unconfirmed never fails your build by default. Only an explicit, permanent dead state does.

When a known-dead pattern has a modern replacement (e.g. shields.io's retired Visual Studio Marketplace routes), badgevet prints the suggested URL.

Fixing

scan never touches your files. The separate fix command applies those suggestions in place:

badgevet fix              # rewrite broken badges in README.md
badgevet fix docs/        # ...or across a directory of Markdown

It swaps only the badge image URL (leaving the surrounding link untouched), changes only broken badges that have a known replacement, and is idempotent. Broken badges with no known replacement are left alone and reported as unfixable (exit 1). fix is local-only; it does not work with --github. Since scan is read-only and fix mutates, they are separate commands with honest mutating markers in the schema.

Options

Exit codes

Exit 1 is an outcome, not an error: stdout still carries the full report and no error envelope is written. This makes badgevet a natural CI or pre-commit gate.

For agents (clispec)

badgevet follows The CLI Spec: structured output on stdout, structured error envelopes on the last line of stderr, and a schema subcommand whose output validates against clispec.dev/schema/v0.3.json (checked by the test suite).

badgevet schema

License

MIT