CLI commands
PragyaLint is a single flag-based CLI — there are no subcommands.
Everything is either an analysis option, a report option, or a fix
option on the pragyalint command. This page is the
reference for all of them.
Basics
pragyalint # analyze the current directory
pragyalint --help # full option list
pragyalint --version # print version
python3 -m pragyalint # run as a module (works even when not on PATH)
py -m pragyalint # Windows (py launcher)
Analysis options
| Flag | Default | Description |
|---|
-r, --root-dir <path> | current directory | Root directory of the project. |
-e, --entry <module...> | auto-detect | Entry-point modules, globs, or file paths. Space-separated or repeated; see Entry files. |
-i, --ignore <patterns...> | [] | Glob patterns to ignore while scanning. |
-x, --extensions <exts...> | .py | File extensions to analyze. |
--include <paths...> | [] | Only analyze files under these paths. |
--rules <rules...> | all | Restrict analysis to listed rules: unused_file, unused_export, unused_import, unused_local, cycle. |
--no-report-unused-exports | enabled | Disable unused-export reporting. |
--no-conventional-entries | included | Exclude conventional entries (main.py, app.py, cli.py, __main__.py, setup.py). |
--include-entry-exports | disabled | Report unused exports declared in entry files. |
--ignore-tests | disabled | Ignore test files and directories. |
--cycles | disabled | Detect and report circular import cycles. |
Report options
| Flag | Description |
|---|
--fail-on high|medium|low|none | Exit non-zero when findings meet this confidence threshold. Default: never fails on findings alone. |
--json | Print the structured JSON report. See Reports. |
--sarif | Print SARIF output for Code Scanning. See Reports. |
--no-color | Disable ANSI colors in terminal output. |
-v, --verbose | Print internal graph state: entry points and every module marked R (reachable) or D (dead). |
Fix options
Analysis is always read-only. Fixes are opt-in and confidence-gated —
see Fixes & --fix for the safety model.
| Flag | Default | Description |
|---|
--fix [files imports exports] | all targets | Apply fixes for the given targets. With no targets, applies files, imports, and exports. |
--confidence high|medium+|low+|all | high | Minimum confidence to fix. |
--dry-run | off | Log planned fixes without changing any files. |
--force | off | Allow a fix normally considered unsafe (e.g. a name listed in __all__, or any definition when the project uses dynamic dispatch). |
Common combinations
# Fast CI pass: dead files and unused imports only
pragyalint --rules unused_file unused_import --fail-on high
# Preview exactly what --fix would change
pragyalint --fix --dry-run
# Machine-readable report for other tools
pragyalint --json > report.json
pragyalint --sarif > pragyalint.sarif
# Verbose graph dump (debugging reachability)
pragyalint -v
Config files feed the same options
Every value above can also come from pragyalint.toml,
pragyalint.json, or the [tool.pragyalint]
table in pyproject.toml (dashes become underscores).
Command-line flags always win. See Configuration.
Exit codes
| Code | Meaning |
|---|
0 | Scan completed; no finding met the --fail-on threshold (default). |
1 | At least one finding met or exceeded --fail-on. |
2 | Usage or configuration error — bad flags, invalid config value, unreadable config file. |
130 | Interrupted (Ctrl-C). |