@gscdump/cli 0.4.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +82 -56
  2. package/dist/index.mjs +2050 -2365
  3. package/package.json +12 -9
package/README.md CHANGED
@@ -4,15 +4,7 @@
4
4
  [![npm downloads](https://img.shields.io/npm/dm/@gscdump/cli?color=yellow)](https://npm.chart.dev/@gscdump/cli)
5
5
  [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
6
6
 
7
- > CLI for Google Search Console - dump, sync, compare, analyze, and run MCP server.
8
-
9
- ## Features
10
-
11
- - **Data Export** - Dump analytics to stdout, file, or SQLite database
12
- - **Period Comparison** - Compare metrics across time periods
13
- - **SEO Analysis** - Striking distance, movers & shakers, decay detection
14
- - **Indexing Tools** - Check status, request indexing, batch operations
15
- - **MCP Server** - Let AI agents query your search data directly
7
+ > CLI for Google Search Console — sync to a local DuckDB/Parquet store, run typed queries, execute 21 SEO analyzers, and serve an MCP endpoint for AI assistants.
16
8
 
17
9
  ## Install
18
10
 
@@ -22,92 +14,126 @@ npm install -g @gscdump/cli
22
14
  npx @gscdump/cli
23
15
  ```
24
16
 
25
- ## Quick Start
17
+ ## Quick start
26
18
 
27
19
  ```bash
28
- # First-run setup (choose cloud or local auth)
20
+ # First-run setup — OAuth with Google
29
21
  gscdump init
30
22
 
31
- # List your sites
23
+ # List sites
32
24
  gscdump sites
33
25
 
34
- # Dump last 7 days to stdout
35
- gscdump dump --site https://example.com --period 7d
36
-
37
- # Sync to SQLite database
38
- gscdump sync --site https://example.com --db ./gsc.db
26
+ # Sync the last 28 days to a local Parquet store
27
+ gscdump sync --site https://example.com
39
28
 
40
- # Compare periods
41
- gscdump compare --site https://example.com --period 28d
29
+ # Query the store
30
+ gscdump query --site https://example.com --dimensions page,query --limit 50
42
31
 
43
- # Run SEO analysis
32
+ # Run an analyzer
44
33
  gscdump analyze striking-distance --site https://example.com
34
+
35
+ # Start the MCP server
36
+ gscdump mcp
45
37
  ```
46
38
 
47
39
  ## Commands
48
40
 
49
41
  | Command | Description |
50
- |---------|-------------|
51
- | `init` | First-run setup (choose cloud/local mode) |
52
- | `auth` | OAuth2 login with Google |
53
- | `sites` | List GSC properties |
54
- | `dump` | Export analytics to stdout/file |
55
- | `sync` | Persist to SQLite database |
56
- | `compare` | Period-over-period comparison |
57
- | `analyze` | Run SEO analysis (striking-distance, movers, decay, etc.) |
42
+ |---|---|
43
+ | `init` | Set up GSCDump authentication |
44
+ | `auth` | Manage authentication (`status`, `logout`) |
45
+ | `config` | Manage CLI configuration (`show`, `set`, `unset`, `path`) |
46
+ | `sites` | List available GSC sites |
58
47
  | `sitemaps` | List/manage sitemaps for a site |
59
- | `index` | URL indexing (status, inspect, request) |
60
- | `inspect` | Quick URL inspection |
61
- | `config` | Manage CLI configuration |
62
- | `mcp` | Start MCP server for AI assistants |
48
+ | `inspect` | Inspect a URL's indexing status |
49
+ | `sync` | Sync GSC data to the local Parquet store |
50
+ | `query` | Run a search analytics query (local store by default; `--live` hits GSC API) |
51
+ | `dump` | Export live Parquet files from the store to a directory |
52
+ | `analyze <tool>` | Run an SEO analyzer against the store (`--live` for row-based against fresh API) |
53
+ | `store stats` | Show row/byte counts per table and on-disk footprint |
54
+ | `store compact` | Roll daily partitions older than N days into monthly files |
55
+ | `store gc` | Delete orphaned objects past the grace window |
56
+ | `store export` | Export raw Parquet files |
57
+ | `mcp` | Start the MCP server for AI assistants |
58
+
59
+ ## Analyzers
60
+
61
+ `gscdump analyze <tool>` dispatches to `@gscdump/analysis`. 21 tools available:
62
+
63
+ **Core SEO:** `striking-distance`, `opportunity`, `movers`, `decay`, `zero-click`, `brand`, `cannibalization`
64
+
65
+ **Statistical:** `ctr-anomaly`, `position-volatility`, `bayesian-ctr`, `stl-decompose`, `change-point`, `survival`
66
+
67
+ **Structural:** `long-tail`, `intent-atlas`, `query-migration`, `clustering`, `concentration`, `seasonality`, `trends`, `bipartite-pagerank`
68
+
69
+ Each analyzer accepts `--site`, date range flags, and tool-specific options (see `gscdump analyze <tool> --help`). Pass `--live` to bypass the local store and run against fresh GSC API results.
70
+
71
+ ## Sync
63
72
 
64
- ## MCP Server
73
+ ```bash
74
+ # Default: sync the last 7 days, skipping dates already marked done
75
+ gscdump sync --site https://example.com
76
+
77
+ # Backfill the full 450-day history
78
+ gscdump sync --site https://example.com --full
79
+
80
+ # Custom range
81
+ gscdump sync --site https://example.com --start 2024-01-01 --end 2024-01-31
82
+
83
+ # Check status — watermarks + pending/inflight/done/failed counts
84
+ gscdump sync --site https://example.com --status
85
+
86
+ # Parallel table fetches
87
+ gscdump sync --site https://example.com --concurrency 4
88
+ ```
65
89
 
66
- Start the MCP server for AI assistants:
90
+ Sync is idempotent. Cross-process locking protects concurrent `sync`/`compact`/`gc` runs. Pagination walks past GSC's 25k-row-per-request cap automatically.
91
+
92
+ ## MCP server
93
+
94
+ Expose your GSC data to AI assistants over the Model Context Protocol.
67
95
 
68
96
  ```bash
69
97
  gscdump mcp
70
98
  ```
71
99
 
72
- Or add to your Claude config (`~/.claude.json` or VS Code settings):
100
+ Add to your Claude / VS Code config:
73
101
 
74
102
  ```json
75
103
  {
76
104
  "mcpServers": {
77
105
  "gscdump": {
78
106
  "command": "npx",
79
- "args": ["@gscdump/mcp"]
107
+ "args": ["@gscdump/cli", "mcp"]
80
108
  }
81
109
  }
82
110
  }
83
111
  ```
84
112
 
85
- Then ask Claude:
113
+ Then ask questions like:
114
+
86
115
  - "What pages lost traffic this week?"
87
- - "Find keywords in striking distance (position 4-20)"
88
- - "Which queries have keyword cannibalization?"
89
- - "Compare this month vs last month"
116
+ - "Find keywords in striking distance (position 4-20)."
117
+ - "Which queries have cannibalization issues?"
118
+ - "Compare this month vs last month for /blog/ pages."
90
119
 
91
- ## Auth Setup
120
+ ## Auth
92
121
 
93
- **Cloud mode** (recommended):
94
- ```bash
95
- gscdump init # Select "cloud"
96
- ```
97
- Easy setup via cloud.gscdump.com - no API keys needed.
122
+ `gscdump init` walks you through OAuth2 with Google. Credentials are stored locally under `~/.config/gscdump/` (XDG) or equivalent.
123
+
124
+ For manual setup:
98
125
 
99
- **Local mode** (bring your own credentials):
100
- 1. Create a Google Cloud project
101
- 2. Enable "Search Console API" and "Web Search Indexing API"
102
- 3. Create OAuth2 credentials (Desktop app)
103
- 4. Run `gscdump init` and select "local"
126
+ 1. Create a Google Cloud project.
127
+ 2. Enable **Search Console API** and **Web Search Indexing API**.
128
+ 3. Create OAuth2 credentials (Desktop app).
129
+ 4. Run `gscdump init`.
104
130
 
105
- ## Related Packages
131
+ ## Related
106
132
 
107
- - [`gscdump`](../gscdump) - Core library
108
- - [`@gscdump/mcp`](../mcp) - MCP server
109
- - [`@gscdump/db`](../db) - SQLite persistence
110
- - [`@gscdump/query`](../query) - Unified data provider
133
+ - [`gscdump`](../gscdump) — Core library: GSC API client + query builder + analytics pipeline.
134
+ - [`@gscdump/engine`](../engine) — Storage engine the CLI syncs into.
135
+ - [`@gscdump/analysis`](../analysis) — SEO analyzers (row-based + DuckDB-native).
136
+ - [`@gscdump/nuxt-analytics`](../nuxt-analytics) — Nuxt layer for embedding analytics dashboards.
111
137
 
112
138
  ## License
113
139