Monitoring and Optimizing AI Search Visibility with Canonry

Practical Summary and Core Functionality

Canonry is an open-source, agent-first platform designed for AEO (Answer Engine Optimization) and GEO (Generative Engine Optimization). It provides a comprehensive operating environment for tracking how websites appear in AI-driven search results. By utilizing a self-hosted SQLite backend and direct provider API keys, Canonry allows users to measure brand mentions, citation coverage, and technical site health. The platform is built to support both manual CLI operations and automated agent workflows, enabling users to investigate visibility changes across various search engines and answer models while maintaining a clear audit trail of evidence.

Prerequisites and Initial Setup

To begin using Canonry, you must have a system capable of running Node.js applications. The platform is designed to be self-hosted, requiring you to manage your own provider keys for AI models such as Gemini, OpenAI, Claude, or Perplexity. Before starting, ensure you have installed the CLI tool globally:

npm install -g @canonry/canonry

After installation, initialize the environment using cnry bootstrap. This command sets up the necessary configuration and database files. Once initialized, you can start the background daemon with cnry start. The CLI and REST API are the primary interfaces for interacting with the platform, which is single-tenant by design to ensure team isolation for each instance.

Establishing a Technical Baseline

Before optimizing for AI visibility, it is essential to establish a Page Health baseline. This process involves crawling your site to identify technical issues that might hinder search engine indexing. You can create a project and initiate a bounded scan using the following commands:

cnry project create my-site --domain example.com --country US --language en
cnry technical-aeo run my-site --max-pages 100 --wait --format json

The --wait flag is critical for automated workflows, as it polls the status of the scan for up to 15 minutes. If the scan is still active, you can monitor progress using cnry technical-aeo progress <project> --run-id <run-id> --format json. Always verify the hasData field in the score output to ensure the crawl successfully captured site information before proceeding to analysis.

Tracking AI Visibility and Citations

AI visibility tracking focuses on how your brand is mentioned and cited across different answer engines. Unlike traditional SEO, this requires monitoring specific queries to see if your site is included in generated responses. You must configure your chosen provider by setting the appropriate environment variable (e.g., OPENAI_API_KEY). Once configured, add your target queries to the project:

cnry query add my-site "your first query" "your second query"
cnry run my-site --wait
cnry visibility-stats my-site --by-provider

This workflow allows you to track share-of-mention trends over time. The citation map provides diagnostic data, showing which domains and pages are cited for specific queries, enabling you to identify gaps where competitors are being cited instead of your own properties.

Advanced Research and Portfolio Management

For complex sites, Canonry supports versioned measurement plans through properties and market groups. This allows you to segment your tracking by location, product line, or site section, ensuring that branded and non-branded coverage are analyzed separately. If you need to perform one-off research without altering your primary tracking queries, use the research command:

cnry research run <project> "query one" "query two" --wait

This command saves the destination and answers without adding them to your tracked query list. Additionally, the platform supports discovery runs via cnry discover run <project> --icp "...", which helps identify new questions relevant to your site's content strategy.

Acting on Evidence and Integration

Canonry is designed to facilitate action based on the evidence collected. Once you have identified visibility gaps or technical issues, you can use the platform's integrations to implement changes. This includes publishing content directly to WordPress, managing JSON-LD data, or submitting URLs for indexing. The platform also supports webhook alerts for Slack or Discord, ensuring your team is notified of significant changes in visibility. By combining site audits with search data, you can create targeted pull requests or content drafts to improve your site's standing in AI-generated answers.

Limitations and Troubleshooting

Users should be aware that Canonry is a single-tenant, self-hosted platform; you are responsible for managing your own instances and API quotas. If a scan fails or returns partial results, use cnry run show <run-id> --format json to inspect the error logs. A partial scan indicates that the crawler reached a limit—such as a page, depth, or time constraint—rather than completing a full site audit. Adjusting your scan parameters, such as --max-pages or --max-depth, is necessary to resolve these limitations. For further assistance, the official documentation is available at https://github.com/AINYC/canonry.

Who Should Use Canonry

Canonry is intended for developers, SEO professionals, and technical teams who require granular control over their AI search visibility data. It is particularly well-suited for organizations that need to maintain strict data privacy by self-hosting their SEO infrastructure and those who want to integrate visibility metrics directly into their CI/CD or agentic workflows. Because it relies on direct provider APIs rather than model routers, it is the preferred choice for users who need high-fidelity data on how their brand is represented in AI-generated citations. It is not a passive tool; it requires active management of configurations, API keys, and scan schedules.