@xyleapp/cli 0.8.0 → 0.11.0

package/README.md

@@ -34,6 +34,18 @@ xyle rewrite --url https://example.com/blog/seo-guide --type title
 # Crawl a page
 xyle crawl --url https://example.com/blog/seo-guide
 
+# Full-site crawl (BFS every internal page, detect site-wide issues)
+xyle site-crawl https://example.com --max-pages 500
+
+# View snapshot history
+xyle history --url https://example.com
+
+# View score trends
+xyle trends --site example.com --days 30
+
+# Compare two snapshots
+xyle diff --before <snapshot-id> --after <snapshot-id>
+
 # Sync Search Console data
 xyle sync --site https://example.com
 ```
@@ -50,6 +62,10 @@ xyle sync --site https://example.com
 | `analyze`     | Analyze page content against competitors       |
 | `rewrite`     | Get AI rewrite suggestions                     |
 | `crawl`       | Crawl a URL and extract SEO metadata           |
+| `site-crawl`  | Full-site BFS crawl with issue detection, link graph, and site health score |
+| `history`     | View snapshot history for a URL or site        |
+| `trends`      | View score trends over time                    |
+| `diff`        | Compare two snapshots side-by-side             |
 | `sync`        | Sync Google Search Console data                |
 | `login`       | Authenticate with Google OAuth                 |
 | `logout`      | Remove stored credentials                      |

package/bin/xyle.mjs

@@ -8,7 +8,7 @@ const program = new Command();
 program
   .name("xyle")
   .description("SEO & AEO Intelligence Engine CLI")
-  .version("0.8.0");
+  .version("0.11.0");
 
 registerCommands(program);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyleapp/cli",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "CLI for the Xyle SEO & AEO Intelligence Engine",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -49,7 +49,12 @@ async function request(method, path, { params, body, timeout = 30000, auth = tru
     let detail;
     try {
       const json = await resp.json();
-      detail = json.detail || resp.statusText;
+      const raw = json.detail;
+      if (Array.isArray(raw)) {
+        detail = raw.map((e) => e.msg || JSON.stringify(e)).join("; ");
+      } else {
+        detail = raw || resp.statusText;
+      }
     } catch {
       detail = resp.statusText;
     }
@@ -65,7 +70,9 @@ export function checkHealth() {
 }
 
 export function getTopQueries(site, limit = 20) {
-  return request("GET", "/queries", { params: { site, limit } });
+  const creds = getCredentials();
+  const email = creds?.email || null;
+  return request("GET", "/queries", { params: { site, limit, email } });
 }
 
 export function getCompetitors(query) {
@@ -93,7 +100,9 @@ export function crawlPage(url) {
 }
 
 export function syncGsc(site) {
-  return request("POST", "/admin/sync", { params: { site } });
+  const creds = getCredentials();
+  const email = creds?.email || null;
+  return request("POST", "/admin/sync", { params: { site, email } });
 }
 
 export function listSites() {
@@ -117,4 +126,67 @@ export function getInstructions(tool) {
   return request("GET", "/seed/instructions", { params: { tool }, timeout: 10000 });
 }
 
+export function listSnapshots(url, siteDomain, limit = 20) {
+  return request("GET", "/snapshots", { params: { url, site_domain: siteDomain, limit } });
+}
+
+export function getSnapshotTrends(url, siteDomain, days = 90) {
+  return request("GET", "/snapshots/trends", { params: { url, site_domain: siteDomain, days } });
+}
+
+export function diffSnapshots(beforeId, afterId) {
+  return request("GET", "/snapshots/diff", { params: { before: beforeId, after: afterId } });
+}
+
+export function askKnowledgeBase(question, url, topic, nSources = 5) {
+  const body = { question, n_sources: nSources };
+  if (url) body.context_url = url;
+  if (topic) body.topic = topic;
+  return request("POST", "/kb/ask", { body, timeout: 60000 });
+}
+
+export function getKbStats() {
+  return request("GET", "/kb/stats", { timeout: 10000 });
+}
+
+// ---------------------------------------------------------------------------
+// Site Crawl
+// ---------------------------------------------------------------------------
+
+export function startSiteCrawl(seedUrl, config = {}) {
+  // immediate=1 tells the API to run the crawl in-process via BackgroundTask.
+  // The CLI keeps polling /status, which keeps the Cloud Run instance warm
+  // for the duration. The web UI uses Trigger.dev instead and omits this.
+  return request("POST", "/site-crawl", {
+    params: { immediate: 1 },
+    body: { seed_url: seedUrl, config },
+    timeout: 30000,
+  });
+}
+
+export function getSiteCrawlStatus(jobId) {
+  // 60s timeout: the API container runs the crawl loop on the same event
+  // loop as the HTTP handler, so individual status requests can spike in
+  // latency when the crawl is hot. 15s was too tight.
+  return request("GET", `/site-crawl/${jobId}`, { timeout: 60000 });
+}
+
+export function getSiteCrawlPages(jobId, { limit = 50, offset = 0, filter } = {}) {
+  return request("GET", `/site-crawl/${jobId}/pages`, {
+    params: { limit, offset, filter },
+    timeout: 15000,
+  });
+}
+
+export function getSiteCrawlIssues(jobId, { severity, category, limit = 200 } = {}) {
+  return request("GET", `/site-crawl/${jobId}/issues`, {
+    params: { severity, category, limit },
+    timeout: 15000,
+  });
+}
+
+export function listSiteCrawls(limit = 25) {
+  return request("GET", "/site-crawl", { params: { limit }, timeout: 15000 });
+}
+
 export { SEO_BASE };

package/src/commands.mjs

@@ -3,10 +3,6 @@
  * Mirrors the Python CLI 1:1.
  */
 
-import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { execSync } from "node:child_process";
 import { printJson, printTable } from "./formatting.mjs";
 import {
   checkHealth,
@@ -18,6 +14,16 @@ import {
   crawlPage,
   syncGsc,
   listSites,
+  listSnapshots,
+  getSnapshotTrends,
+  diffSnapshots,
+  askKnowledgeBase,
+  getKbStats,
+  startSiteCrawl,
+  getSiteCrawlStatus,
+  getSiteCrawlPages,
+  getSiteCrawlIssues,
+  listSiteCrawls,
   SEO_BASE,
 } from "./api.mjs";
 import { getCredentials, clearCredentials, runLoginFlow } from "./auth.mjs";
@@ -171,6 +177,12 @@ export function registerCommands(program) {
             console.log(`${aeoColor}AEO Score: ${Math.round(data.aeo_score * 100)}%\x1b[0m`);
           }
 
+          // GEO Score
+          if (data.geo_score != null) {
+            const geoColor = data.geo_score >= 0.7 ? "\x1b[32m" : "\x1b[33m";
+            console.log(`${geoColor}GEO Score: ${Math.round(data.geo_score * 100)}%\x1b[0m`);
+          }
+
           // Structured Recommendations
           const structured = data.recommendations || [];
           if (structured.length) {
@@ -352,6 +364,23 @@ export function registerCommands(program) {
             }
           }
 
+          // GEO Signals
+          const geo = data.geo_signals;
+          if (geo) {
+            console.log(`\n\x1b[1mGEO Signals\x1b[0m`);
+            console.log(
+              `  ${check(geo.has_summary_section)} Summary Section    ${check(geo.has_last_reviewed_date)} Reviewed Date      ${check(geo.has_methodology_section)} Methodology`
+            );
+            console.log(
+              `  Quotable: ${geo.quotable_statement_count}  Statistics: ${geo.statistic_count}  Entities: ${geo.named_entity_count}  Definitions: ${geo.definition_clarity_count}`
+            );
+            console.log(
+              `  Comparisons: ${geo.comparison_structure_count}  Steps: ${geo.step_by_step_count}  Sources: ${geo.source_attribution_count}  Expertise: ${geo.author_expertise_signals}`
+            );
+            console.log(scoreBar("Topical Coverage", geo.topical_coverage_score));
+            console.log(scoreBar("Content Segmentation", geo.content_segmentation_score));
+          }
+
           const wc = data.word_count || 0;
           if (wc > 0 && wc < 50) {
             console.log(
@@ -382,6 +411,9 @@ export function registerCommands(program) {
           console.log(
             `\x1b[32mSynced ${data.synced_queries || 0} queries for ${data.site || opts.site}\x1b[0m`
           );
+          if (data.warning) {
+            console.log(`\x1b[33mWarning: ${data.warning}\x1b[0m`);
+          }
         }
       } catch (e) {
         handleError(e);
@@ -594,37 +626,486 @@ export function registerCommands(program) {
       }
     });
 
-  // --- deploy ---
+  // --- history ---
   program
-    .command("deploy")
-    .description("Deploy Xyle services (API, frontend, trigger.dev)")
-    .option("--api", "Deploy API to Cloud Run")
-    .option("--frontend", "Deploy frontend to Vercel")
-    .option("--trigger", "Deploy Trigger.dev tasks")
-    .option("--dir <path>", "Project root directory", process.cwd())
+    .command("history")
+    .description("View snapshot history for a URL or site")
+    .option("--url <url>", "Page URL to view history for")
+    .option("--site <domain>", "Site domain to view history for")
+    .option("--limit <n>", "Max snapshots to return", "10")
+    .option("--json", "Output as JSON")
     .action(async (opts) => {
-      const scriptPath = resolve(opts.dir, "scripts", "deploy.sh");
-      if (!existsSync(scriptPath)) {
-        process.stderr.write(
-          `\x1b[31mDeploy script not found: ${scriptPath}\x1b[0m\n` +
-            `\x1b[2mRun this command from the project root or use --dir <path>\x1b[0m\n`
-        );
+      if (!opts.url && !opts.site) {
+        process.stderr.write("\x1b[31mProvide --url or --site\x1b[0m\n");
         process.exit(1);
       }
+      try {
+        const data = await listSnapshots(opts.url, opts.site, parseInt(opts.limit, 10));
+        if (opts.json) {
+          console.log(printJson(data));
+        } else if (!data || data.length === 0) {
+          console.log("\x1b[33mNo snapshots found.\x1b[0m");
+        } else {
+          const rows = data.map((s) => {
+            const seo = s.seo_score != null ? Math.round(s.seo_score * 100) : null;
+            const aeo = s.aeo_score != null ? Math.round(s.aeo_score * 100) : null;
+            const seoColor = seo != null ? (seo >= 70 ? "\x1b[32m" : seo >= 40 ? "\x1b[33m" : "\x1b[31m") : "\x1b[2m";
+            const aeoColor = aeo != null ? (aeo >= 70 ? "\x1b[32m" : aeo >= 40 ? "\x1b[33m" : "\x1b[31m") : "\x1b[2m";
+            return {
+              created_at: new Date(s.created_at).toLocaleString(),
+              trigger: s.trigger_source || "-",
+              seo_score: `${seoColor}${seo != null ? seo + "%" : "-"}\x1b[0m`,
+              aeo_score: `${aeoColor}${aeo != null ? aeo + "%" : "-"}\x1b[0m`,
+              signals: `${s.passing_signals}/${s.total_signals}`,
+            };
+          });
+          console.log(`\n\x1b[1mSnapshot History\x1b[0m  (${data.length} snapshots)\n`);
+          console.log(printTable(rows, ["created_at", "trigger", "seo_score", "aeo_score", "signals"]));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
 
-      const flags = [];
-      if (opts.api) flags.push("--api");
-      if (opts.frontend) flags.push("--frontend");
-      if (opts.trigger) flags.push("--trigger");
-      // No flags = deploy all (script's default behavior)
+  // --- trends ---
+  program
+    .command("trends")
+    .description("View score trends over time")
+    .option("--url <url>", "Page URL to view trends for")
+    .option("--site <domain>", "Site domain to view trends for")
+    .option("--days <n>", "Number of days to look back", "90")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      if (!opts.url && !opts.site) {
+        process.stderr.write("\x1b[31mProvide --url or --site\x1b[0m\n");
+        process.exit(1);
+      }
+      try {
+        const data = await getSnapshotTrends(opts.url, opts.site, parseInt(opts.days, 10));
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const points = data.points || [];
+          if (points.length === 0) {
+            console.log("\x1b[33mNo trend data found.\x1b[0m");
+          } else {
+            const target = data.url || data.site || opts.url || opts.site;
+            console.log(`\n\x1b[1mScore Trends\x1b[0m  ${target}  (${data.period_days} days)\n`);
+
+            // ASCII sparkline
+            const seoVals = points.map((p) => (p.seo_score != null ? Math.round(p.seo_score * 100) : null));
+            const aeoVals = points.map((p) => (p.aeo_score != null ? Math.round(p.aeo_score * 100) : null));
+            const geoVals = points.map((p) => (p.geo_score != null ? Math.round(p.geo_score * 100) : null));
+            const spark = (vals) => {
+              const ticks = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+              const valid = vals.filter((v) => v != null);
+              if (valid.length === 0) return "-";
+              const min = Math.min(...valid);
+              const max = Math.max(...valid);
+              const range = max - min || 1;
+              return vals.map((v) => (v != null ? ticks[Math.min(7, Math.floor(((v - min) / range) * 7))] : " ")).join("");
+            };
+
+            console.log(`  SEO  ${spark(seoVals)}  ${seoVals.filter((v) => v != null).slice(-1)[0] ?? "-"}%`);
+            console.log(`  AEO  ${spark(aeoVals)}  ${aeoVals.filter((v) => v != null).slice(-1)[0] ?? "-"}%`);
+            console.log(`  GEO  ${spark(geoVals)}  ${geoVals.filter((v) => v != null).slice(-1)[0] ?? "-"}%`);
+            console.log();
+            console.log(printTable(
+              points.map((p) => ({
+                date: p.date,
+                seo: p.seo_score != null ? Math.round(p.seo_score * 100) + "%" : "-",
+                aeo: p.aeo_score != null ? Math.round(p.aeo_score * 100) + "%" : "-",
+                geo: p.geo_score != null ? Math.round(p.geo_score * 100) + "%" : "-",
+                signals: p.passing_signals,
+              })),
+              ["date", "seo", "aeo", "geo", "signals"]
+            ));
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
 
-      const cmd = `bash "${scriptPath}" ${flags.join(" ")}`;
-      console.log(`\x1b[36mRunning:\x1b[0m ${cmd}\n`);
+  // --- diff ---
+  program
+    .command("diff")
+    .description("Compare two snapshots")
+    .requiredOption("--before <id>", "Before snapshot ID")
+    .requiredOption("--after <id>", "After snapshot ID")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
       try {
-        execSync(cmd, { stdio: "inherit", cwd: opts.dir });
+        const data = await diffSnapshots(opts.before, opts.after);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(`\n\x1b[1mSnapshot Diff\x1b[0m\n`);
+
+          const delta = (label, val) => {
+            if (val == null) return `  ${label.padEnd(20)} -`;
+            const pct = Math.round(val * 100);
+            const sign = pct > 0 ? "+" : "";
+            const color = pct > 0 ? "\x1b[32m" : pct < 0 ? "\x1b[31m" : "\x1b[2m";
+            return `  ${label.padEnd(20)} ${color}${sign}${pct}%\x1b[0m`;
+          };
+
+          console.log(delta("SEO Score", data.seo_delta));
+          console.log(delta("AEO Score", data.aeo_delta));
+          console.log(delta("GEO Score", data.geo_delta));
+
+          if (data.breakdown_delta) {
+            for (const [key, val] of Object.entries(data.breakdown_delta)) {
+              console.log(delta(`  ${key}`, val));
+            }
+          }
+
+          const sigDelta = data.signals_delta || 0;
+          const sigColor = sigDelta > 0 ? "\x1b[32m" : sigDelta < 0 ? "\x1b[31m" : "\x1b[2m";
+          const sigSign = sigDelta > 0 ? "+" : "";
+          console.log(`  ${"Signals".padEnd(20)} ${sigColor}${sigSign}${sigDelta}\x1b[0m`);
+
+          const resolved = data.resolved_issues || [];
+          if (resolved.length) {
+            console.log(`\n  \x1b[32mResolved:\x1b[0m`);
+            for (const issue of resolved) {
+              console.log(`    \x1b[32m\u2713\x1b[0m ${issue}`);
+            }
+          }
+
+          const newIssues = data.new_issues || [];
+          if (newIssues.length) {
+            console.log(`\n  \x1b[31mNew Issues:\x1b[0m`);
+            for (const issue of newIssues) {
+              console.log(`    \x1b[31m\u2717\x1b[0m ${issue}`);
+            }
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- ask ---
+  program
+    .command("ask")
+    .description("Query the knowledge base for expert SEO/AEO/GEO guidance")
+    .requiredOption("--question <text>", "Question to ask the knowledge base")
+    .option("--url <url>", "Context URL for the question")
+    .option("--topic <topic>", "Topic filter (e.g., schema, technical-seo)")
+    .option("--sources <n>", "Number of sources to retrieve", "5")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await askKnowledgeBase(
+          opts.question,
+          opts.url,
+          opts.topic,
+          parseInt(opts.sources, 10)
+        );
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(`\n\x1b[1mAnswer\x1b[0m${data.grounded ? " \x1b[32m(grounded)\x1b[0m" : ""}\n`);
+          console.log(data.answer);
+          console.log();
+        }
       } catch (e) {
-        process.stderr.write(`\x1b[31mDeploy failed.\x1b[0m\n`);
-        process.exit(e.status || 1);
+        handleError(e);
       }
     });
+
+  // --- geo ---
+  program
+    .command("geo")
+    .description("Show GEO (Generative Engine Optimization) signals and score for a URL")
+    .requiredOption("--url <url>", "URL to analyze for GEO signals")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await crawlPage(opts.url);
+        if (opts.json) {
+          console.log(printJson({
+            url: data.url,
+            geo_signals: data.geo_signals,
+          }));
+        } else {
+          const geo = data.geo_signals;
+          if (!geo) {
+            console.log("\x1b[33mGEO signals not available for this page.\x1b[0m");
+            return;
+          }
+          const check = (v) => (v ? "\x1b[32m\u2713\x1b[0m" : "\x1b[31m\u2717\x1b[0m");
+          const scoreBar = (label, score) => {
+            const pct = Math.round((score || 0) * 100);
+            const filled = Math.round(pct / 5);
+            const bar = "\u2588".repeat(filled) + "\u2591".repeat(20 - filled);
+            const color = pct >= 70 ? "\x1b[32m" : pct >= 40 ? "\x1b[33m" : "\x1b[31m";
+            return `  ${label.padEnd(28)} ${color}${bar} ${pct}%\x1b[0m`;
+          };
+
+          console.log(`\n\x1b[1mGEO Signals\x1b[0m  ${data.url}\n`);
+
+          console.log(`\x1b[1mCitability (40%)\x1b[0m`);
+          console.log(`  Quotable statements:  ${geo.quotable_statement_count}`);
+          console.log(`  Statistics:           ${geo.statistic_count}`);
+          console.log(scoreBar("Unique insight density", geo.unique_insight_density));
+          console.log(`  Source attributions:   ${geo.source_attribution_count}`);
+
+          console.log(`\n\x1b[1mEntity/Topical (25%)\x1b[0m`);
+          console.log(`  Named entities:       ${geo.named_entity_count}`);
+          console.log(scoreBar("Topical coverage", geo.topical_coverage_score));
+          console.log(`  Clear definitions:    ${geo.definition_clarity_count}`);
+
+          console.log(`\n\x1b[1mStructural (25%)\x1b[0m`);
+          console.log(`  ${check(geo.has_summary_section)} Summary/TL;DR section`);
+          console.log(`  Comparison structures: ${geo.comparison_structure_count}`);
+          console.log(`  Step-by-step content:  ${geo.step_by_step_count}`);
+          console.log(scoreBar("Content segmentation", geo.content_segmentation_score));
+
+          console.log(`\n\x1b[1mAuthority (10%)\x1b[0m`);
+          console.log(`  ${check(geo.has_last_reviewed_date)} Last reviewed date`);
+          console.log(`  Expertise signals:    ${geo.author_expertise_signals}`);
+          console.log(`  ${check(geo.has_methodology_section)} Methodology section`);
+          console.log(scoreBar("Authority link ratio", geo.outbound_authority_ratio));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- site-crawl ---
+  const siteCrawlCmd = program
+    .command("site-crawl")
+    .description("Full-site SEO crawler — Screaming Frog-style audit");
+
+  // site-crawl <url> — start a crawl and poll until complete
+  siteCrawlCmd
+    .command("start")
+    .description("Start a full-site crawl")
+    .argument("<url>", "Seed URL to crawl")
+    .option("--max-pages <n>", "Maximum pages to crawl (default 50, max 500)", "50")
+    .option("--max-depth <n>", "Maximum crawl depth (default 3, max 10)", "3")
+    .option("--render-js", "Enable JavaScript rendering (slower, for SPA sites)")
+    .option("--include-subdomains", "Follow links to subdomains of the seed host")
+    .option("--json", "Output as JSON (no live polling)")
+    .action(async (url, opts) => {
+      try {
+        // NOTE: robots.txt is always respected server-side. The crawler
+        // identifies as Xyle-Crawler/<version> and cannot be spoofed.
+        const config = {
+          max_pages: parseInt(opts.maxPages, 10),
+          max_depth: parseInt(opts.maxDepth, 10),
+          render_js: opts.renderJs === true,
+          include_subdomains: opts.includeSubdomains === true,
+        };
+        const data = await startSiteCrawl(url, config);
+        const jobId = data.job_id;
+
+        if (opts.json) {
+          console.log(printJson(data));
+          return;
+        }
+
+        console.log(`\x1b[36mCrawl started:\x1b[0m ${jobId}`);
+
+        // Poll every 2 seconds. Progress bar denominator is `max_pages`
+        // (the hard cap), not `pages_discovered` — which is the frontier
+        // size and can explode on link-heavy sites, making the bar look
+        // broken. We also tolerate a few transient poll failures (the API
+        // container is busy running the crawl on the same event loop so
+        // individual status requests can spike latency).
+        const POLL_MS = 2000;
+        const MAX_POLL_ERRORS = 5;
+        const target = config.max_pages;
+        let prev = -1;
+        let pollErrors = 0;
+        while (true) {
+          await new Promise((r) => setTimeout(r, POLL_MS));
+          let status;
+          try {
+            status = await getSiteCrawlStatus(jobId);
+            pollErrors = 0;
+          } catch (err) {
+            pollErrors += 1;
+            if (pollErrors >= MAX_POLL_ERRORS) {
+              process.stdout.write("\n");
+              console.log(`\x1b[31mLost connection while polling.\x1b[0m The job may still be running server-side.`);
+              console.log(`Re-check with: xyle site-crawl status ${jobId}`);
+              return;
+            }
+            continue;
+          }
+          const crawled = status.pages_crawled || 0;
+          const errors = status.errors_count || 0;
+
+          if (crawled !== prev) {
+            const pct = Math.min(100, Math.round((crawled / target) * 100));
+            const filled = Math.round(pct / 5);
+            const bar = "\u2588".repeat(filled) + "\u2591".repeat(20 - filled);
+            process.stdout.write(`\r  ${bar} ${pct}%  ${crawled}/${target} pages  ${errors} errors  `);
+            prev = crawled;
+          }
+
+          if (["completed", "failed", "cancelled"].includes(status.status)) {
+            process.stdout.write("\n");
+            if (status.status === "completed") {
+              const h = status.health_score != null ? Math.round(status.health_score * 100) : null;
+              const hColor = h != null ? (h >= 70 ? "\x1b[32m" : h >= 40 ? "\x1b[33m" : "\x1b[31m") : "\x1b[2m";
+              console.log(`\x1b[32mCompleted.\x1b[0m  Pages: ${crawled}  Errors: ${errors}`);
+              if (h != null) {
+                console.log(`Site Health: ${hColor}${h}%\x1b[0m`);
+              }
+              console.log(`\nView pages:  xyle site-crawl pages ${jobId}`);
+              console.log(`View issues: xyle site-crawl issues ${jobId}`);
+            } else {
+              console.log(`\x1b[31mCrawl ${status.status}\x1b[0m${status.error_message ? ": " + status.error_message : ""}`);
+            }
+            break;
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // site-crawl status <job_id>
+  siteCrawlCmd
+    .command("status")
+    .description("Check crawl job status")
+    .argument("<jobId>", "Crawl job ID")
+    .option("--json", "Output as JSON")
+    .action(async (jobId, opts) => {
+      try {
+        const data = await getSiteCrawlStatus(jobId);
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const color = data.status === "completed" ? "\x1b[32m" : data.status === "failed" ? "\x1b[31m" : "\x1b[33m";
+          console.log(`Status: ${color}${data.status}\x1b[0m`);
+          console.log(`Pages: ${data.pages_crawled}/${data.pages_discovered}  Errors: ${data.errors_count}`);
+          if (data.health_score != null) {
+            console.log(`Health: ${Math.round(data.health_score * 100)}%`);
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // site-crawl pages <job_id>
+  siteCrawlCmd
+    .command("pages")
+    .description("List crawled pages")
+    .argument("<jobId>", "Crawl job ID")
+    .option("--limit <n>", "Results per page", "50")
+    .option("--filter <type>", "Filter: broken, redirect, thin")
+    .option("--json", "Output as JSON")
+    .action(async (jobId, opts) => {
+      try {
+        const data = await getSiteCrawlPages(jobId, {
+          limit: parseInt(opts.limit, 10),
+          filter: opts.filter,
+        });
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(`\n\x1b[1mCrawled Pages\x1b[0m  (${data.total} total)\n`);
+          const rows = (data.pages || []).map((p) => ({
+            status: p.http_status || "-",
+            depth: p.depth,
+            seo: p.seo_score != null ? Math.round(p.seo_score * 100) + "%" : "-",
+            aeo: p.aeo_score != null ? Math.round(p.aeo_score * 100) + "%" : "-",
+            geo: p.geo_score != null ? Math.round(p.geo_score * 100) + "%" : "-",
+            words: p.word_count,
+            issues: p.issues_count,
+            url: p.url.length > 60 ? p.url.slice(0, 57) + "..." : p.url,
+          }));
+          console.log(printTable(rows, ["status", "depth", "seo", "aeo", "geo", "words", "issues", "url"]));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // site-crawl issues <job_id>
+  siteCrawlCmd
+    .command("issues")
+    .description("List crawl issues")
+    .argument("<jobId>", "Crawl job ID")
+    .option("--severity <level>", "Filter: critical, warning, info")
+    .option("--category <cat>", "Filter by category")
+    .option("--json", "Output as JSON")
+    .action(async (jobId, opts) => {
+      try {
+        const data = await getSiteCrawlIssues(jobId, {
+          severity: opts.severity,
+          category: opts.category,
+        });
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const counts = data.counts_by_severity || {};
+          console.log(`\n\x1b[1mCrawl Issues\x1b[0m  \x1b[31m${counts.critical || 0} critical\x1b[0m  \x1b[33m${counts.warning || 0} warning\x1b[0m  \x1b[2m${counts.info || 0} info\x1b[0m\n`);
+          for (const issue of data.issues || []) {
+            const sevColor = issue.severity === "critical" ? "\x1b[31m" : issue.severity === "warning" ? "\x1b[33m" : "\x1b[2m";
+            console.log(`  ${sevColor}[${issue.severity}]\x1b[0m \x1b[36m${issue.category}\x1b[0m ${issue.message}`);
+          }
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // site-crawl list
+  siteCrawlCmd
+    .command("list")
+    .description("List recent crawl jobs")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await listSiteCrawls();
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          const jobs = data.jobs || [];
+          if (!jobs.length) {
+            console.log("\x1b[33mNo crawl jobs found.\x1b[0m");
+            return;
+          }
+          const rows = jobs.map((j) => ({
+            id: j.job_id.slice(0, 8),
+            status: j.status,
+            pages: j.pages_crawled,
+            errors: j.errors_count,
+            health: j.health_score != null ? Math.round(j.health_score * 100) + "%" : "-",
+            seed: j.seed_url.length > 40 ? j.seed_url.slice(0, 37) + "..." : j.seed_url,
+          }));
+          console.log(printTable(rows, ["id", "status", "pages", "errors", "health", "seed"]));
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
+  // --- kb-stats ---
+  program
+    .command("kb-stats")
+    .description("Show knowledge base indexing statistics")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await getKbStats();
+        if (opts.json) {
+          console.log(printJson(data));
+        } else {
+          console.log(`\n\x1b[1mKnowledge Base\x1b[0m\n`);
+          const ready = data.ready === true || data.status === "indexed";
+          console.log(`  Status:  ${ready ? "\x1b[32mready\x1b[0m" : "\x1b[31mnot ready\x1b[0m"}`);
+        }
+      } catch (e) {
+        handleError(e);
+      }
+    });
+
 }

package/src/seed.mjs

@@ -89,6 +89,10 @@ npx @xyleapp/cli <command> [options]
 | \`xyle sync --site <url> [--json]\` | \`--site\` (required) | Syncs Search Console data; returns synced_queries count |
 | \`xyle queries --site <domain> [--limit N] [--json]\` | \`--site\` (required), \`--limit\` (default 20) | query, impressions, clicks, ctr, position |
 | \`xyle crawl --url <url> [--json]\` | \`--url\` (required) | title, meta_desc, word_count, headings |
+| \`xyle site-crawl <url> [--max-pages N] [--max-depth N] [--no-robots] [--no-js] [--json]\` | \`url\` (required) | Full-site BFS crawl; returns job_id, polls to completion, prints site health score |
+| \`xyle site-crawl status <job_id>\` | \`job_id\` | Crawl job status + progress |
+| \`xyle site-crawl pages <job_id> [--limit N] [--filter broken\\|redirect\\|thin] [--json]\` | \`job_id\` | Per-page SEO/AEO/GEO scores |
+| \`xyle site-crawl issues <job_id> [--severity critical\\|warning] [--json]\` | \`job_id\` | Site-wide issues (broken links, duplicates, orphans, thin content, canonicals) |
 
 ### Analysis
 | Command | Key Flags | Returns |
@@ -112,8 +116,19 @@ Always use \`--json\` when parsing output programmatically.
 
 ## Strategic Workflows
 
-### 1. Full SEO Audit
-**When:** User wants a health check on their site's SEO performance.
+### 1. Full-Site Audit (Screaming Frog replacement)
+**When:** User wants a whole-site health report, not a single-page audit.
+**Goal:** BFS every internal page, detect site-wide issues, deliver a prioritized fix plan with a Site Health Score.
+
+1. \`xyle status --json\` — verify connectivity
+2. \`xyle site-crawl https://<domain> --max-pages 500 --json\` — run the crawl; the CLI polls until complete and prints a progress bar
+3. \`xyle site-crawl issues <job_id> --severity critical --json\` — triage broken links, redirect chains, canonical mismatches, duplicates, orphans, thin content
+4. \`xyle site-crawl pages <job_id> --filter thin --json\` — find pages that need content work
+5. \`xyle site-crawl pages <job_id> --limit 50 --json\` — sort by lowest SEO/AEO/GEO scores
+6. **Deliver a prioritized report**: Site Health Score, critical issue count, top 10 lowest-scoring pages, 30-day fix roadmap
+
+### 2. Single-Page / Query-Driven SEO Audit
+**When:** User wants a deep dive on one page or a performance check driven by Search Console data.
 **Goal:** Categorize queries by intent, flag striking-distance opportunities, and deliver a prioritized action plan.
 
 1. \`xyle status --json\` — verify connectivity
@@ -174,7 +189,8 @@ When the user asks something SEO-related, route to the right workflow:
 
 | User Says | Workflow | Why |
 |-----------|----------|-----|
-| "How's my SEO?" / "Audit my site" | Full SEO Audit | Need holistic view before specific fixes |
+| "Audit my whole site" / "Crawl my site" / "Screaming Frog" / "Site health" | Full-Site Audit | Need site-wide view: broken links, duplicates, orphans, thin content, link graph |
+| "How's my SEO?" / "Audit my site" | Single-Page / Query-Driven SEO Audit | Need holistic view before specific fixes |
 | "Optimize this page" / "Improve rankings for X" | Page Optimization | Specific page needs score-based action |
 | "Who is my audience?" / "What should I write about?" | ICP Discovery | Need strategy before tactics |
 | "What content am I missing?" / "Find gaps" | Content Gap Sprint | Ready to create, need briefs |