You finish a small tool, push it to GitHub, share the link. Then someone opens it and the README has no install steps. Or there is no licence file. Or the CI workflow exists but never actually runs a test. You find out from a stranger — or you never find out at all.

A checklist in your head does not catch this. I kept forgetting one file or another, so I made the checklist a command.

repo-hygiene-checker-cli is a Python CLI. Standard library only. It reads a repo and checks it against a fixed publish list, and reports each check as one of four things:

  • PASS — the check ran and the repo has it.
  • FAIL — the check ran and the repo is missing it.
  • WARN — a recommended file is missing, not a required one.
  • SKIP — the check could not run, with the reason given.

A check is never reported PASS unless it actually ran. If something cannot be checked, it says so — it never guesses.

What it checks

Required — a missing one is a FAIL:

  • README exists, is not empty, and has a top-level heading, with Install, Usage, and Examples sections.
  • A licence file exists and actually contains MIT licence text. A file named LICENSE with other text inside fails.
  • .gitignore exists and actually covers .env plus Python cache files when the repo has Python in it.
  • A CI workflow exists in .github/workflows/ and contains a step that runs tests. A workflow with no test step fails.
  • At least one issue template exists in .github/ISSUE_TEMPLATE/.

Recommended — a missing one is a WARN, not a FAIL (--strict turns warnings into failures):

  • CONTRIBUTING.md and SECURITY.md present.
  • A tests/ directory with at least one test file.
  • If the repo has a skills/ directory, every skills/*/SKILL.md carries name: and description: frontmatter.

With --online only, it also checks the GitHub description is non-empty and at least one topic is set, read from the public GitHub API with no token. Without --online both report SKIP, never PASS.

Try it

pip install repo-hygiene-checker-cli 

Point it at a repo:

repo-hygiene-checker /path/to/your-repo 

The repo ships with an examples/ folder you can try first:

git clone https://github.com/haiderstudio/repo-hygiene-checker-cli.git cd repo-hygiene-checker-cli repo-hygiene-checker examples/good-repo 

Real output:

repo-hygiene-checker: examples/good-repo PASS README: README.md present, non-empty, has heading PASS README sections: Install, Usage, and Examples sections present PASS Licence (MIT): LICENSE contains MIT licence text PASS .gitignore: .gitignore present, non-empty PASS .gitignore coverage: .env and Python cache patterns covered PASS CI runs tests: ci.yml contains a step that runs tests PASS Issue templates: 1 template(s) in .github/ISSUE_TEMPLATE/ PASS CONTRIBUTING.md: CONTRIBUTING.md present PASS SECURITY.md: SECURITY.md present SKIP Skill frontmatter: no skills/ directory PASS Tests present: 1 test file(s) in tests/ SKIP GitHub description: needs --online (no network call made) SKIP GitHub topics: needs --online (no network call made) repo-hygiene-checker: 10 passed, 0 failed, 0 warnings, 3 skipped 

A bad repo fails five checks and exits 1, so you see the whole list at once instead of finding problems one at a time.

Useful flags

# Also check the GitHub description and topics (one public API read, no token) repo-hygiene-checker --online /path/to/your-repo # Machine-readable output for CI repo-hygiene-checker --format json /path/to/your-repo # Treat warnings as failures (for CI gates) repo-hygiene-checker --strict /path/to/your-repo 

Exit code 0 means no failures (warnings allowed), 1 means at least one failure, 2 means a usage error such as a missing path — so it drops straight into CI as a gate.

What it does not do

It does not fix anything. It only reads and reports — no file is ever written, deleted, or renamed. It does not check README quality, spelling, or whether your code is correct — only that the publish list is present and followed. And it does not send your code anywhere. Without --online it makes no network call at all.

I built it because I publish small tools one after another and the same files kept going missing. Other checkers I tried either scored the repo and auto-generated files, or only checked that a file with the right name exists. This one checks the content — the licence text, the .gitignore patterns, whether CI actually runs tests — and it never writes anything.

The repo is MIT licensed: https://github.com/haiderstudio/repo-hygiene-checker-cli

If it catches a missing file in your repo before you publish, a star helps other people find it.