axray-cli

See your website the way an AI agent does.

npx axray-cli example.com

AXRAY fetches a URL exactly the way a crawling AI agent does — plain HTTP, no browser, no JavaScript, one request, a hard timeout — and tells you what actually arrived. It returns an Agent Experience (AX) score out of 100 and a fix list ordered by how many points each change recovers.

  AXRAY  example.com  https://example.com/

   46 /100   D   ███████████░░░░░░░░░░░░░
   89 /100   potential after config-only fixes

  Reachability     88  ████████████████░░  weight 25
  Comprehension    48  █████████░░░░░░░░░  weight 25
  Structure        15  ███░░░░░░░░░░░░░░░  weight 18
  Actionability    42  ████████░░░░░░░░░░  weight 17
  Agent Contract   13  ██░░░░░░░░░░░░░░░░  weight 15

  Fix list, highest value first

   1. FAIL  Ships structured data  +6.2 pts [config-only]
      No JSON-LD and no microdata anywhere on the page.
      Fix: Add a JSON-LD block describing what this page actually is.

Why

You already measure how fast a page paints and how it ranks. Neither tells you whether an assistant can quote your pricing correctly, whether a shopping agent can find your stock status, or whether the crawler that would have cited you was turned away at your CDN this morning.

The failure is silent. No error, no 500, no alert — your CDN returns a challenge page, your React app ships an empty <div id="root">, your price lives in a styled span, and the assistant confidently summarises you from whatever fragment it managed to read.

Usage

npx axray-cli example.com                 # human-readable report
npx axray-cli example.com --verbose       # every finding, the reasoning and code snippets
npx axray-cli example.com --probe         # also fetch as real AI crawler user-agents
npx axray-cli example.com --crawl 50      # crawl the site, find systemic issues
npx axray-cli example.com --json > ax.json
npx axray-cli example.com --min 70        # exit 1 below 70, for CI

axray-cli localhost:3000 --allow-private   # your own dev server, before you deploy

| Option | | | --- | --- | | --json | Print the full result as JSON instead of a report | | --verbose, -v | Every finding with reasoning, evidence and snippets | | --crawl [n] | Crawl up to n pages of the site (default 20) | | --probe | Also fetch with real AI crawler user-agents (extra requests) | | --min <score> | Exit with code 1 below this score. For CI. | | --timeout <ms> | Per-request timeout (default 12000) | | --allow-private | Permit localhost, private addresses and any port |

About --allow-private

By default the scanner refuses private, loopback, link-local and cloud-metadata addresses, on every redirect hop, and only speaks to ports 80 and 443. That is the server-side request forgery defence, and on the hosted service at axray.online it can never be switched off — that service fetches URLs strangers hand it.

Here the situation is the reverse. You are running this on your own machine against a target you chose, and reaching your own dev server is not forgery. So --allow-private opts out, explicitly and per invocation. It relaxes the address and port rules; it does not relax the scheme rule, because there is no version of this tool that needs to read file:///etc/passwd.

As a library

import { scan, crawl, describeSpec, CHECK_COUNT } from 'axray-cli';

const result = await scan('example.com');
console.log(result.score, result.grade);
for (const fix of result.priorities.slice(0, 3)) {
  console.log(`+${fix.impact} pts — ${fix.title}: ${fix.fix?.summary}`);
}

const spec = describeSpec(); // the whole rubric, as data

Zero runtime dependencies. Node 22.6 or newer, for the built-in node:sqlite used by the server package; the scanner itself needs only the standard library.

What it measures

Five pillars, 70 checks, published in full and generated from the scoring code so the specification cannot drift from the scanner.

| Pillar | Weight | The question | | --- | ---: | --- | | Reachability | 25 | Can an agent get the bytes at all? | | Comprehension | 25 | Can it tell what this page is? | | Structure | 18 | Can it read the facts, or must it infer them? | | Actionability | 17 | Can it do the next thing — navigate, search, submit, buy? | | Agent Contract | 15 | Have you told it the rules? |

Checks measure substance, not presence. An empty llms.txt, a JSON-LD block with no properties, an h1 that repeats your domain name — each is marked thin evidence and earns at most half its weight, because a published rubric is also a recipe for satisfying it without improving anything.

Politeness

The scanner identifies itself as Mozilla/5.0 (compatible; AXRAY/1.0; +https://axray.online/bot) AgentExperienceScanner.

It refuses private, loopback, link-local and cloud-metadata addresses on every redirect hop; it only speaks http and https on ports 80 and 443; and it honours your robots.txt. To turn it away entirely:

User-agent: AXRAY
Disallow: /

Links

• axray.online — scan a URL in the browser
• The AX specification — every check and its weight
• JSON API — the same engine over HTTP
• Changelog

MIT licensed.