Skip to content

Getting started

Install

npm install -g mobile-repo-doctor

mrd is a short alias for mobile-repo-doctor.

Scan a project

mrd scan .            # scan the current directory
mrd scan ./my-app     # scan a specific path

The scan runs entirely on your machine. There is no account, no upload, and the only network request is an optional check for a newer version on npm (skipped in CI, disable with --no-update-check).

What gets scanned

The files your repository tracks in git — what someone cloning it would get. The tracked list is read straight out of .git/index; no git command is ever run.

Everything else in the working directory is skipped, which is usually what you want: a .venv, a target/, DerivedData, a Maven or Gradle cache, an agent's worktree, a Podfile.lock you never committed. None of that is in the repository, so grading it grades your machine — two people scanning the same commit would get different scores. When files are skipped the scan says so:

Note: 504 path(s) skipped: not committed to git.

The trade-off: a file you have written but not committed yet is not in the report. Commit it (or git add it — the index updates immediately) and it will be.

Dependency trees and build output — node_modules, Pods, Carthage, build, .gradle, DerivedData and friends — are skipped even when they are committed. If your repository commits them, hygiene-cached-artifacts and hygiene-generated-dir will tell you; the checks do not need to read ten thousand files of somebody else's code to do it.

Scanning a directory that is not a git repository (an unpacked archive, a git archive export) still works: the whole directory tree is scanned, minus the same dependency trees and the editor/agent directories.

Options

mrd scan [options] <path>

  -o, --output <path>   Output file path (default: ./repo-health-report.html)
  -f, --format <type>   Report format: html, json, md, or comma-separated
  --open                Open the report in your browser after generating
  -v, --verbose         Verbose output
  --no-update-check     Disable the npm update notification

Examples:

mrd scan . -f html --open          # HTML report, opened in the browser
mrd scan . -f json -o report.json  # machine-readable JSON
mrd scan . -f md -o report.md      # Markdown report for an AI assistant
mrd scan . -f html,json,md         # all three at once

See Reports for what each format looks like.

Exit code

The CLI exits with code 1 when it finds any critical or high severity issue, and 0 otherwise. This lets you fail a CI job on serious findings — though the GitHub Action gives you a finer failure policy.