AEO Auditor CLI
PageSpeed for AI agents. Scan any website and score its Agent/Engine Optimization (AEO) readiness across 5 dimensions — Discovery, Identity, Capabilities, Commerce, and Trust — then get a graded report with prioritized, actionable fixes.
Grades are relative: a site is ranked against a benchmark corpus (A = top tier of agent-readiness today), so the score stays a meaningful, movable target while agent-native standards are still emerging.
Architecture Overview
graph TD
CLI[CLI: aeo-audit] --> Engine[ScanEngine]
Engine --> Config[ConfigLoader]
Engine --> Crawler[Playwright Crawler]
Engine --> Registry[CheckRegistry]
Crawler --> Fetch[Fetch URL & Render DOM]
Registry --> Run[Run 26 Audit Checks]
Run --> Score[Scoring Pipeline]
Score --> Reporter[ReporterFactory]
Reporter --> Terminal[Rich Terminal]
Reporter --> HTML[HTML Report]
Reporter --> PDF[WeasyPrint PDF]
Reporter --> JSON[JSON Metadata]
Installation
1. System Dependencies (Required for WeasyPrint PDF)
PDF reports require external layout libraries installed on your OS:
-
macOS (Homebrew):
brew install pango cairo gdk-pixbuf upx
-
Ubuntu/Debian:
sudo apt-get update sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 upx
2. Install Methods
Method A: Via pip / pipx (Recommended)
pipx install aeo-audit # isolated CLI install (recommended)
# or: pip install aeo-audit
# bleeding edge from main:
# pipx install git+https://github.com/AJ-EN/aeo-audit.git
That's it — on your first scan, aeo-audit downloads the headless Chromium it needs automatically (one-time, ~30s). To pre-install it yourself:
playwright install chromium
Method B: Standalone Binary Installer (No Python Needed)
Run the automated installation script:
curl -fsSL https://raw.githubusercontent.com/AJ-EN/aeo-audit/main/scripts/install.sh | bash
Method C: Source installation
git clone https://github.com/AJ-EN/aeo-audit.git
cd aeo-audit
pip install -e .
playwright install chromium
Quick Start
Scan a site and generate reports using the scan command:
# Terminal report (default)
aeo-audit scan https://api.example.com --format terminal
# Premium HTML report with embedded graphs
aeo-audit scan https://api.example.com --format html --output report.html
# Accessible PDF report
aeo-audit scan https://api.example.com --format pdf --output report.pdf
# Machine-readable JSON report
aeo-audit scan https://api.example.com --format json --output report.json
Scoring & Grading
Each of the 26 checks returns a raw score (0.0–1.0). Checks roll up into 5 weighted category scores, which roll up into a single 0–100 overall score. The grade is then assigned by percentile rank against a benchmark corpus — so it reflects how a site compares to the field, not an absolute bar that nobody clears yet.
Category weights
aeo-audit is foundation-weighted: dimensions where well-run APIs already differ today (Trust, Capabilities, Discovery) carry the most weight, while emerging agent-native dimensions (Identity, parts of Commerce) contribute upside without dominating the score.
| Category | Weight | What it measures |
|---|---|---|
| Discovery | 0.25 |
robots/agent access, sitemap, .well-known, DNS, and MCP discovery. |
| Capabilities | 0.25 |
Interface docs — OpenAPI, JSON Schema, GraphQL, async webhooks. |
| Trust | 0.25 |
SLA/status page, structured errors, health checks, audit logs. |
| Commerce | 0.15 |
Agent transactions — pricing, Stripe/crypto hints, usage metering. |
| Identity | 0.10 |
Ownership & auth — DID docs, OAuth metadata, wallet hints. |
Grade bands (percentile)
| Grade | Percentile | Meaning |
|---|---|---|
| A | top 10% | Leading the field on agent-readiness. |
| B | top 30% | Strong; a few high-leverage gaps. |
| C | top 60% | Foundational signals present, frontier gaps. |
| D | top 85% | Minimal agent-readiness. |
| F | bottom 15% | Not addressed. |
Weights, thresholds, and grade bands are all defined in config.yaml and overridable via a custom config. See docs/CONFIG_REFERENCE.md.
CI/CD Pipeline Integration
You can easily configure aeo-audit as a compliance block (exits with code 2 if scores drop below requirements). Here's a brief example for GitHub Actions:
- name: AEO Compliance Gate
run: aeo-audit scan https://preview.example.com --fail-on-grade B --format terminal
See docs/CI_RECIPES.md for GitHub Actions, GitLab CI, and Git hooks code snippets.
Extending: Custom Check Plugins
To implement custom checking rules, subclass BaseCheck and expose it under the aeo_audit.checks entrypoint.
See docs/CUSTOM_CHECKS.md for a complete template walkthrough.
FAQ
1. How do I install Playwright browser binaries?
If running the scanner for the first time, you may need to install Playwright's headless browser binaries:
playwright install chromium
2. Where is the SQLite cache stored?
By default, the SQLite cache database is created in your working directory as .aeo_cache.db to speed up consecutive audit scans. This can be customized or disabled using --no-cache.
3. Why are my PDF files empty or raising font errors?
Ensure you have installed the native pango and cairo system dependencies (see Step 1 of installation).
Metadata
Release files for aeo-audit 1.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aeo_audit-1.2.1.tar.gz | 238.3 kB | Without provenance | Details for aeo_audit-1.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aeo_audit-1.2.1-py3-none-any.whl | Python 3 | none | any | Details for aeo_audit-1.2.1-py3-none-any.whl |
Total release size: 373.9 kB
Release files / aeo_audit-1.2.1.tar.gz
| Download URL | aeo_audit-1.2.1.tar.gz |
|---|---|
| Size | 238.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e62de83cd0db35007d070ebe344915bda5420e50147ef739d0720622556d2281
|
|
BLAKE2b-256 checksum How to use checksums |
e76e31e57847839005c677fc378918e23814593954ac7b7e65fb5b31ed4d8c94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / aeo_audit-1.2.1-py3-none-any.whl
| Download URL | aeo_audit-1.2.1-py3-none-any.whl |
|---|---|
| Size | 135.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
039c4a57646f9119946d4540077c6a6f19987de059374438dd3bf8b68f938a59
|
|
BLAKE2b-256 checksum How to use checksums |
089b3cf2b858d51d7600967649f59c232c055012cb2d8731c3043e9adcd5576e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for aeo-audit 1.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.