Documentation
Everything you need to get started with Xyle — from connecting Google Search Console to running AI-powered SEO, AEO, and GEO analysis from the terminal or dashboard.
Quickstart
Get your AI agent optimizing content in 3 commands.
For AI Agents (Recommended)
$ npm install -g @xyleapp/cli
$ xyle login
✓ Logged in as you@example.com
$ xyle seed --tool cursor
✓ Created .cursorrules with SEO workflow
✓ Added site context and query data
✓ Agent ready to optimize your content
That's it for vibe coding — your agent handles the rest. Replace cursor with claude-code, copilot, windsurf, or any supported tool. For manual CLI usage, see below.
Manual CLI Workflow
Zero to first SEO query in 5 steps.
# 1. Sign in at xyle.app (creates your account)
# Then go to Settings → connect your Google Search Console
# 2. Install the CLI
$ npm install -g @xyleapp/cli
# 3. Log in (opens browser → Google OAuth)
$ xyle login
✓ Logged in as you@example.com
# 4. Confirm your site is connected
$ xyle sites
your-domain.com · 142 queries
# 5. Run your first query
$ xyle queries --site your-domain.com --limit 5
1. best react frameworks pos 4 · 1.2k clicks
2. nextjs vs remix pos 7 · 890 clicks
3. server components tutorial pos 12 · 340 clicks
Sign up & connect GSC
Sign in with Google at xyle.app. Then go to Settings and follow the 4-step wizard to verify your domain and add the Xyle service account.
xyle login
Opens Google OAuth in your browser. After you authorize, the CLI saves credentials to ~/.config/xyle/credentials.json. Alternatively, set AGENT_API_KEY from Settings to skip OAuth entirely.
CLI Reference
All commands available in the @xyleapp/cli package. Every command supports --json for machine-readable output.
Data Commands
queries
List top search queries for a site from Google Search Console.
xyle queries --site <domain> [--limit <n>] [--json]
| Option | Description |
|---|---|
| --site <domain> | Site domain or URL (required) |
| --limit <n> | Max queries to return (default: 20) |
| --json | Output as JSON |
competitors
Show competitor pages ranking for a given search query.
xyle competitors --query "<query>" [--json]
| Option | Description |
|---|---|
| --query <query> | Search query to analyze (required) |
| --json | Output as JSON |
gaps
Identify content gaps for a page — missing topics, CTR issues, and position buckets.
xyle gaps --page <url> [--query "<query>"] [--json]
| Option | Description |
|---|---|
| --page <url> | Page URL to check gaps for (required) |
| --query <query> | Optional query to filter results |
| --json | Output as JSON |
analyze
Score your page content against competitors. Returns SEO score, AEO score, summary, missing topics, and AEO recommendations.
xyle analyze --url <url> --content "<text>" [--query "<query>"] [--json]
| Option | Description |
|---|---|
| --url <url> | Page URL to analyze (required) |
| --content <text> | Page content text (required) |
| --query <query> | Target query for analysis |
| --json | Output as JSON |
rewrite
Get AI-powered rewrite suggestions for page elements — titles, meta descriptions, headings, or content sections.
xyle rewrite --url <url> [--type title|meta|heading|section] [--query "<query>"] [--json]
| Option | Description |
|---|---|
| --url <url> | Page URL to rewrite (required) |
| --type <element> | Element type: title, meta, heading, section (default: title) |
| --query <query> | Target query for rewrite |
| --json | Output as JSON |
crawl
Crawl a URL and extract SEO metadata, AEO, and GEO signals — title, meta description, word count, headings, 18 AEO signals, and 15 GEO signals (schema markup, citability, content structure, quality metrics).
xyle crawl --url <url> [--json]
| Option | Description |
|---|---|
| --url <url> | URL to crawl (required) |
| --json | Output as JSON |
sync
Sync Google Search Console data for a site. Pulls latest queries, impressions, clicks, and positions.
xyle sync --site <url> [--json]
| Option | Description |
|---|---|
| --site <url> | Site URL to sync (required) |
| --json | Output as JSON |
sites
List all connected sites for your account.
xyle sites [--json]
| Option | Description |
|---|---|
| --json | Output as JSON |
Auth Commands
login
Authenticate with Google. Opens OAuth flow in your browser and saves credentials to ~/.config/xyle/credentials.json.
xyle login
logout
Remove stored credentials.
xyle logout
whoami
Show current authentication status — email, API key prefix, and base URL.
xyle whoami
Agent Commands
seed
Add Xyle agent instructions to your project. Seeds your AI coding tool with SEO workflow context.
xyle seed [--tool <name>] [--all] [--dir <path>] [--list]
| Option | Description |
|---|---|
| --tool <name> | Specific tool to seed (see list below) |
| --all | Seed all supported tools |
| --dir <path> | Target directory (default: cwd) |
| --list | List all supported tools |
Utility Commands
status
Check if the Xyle API is reachable.
xyle status [--json]
API Reference
Access Xyle programmatically with your personal API key. All endpoints return JSON.
Authentication
Generate a personal API key in Settings. Include it in every request as a header:
X-Agent-Key: your-api-key
Or set it as an environment variable:
export AGENT_API_KEY="your-api-key"
Base URL
All endpoints are relative to:
https://api.xyle.app
Override with the SEO_BASE environment variable for self-hosted instances.
Endpoints
| Method | Path | Params | Response |
|---|---|---|---|
| GET | /health | — | { status } |
| GET | /queries | site, limit? | [{ query, impressions, clicks, ctr, position }] |
| GET | /competitors | query | [{ position, url, title, word_count }] |
| GET | /gaps | page, query? | [{ query, missing_topics, ctr_issue, position_bucket }] |
| POST | /analyze | url, content, query? | { score, aeo_score, summary, missing_topics, aeo_recommendations } |
| POST | /rewrite | url, type?, query? | { original, suggested, reasoning } |
| POST | /crawl | url | { title, meta_desc, word_count, headings, aeo_signals } |
| POST | /admin/sync | site | { synced_queries, site } |
| GET | /admin/sites | email? | [{ domain, synced_queries, gsc_url, created_at }] |
Dashboard Guide
The Xyle dashboard gives you a visual overview of all connected Search Console properties.
Connecting Search Console
Head to Settings to connect your first site. The setup wizard guides you through domain verification, adding the Xyle service account, and running your initial data sync.
Multi-Site Support
Connect as many Search Console properties as you need. Each site appears as a card on your dashboard showing the domain and number of synced queries. Click "+ Add site" to connect another property.
What the Dashboard Shows
For each connected site you can see the domain name and total synced queries at a glance. Use the CLI for deeper analysis — run xyle queries, xyle gaps, or xyle analyze to dig into the data.
Site Analysis
The Analysis page lets you analyze any public URL without the CLI. Enter a URL to see:
- •Crawl summary — title, meta description, word count, headings
- •SEO, AEO, and GEO Scores as visual ring charts
- •13 AEO signals checklist — schema markup, content structure, quality metrics
- •Actionable AEO recommendations with numbered priorities
API Keys
Generate personal API keys in Settings for programmatic access. Each key shows its prefix, creation date, last used date, and can be revoked at any time. Use the X-Agent-Key header or the AGENT_API_KEY environment variable.
After Connecting Your Domain
You've added your domain in Settings and verified it with Google Search Console. Here's exactly what to do next — from the dashboard and the CLI.
Wait for the initial sync
After clicking Verify & Sync in Settings, Xyle pulls your latest Google Search Console data. Head back to the Dashboard — your site card will show the number of synced queries once the sync is complete (usually a few seconds).
View your top queries
Use the CLI to see which search queries drive traffic to your site. Replace your-domain.com with the domain you just connected.
$ xyle queries --site your-domain.com --limit 10
1. your top keyword pos 3 · 2.1k clicks
2. second keyword pos 8 · 540 clicks
...
Find content gaps
Pick a page on your site and discover missing topics, CTR issues, and ranking buckets.
$ xyle gaps --page https://your-domain.com/blog
query: react tutorial missing: hooks, server components
query: nextjs guide CTR issue · position 6-10
Analyze a page against competitors
Crawl your page, then score it against competing pages for a target keyword.
# Crawl SEO metadata
$ xyle crawl --url https://your-domain.com/blog/post
# See who you're competing against
$ xyle competitors --query "target keyword"
Get AI-powered rewrites
Let Xyle suggest optimized titles, meta descriptions, headings, or content sections for any page.
# Rewrite the title for a target keyword
$ xyle rewrite --url https://your-domain.com/blog/post --type title --query "target keyword"
✓ "10 Best Tips for Target Keyword — 2026 Guide"
# Rewrite the meta description
$ xyle rewrite --url https://your-domain.com/blog/post --type meta
Keep data fresh with sync
Run a manual sync anytime to pull the latest data from Google Search Console, or use the Full Sync button in Settings.
$ xyle sync --site your-domain.com
✓ Synced 142 queries for your-domain.com
Generate an API key (optional)
If you want programmatic access or want to use the API from CI/CD, go to Settings and create a personal API key. Use it with the CLI or direct HTTP requests:
export AGENT_API_KEY="your-key-here"
xyle queries --site your-domain.com --json
Seed your AI coding agent (optional)
Give your AI agent full SEO context so it can optimize content for you automatically. See Agent Integration below for all supported tools.
$ xyle seed --tool claude-code
✓ Created CLAUDE.md with SEO workflow
Agent Integration
Give your AI coding agent full SEO context in 4 commands.
Quick Setup
# 1. Install the CLI
$ npm install -g @xyleapp/cli
# 2. Log in with Google
$ xyle login
✓ Logged in as you@example.com
# 3. Confirm your site is connected
$ xyle sites
your-domain.com · 142 queries
# 4. Seed your agent (pick your tool)
$ xyle seed --tool cursor
✓ Created .cursorrules with SEO workflow
That's it. Your agent now has every Xyle command, two ready-made workflows, and full SEO context. Replace cursor with your tool — see the table below.
Supported Tools
| Tool | --tool flag | Config file |
|---|---|---|
| Claude Code | claude-code | CLAUDE.md |
| Cursor | cursor | .cursorrules |
| GitHub Copilot | vscode | .github/copilot-instructions.md |
| Windsurf | windsurf | .windsurfrules |
| Cline | cline | .clinerules |
| Codex | codex | AGENTS.md |
| Aider | aider | CONVENTIONS.md |
| Augment | augment | .augment-guidelines |
What Gets Created
Each seeded file contains a complete Xyle reference — all CLI commands with syntax and return fields (including AEO signals and scores), environment variables, and ready-made workflows: Full SEO, AEO & GEO Audit, Page Optimization, and AEO Optimization Sprint. If the config file already exists, Xyle appends to it instead of overwriting.
Example Workflows
Full SEO, AEO & GEO Audit
# 1. Check connection
$ xyle status
# 2. List sites and sync data
$ xyle sites
$ xyle sync --site example.com
# 3. Get top queries
$ xyle queries --site example.com --limit 20
# 4. Find content gaps
$ xyle gaps --page https://example.com/blog
# 5. Get SEO + AEO + GEO scores
$ xyle crawl --url https://example.com/blog
# Check AEO signals and schema markup
$ xyle analyze --url https://example.com/blog --content "..."
# Apply AEO recommendations, then rewrite
$ xyle rewrite --url https://example.com/blog --type title
Page Optimization
# 1. Crawl the target page
$ xyle crawl --url https://example.com/post
# 2. Check competitors
$ xyle competitors --query "target keyword"
# 3. Identify gaps
$ xyle gaps --page https://example.com/post --query "target keyword"
# 4. Get AI rewrites
$ xyle rewrite --url https://example.com/post --type title --query "target keyword"
$ xyle rewrite --url https://example.com/post --type meta
Environment Variables
| Variable | Default | Description |
|---|---|---|
| SEO_BASE | https://api.xyle.app | API base URL (override for self-hosted) |
| AGENT_API_KEY | — | Personal API key (alternative to OAuth login) |