Quickstart | a11ied

Step 1

Install the CLI

Install a11ied globally, or add it to your project as a developer dependency:

npm install --global a11ied

The package provides two identical binaries: a1 (short shorthand) and a11ied. Every example throughout these docs uses a1.

If you prefer not to install globally, run any command with npx a11ied <command>.

Step 2

Check your environment

Run a1 doctor to inspect your local setup. It checks for installed browsers, system permissions, and available screen reader targets:

a1 doctor

✓ Ready for a1 commands on macOS 26.5.2 (arm64)

Targets
  ✓ macos-voiceover  ready  Ready for real screen reader sessions.
      ✓ AppleScript control enabled in VoiceOver settings
      ✓ AppleScript control confirmed by macOS
      ✓ VoiceOver local preferences exist
      ✓ VoiceOver welcome dialog suppressed
      ✓ Guidepup VoiceOver preferences bundle installed
      ✓ Screen recording available to the current host app
  - windows-nvda     Only available on Windows.
  ✓ virtual-dom      ready  No setup needed.

Browser automation
  ✓ Google Chrome  ready  Used for a1 axe scans.
      Path    /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
      Launch  system install, opened through the "chrome" browser channel
      Others  Playwright Chromium

  Policy    system-browser-first: an installed Chrome, Edge, Brave, or Chromium is used before Playwright's Chromium
  Fallback  npx playwright install chromium

Environment
  a11ied  0.1.0
  Node    v24.19.0
  npm     11.17.0
  Host    macOS 26.5.2 (arm64) [darwin]

A leading ✓ indicates your system is ready. If a native tool needs configuration, a1 doctor displays an Action items list with the exact command to resolve it. Because the virtual screen reader used in this quickstart runs entirely in software, it requires zero OS configuration or elevated permissions.

Step 3

Run an automated accessibility audit

Start your local development server, then scan a route with a1 audit. Powered by axe-core, it checks rendered DOM structure against official WCAG success criteria:

a1 audit http://localhost:3000/checkout --level AA

✗ 1 problem to fix.

4.1.2  Name, Role, Value  [A]
  button[type="button"]
  Fix: Buttons must have discernible text. Add an aria-label or visible text.

Check by hand
  18 criteria this page triggers require interactive or screen reader review:
    • 2.1.1  Keyboard
    • 2.4.3  Focus Order
    • 4.1.3  Status Messages

The page
  Titled Checkout. It has 1 main landmark, 1 form, 2 textboxes, 2 buttons.

Every finding includes the official WCAG criterion, the failing element selector, and actionable remediation advice. When scripting in CI, pass --json for machine-readable output.

Static vs. runtime

Notice the Check by hand section: static scanners catch DOM syntax errors, but cannot verify keyboard focus sequence, live region announcements, or widget state transitions.

Step 4

Start a virtual screen reader session

To verify what assistive technology actually announces when interacting with your interface, launch a virtual screen reader session against your URL:

a1 sr start --sr virtual http://localhost:3000/checkout

✓ Session drv_c33f1d8f4461 started
  Target: virtual (headless Chromium)
  URL:    http://localhost:3000/checkout

The virtual target runs inside a headless browser engine, computing the full ARIA accessibility tree and speech queue. Page scripts, CSS transitions, and client-side framework components execute normally.

Active session

Subsequent a1 sr commands automatically target this active session. You don't need to copy or manage session IDs in your terminal.

Step 5

Drive navigation and inspect speech

Step through interactive elements one by one, or read the entire page from top to bottom with read-all:

a1 sr read-all

document
heading, Checkout, level 1
form
Email
textbox, Email, required
Card number
textbox, Card number
button, Pay now
button
end of form
end of document

Review the transcript in chronological order:

The first input correctly announces its label and its required state (satisfying WCAG 4.1.2).
The second button speaks only button with no accessible name—confirming the exact violation identified during the audit in Step 3.

You can also send individual keyboard strokes like a1 sr press Tab, a1 sr press ArrowDown, or a1 sr next to test dynamic widgets step-by-step.

Step 6

Stop the session

When you're finished testing, stop the session to release worker processes and temporary state:

a1 sr stop

✓ Session drv_c33f1d8f4461 stopped

Next steps

Integrate accessibility into your workflow

You've just audited a page and verified screen reader announcements from your terminal. Here is how to take it further:

Automate with Vitest Run screen reader assertions alongside your unit tests using a11ied/vitest. See the Vitest guide.

Equip AI coding agents Connect the local MCP server to Cursor, Claude Code, or Windsurf so agents can verify their own UI code. See the AI agents guide.

Test on real OS screen readers Automate real macOS VoiceOver or Windows NVDA sessions and record video demos. See the screen readers guide.