Usage

Point mirago at a single file, a folder, or your whole project:

mirago check your_file.py   # check one file
mirago check src/           # check a folder
mirago check .              # check this folder and everything under it

When you point it at a folder, mirago walks every .py file inside it, pruning noise directories during the walk so it never descends into them — .git, __pycache__, .venv, venv, env, .tox, .nox, node_modules, build, dist, site-packages, and the mypy/pytest/ruff caches.

What you'll see

A package that doesn't exist is an error (🚨):

🚨 1 hallucination in app.py

  Line 1: import fastjson_validator
    → Package 'fastjson_validator' does not exist on PyPI

A package that exists but looks risky is a warning (⚠️):

⚠️  1 suspicious package in app.py

  Line 2: import quickjson
    → Package 'quickjson' exists but looks suspicious (created 5d ago, 12 downloads/month)

When everything is fine, mirago prints a short summary like ✓ Checked 87 files, no problems found.

Options

Option	What it does
`--fix`	Interactively replace a misspelled import with its suggestion (`requets` → `requests`).
`--fail-on error\|warning`	Minimum severity that fails the run. Default `error`; use `warning` to fail on warnings too.
`--json`	Print results as JSON instead of formatted text.
`--no-cache`	Disable the PyPI lookup cache and re-check live.
`--version`, `-v`	Print the installed version and exit.

--fix needs an interactive terminal — in CI (no TTY) it's skipped with a notice rather than guessing.

Exit codes

mirago drops straight into automation via its exit code:

Code	Meaning
`0`	Clean — nothing flagged (or only warnings, when `--fail-on` is `error`).
`1`	Problems found at or above the `--fail-on` severity.
`2`	Usage error — e.g. a path that doesn't exist, or an invalid `--fail-on` value.

JSON output

--json emits an array of issues, one object per finding — handy for CI dashboards or other tools:

[
  {
    "file": "app.py",
    "line": 1,
    "code": "import fastjson_validator",
    "message": "Package 'fastjson_validator' does not exist on PyPI",
    "severity": "error",
    "suggestion": null,
    "signals": { "exists": false, "risk_factors": ["not_on_pypi"] }
  }
]

The signals object carries the evidence behind each verdict (existence, age, downloads, lockfile status). See How it works for what those signals mean, and Continuous integration to wire mirago into CI.