Marlo accessibility checker

# Marlo API and CLI documentation

Read measured accessibility coverage, inspect rule evidence, and scan local HTML with Marlo.

## Public API: authentication and endpoints

The public API is read-only and requires no authentication or API key. Its base URL is `https://trymarlo.pages.dev/api/v1`. Successful responses use `application/json`. The [OpenAPI specification](https://trymarlo.pages.dev/openapi.json) defines operation identifiers, parameters, and response schemas.

-   `GET /api/v1/coverage`: published coverage and corpus totals.
-   `GET /api/v1/rules`: the published ACT rule catalog.
-   `GET /api/v1/rules/{actRuleId}`: a rule and its measured evidence. Replace the path parameter with an identifier returned by the catalog.
-   `GET /api/v1/calibration`: the published calibration table, including measurements and routing.

```
curl -sS 'https://trymarlo.pages.dev/api/v1/coverage'
curl -sS 'https://trymarlo.pages.dev/api/v1/rules'
curl -sS 'https://trymarlo.pages.dev/api/v1/calibration'
```

These endpoints serve the same published data as the website. They do not perform a live audit. Corpus measurements describe behavior on that corpus and should not be presented as a prediction for every production page.

## Errors and Markdown responses

API errors use RFC 9457 Problem Details with `Content-Type: application/problem+json`. The standard fields describe the problem and HTTP status; the `code` and `hint` extensions provide a stable error code and a resolution hint. Inspect the HTTP status before parsing a successful response.

```
curl -sS -i 'https://trymarlo.pages.dev/api/v1/does-not-exist'
curl -sS -i -H 'Accept: text/markdown' 'https://trymarlo.pages.dev/'
curl -sS -i -H 'Accept: text/markdown' 'https://trymarlo.pages.dev/does-not-exist'
```

Pages support Markdown negotiation using `Accept: text/markdown`; the response has `Content-Type: text/markdown` and `Vary: Accept`. Requests for HTML continue to receive HTML. Unknown page paths return HTTP 404, including a Markdown explanation when requested. API paths keep their structured JSON errors.

## Local CLI quickstart

Install from a [source checkout](https://github.com/KarthikSubramanian07/Marlo), using the Node and pnpm versions declared in the repository. Run the commands below from the repository root, replacing `file.html` with an HTML file you own.

```
pnpm install
pnpm build
node packages/cli/dist/bin.js scan file.html --json
node packages/cli/dist/bin.js coverage
node packages/cli/dist/bin.js explain ACT_RULE_ID
```

The scan writes its machine-readable report to standard output. Exit code `0` means no findings among evaluated rules, `1` means findings, `2` means a usage or input error, and `3` means incomplete evaluation when an error occurs or skipped rules are treated as failures. Add `--fail-on-skipped` when incomplete coverage must fail your check.

The default static renderer does not evaluate layout-dependent rules. The optional browser renderer provides additional capabilities; consult the repository setup instructions before using `--renderer browser`. The default renderer executes inline scripts in the input, so scan trusted files you own. No hosted scan endpoint is provided.

## MCP quickstart

Connect a client supporting Streamable HTTP to `https://trymarlo.pages.dev/mcp`. Initialize the connection using the MCP protocol before listing or calling tools. Requests are stateless and do not require an API key. The manifest is available at [/.well-known/mcp](https://trymarlo.pages.dev/.well-known/mcp).

-   `marlo_coverage` reads published coverage.
-   `marlo_list_rules` lists the published rule catalog.
-   `marlo_explain_rule` reads evidence for an ACT rule identifier.

Use metadata to choose a suitable rule or engine. Run the CLI locally to evaluate a page, and retain skipped rules, peer disagreements, and measurement provenance in the report.
