Detector CLI
Run Impeccable's deterministic design checks without an AI harness.
npx impeccable detect runs Impeccable’s deterministic design checks directly from the terminal. Use it when you want a fast signal without asking an AI command to review the work.
Fast path
Scan the source folder:
npx impeccable detect src/Scan one file:
npx impeccable detect src/components/Card.tsxScan a rendered page:
npx impeccable detect https://example.comUse JSON when another script or CI job needs to read the result:
npx impeccable detect --json src/What it checks
The detector looks for design and implementation patterns that are usually visible to users: contrast problems, typography drift, layout overflow, generic AI-design tells, brittle motion, and design-system violations when DESIGN.md exists.
Directories are walked for design-relevant files. HTML files include linked local CSS. Framework files such as JSX, TSX, Vue, Svelte, Astro, and CSS modules get source-text checks. URL targets use a browser and inspect the rendered page.
How to read results
Plain output groups findings by file and prints the rule id, snippet, and explanation. Exit codes are:
| Code | Meaning |
|---|---|
0 |
No findings. |
2 |
Findings were detected. |
1 |
The command failed. |
That makes CI usage straightforward: fail the job on 2, then decide whether to fix the issue or add a narrow ignore.
DESIGN.md awareness
When a local DESIGN.md exists, detect loads it by default and enables design-system checks for fonts, literal colors, and border radii. The generated .impeccable/design.json sidecar gives those checks richer token and ramp data.
If the design file is stale, refresh it:
/impeccable documentIf you need one scan without design-system checks:
npx impeccable detect --no-design-system src/Managing intentional findings
Detector ignores are shared with the design hook:
npx impeccable ignores list
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-file "src/legacy/**"For a waiver that should travel with one file instead of living in the repo config, drop an inline comment in the file itself:
<!-- impeccable-disable overused-font: exported brand doc -->Use Config and ignores for the full ignore workflow, including the line-scoped impeccable-disable-line and impeccable-disable-next-line forms.
Details when the default path is not enough
Scan stdin
If you pipe text into the command with no target, it scans stdin:
cat component.css | npx impeccable detectProject config and raw scans
By default, detect reads .impeccable/config.json and .impeccable/config.local.json.
It respects detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled.
It does not respect hook.enabled; manual scans still run when the automatic hook is disabled.
In-file impeccable-disable* comments are honored too, so a waiver can travel with a file. --no-inline-ignores skips just those; --no-config skips config and inline ignores together.
Use --no-config only when you want a raw detector run with no project config, no detector ignores, and no DESIGN.md context.
Provider-specific checks
Some rules are provider-specific and opt in:
npx impeccable detect --gpt src/
npx impeccable detect --gemini src/Leave them off for normal project quality checks. Turn them on when you specifically want to catch model-family fingerprints.
Where the detector fits
The same detector also powers the design hook, /impeccable audit, the public slop catalog, the browser extension, and the local detector lab.
Use Design hooks when you want findings inside the agent flow. Use detect when you want a direct terminal signal.