# Lensy command line.

> Part of [Lensy by Perseverance AI](https://perseveranceai.com/). The index of every page for AI agents is at [https://perseveranceai.com/llms.txt](https://perseveranceai.com/llms.txt).

Last updated: 2026-11-21

Check a docs page from your terminal or your CI. You get the same two scores as perseveranceai.com, and the same fixes.

## What it is

`lensy` checks live documentation pages and gives each one two scores out of 100. Coding agents is how well a coding agent can find and read the page. AI search is how well AI search engines can retrieve and cite it. It runs the same checks as the website. The Coding agents score is built on AFDocs, the open Agent-Friendly Documentation checks, plus one Lensy check for headings.

It checks exactly the pages you give it and doesn't crawl your site. It runs on your own machine or CI runner, so nothing about your pages is sent to Perseverance AI.

## Install

You need Node 22 or newer.

```
npm install -g @perseverance-ai/lensy@next
lensy --version
```

To run it once without installing:

```
npx @perseverance-ai/lensy@next check https://docs.example.com/guide
```

The tool is an early release, published under the `next` tag. For now it's also what `npm install -g @perseverance-ai/lensy` installs.

## Check a page

```
lensy check https://docs.example.com/guide
```

A bare hostname such as `docs.example.com` works too and gets `https://` added. For one page, the terminal shows both scores, whether an honest AI agent can reach the page and how much of the page an agent receives. Then it lists what to fix first, ordered by the points each fix is worth, with one line on what to do. The points add up to each score: fix everything listed and both scores reach 100. A page takes a few seconds, or up to half a minute on a large site.

Example output, shortened:

```
https://vitepress.dev/guide/getting-started
  Coding agents 87/100    AI search 95/100
  Reachability: an honest AI agent can read this page (HTTP 200). robots.txt allows all 6 AI search bots.
  What an agent receives: Markdown, 6,235 characters (about 1,559 tokens), fits in one fetch

  Fix these first
   1. Page points agents to llms.txt (HTML)       −6  Coding agents
      Add a visually-hidden element near the top of each page containing a link to your llms.txt.
   2. JSON-LD                                     −5  AI search
      Add a JSON-LD block (for example TechArticle) with dateModified.
   3. Page points agents to llms.txt (Markdown)   −4  Coding agents
   4. Markdown on request                         −3  Coding agents

  Passed: 20 of 25 Coding agents checks, 5 of 6 AI search checks.
```

Add `--verbose` to see every check instead: its id, its points, what it found and the full fix. Checks that come from AFDocs are marked `AFDocs`. AFDocs checks add up to more than 100 points, so the score scales them to 100, and the verbose view says so.

Colour is off when the output goes to a file or a pipe, when you pass `--no-color`, and when the `NO_COLOR` variable is set.

## Check several pages

Give more than one URL:

```
lensy check https://docs.example.com/start https://docs.example.com/api
```

Or list them in a file, one URL per line. Blank lines and lines that start with `#` are ignored.

```
# docs to check
https://docs.example.com/start
https://docs.example.com/api
```

```
lensy check --urls-file urls.txt
```

With several pages, the terminal shows one row per page with both scores, then the three most useful fixes for each page. The full detail goes in a report file. A URL listed twice is checked once.

```
Page                               Coding agents  AI search  Status
https://vitest.dev/guide/cli       83/100         68/100     ok
https://vitest.dev/guide/features  87/100         71/100     ok
https://vitest.dev/guide/          87/100         68/100     ok
```

Pages are checked two at a time. `--concurrency` takes a number from 1 to 5. There is no page limit. Above 15 pages, the tool prints the page count and a rough time before it starts.

## Check a local build

Check your docs before you publish them: build the site, then point Lensy at the build folder. Lensy serves the folder on your machine for the length of the run and checks it like a published site. Nothing is sent anywhere else.

```
npx vitepress build docs
lensy check --dir docs/.vitepress/dist --site-url https://docs.example.com --all
```

`--site-url` is your published docs address. Your build's sitemap, `llms.txt` and canonical links name that address, and Lensy matches them to the local files, so the result is what the published site will get. `--all` checks every page in the build. Without it, name pages by their path, such as `/guide/getting-started`, or leave them out to check the home page.

The build folder depends on your docs tool: `docs/.vitepress/dist` for VitePress, `build` for Docusaurus, `site` for MkDocs and `dist` for Astro Starlight. If your docs live under a path, such as VitePress `base: '/docs/'`, include it in `--site-url`: `https://example.com/docs`.

Some checks depend on your web server or CDN, not your build, so a local check leaves them out and says so. Each score shows the points earned out of the points it could check:

```
https://docs.example.com/guide/getting-started
  Coding agents 58 of 70 points checked    AI search 77 of 100 points checked

  Fix these first
   1. Freshness declared                         −15  AI search
      Set lastUpdated: true in the VitePress config.
   2. Page points agents to llms.txt (HTML)       −6  Coding agents

  Not checked here (your web server or CDN decides these, so check the live site for them): Markdown
  on request, Real 404s for missing pages, Redirects, Cache headers, Public without login, Bot
  protection lets agents in.
```

Fix something, rebuild and check again. With saving on, you see the change straight away:

```
  Since today: Coding agents 58 → 58    AI search 77 → 89 (+12)
```

Already running your docs tool's preview of the production build? Point Lensy at it instead: `lensy check http://localhost:4173 --site-url https://docs.example.com --all`, where `--all` reads the preview's sitemap. Use the preview command (`vitepress preview`, `docusaurus serve`), not the dev server, which can render pages differently.

## Save a report

Add `--html`, `--md` or `--json` to save the full result. Use any of them together in one run.

```
lensy check https://docs.example.com/guide --html report.html --md report.md --json report.json
```

The HTML report is one file that opens offline: no scripts and no external links, with light and dark themes. The Markdown report is for coding agents. It starts with the scores and the tool version, then the checks in tables, then each fix as a checkbox, ordered by how many points it gains, so you can hand it to an agent as a to-do list. Both reports hold the same content in the same structure, called report version 1. The JSON file is for scripts and CI: each page has its scores, its fixes ordered by points lost, and the full check results. Use `--json -` to print only the JSON, for example to pipe it to `jq`. The folder you name must already exist. If it doesn't, the command stops before it checks anything.

## Save and compare runs

Lensy can keep every run and compare each page with its last run, so you can see whether your docs got better or worse, what you fixed and what broke. The first time you run `lensy check` in a project, it asks:

```
Save Lensy results for this project in .lensy? Each run is compared with the last one, so you can see what changed. [Y/n]
```

Answer `y` and Lensy creates a `.lensy` folder at the root of your project (the folder with `.git`, or the current folder outside a git project) and remembers the answer there. Answer `n` and nothing is created; Lensy remembers that in `~/.lensy/config.json` and doesn't ask again. It only asks in a terminal. In CI, in a script, or with `--json -`, it never asks, and saves only when told to.

From the next run on, each page shows what changed since its last saved run:

```
https://vitepress.dev/guide/getting-started
  Coding agents 87/100    AI search 95/100
  Since Nov 2 (6 days ago): Coding agents 80 → 87 (+7)    AI search 95 → 95
  Fixed: llms.txt exists
```

`New:` lists checks that passed last time and lose points now. With several pages, the summary table gets a `Change` column, such as `+7 / 0` or `first run`.

The folder holds JSON for scripts and Markdown for people and coding agents:

```
.lensy/
├── config.json      project settings
├── latest.md        the last run, every page: hand it to a coding agent
├── history.md       one row per page per run, newest first
└── pages/
    └── docs.example.com/guide/start/
        ├── page.json        which URL this folder is for
        ├── latest.json      the newest result for this page
        ├── latest.md        the report for this page
        └── runs/2026-11-08T183012Z.json   one file per run
```

Lensy keeps the newest 52 runs of each page. List the pages you check in `.lensy/config.json`, and `lensy check` with no URLs checks them all. Keep `"save": true` in that file so runs without a terminal, such as in CI, save too; if `.lensy` exists but a run doesn't save, Lensy says so.

```
{
  "configVersion": 1,
  "save": true,
  "keep": 52,
  "pages": ["https://docs.example.com/guide/start", "https://docs.example.com/api"]
}
```

For one run, `--save` saves even if you answered no, `--no-save` skips saving and the question, and `--save-dir` saves in another folder. Saved results stay on your machine. Commit `.lensy` to share the history with your team.

## Explain a check

```
lensy explain llms-txt-exists
```

This prints what the check measures, why it matters, how many points it is worth and the evidence behind it. Use any check id from a report or from `--verbose`. Ids are not case sensitive. They are the AFDocs names, such as `llms-txt-exists` and `rendering-strategy`, `lensy-headings` for Lensy's heading check, and `S1` to `S6` for AI search. `C1` to `C6` are the Coding agents checks Lensy uses only when AFDocs can't run.

## Exit codes

- `0`: every page was checked.
- `2`: the command was wrong. There was no URL, an option had a bad value, a `--dir` folder had no built pages, `.lensy/config.json` had a problem, or results couldn't be saved where asked. Nothing was fetched.
- `3`: at least one page couldn't be checked. It was unreachable, it wasn't an HTML page, or its bot protection refused the tool. The other pages still print.
- `1`: something unexpected failed, or the results of a run that was told to save couldn't be written. The message starts with `lensy:` or `Couldn't save results`.

Scores never change the exit code, so a failing check doesn't fail a CI job. A page that couldn't be checked does. If a site's bot protection refuses the tool, it doesn't retry as a browser. It says the page wasn't checked and points you to the audit on perseveranceai.com.

## What it sends

Every request carries `lensy-cli/<version> (+https://perseveranceai.com/bot)`. The [Lensy checker page](https://perseveranceai.com/docs/bot) explains what Lensy fetches and how a site owner can allow it.

For each page the tool fetches the page itself, robots.txt, the sitemap, llms.txt, a sample of the pages llms.txt links to, the Markdown version of the page, and a few other URLs that the AFDocs checks need. That is usually 15 to 60 requests per page. They go from your machine to the sites you named, and nowhere else. Saved results are written only to your own disk.

`--user-agent` sends a different name, for example to test a rule on your own site. `--timeout` sets how long each request may take, in milliseconds, from 1000 to 120000.

## What it can't do yet

- Check source files before you build.
- Check pages behind a login. The tool can't sign in, so it only checks public pages.

## Requirements and help

You need Node 22 or newer and npm. There's no account, API key or setup. For live pages, Lensy needs network access to the sites you check and nothing else. A local build check sends nothing off your machine.

**Tested on.** Every pull request runs the full test suite on Linux, macOS and Windows with Node 22 and 24. By hand, on macOS with Node 22, 24 and 26, we checked live pages on VitePress, Docusaurus, Mintlify, GitBook, Read the Docs, MkDocs Material, Nextra, Starlight and others, and local builds from VitePress 1.6 (with and without a base path), Docusaurus 3.10, Astro Starlight 0.42 and MkDocs Material 9.8. Windows and Linux desktops are covered by the automated tests, not yet by hand.

**Known issues being fixed:** Astro's `sitemap-index.xml` and sitemaps under a base path aren't read yet, and a canonical link written without quotes, as Docusaurus minifies it, isn't detected. Each costs some AI search points it shouldn't.

**Found a problem?** Email [hello@perseveranceai.com](mailto:hello@perseveranceai.com) or use the [contact page](https://perseveranceai.com/contact). Include `lensy --version`, `node -v`, your operating system, the command and its output; add `LENSY_DEBUG=1` if it failed with an error. Never send tokens, internal hostnames or unpublished content. The command line tool is free to use under the [Terms of Use](https://perseveranceai.com/legal/terms#cli).
