Skip to main content
Status indicator: Under construction — coming soon

Command Reference

Every command, flag, and option available in the WCAG Audit CLI.

install

The CLI is installed via a license-gated curl command — not npm. Replace <your-license-key> with your actual key:

bash
curl -fsSL https://wcagaudit.io/install | bash -s -- <your-license-key>

After install, all commands are available as wcag-audit. Your license key is saved automatically — no separate init step needed.

verify

Deterministic-only re-verify of a specific finding by rc-id. Runs the same rule-based checkers as the scan — no AI, no credit cost. Used by WCAG_FIXES.prompt.md to validate each fix before the agent moves on to the next finding.

bash
wcag-audit verify rc-014

dismiss

Record a confirmed false positive in .wcag-audit/false-positives.json. The finding won't appear in future scans (identified by stable sha1 fingerprint). Reason must be ≥ 20 characters — this forces a real WCAG analysis.

bash
wcag-audit dismiss rc-014 --reason "This element is not interactive and does not need a label per WCAG 1.3.1"

LLM fix-pass agents can call dismiss directly when they determine the rule is firing incorrectly. The reason is stored for traceability and appears in the next scan's false-positive summary.

plugin-init

Auto-installs @wcag-audit/next-plugin into your Next.js project. Wraps next.config.{js,ts,mjs} with withWcagAudit() and adds WCAG_AUDIT=1 to .env.local. With the plugin active, every finding is mapped to an exact file:line, enabling the 10 deterministic codemods to apply at scan time. Production builds are no-ops when WCAG_AUDIT is not set.

bash
wcag-audit plugin-init

scan

Audit every route in the current project. Detects your framework, starts the dev server, and runs all 12 checkers on each page.

bash
wcag-audit scan

scan --auth

Opens a visible browser for interactive login. The CLI captures the session and audits all routes including authenticated pages.

bash
wcag-audit scan --auth

scan --auth-storage

Use a saved Playwright session file for headless authenticated scans (ideal for CI).

bash
# Export session once:
wcag-audit scan --auth --export-auth ./auth.json

# Reuse headlessly:
wcag-audit scan --auth-storage ./auth.json

scan --url

Crawl a deployed site via BFS instead of reading local framework routes.

bash
wcag-audit scan --url https://example.com

scan --url with crawl depth

Control how many link levels deep the crawler follows.

bash
wcag-audit scan --url https://example.com --crawl-depth 3

scan --dry-run

Preview how many pages will be scanned and the credit cost. No browser launches, no credits consumed.

bash
wcag-audit scan --dry-run
dry-run output
Found 24 routes. Estimated cost: 24 credits.
No scan performed — dry run only.

scan --no-ai

Skip the AI vision review. Runs only the 11 rule-based checkers. Faster, useful for rapid local iteration.

bash
wcag-audit scan --no-ai

scan --no-cache

Ignore the 24-hour route cache and re-audit everything.

bash
wcag-audit scan --no-cache

scan --resume

Resume an interrupted scan from where it left off.

bash
wcag-audit scan --resume

scan --routes

Scan only routes listed in a text file (one URL per line).

bash
# routes.txt:
# /
# /about
# /pricing
# /dashboard

wcag-audit scan --routes ./routes.txt

scan --full --coverage

Full scan with coverage stats output.

bash
wcag-audit scan --auth --full --coverage

ci

CI-optimized scan. Exits with code 1 when findings at the specified severity threshold are found. Designed for pipeline gates.

bash
wcag-audit ci --fail-on critical

Threshold options: critical (default), serious, moderate, minor, none.

ci with auth

bash
wcag-audit ci --fail-on serious --auth-storage ./auth.json

watch

Watch source files and auto-rescan when changes are detected (2-second debounce).

bash
wcag-audit watch

doctor

Diagnose your setup: license status, AI vision availability, framework detection, dev server config.

bash
wcag-audit doctor

config

Print current config with secrets masked.

bash
wcag-audit config

audit (legacy)

Audit a single URL. Prefer scan for full projects.

bash
wcag-audit audit https://example.com/pricing

Common fix recipes

The 10 most common findings and how they're fixed. The Auto-fix column shows whether the codemod handles it automatically when @wcag-audit/next-plugin is installed.

text-spacing-clip — WCAG 1.4.12 AA

Triggers: truncate / line-clamp-N on text containers.

Auto-fix (codemod): Strips those classes and adds min-w-0 break-words.

Manual fix: Drop overflow: hidden, replace fixed height with min-height, and add overflow-wrap: anywhere; word-break: break-word.

fixed-width-overflow — WCAG 1.4.10 AA

Triggers: w-[Npx] / min-w-[Npx] without a breakpoint prefix.

Auto-fix (codemod): Replaces with max-w-full.

Manual fix: Add max-width: 100%; min-width: 0; box-sizing: border-box to the rule.

color-contrast — WCAG 1.4.3 AA

Triggers: Text color insufficient against ancestor background.

Auto-fix (codemod): Bumps text-gray-{300,400,500} to the smallest darker step that reaches 4.5:1 (detects bg-* from ancestor chain).

Manual fix: Pick a darker foreground or lighter background; verify with the WebAIM contrast checker.

label-content-name-mismatch — WCAG 2.5.3 A

Triggers: Element has both aria-label and visible text and they don't match.

Auto-fix (codemod): Drops the redundant aria-label when normalized text matches.

Manual fix: Either drop the aria-label or rewrite it to start with the visible text exactly.

redundant-alt — WCAG 1.1.1 A

Triggers: alt="image of …" / alt="picture of …".

Auto-fix (codemod): Strips redundant prefixes (image of, picture of, photo of, graphic of, icon of).

Manual fix: Describe the content, not the medium.

button-name — WCAG 4.1.2 A

Triggers: <button> with no accessible name (icon-only, no text, no aria-label).

Auto-fix (codemod): Promotes title or data-tooltip attribute to aria-label.

Manual fix: Add aria-label="<action verb>" describing the button's action.

Triggers: <a> with no accessible name.

Auto-fix (codemod): Promotes title / data-tooltip to aria-label (same as button-name).

Manual fix: Add visible link text or aria-label.

image-alt — WCAG 1.1.1 A

Triggers: <img> / <Image> with no alt attribute.

Auto-fix (codemod): Adds alt="" (decorative marker per WCAG).

Manual fix: Add descriptive alt for content images; empty alt="" for decorative.

lang-html — WCAG 3.1.1 A

Triggers: <html> missing lang attribute.

Auto-fix (codemod): Adds lang="en".

Manual fix: Customize to your actual language code.

missing-form-label — WCAG 1.3.1 / 4.1.2

Triggers: <input> / <select> / <textarea> without label association and without aria-label / aria-labelledby.

Auto-fix (codemod): When the input has placeholder="X", copies it into aria-label="X" (preserves placeholder for non-AT users).

Manual fix: Add a proper <label htmlFor="…"> or aria-label.

Next step: See common workflows for CI/CD, auth, and multi-role scanning →