Documentation

Run your first audit

Run a page audit, add a target query, and save a report you can compare after making changes.

Jeff Patterson / Agency Enterprise. Updated August 30, 2026.

Quickstart overview

aiseo-audit is a command-line tool that checks page-side signals related to retrieval and citation readiness. It analyzes fetched HTML without calling an external model. It cannot predict whether a search engine will cite the page.

Start by running the package with npx against a public or local URL. npx executes the published package without a global install. Add the real questions the page needs to answer before acting on the recommendations.

Requirements

aiseo-audit requires Node.js 20.19 or later and npm 10 or later. It needs no account, telemetry connection, or external AI service key.

Install and run the first audit

The result is a terminal report with the overall score, grade, pipeline stages, and top three recommendations. Detailed factor rows include evidence tiers and citations.

npx aiseo-audit https://example.com

Add AI search target queries

Target queries enable Query Alignment. The audit checks terms in structural fields, terms in the body, and whether a section addresses each query’s aspects. It scores the weakest supplied query rather than averaging away a gap.

npx aiseo-audit https://example.com/guide \
  --query "how to audit ai seo" \
  --query "generative engine optimization evidence"

How to interpret the result

Inspect the four stages in order. Technical eligibility checks page fetching and extraction. Retrieval alignment checks topic and query signals. Citation fitness checks directness, evidence, and reusable answers. Provenance checks authorship, organization identity, and attribution.

Fix a failed eligibility gate before optimizing downstream factors. For pages that pass, prioritize gaps tied to the supplied queries and prefer supported or conditional evidence over low-confidence heuristics.

Key takeaways

  • In short, start with one representative URL and the queries that define success.
  • Use --out report.html for a self-contained shareable report.
  • Use --sitemap to audit a site and build a host-level profile.
  • Use --diff to establish a baseline and track changes.
  • Use --fail-under only after calibrating a threshold against your own pages.

Official sources

The official npm package [1] and GitHub repository [2] confirm that aiseo-audit uses the MIT license and one analyzer for its command line and TypeScript interfaces.

  1. aiseo-audit on npm: package, version, and installation details.
  2. agencyenterprise/aiseo-audit: source code and project documentation.