CLI Reference
Commands, flags, and exit codes for the docker-doctor CLI.
On this page
Default scan command
npx @docker-doctor/cli@latest [dir][dir] is the directory to scan and defaults to ..
| Flag | Alias | Description |
|---|---|---|
--verbose | -v | Show the affected file, line, an explanation, and a Help: fix hint for every diagnostic |
--score | -s | Print only the numeric health score. Prints nothing when no file was analyzed. |
--json | -j | Output the full report as JSON |
--config <path> | -c | Use a custom config file; the path is relative to the current directory (or absolute) |
--version | -V | Print the CLI version |
--help | -h | Print usage for the command |
Piped / CI output
--score and --json both suppress the interactive spinner and prompts, so they're safe to pipe or run in CI:
npx @docker-doctor/cli@latest . --scorenpx @docker-doctor/cli@latest . --json > report.jsonExit codes
The same rules apply to the default scan, --score, and --json:
| Code | Meaning |
|---|---|
0 | Scan complete, no error-severity diagnostics. Also returned when docker-doctor finds no Dockerfile or Compose file, or finds only files with nothing to check. Such a scan has no score. The terminal output says so, and --json and --score print a warning on stderr. |
1 | Scan complete, at least one error-severity diagnostic. In interactive mode, also returned when docker-doctor can't write the workflow scaffold, the .docker-doctor/ handoff files or the .gitignore entry for them. |
2 | Scan incomplete: one or more discovered files could not be read or parsed. The report and score cover only the files that were analyzed; the failures are listed on stderr. 2 wins over 1. In --json output the affected files are listed under failures. When no file could be analyzed there is no score. See JSON report. |
130 / 143 | Interrupted (SIGINT / SIGTERM) |
Environment variables
| Variable | Effect |
|---|---|
FORCE_COLOR=0 | Disable colors in the terminal report. TERM=dumb and a stdout that isn't a TTY also turn them off. |
CI, NO_ANIMATION, TERM=dumb | Print the score box without animating it. This also happens when stdout isn't a TTY. |
The CLI doesn't read NO_COLOR. Set FORCE_COLOR=0 instead.
JSON report
--json prints one object with these fields:
| Field | Meaning |
|---|---|
schemaVersion | The report format version. See the table below. |
score, label | The health score and its label. Both are null when no file was analyzed, including when no Dockerfile or Compose file was found. |
analyzedFiles | How many Dockerfiles and Compose files the score covers. |
diagnostics | One entry per finding, with rule, category, severity, file, message and help, plus line and column when known. |
failures | Files docker-doctor found but could not read or parse, each with its error message. |
project | The Dockerfiles, Compose files and .dockerignore files docker-doctor found. |
timestamp | When the scan ran, in ISO 8601. |
schemaVersion changes when a field is added or when the score formula changes. Compare scores only between reports with the same version.
| Version | Release | Change |
|---|---|---|
| 2 | 0.3.0 | Added schemaVersion. The score became round(100 * e^(-penalty / 70)). |
| 3 | 0.5.2 | Added diagnostics[].category. |
| 4 | 0.6.0 | Added failures. |
| 5 | 0.7.0 | The score averages the penalty over the analyzed files. Scores are not comparable with version 4. |
| 6 | 0.8.0 | Added analyzedFiles. score and label are null when no file was analyzed. Empty files and files with nothing to check no longer count toward the average. |
Reports from before 0.3.0 have no schemaVersion field. Treat them as version 1.
Install for agents
Install the Docker Doctor agent skill for your coding agents (interactive multi-select in a TTY):
npx @docker-doctor/cli@latest installNon-interactive runs must name the agents:
npx @docker-doctor/cli@latest install --agent claude-code cursor| Flag | Alias | Description |
|---|---|---|
--agent <agents...> | -a | Agent id(s) to install for; required when not running in a TTY |
--global | -g | Install into each agent's global skills directory (e.g. ~/.claude/skills) instead of the current project |
See the Coding Agents guide for details.
Rules subcommands
List every built-in rule, its category, default severity, and description:
npx @docker-doctor/cli@latest rules listPrint one rule's category, default severity, description and fix hint. The fix hint is the same text as the Help: line in a scan. The full key or the short name after docker-doctor/ both work:
npx @docker-doctor/cli@latest rules explain docker-doctor/no-root-userInteractive mode
When run in a TTY without --score or --json, docker-doctor shows a spinner while scanning and, after printing results, offers to scaffold a .github/workflows/docker-doctor.yml CI workflow for you. It writes the workflow at the root of the repository that contains the scanned directory. When you scan a subdirectory, the workflow passes that path as the action's directory input.
If the scan found issues, it then offers to hand them to a coding agent detected on your machine — launching the agent with the issues as its prompt — or to copy that prompt to your clipboard. See the Coding Agents guide.