Reference integration

Ally Demo Python.

A minimal CLI that emits structured error messages and demonstrates the full Ally pipeline — a11y-assist, a11y-lint, and a11y-ci working together.

Get started Read the Handbook

Install

pip install -e .

Emit

demo-cli network-timeout --json-out error.json

Explain

a11y-assist explain --json error.json --profile lowvision

What This Demonstrates

End-to-end Ally pipeline in a single repo.

Structured Errors

Emits cli.error.v0.1 JSON on every failure — machine-readable ground truth alongside human-friendly output.

Five A11y Profiles

Low vision, cognitive load, screen reader, dyslexia, and plain language — each transforms the same error differently.

Lint & Validate

a11y-lint validates your error messages against the contract. a11y-ci gates your CI pipeline with scorecards.

Safe Commands Only

a11y-assist only suggests commands marked SAFE (like --dry-run). Never escalates privilege or mutates state.

Copy-Paste Adoption

Designed as a template — adopt the Ally pipeline in your own CLI in under 10 minutes.

Intentionally Boring

No magic, no frameworks. Just a reference integration that shows exactly what "good" looks like.

Quick Start

Install & run

python -m venv .venv
source .venv/bin/activate

pip install -e .
pip install a11y-assist a11y-lint

demo-cli network-timeout --json-out /tmp/error.json

Explain with profiles

a11y-assist explain --json /tmp/error.json --profile lowvision
a11y-assist explain --json /tmp/error.json --profile cognitive-load
a11y-assist explain --json /tmp/error.json --profile screen-reader
a11y-assist explain --json /tmp/error.json --profile dyslexia
a11y-assist explain --json /tmp/error.json --profile plain-language

Error Scenarios

Built-in demo commands that emit structured errors.

Command

Error ID

Description

demo-cli network-timeout

DEMO.NETWORK.TIMEOUT

HTTP request timeout

demo-cli config-missing

DEMO.CONFIG.MISSING

Missing config file

demo-cli auth-failed

DEMO.AUTH.INVALID_TOKEN

Authentication failure

demo-cli permission-denied

DEMO.FS.PERMISSION_DENIED

File permission error

demo-cli validation-error

DEMO.VALIDATION.SCHEMA

Schema validation failure

What "Good" Looks Like

Human output

[ERROR] Title (ID: DEMO.NETWORK.TIMEOUT)

What:
  Description of what happened.

Why:
  Explanation of why it happened.

Fix:
  Steps to resolve the issue.
  Re-run: command --dry-run

Validate with lint

# Validate message contract
a11y-lint validate /tmp/error.json

# Gate CI with scorecards
a11y-ci gate

Adopt Ally in 10 Minutes

Four steps to accessible error messages in your CLI.

Step

Action

Emit cli.error.v0.1 JSON on failure (machine output)

Print the same content in a predictable text structure (human output)

Add CI: a11y-lint validate + a11y-ci gate for scorecards

Tell users: a11y-assist explain --json <file>