CLI reference
Every flag, every subcommand, every output format. The complete @geoql/vue-doctor and @geoql/nuxt-doctor CLI surface.
The CLI surface is identical for @geoql/vue-doctor and
@geoql/nuxt-doctor — the latter just adds Nuxt-specific context
to the same engine. This page uses @geoql/vue-doctor for all
examples; swap the package name as needed.
Synopsis
npx -y @geoql/vue-doctor [flags]
npx -y @geoql/vue-doctor <subcommand> [flags]
Audit flags
These flags control the audit pass. They are the most-used subset.
| flag | description | default |
|---|---|---|
--root <path> | project root to scan | cwd |
--include <glob> | extra include glob (repeatable) | — |
--exclude <glob> | extra exclude glob (repeatable) | — |
--rule <id>:<level> | override a single rule's severity (repeatable). level = error|warn|info|off | — |
--preset <name> | minimal | recommended | strict | all | recommended |
--format <fmt> | agent | pretty | json | json-compact | sarif | html | agent |
--output <path> | write the report to a file (extension can imply format) | stdout |
--fix | apply auto-fixes where the rule supports it | off |
--fix-exclude <glob> | never auto-fix files matching this glob (repeatable) | — |
--no-lint | skip the oxlint subprocess pass | off |
--respect-inline-disables | honor // vue-doctor-disable-next-line comments | off |
--diff | scope the audit to files changed vs. the merge base | off |
--staged | scope the audit to files in the git index | off |
--full | override --diff / --staged and audit everything | off |
--score | print the score in CI-friendly format even when format is json | off |
--annotations | emit ::error file=…:: GitHub-style annotations | auto (in CI) |
--threshold <n> | override the score threshold (0–100) | 0 |
--fail-on <level> | error | warn | none — when to exit non-zero | error |
--verbose / --quiet | adjust log level | default |
--ci / --no-ci | force-enable or disable CI-only behavior (annotations, color) | auto |
Subcommands
list-rules
Print the registered rule catalogue. Use --json or --json-compact
to get a machine-readable form.
npx -y @geoql/vue-doctor list-rules
npx -y @geoql/vue-doctor list-rules --category hydration --json
Filters:
| flag | description |
|---|---|
--preset <name> | restrict to rules enabled by the given preset |
--category <cat> | ai-slop | composition | performance | reactivity | hydration | data-fetching | server-routes |
--source <src> | oxlint | core |
--severity <sev> | error | warn | info |
explain <ruleId>
Print the long-form description, the rationale, and the recommended fix for a single rule.
npx -y @geoql/vue-doctor explain no-em-dash-in-str
The output is the same text that appears in the docs at
/rules/vue and /rules/nuxt, but reachable from the terminal.
inspect [dir]
Print the detected project profile: framework versions, capabilities (auto-imports, Pinia, Vue Router), monorepo layout, and the rules that would be enabled under the active preset.
npx -y @geoql/vue-doctor inspect
npx -y @geoql/vue-doctor inspect apps/web --json
Useful in CI to debug "why is rule X not firing on this project?".
init
Generate a doctor.config.ts in the current directory. Interactive by
default; pass --yes to accept defaults.
npx -y @geoql/vue-doctor init --yes
npx -y @geoql/vue-doctor init --yes --config-format json
The init flow asks five questions (preset, output format, fail-on threshold, file scope, ignore globs) and writes a typed config that matches the config schema.
Output formats
| format | best for | shape |
|---|---|---|
agent | local dev, CI logs (default) | one-line summary + per-finding block |
pretty | local dev, human reading | boxed tables with rule descriptions |
json | programmatic consumption | full AuditReport JSON |
json-compact | high-volume CI | single-line JSON per finding |
sarif | GitHub code scanning, GitLab code quality | SARIF 2.1.0 |
html | shareable report (emailable, PR comment) | self-contained HTML |
The format is auto-detected from the --output extension if you
don't pass --format. .json → json, .sarif → sarif,
.html → html, anything else → agent.
Exit codes
Stable across all subcommands:
| code | meaning |
|---|---|
0 | success — score above threshold, no findings at or above --fail-on |
1 | at or above --fail-on threshold (or score below --threshold) |
2 | invalid arguments, missing config, doctor crash, or I/O error |
Environment variables
| variable | equivalent flag | notes |
|---|---|---|
DOCTOR_NO_COLOR | --no-color | disable ANSI in output |
DOCTOR_PRESET | --preset | picked up before the CLI flag |
DOCTOR_FAIL_ON | --fail-on | |
DOCTOR_FORMAT | --format | |
DOCTOR_ROOT | --root | |
CI | — | auto-enables annotations when set |
GITHUB_ACTIONS | — | also auto-enables annotations |
The CLI flag always wins over the env var. The env var is useful for shell aliases and CI matrix defaults.