@gscdump/cli 0.0.1 → 0.1.2

package/README.md

@@ -0,0 +1,114 @@
+# @gscdump/cli
+
+[![npm version](https://img.shields.io/npm/v/@gscdump/cli?color=yellow)](https://npmjs.com/package/@gscdump/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@gscdump/cli?color=yellow)](https://npm.chart.dev/@gscdump/cli)
+[![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
+
+> CLI for Google Search Console - dump, sync, compare, analyze, and run MCP server.
+
+## Features
+
+- **Data Export** - Dump analytics to stdout, file, or SQLite database
+- **Period Comparison** - Compare metrics across time periods
+- **SEO Analysis** - Striking distance, movers & shakers, decay detection
+- **Indexing Tools** - Check status, request indexing, batch operations
+- **MCP Server** - Let AI agents query your search data directly
+
+## Install
+
+```bash
+npm install -g @gscdump/cli
+# or run with npx
+npx @gscdump/cli
+```
+
+## Quick Start
+
+```bash
+# First-run setup (choose cloud or local auth)
+gscdump init
+
+# List your sites
+gscdump sites
+
+# Dump last 7 days to stdout
+gscdump dump --site https://example.com --period 7d
+
+# Sync to SQLite database
+gscdump sync --site https://example.com --db ./gsc.db
+
+# Compare periods
+gscdump compare --site https://example.com --period 28d
+
+# Run SEO analysis
+gscdump analyze striking-distance --site https://example.com
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | First-run setup (choose cloud/local mode) |
+| `auth` | OAuth2 login with Google |
+| `sites` | List GSC properties |
+| `dump` | Export analytics to stdout/file |
+| `sync` | Persist to SQLite database |
+| `compare` | Period-over-period comparison |
+| `analyze` | Run SEO analysis (striking-distance, movers, decay, etc.) |
+| `sitemaps` | List/manage sitemaps for a site |
+| `index` | URL indexing (status, inspect, request) |
+| `inspect` | Quick URL inspection |
+| `config` | Manage CLI configuration |
+| `mcp` | Start MCP server for AI assistants |
+
+## MCP Server
+
+Start the MCP server for AI assistants:
+
+```bash
+gscdump mcp
+```
+
+Or add to your Claude config (`~/.claude.json` or VS Code settings):
+
+```json
+{
+  "mcpServers": {
+    "gscdump": {
+      "command": "npx",
+      "args": ["@gscdump/mcp"]
+    }
+  }
+}
+```
+
+Then ask Claude:
+- "What pages lost traffic this week?"
+- "Find keywords in striking distance (position 4-20)"
+- "Which queries have keyword cannibalization?"
+- "Compare this month vs last month"
+
+## Auth Setup
+
+**Cloud mode** (recommended):
+```bash
+gscdump init  # Select "cloud"
+```
+Easy setup via cloud.gscdump.com - no API keys needed.
+
+**Local mode** (bring your own credentials):
+1. Create a Google Cloud project
+2. Enable "Search Console API" and "Web Search Indexing API"
+3. Create OAuth2 credentials (Desktop app)
+4. Run `gscdump init` and select "local"
+
+## Related Packages
+
+- [`gscdump`](../gscdump) - Core library
+- [`@gscdump/mcp`](../mcp) - MCP server
+- [`@gscdump/db`](../db) - SQLite persistence
+- [`@gscdump/query`](../query) - Unified data provider
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.mjs

@@ -5,7 +5,7 @@ import process from "node:process";
 import { defineCommand, runMain } from "citty";
 import path from "node:path";
 import { batchInspectUrls, batchRequestIndexingForPaths, createGscDb, getIndexingStats, getLastSyncedDate, getSiteByProperty, setupSchema, sitePathDateAnalytics, syncCountries, syncDevices, syncKeywordPaths, syncKeywords, syncPages, syncSites, updateLastSynced } from "@gscdump/db";
-import { createProvider, fetchCannibalizationAnalysis, fetchDecayAnalysis, fetchMoversAnalysis, fetchOpportunityAnalysis, fetchStrikingDistanceAnalysis, fetchZeroClickAnalysis } from "@gscdump/query";
+import { createProvider, daysAgo, fetchCannibalizationAnalysis, fetchDecayAnalysis, fetchMoversAnalysis, fetchOpportunityAnalysis, fetchStrikingDistanceAnalysis, fetchZeroClickAnalysis } from "@gscdump/query";
 import dayjs from "dayjs";
 import betterSqlite3 from "db0/connectors/better-sqlite3";
 import fs from "node:fs/promises";
@@ -14,7 +14,7 @@ import { cancel, confirm, isCancel, multiselect, select, text } from "@clack/pro
 import { OAuth2Client } from "google-auth-library";
 import os from "node:os";
 import { consola } from "consola";
-import { deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, formatErrorForCli, googleSearchConsole, submitSitemap, userPeriodRange } from "gscdump";
+import { deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, formatErrorForCli, googleSearchConsole, submitSitemap } from "gscdump";
 import { createGscMcpServer } from "@gscdump/mcp/server";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -423,6 +423,17 @@ async function getAuth(opts = {}) {
 
 //#endregion
 //#region src/commands/analyze.ts
+function getProviderForSource$2(auth, db, source) {
+	if (source === "api") return createProvider({ auth });
+	if (source === "db") {
+		if (!db) throw new Error("Database required for db source");
+		return createProvider({ db });
+	}
+	return db ? createProvider({
+		auth,
+		db
+	}) : createProvider({ auth });
+}
 const ANALYSIS_TYPES = [
 	"striking-distance",
 	"opportunity",
@@ -532,13 +543,7 @@ const analyzeCommand = defineCommand({
 				end: prevEndDate.format("YYYY-MM-DD")
 			}
 		};
-		const provider = await createProvider({
-			auth,
-			db: dbPath ? createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db : null,
-			source: args.source,
-			siteUrls: [siteArg],
-			range
-		});
+		const provider = getProviderForSource$2(auth, dbPath ? createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db : null, args.source);
 		const limit = Number.parseInt(args.limit, 10) || 20;
 		if (!args.json) {
 			console.log();
@@ -717,6 +722,17 @@ const authCommand = defineCommand({
 
 //#endregion
 //#region src/commands/compare.ts
+function getProviderForSource$1(auth, db, source) {
+	if (source === "api") return createProvider({ auth });
+	if (source === "db") {
+		if (!db) throw new Error("Database required for db source");
+		return createProvider({ db });
+	}
+	return db ? createProvider({
+		auth,
+		db
+	}) : createProvider({ auth });
+}
 const SEARCH_TYPES = [
 	"web",
 	"image",
@@ -876,13 +892,7 @@ const compareCommand = defineCommand({
 		const searchType = SEARCH_TYPES.includes(args.searchType) ? args.searchType : "web";
 		const effectiveSource = searchType !== "web" ? "api" : args.source || "auto";
 		if (searchType !== "web" && args.source === "db") logger.warn(`Search type '${searchType}' requires API. Ignoring --source db.`);
-		const provider = await createProvider({
-			auth,
-			db: dbPath ? createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db : null,
-			source: effectiveSource,
-			siteUrls: [siteArg],
-			range
-		});
+		const provider = getProviderForSource$1(auth, dbPath ? createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db : null, effectiveSource);
 		if (args.json) {
 			const [dates, pages, keywords] = await Promise.all([
 				provider.getDatesWithComparison(siteArg, range),
@@ -1054,6 +1064,23 @@ const configCommand = defineCommand({
 
 //#endregion
 //#region src/commands/dump.ts
+/**
+* Maps CLI source option to provider options
+* - 'api': API only (no db)
+* - 'db': DB only (no auth, errors if data missing)
+* - 'auto': Hybrid (both auth and db, syncs on cache miss)
+*/
+function getProviderForSource(auth, db, source) {
+	if (source === "api") return createProvider({ auth });
+	if (source === "db") {
+		if (!db) throw new Error("Database required for db source");
+		return createProvider({ db });
+	}
+	return db ? createProvider({
+		auth,
+		db
+	}) : createProvider({ auth });
+}
 const DUMP_DATA_TYPES = [
 	"pages",
 	"keywords",
@@ -1252,29 +1279,11 @@ async function interactiveMode(auth, dbPath, source) {
 		return;
 	}
 	console.log();
-	const endDate = dayjs().subtract(3, "days").format("YYYY-MM-DD");
-	const startDate = dayjs().subtract(period.amount, period.unit).subtract(3, "days").format("YYYY-MM-DD");
-	const range = {
-		period: {
-			start: startDate,
-			end: endDate
-		},
-		prevPeriod: {
-			start: dayjs(startDate).subtract(period.amount, period.unit).format("YYYY-MM-DD"),
-			end: dayjs(endDate).subtract(period.amount, period.unit).format("YYYY-MM-DD")
-		}
-	};
 	let db = null;
 	if (dbPath) {
 		if (await fs.access(dbPath).then(() => true).catch(() => false)) db = createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db;
 	}
-	const provider = await createProvider({
-		auth,
-		db,
-		source: finalSource,
-		siteUrls: selectedSites,
-		range
-	});
+	const provider = getProviderForSource(auth, db, finalSource);
 	logger.info(`Using ${provider.source.toUpperCase()} as data source`);
 	await runDump(provider, selectedSites, dataTypes, period, format, null);
 }
@@ -1314,19 +1323,6 @@ async function nonInteractiveMode(auth, site, data, periodStr, format, output, d
 		}
 		normalizedSites.push(match);
 	}
-	const daysOffset = options.fresh ? 1 : 3;
-	const endDate = dayjs().subtract(daysOffset, "days").format("YYYY-MM-DD");
-	const startDate = dayjs().subtract(period.amount, period.unit).subtract(daysOffset, "days").format("YYYY-MM-DD");
-	const range = {
-		period: {
-			start: startDate,
-			end: endDate
-		},
-		prevPeriod: {
-			start: dayjs(startDate).subtract(period.amount, period.unit).format("YYYY-MM-DD"),
-			end: dayjs(endDate).subtract(period.amount, period.unit).format("YYYY-MM-DD")
-		}
-	};
 	let db = null;
 	if (dbPath) {
 		if (await fs.access(dbPath).then(() => true).catch(() => false)) db = createGscDb(betterSqlite3({ name: path.resolve(dbPath) })).db;
@@ -1336,13 +1332,7 @@ async function nonInteractiveMode(auth, site, data, periodStr, format, output, d
 			process.exit(1);
 		}
 	}
-	const provider = await createProvider({
-		auth,
-		db,
-		source,
-		siteUrls: normalizedSites,
-		range
-	}).catch(gscErrorHandler);
+	const provider = getProviderForSource(auth, db, source);
 	const extras = [];
 	if (options.fresh) extras.push("fresh");
 	if (options.searchType && options.searchType !== "web") extras.push(options.searchType);
@@ -2158,6 +2148,12 @@ const sitesCommand = defineCommand({
 
 //#endregion
 //#region src/commands/sync.ts
+function parsePeriodDays(period) {
+	if (period === "max") return 480;
+	if (period.endsWith("y")) return Number.parseInt(period) * 365;
+	if (period.endsWith("m") || period.endsWith("mo")) return Number.parseInt(period) * 30;
+	return Number.parseInt(period.replace("d", ""));
+}
 async function runSync(client, dbPath, siteArg, period, granular, options) {
 	const resolvedPath = path.resolve(dbPath);
 	const report = {
@@ -2195,12 +2191,12 @@ async function runSync(client, dbPath, siteArg, period, granular, options) {
 		siteId: s.siteId,
 		siteUrl: s.property
 	}));
-	const periodRange = userPeriodRange(period);
+	const periodDays = parsePeriodDays(period);
 	const daysOffset = options.fresh ? 1 : 3;
-	const adjustedEndDate = dayjs(periodRange.period.endDate).subtract(daysOffset, "day").format("YYYY-MM-DD");
-	const baseStartDate = dayjs(periodRange.period.startDate).subtract(daysOffset, "day").format("YYYY-MM-DD");
-	const adjustedPrevEndDate = dayjs(periodRange.prevPeriod.endDate).subtract(daysOffset, "day").format("YYYY-MM-DD");
-	const adjustedPrevStartDate = dayjs(periodRange.prevPeriod.startDate).subtract(daysOffset, "day").format("YYYY-MM-DD");
+	const adjustedEndDate = daysAgo(daysOffset);
+	const baseStartDate = daysAgo(periodDays + daysOffset);
+	const adjustedPrevEndDate = daysAgo(periodDays + daysOffset + 1);
+	const adjustedPrevStartDate = daysAgo(periodDays * 2 + daysOffset);
 	const getRangeForSite = async (siteId) => {
 		let startDate = baseStartDate;
 		if (options.since) startDate = options.since;

package/package.json

@@ -1,19 +1,34 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "0.0.1",
-  "description": "CLI for GSCDump - Google Search Console data extraction",
+  "version": "0.1.2",
+  "description": "CLI for Google Search Console - dump, sync, compare, analyze, and run MCP server",
   "author": {
     "name": "Harlan Wilton",
     "email": "harlan@harlanzw.com",
     "url": "https://harlanzw.com/"
   },
   "license": "MIT",
+  "funding": "https://github.com/sponsors/harlan-zw",
+  "homepage": "https://github.com/harlan-zw/gscdump/tree/main/packages/cli#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/harlan-zw/gscdump.git",
     "directory": "packages/cli"
   },
+  "bugs": {
+    "url": "https://github.com/harlan-zw/gscdump/issues"
+  },
+  "keywords": [
+    "google-search-console",
+    "gsc",
+    "seo",
+    "cli",
+    "mcp",
+    "search-analytics",
+    "data-export",
+    "sqlite"
+  ],
   "bin": {
     "gscdump": "./dist/index.mjs"
   },
@@ -22,20 +37,20 @@
   ],
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@modelcontextprotocol/sdk": "^1.25.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "citty": "^0.1.6",
     "consola": "^3.4.2",
-    "dayjs": "^1.11.18",
+    "dayjs": "^1.11.19",
     "db0": "^0.3.4",
     "google-auth-library": "^10.5.0",
-    "open": "^10.1.0",
-    "@gscdump/query": "0.0.1",
-    "@gscdump/db": "0.0.1",
-    "gscdump": "0.0.1",
-    "@gscdump/mcp": "0.0.1"
+    "open": "^11.0.0",
+    "@gscdump/db": "0.1.2",
+    "@gscdump/mcp": "0.1.2",
+    "@gscdump/query": "0.1.2",
+    "gscdump": "0.1.2"
   },
   "devDependencies": {
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "scripts": {
     "build": "obuild",