The AILK AEO scoring CLI — what it measures, how to run it

ailk audit scores the citation-readiness of an AILK site's MDX content. Run it before launch to catch structural AEO gaps. Run it in CI to block regressions before they reach the client.

The CLI ships in the OSS. Apache 2.0. No separate tool to install if you are already on the AILK substrate.

What the CLI measures

ailk audit runs four rules against the content directory. Each one measures a structural property the foundation either has or lacks — not a style preference, not a keyword density score.

Schema coverage. Every AILK page declares a schema.org type in its frontmatter. The schemaCoverage rule checks that the page actually emits valid JSON-LD for that type. A page typed FAQPage that does not emit FAQ-structured markup fails this rule. The citation consequence: a model reading the page cannot trust the structure it finds.

JSON-LD validity. The jsonldValidity rule checks whether the emitted structured data is well-formed — correct @context, correct @type, no malformed property values. Invalid JSON-LD is silently ignored by search engines and LLMs alike. The error is invisible until the citation never shows up.

Entity markup. The entityMarkup rule checks whether the page's entity — the Organization or Person whose site this is — is declared unambiguously. A page that names the product in body copy but does not anchor it to a structured entity leaves the model to guess. Models that guess often attribute the page to the wrong entity or skip attribution entirely.

FAQ and HowTo incentive. The faqHowtoIncentive rule checks whether pages carrying FAQ or HowTo content use structured markup for it. FAQ and HowTo are high-incentive schema types — LLMs extract and cite them disproportionately relative to equivalent prose. A page with five Q&A paragraphs but no FAQ schema is leaving citation share on the table.

How to run it

Three modes cover the standard deployment lifecycle.

Pre-launch audit. Run pnpm aeo audit from the project root. The human-readable output names each rule, its pass/fail status, and the pages involved. The score is a summary percentage of rules passing across all pages. Zero configuration required for a standard AILK setup.

CI baseline mode. Run pnpm aeo audit --baseline baseline.json. The CLI compares the current audit against the saved baseline and exits with code 1 if any previously-passing rule now fails. Wire this into the PR check. A regression detected before merge costs minutes. Discovered after deploy, it costs the client citation share until the next release cycle.

To capture a baseline: pnpm aeo audit --format json > baseline.json. Commit the baseline file. The CI step catches any drift.

JSON output for tooling. pnpm aeo audit --format json pipes the full audit report into any downstream toolchain. The JSON output carries the rule-level breakdown — per-page results, evidence strings, score. Use it to drive dashboards, Slack alerts, or custom reporting.

Additional flags: --advisory-only suppresses the exit 1 on regression, useful for tracking without blocking during active remediation. --identity-mode person or organization sets whether the site's root entity is a Person or Organization. --content-root sets a custom path to the content directory.

What this replaces

Enterprise AEO platforms — Authoritas, Semrush's AEO feature set, Moz's schema validator — charge $295 a month and up to run the same measurement pass. The key difference: they measure gaps after the site ships. A gap found post-launch means the citation work has already been losing for however long the site was live.

ailk audit runs pre-launch. The gap is caught in the same session the page was written, not three months later when the client asks why they are not showing up in the AI answers their competitors are in.

The Apache 2.0 license means the CLI is free, permanently, without conditions. Not a freemium with a gate. Not "free until you have paying clients." Free.

The schema cluster this anchors

ailk audit is the tool surface for the Pillar 2 schema-tool cluster. The related surfaces in this cluster — all live at /aeo-audit.

• Schema markup generator — AILK's typed schema registry generates JSON-LD from frontmatter. No manual schema authoring. Ship a page, ship the structure.
• Schema markup validator — The jsonldValidity rule in ailk audit is the validation pass. Catches malformed structured data output before it ships.
• Structured data testing tool — ailk audit is the structured-data test suite for an AILK site. Same job as Google's Rich Results Test, earlier in the pipeline and integrated with CI.
• AEO scoring — The overall score from ailk audit is the AEO score — a percentage of rules passing across all pages, broken down by rule and page.

Frequently asked

Does ailk audit work on any website or only AILK sites?

ailk audit runs against any content directory that follows the AILK MDX frontmatter contract — type, slug, title, description as required fields, with the schema.org type declared in frontmatter. If your site was built on AILK, the CLI works out of the box. If not, it can be configured to point at a compatible content directory via --content-root.

What does the score represent?

The score is the percentage of audit rules passing across all pages. A score of 80 means 20% of rule evaluations across the site's pages found a gap. The per-rule and per-page breakdown in the output shows exactly which pages failed which rules. The score is a summary; the breakdown is where the work is.

How do I track AEO regressions in CI?

Run pnpm aeo audit --format json > baseline.json on a known-good build. Commit the baseline. Add pnpm aeo audit --baseline baseline.json to the PR check. The CLI exits 1 on any regression — a rule that was passing on the baseline now failing. Use --advisory-only to track without blocking, if the client site is mid-remediation.

Is this the same as enterprise AEO platforms like Authoritas or Semrush?

No. Enterprise AEO platforms are analytics services — they crawl a live site, measure structured data, and report gaps. ailk audit is a pre-launch CLI that runs in CI before the site ships. Different moment in the pipeline. The enterprise platforms are useful for sites already live that want to measure the gap. ailk audit is for catching the gap before it becomes one.

See the audit tool in action

The full tool surface — including a live demo of ailk audit running against the AILK marketing site — is at /aeo-audit. The broader capability roster is at /platform.