pagereflect

CLI and Model Context Protocol server for PageReflect. One package, two modes: run it as an MCP server so Claude (or any MCP client) can audit sites and manage action workflows, or run it as a plain CLI to do the same from your terminal. Typed tools cover account connection, audit runs/reports, site history/schedules, and action interactivity (list, update, comment, and handoff).

Get started

npm i -g pagereflect    # or use npx -y pagereflect ... with no install
pagereflect login        # opens your browser, click Accept, done
pagereflect audit https://example.com

pagereflect login opens your browser to a PageReflect approve screen. Click Accept, and the browser hands an org-scoped API key back to the CLI, which stores it at ~/.pagereflect/credentials.json (0600). After that the CLI and the MCP server authenticate with no env key. On a headless box or over SSH, use pagereflect login --no-browser for the device-code flow (a short code you approve in any browser).

The key is a normal PageReflect org API key: scoped to one organization, stored as an Argon2id hash server-side, and revocable any time from Settings → API & Webhooks. You can still skip login and pass PAGEREFLECT_API_KEY directly if you prefer.

CLI

pagereflect <command> [options]

Commands:
  login                        Connect your account in the browser
  logout                       Remove the stored credential
  whoami                       Show the currently connected account
  doctor                       Check Node, config, auth, and connectivity
  mcp                          Run the MCP server over stdio (Claude Desktop / Claude Code)
  account                      Show the connected organization and API key
  audit <url> [--site <id>]    Run an audit with a live progress bar
  run <runId>                  Show run status
  report <reportId>            Show a report (--format json|pdf_url)
  sites                        List sites in the organization
  history <siteId> [--limit N] Recent runs for a site (default 10, max 100)
  schedule <siteId>            Show a site's re-audit schedule
  actions                      List actions (--status/--priority/--site/--assignee/--limit)
  action:update <actionId>     Update action metadata (status, priority, assignee, due-at, title, description)
  action:comment <actionId>    Add an action comment (--body "...")
  action:brief <actionId>      Read the async action brief status/content
  action:brief:request <id>    Queue async action brief generation
  actions:handoff <ids...>     Generate handoff prompt from action IDs

Options:
  --json            Raw JSON output (no spinner, no color) for scripting
  --no-wait         For 'audit': queue and exit without polling
  --timeout <sec>   For 'audit': max seconds to wait (default 300)
  --no-browser      For 'login': use the device-code flow (SSH / headless)
  --api-key <key>   Override the stored credential / PAGEREFLECT_API_KEY
  --api-url <url>   Override PAGEREFLECT_API_URL
  --no-color        Disable color
  -v, --version
  -h, --help

Credential resolution order for every command: --api-key flag, then PAGEREFLECT_API_KEY env, then the stored pagereflect login credential.

By default audit polls the run and shows a live progress bar, then prints the score and report links. In a real terminal you get a spinner, colored status badges, and aligned tables; when piped or in CI those degrade to plain lines. Use --json for machine-readable output on stdout (errors go to stderr with a non-zero exit code).

MCP install

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

After you've run pagereflect login once, no env key is needed:

{
  "mcpServers": {
    "pagereflect": {
      "command": "npx",
      "args": ["-y", "pagereflect", "mcp"]
    }
  }
}

If you'd rather not use login, add an "env": { "PAGEREFLECT_API_KEY": "sk_pageref_..." } block instead. Restart Claude Desktop either way. The seven tools appear in the tools picker.

Claude Code

# after `pagereflect login`:
claude mcp add pagereflect -- npx -y pagereflect mcp

# or with an explicit key:
claude mcp add pagereflect --env PAGEREFLECT_API_KEY=sk_pageref_... -- npx -y pagereflect mcp

Account & plan

pagereflect login works on any plan; running audits through the tools requires a Pro PageReflect plan. Manage or revoke CLI keys at Settings → API & Webhooks (keys created by login are named CLI - <hostname>).

After connecting, call get_account (or run pagereflect account). It returns the connected organization, the API-key name/prefix, and the user who issued the key. If it returns 401, the key is missing, mistyped, or revoked.

Tools

| Tool | Description | |---|---| | get_account | Verify the connection to a PageReflect org/account. | | start_audit | Start an audit for a URL. Returns a runId. | | get_run | Poll run status; includes the linked report when scoring finishes. | | get_report | Fetch report JSON or a signed PDF URL. | | list_sites | List sites in your org with last-audited timestamps. | | get_history | Recent runs for a site (newest first). | | get_schedule | Current re-audit schedule for a site. | | get_actions | List action items with optional status/priority/site/assignee filters. | | update_action | Update action status/priority/assignee/due-at/title/description. | | comment_action | Add a comment to an action item. | | get_action_brief | Get async brief status/content for an action. | | request_action_brief | Trigger async brief generation for an action. | | get_actions_handoff | Generate a handoff prompt for selected actions. |

Env vars

| Var | Required | Default | |---|---|---| | PAGEREFLECT_API_KEY | no (use login instead) | stored credential | | PAGEREFLECT_API_URL | no | https://www.pagereflect.com | | PAGEREFLECT_TIMEOUT_MS | no | 60000 | | PAGEREFLECT_CONFIG_DIR | no | ~/.pagereflect |

Files it writes

The CLI writes exactly one file: ~/.pagereflect/credentials.json (mode 0600), created by pagereflect login and removed by pagereflect logout. Set PAGEREFLECT_CONFIG_DIR to relocate it. Nothing else on disk is touched.

Troubleshooting

• 401 / not authenticated — the key is missing, mistyped, or revoked. Run pagereflect login again, or check the key at Settings -> API & Webhooks.
• Calls hit the wrong environment — set PAGEREFLECT_API_URL (the apex redirects to www, so use https://www.pagereflect.com, not the apex).
• Need detail on a failure — re-run with --debug for the full stack trace.

Rate limits

Requests are rate limited. A 429 response means you've hit the limit, so back off and retry with exponential backoff. Tool calls are logged to the organization's MCP invocation history with argument hashes, not raw arguments.

License

MIT.