pour-cli
Audit any URL against WCAG 2.2 from your terminal, powered by the
pour engine: a clean-room WCAG
engine written from the W3C specifications, the same engine behind
pour.dev.
The page is loaded in headless Chrome, the engine runs against the live DOM,
and the findings land on stdout: rule, severity, WCAG success criterion, the
exact failing elements as CSS paths, and what to fix. Findings the engine
cannot judge conclusively are reported as "needs review" rather than guessed
at, and the exit code makes it a CI gate out of the box.
Requirements
Node 18+, and an installed Chrome (or Chromium, or Edge). The CLI drives the
browser you already have via puppeteer-core, so installing it never
downloads one. Point --browser (or PUPPETEER_EXECUTABLE_PATH) at a
binary to use something else.
Usage
Exit codes: 0 clean, 1 findings (per --fail-on), 2 error.
A scheme-less URL is tried over https first and falls back to http when the
TLS handshake fails, the same way a browser address bar behaves.
Vision simulations
--filter renders the page as someone with a particular vision or sensory
condition experiences it and saves the result as a PNG:
Color-vision filters use the Brettel/Vienot/Mollon and Machado matrices (via
DaltonLens), the same
simulations the pour extension ships. Filters and audits are exclusive modes:
some simulations restyle the page, so auditing through one would audit the
simulation rather than the site.
The numbers depend on the page state
Responsive pages serve different content per breakpoint, and the engine
measures what is actually rendered, so the viewport is part of the result:
the report header echoes it, and comparing two runs only makes sense at the
same width. --scroll walks the page first so lazy-loaded content is in
the DOM; that changes the numbers too, by design.
A page on disk
A target that names an .html file is audited as the page it is, in the
browser, with every rule that needs layout and paint:
The file is served from a loopback port for the length of the audit, so its
relative and root-relative assets load the way they will in production.
Opening it as a file:// URL instead would leave a stylesheet at
/css/site.css unfetched, and the audit would report an unstyled page as if
it were the real one, usually as a clean result. --root says which folder
is the site root when the page addresses its assets from there rather than
from its own folder.
file:// URLs still work if you type one, and carry that caveat with them.
Checking files
pour check reads HTML, JSX, TSX, Vue, Svelte, Angular, Liquid and Nunjucks
files and runs the engine's markup rules over them with no browser, the same
lane the pour extension for VS Code runs as you type. Every finding comes
with its file, line and column.
Values that come from code (alt={name}), script-built markup and anything
a template tag leaves unknowable are left unjudged and counted rather than
guessed. Colour contrast, target size, focus and motion need the page in a
browser, so those stay with pour <url>. --bp, --fail-on, --level,
--max-nodes and --format apply; --no-css skips reading the local
stylesheets a page links.
Reports over many pages
pour report crawls a site breadth first from the address given (or audits
the home page of every domain in a list file), with a live progress screen
in the browser and one standalone HTML report at the end. Ctrl+C stops
cleanly; the same command resumes.
An address with a path keeps the crawl under that path; --whole-site
follows links above it too. An address on a subdomain keeps the crawl on
that subdomain and its own; a start on the main host covers the whole site
and its subdomains, and --same-host narrows it to the one host.
--login, --basic and --browser apply as above.
Signed-in sites
Pages behind a login are audited with the session you sign in with:
The window is the Chrome you have installed, opened as an ordinary browser,
so sign-in providers that refuse automated browsers (Google's "This browser
or app may not be secure") accept it; the audit itself keeps using the
testing build. The session is read from that window into memory and used
for this run only: the site's own cookies and storage, not the sign-in
provider's. Nothing is written to disk, so there is no session file to
leak; the next run signs in again.
A staging site behind HTTP authentication is the one case a sign-in window
cannot cover, since the browser keeps those credentials outside its cookies:
--basic user:pass answers the site's challenge. Only the site's: another
host's own authentication challenge on the page is declined.
A page that answers with a sign-in form instead of the address asked for is
reported as exactly that, never audited as if it were the site. pour mcp
has no one to sign in for it, so pages behind a login are audited from the
terminal.
CI
--level quiet keeps the log to the one totals line; the exit code still
carries the verdict. Drop it (or use --level rules) when you want the
findings in the CI log too.
Findings can land in the pull request itself. Annotations on the changed
lines work on any repository:
SARIF goes to GitHub code scanning, which tracks each alert across commits
and closes it when the finding goes:
And --format markdown, on pour <url> or pour check, writes a comment
for gh pr comment --body-file.
AI agents
pour mcp serves the same audit, the sequential focus order and the
simulation screenshots to an AI agent as tools, over the Model Context
Protocol on stdio. Any MCP client can use it; the command is pour with
the argument mcp:
In VS Code the pour extension registers the server by itself once pour-cli
is installed. The tools:
pour_audit: audit a URL. Totals, then each failing rule with its
severity, success criteria and up to five elements with the fix (detail
and maxNodes change how much comes back), then the rules the engine
would not judge without a human.pour_focus_order: the keyboard focus order as Tab visits it, each stop
with its accessible name and CSS path, positive tabindex flagged, and the
native controls a tabindex of -1 has taken out of reach.pour_screenshot: a PNG of the page, plain or through any of the
vision, sensory, motor and structure simulations.
Every tool takes a viewport, a scroll switch and a settle delay, because
the numbers depend on the page state.
Each tool takes either a url or a path to a file on disk. A path is
served over a loopback port, the same way pour index.html is, so relative
assets load; root names the site root when they are addressed from there.
A path to a template or a component (.jsx, .vue, .liquid and the rest)
is read as source by the static lane instead, and answers with the line and
column of every finding, saying plainly that it was not rendered.
A path reaches only inside the directory the server was started in, which
POUR_MCP_ROOT can point elsewhere. Started at the filesystem root, with no
project to stay inside, the server refuses paths altogether.
The server loads http and https and nothing else. file:// is refused
there, though the command still takes it: an agent chooses the addresses it
asks for, often from a page it has just read, and the disk is not a web
page.
The skill
The tools say what fails; the skill tells an agent what to do about it. It
is an Agent Skill, one SKILL.md: check source
files first and the rendered page after, note the viewport and scroll state
with every figure, fix in the source and audit again, keep the findings that
need review apart from the violations, never hide a finding with
aria-hidden or an exclusion, and never call a page compliant because a run
came back clean.
An install never overwrites a copy that has been edited; --force does.
In Claude Code, the plugin brings the skill and the MCP server together,
and runs the server through npx, so nothing else has to be installed:
License
MIT
pour is a registered trade mark in the UK, number UK00004432542. The MIT licence covers the code, not the name: forks are welcome under a name of their own.
