gsc-cli 2.2.0 → 2.2.2

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 (8) hide show
  1. checksums.yaml +4 -4
  2. data/AUTH.md +4 -1
  3. data/README.md +184 -140
  4. data/bin/gsc +9 -9
  5. data/dist/gsc +9 -9
  6. data/lib/gsc/cli/keywords.rb +7 -7
  7. data/lib/gsc/version.rb +1 -1
  8. metadata +1 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: cfc89a987633cd3ebe87687aeb568bf3e580dff0dceda12bbda364858ec1e09e
4
- data.tar.gz: 12553e6e7e33cc33fcc2fd83a003e27bf6b81a56525104a1d9a8fa07fc69b3ad
3
+ metadata.gz: ab180fed2f9ef6a48d37dd386354f989bc28754efed1ab80d266376663508758
4
+ data.tar.gz: e6da57a476597d37e570d8fabd2853fbbec7b06d26be4fcf1c2fb6dee3de6627
5
5
  SHA512:
6
- metadata.gz: b37602987f85a260627f8f2dcd1f82516d9974ff4290ed2f37b939ff2e32c0d1f7f4a366985d85cba373f9a20071452c73fd3e3676a6f8a98f49a852a0095140
7
- data.tar.gz: 0ca4aac728ab0b2a53f8e95c17d81109ca8104c02eee3dc96e4524eb8467fe10b3d29bb5c23e88eec4a837108a7741b547d6e151f29c775f832b7143661133d2
6
+ metadata.gz: 44f6b7a4bb0a9234cc55cf106454bca07bafa45f6137cbb34a159ca4641f7b2e2733313480730f65168444332b8b52d617051f98582c408e53373a12dd81323b
7
+ data.tar.gz: bf58ea4760ab212945846dabcddbb75e65e3c3a482c86d6ec34b2ecf4480b89a3aaa16b0810c5b84b61d31624ed1c6990aaa44503fc4fbac19551d0d5e52908c
data/AUTH.md CHANGED
@@ -152,9 +152,12 @@ gsc import clip
152
152
 
153
153
  ### Option B: Direct API Integration
154
154
  If you prefer automated terminal lookups without using the browser extension:
155
- 1. Get an API key from [Keywords Everywhere](https://keywordseverywhere.com/) ($1.25 one-time for 100,000 credits).
155
+ 1. Get an API key from [Keywords Everywhere](https://keywordseverywhere.com/?fpr=us25sg) *(referral link that supports gsc-cli development)* ($1.25 one-time for 100,000 credits).
156
156
  2. Save your key:
157
157
  ```bash
158
+ gsc connect ke <YOUR_API_KEY>
159
+
160
+ # Or manually:
158
161
  gsc config set keywords_everywhere_api_key your_ke_api_key_here
159
162
 
160
163
  # Or pass as environment variable
data/README.md CHANGED
@@ -1,7 +1,7 @@
1
- # 🚀 High-Growth Operators & Autonomous AI Agents: The Zero-Dependency Google Search Console, AIO Hunter & Instant Indexing Engine
1
+ # 🚀 GSC-CLI: The Zero-Gem Google Search Console & Technical SEO Engine in Pure Ruby
2
2
 
3
3
  > **Zero Gem Dependencies.** Pure Ruby standard library (`Net::HTTP`, `OpenSSL`, `JSON`).
4
- > **The Sub-50ms Organic Growth Mandate:** Extract ground-truth Google rankings, capture Google AI Overviews, and automate technical SEO in **< 50 milliseconds** — *even if you manage 50 client domains, don't have a Google Service Account key yet, or run offline AI coding agents with strict token budgets.*
4
+ > **Sub-millisecond Google Search Console inspection, instant Googlebot indexing, and AI Overview detection in pure standard library.** Extract first-party Google rankings, automate technical SEO audits, and generate server-side remediation rules in **< 50 milliseconds** with zero external dependencies.
5
5
 
6
6
  [![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-red.svg?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
7
7
  [![Gem Version](https://badge.fury.io/rb/gsc-cli.svg)](https://rubygems.org/gems/gsc-cli)
@@ -23,37 +23,44 @@
23
23
  <sub>Explore other software built by our team:</sub><br>
24
24
  ⚡ <a href="https://superspeedapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli"><b>Superspeed</b></a> — Built for Shopify speed, CRO & revenue leak intelligence app (5.0 ★)<br>
25
25
  🛒 <a href="https://supercartapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli"><b>Supercart</b></a> — Built for Shopify slide cart drawer, in-house shipping protection & upsells (5.0 ★)<br>
26
- 📦 <a href="https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli"><b>PackingLog</b></a> — Smart QR-code box inventory & photo catalog for residential & office moves
26
+ 📦 <a href="https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli"><b>PackingLog</b></a> — Our newly launched physical moving inventory and QR-code tracking SaaS — where waiting weeks for Googlebot to discover new landing pages wasn't an option.
27
27
  </p>
28
28
 
29
29
  ---
30
30
 
31
- ## ⚡ The Brutal Truth About Modern SEO (And Why We Built GSC CLI)
31
+ ## ⚡ Why We Built This: Escaping the 40-Gem Tax
32
32
 
33
- Every software founder, growth engineer, and indie builder faces the exact same bleeding bottlenecks:
33
+ Every software engineer, technical SEO, and developer-operator managing search presence faces the exact same architectural frustrations:
34
34
 
35
- 1. **Bleeding $300 to $1,000+/Month on SEO Tool Fees for Sampled Guesswork**: Third-party estimation suites charge $300 to $1,000+ every month to scrape search results with external proxies and model keyword volumes from sampled databases. Meanwhile, **Google already has the exact, 100% first-party ground-truth data** for your site sitting inside Search Console—completely free.
36
- 2. **Official Google API Gems Are Bloated Monsters**: The official Google API Ruby gems (`google-apis-searchconsole_v1`, `google-apis-indexing_v3`, `googleauth`) drag in **40+ transitive gem dependencies**, take 3 to 5 seconds just to boot, trigger bundle conflicts, and introduce constant supply-chain vulnerabilities.
37
- 3. **Google Search Console's Web UI is Insultingly Slow**: Clicking through Google Search Console's web interface to inspect 50 URLs, check soft-404 errors, or spot cannibalization takes hours of repetitive clicking, filtering, and tab-switching.
38
- 4. **Google AI Overviews (AIO) Are Stealing 40% of Clicks**: Zero-click searches are skyrocketing. If your content isn't structured for direct citation in Google Gemini / AI Overviews, your organic traffic drops even if you rank on Page 1.
39
- 5. **AI Coding Agents Cannot Click Web Buttons**: Modern coding agents (Antigravity, Claude Code, Cursor, Cline) need raw, deterministic, sub-50ms JSON over stdout to diagnose and fix SEO issues autonomously inside your codebase.
35
+ 1. **The 40-Gem Dependency Tax**: The official Google API Ruby gems (`google-apis-searchconsole_v1`, `google-apis-indexing_v3`, `googleauth`, `signet`, `faraday`) pull in **40+ transitive gem dependencies**. They add 3 to 5 seconds to cold-boot time, trigger Bundler version conflicts, inflate container image sizes, and introduce ongoing supply-chain vulnerability alerts.
36
+ 2. **Paying $300 to $1,000+/Month for Sampled Guesswork**: Third-party SEO suites charge hundreds of dollars per month to scrape search results with external proxy farms and estimate traffic using sampled third-party panels. Meanwhile, **Google Search Console provides 100% first-party ground-truth data** for your domain directly from production search logs—completely free.
37
+ 3. **Google Search Console's Web UI Does Not Scale**: Inspecting 50 URLs, isolating soft-404 indexation drops, or detecting cannibalization across multiple client properties requires hours of manual tab switching, filtering, and clicking.
38
+ 4. **Google AI Overviews (AIO) Intercepting Search Clicks**: Zero-click searches continue to expand. If technical content is not structured for citation in Gemini and AI Overviews, organic visibility drops even when ranking on Page 1.
39
+ 5. **AI Coding Agents Cannot Click Web Buttons**: Modern coding agents (Antigravity, Claude Code, Cursor, Cline) require deterministic, sub-50ms JSON over stdout to diagnose and fix search issues directly inside the local repository.
40
40
 
41
- ### The Origin of GSC-CLI
42
- At **[ApollosWave](https://apolloswave.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**, we run multiple production software businesses—from Shopify revenue & speed intelligence (**[Superspeed](https://superspeedapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**) and e-commerce upsell apps (**[Supercart](https://supercartapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**) to physical moving inventory SaaS (**[PackingLog](https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**).
41
+ ### 🛠️ Battle-Tested in Production (The Origin)
43
42
 
44
- We refused to bloat our applications with 40 gems or waste 10 hours a week clicking in Search Console. We needed a **single, standalone, pure-Ruby CLI** that communicates directly with Google's bare-metal HTTP APIs using native `OpenSSL` and `Net::HTTP` in **under 50 milliseconds**.
43
+ `gsc-cli` was not engineered in a vacuum or built as a synthetic demo.
45
44
 
46
- We built **`gsc-cli`** to run our own marketing operations. **We open-sourced it 100% free under the MIT License** so other builders can scale organic search traffic without the corporate SEO tax.
45
+ At **[ApollosWave](https://apolloswave.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**, we operate multiple high-throughput production applications:
46
+ - **[Superspeed](https://superspeedapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: Automated Core Web Vitals, INP, and speed intelligence for high-volume Shopify storefronts.
47
+ - **[Supercart](https://supercartapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: High-converting slide cart and upsell infrastructure processing real-time e-commerce checkouts.
48
+ - **[PackingLog](https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: Our newly launched physical moving inventory and QR-code tracking SaaS — where waiting weeks for Googlebot to discover new landing pages wasn't an option.
49
+
50
+ Managing Search Console indexing, sitemap trees, and SERP positions across these live codebases meant either pulling in 40+ bloated API gems, burning hours clicking in Google's web UI, or paying thousands every year for sampled proxy scrapers.
51
+
52
+ We built **`gsc-cli`** as our internal engine to automate Googlebot indexing and search diagnostics in **< 50 milliseconds** using pure standard-library Ruby.
53
+
54
+ We open-sourced it 100% free under the MIT License so every builder, engineering team, and operator can run first-party search automation with zero dependency bloat.
47
55
 
48
56
  ---
49
57
 
50
- ## 💎 The 5 Immutable Truths of Modern Organic Growth
58
+ ## 📐 Core Engineering Principles
51
59
 
52
- 1. **Compounding Organic Acquisition**: You didn't build your software to burn half your runway on paid ads. You built it to create a compounding, self-sustaining organic acquisition engine that pulls in qualified customers day and night on autopilot.
53
- 2. **First-Party Ground Truth Over Guesswork**: You always suspected that third-party scraping tools and panel-based traffic estimators don't have Google's private internal search logs for your domain. You were right. External proxy estimators rely on sampled clickstream models; meanwhile, Google Search Console stores the exact, 100% first-party click and impression ground truth directly from Google's production infrastructure—completely free.
54
- 3. **Liberation from the 40-Gem Tax**: Official Google API gems drag in 40+ dependency gems, slow down boot times to 4+ seconds, trigger bundle conflicts, and introduce constant supply-chain alerts. GSC-CLI communicates directly with Google's bare-metal HTTP APIs using pure Ruby standard library in **< 1 millisecond**.
55
- 4. **Zero-Trust Local Execution & Anti-Slop Guarantee**: Developers are tired of untrusted scripts that require root privileges or send your private code to remote AI servers. `gsc-cli` is **not an AI slop wrapper**. It runs 100% locally with zero external gem dependencies, zero telemetry, and zero remote code ingestion.
56
- 5. **Actionable Remediation Over Passive Error Tables**: Traditional SEO auditing tools spit out 500 error rows but leave you stranded without actionable fixes. GSC-CLI diagnoses soft-404 traps and automatically synthesizes copy-paste redirect blocks for 14 server environments.
60
+ 1. **First-Party Ground Truth Over Guesswork**: Third-party estimation suites rely on sampled clickstream models and external proxy scraping. Google Search Console stores the exact, 100% first-party click, impression, and position data directly from Google's search infrastructure—completely free.
61
+ 2. **Zero-Dependency Purity (< 1ms Boot Time)**: Official Google API gems drag in 40+ dependency gems, slowing down boot times and creating dependency lock-in. GSC-CLI communicates directly with Google's bare-metal HTTP APIs using pure Ruby standard library (`Net::HTTP`, `OpenSSL`, `JSON`), executing in **< 1 millisecond**.
62
+ 3. **Actionable Remediation Over Passive Error Dumps**: Most diagnostic tools dump hundreds of error rows into a table without solutions. `gsc-cli` pairs forensic diagnostics with automated remediation—such as generating copy-paste redirect blocks for 14 server environments (Nginx, Caddy, Cloudflare, Next.js, Vercel, etc.) for soft-404 traps.
63
+ 4. **Zero-Trust Local Execution (No Telemetry, No External AI Calls)**: Developer tools should respect machine resources and codebase privacy. `gsc-cli` runs 100% locally, requires zero external LLM API keys, makes zero calls to third-party AI servers, collects zero telemetry, and never reads or transmits private repository files.
57
64
 
58
65
  ---
59
66
 
@@ -86,7 +93,7 @@ By implementing Google's JWT service account authentication in pure `OpenSSL` an
86
93
  - 🩺 **Zero-Gem Cold-Start Doctor (`gsc doctor`)**: Verifies 100% standard library purity, measures sub-50ms execution speed, and validates credential security.
87
94
  - 📈 **Real-Time Google Trends Engine (`gsc trends`)**: 5-year and 1-year search trajectory, velocity percentages, Unicode sparklines (` ▂▃▄▅▆▇█`), and regional demand breakdowns with zero authentication.
88
95
  - 🎯 **Zero-Auth Keyword Planner (`gsc planner`)**: Instant seed expansion via Google Autocomplete with automated search intent classification (`Informational`, `Commercial`, `Transactional`).
89
- - 💰 **Keywords Everywhere Ingestion (`gsc import clip` & `gsc ke`)**: Ingest free keyword tables directly from clipboard (zero credits required) or connect paid API keys for 1-step automated terminal lookups.
96
+ - 💰 **Keywords Everywhere Ingestion (`gsc import clip` & `gsc ke`)**: Ingest free keyword tables directly from clipboard (zero credits required) or connect a [Keywords Everywhere API key](https://keywordseverywhere.com/?fpr=us25sg) *(referral link)* for automated terminal lookups.
90
97
  - 🚀 **Instant Googlebot Re-Indexing (`gsc index`)**: Ping Google's Indexing API with `URL_UPDATED` or `URL_DELETED` for priority crawl queueing within seconds.
91
98
  - ⚡ **Multi-Engine IndexNow Protocol (`gsc indexnow`)**: Instantly submit pages and sitemaps across Microsoft Bing, Yandex, Seznam, and Naver simultaneously.
92
99
  - 🖥️ **Google SERP & Title Pixel Simulator (`gsc serp`)**: Simulate desktop (580px) and mobile (650px) Google SERP cards, calculate precise proportional pixel widths, and prevent truncation before publishing.
@@ -97,26 +104,24 @@ By implementing Google's JWT service account authentication in pure `OpenSSL` an
97
104
 
98
105
  ---
99
106
 
100
- ## 🔄 The Transformation: Nightmare Status Quo vs. The GSC-CLI Way
107
+ ## ⚡ Architectural Comparison & Trade-Offs
101
108
 
102
- | Nightmare Status Quo | The GSC-CLI Transformation |
109
+ | Traditional Stack (Official SDK / SaaS) | GSC-CLI Architecture |
103
110
  | :--- | :--- |
104
- | **Manual Clicking Trap**: Clicking through 15 tabs in Google Search Console to inspect 50 URLs (takes 45+ minutes). | **Instant 1-Command Batching**: `gsc inspect-sitemap sitemap.xml` inspects all URLs with automatic quota pacing in seconds. |
111
+ | **Manual Web UI Bottleneck**: Clicking through 15 tabs in Google Search Console to inspect 50 URLs takes 45+ minutes. | **Instant 1-Command Batching**: `gsc inspect-sitemap sitemap.xml` inspects all URLs with automatic quota pacing in seconds. |
105
112
  | **Sampled Third-Party Guesswork**: Paying $300–$1,000+/mo ($3,600–$12,000/yr) for external proxy scrapers that model keyword volumes. | **100% Google Ground Truth ($0)**: Raw impression, click, and position logs direct from Google Search Console. |
106
- | **40-Gem Dependency Hell**: Bloating your `Gemfile` with Google SDK gems that add 4 seconds to cold boot. | **0 Gem Dependencies**: Pure Ruby standard library (`OpenSSL`, `Net::HTTP`, `JSON`) executing in **< 1 millisecond**. |
107
- | **Multi-Client Credential Chaos**: Juggling loose JSON keys across client folders and risking credential leaks. | **Agency Credential Vault (`gsc vault`)**: Local AES-256-GCM encrypted vault with instant domain switching (`gsc switch`). |
113
+ | **40-Gem Dependency Tax**: Bloating your `Gemfile` with Google SDK gems that add 3–5 seconds to cold boot. | **0 Gem Dependencies**: Pure Ruby standard library (`OpenSSL`, `Net::HTTP`, `JSON`) executing in **< 1 millisecond**. |
114
+ | **Multi-Client Credential Chaos**: Juggling loose JSON keys across folders and risking credential leaks. | **Agency Credential Vault (`gsc vault`)**: Local AES-256-GCM encrypted vault with instant domain switching (`gsc switch`). |
108
115
  | **Passive Error Reporting**: Diagnostic tools tell you that you have 404s, but leave you to write the server rules. | **Active Automated Remediation**: `gsc soft-404 <url> --fix nginx` synthesizes instant, copy-paste server blocks for 14 stacks. |
109
116
  | **Blind to AI Overviews**: Unaware that Google Gemini / AI Overviews are intercepting 40% of zero-click searches. | **Google AIO Hunter & Citation Simulator**: `gsc aio-hunter` identifies AI Overviews and extracts competitor citation recipes. |
110
117
  | **Token-Guzzling JSON in AI Agents**: Feeding pretty-printed JSON into coding agents wastes 40% of your LLM context window. | **Ultra-Low Token Modes (`--compact`, `--ndjson`)**: Minified output saving **35–50% of tokens** for Claude Code, Cursor, and Antigravity. |
111
- | **Untrusted Scripts Touching Code**: Running opaque scripts that scan your repository and send files to third parties. | **Zero-Trust Local Execution**: Completely isolated, deterministic UNIX tool. Never scans, reads, or transmits your private code. |
118
+ | **Untrusted Third-Party Scripts**: Running opaque scripts that scan your repository or send files to external servers. | **Zero-Trust Local Execution**: Completely isolated, deterministic UNIX tool. Never scans, reads, or transmits your private code. |
112
119
 
113
120
  ---
114
121
 
115
- > ### ⭐ Join the Zero-Bloat SEO Revolution
116
- > **Did `gsc-cli` save your team from 40 bloated Google gems, bypass the $300–$1,000+/mo SEO suite tax, or give your AI agents instant sub-50ms search ground truth?**
117
- >
118
- > Help fellow engineers and operators discover zero-dependency tooling:
119
- > 👉 **[Drop a Star on GitHub](https://github.com/ApollosWave/gsc-cli)** — *even if you only use it for terminal sparklines, instant Googlebot indexing, or AI Overview detection.* It takes 2 seconds and directly fuels continuous open-source development!
122
+ > ### ⭐ Star the Repository
123
+ > If `gsc-cli` saved your team from 40 bloated gems or streamlined your search data pipeline:
124
+ > 👉 **[Star GSC CLI on GitHub](https://github.com/ApollosWave/gsc-cli)** to support zero-dependency open-source tooling.
120
125
 
121
126
  ---
122
127
 
@@ -186,86 +191,133 @@ gsc domains
186
191
 
187
192
  ## 🧠 Deep-Dive Feature Walkthroughs
188
193
 
189
- ### 1. Google AI Overview (AIO) Opportunity Hunter (`gsc aio-hunter`)
194
+ ### 1. Core Search Performance: Top Queries, Pages & CTR (`gsc top-queries`, `gsc top-pages`, `gsc performance`)
190
195
 
191
196
  #### The Problem
192
- Google AI Overviews (Gemini in search results) are intercepting high-intent search traffic before users ever click a blue link. If an AI Overview appears for your core keywords, your CTR can crater by 40% unless your site is cited inside the AI answer box.
197
+ Google Search Console's web UI is sluggish, hides low-volume long-tail queries behind pagination limits, and makes cross-referencing brand vs. non-brand queries painful. Exporting CSVs to spreadsheets burns 20+ minutes every time you want to check yesterday's organic clicks.
193
198
 
194
199
  #### The Solution
195
- `gsc aio-hunter` queries SERPs, detects AI Overviews, extracts the exact cited sources, identifies your citation gap, and generates a structured snippet capture recipe:
200
+ `gsc-cli` streams your exact Google Search Console ground-truth performance directly into your terminal in **under 50 milliseconds**. Filter by brand, segment devices, compare date ranges, and export clean JSON or CSV in one command:
196
201
 
197
202
  ```bash
198
- # Hunt AI Overview presence and extract cited competitor URLs
199
- gsc aio-hunter "best technical seo audit tools"
203
+ # Top 20 search queries with impressions, clicks, CTR, and average SERP position
204
+ gsc top-queries --limit 20
205
+
206
+ # Filter brand vs. non-brand queries automatically
207
+ gsc top-queries --brand
208
+ gsc top-queries --non-brand
209
+
210
+ # Top indexed landing pages driving search traffic
211
+ gsc top-pages --limit 15
212
+
213
+ # Overall 30-day domain performance scorecard with device & country breakdown
214
+ gsc performance --days 30
200
215
 
201
- # Filter by minimum impressions and export JSON for AI agents
202
- gsc aio-hunter --min-imp 50 --json
216
+ # Retrieve 100% of all queries via automated API pagination (no 1,000-row web limit)
217
+ gsc top-queries --all --csv > all_search_queries.csv
203
218
  ```
204
219
 
205
220
  ---
206
221
 
207
- ### 2. AI Citation Simulator (`gsc cite-sim`)
222
+ ### 2. Tactical Striking Distance Playbook & Organic CTR Curve (`gsc strike` & `gsc ctr-curve`)
208
223
 
209
224
  #### The Problem
210
- How do you know if an LLM (ChatGPT Search, Perplexity, Gemini) will actually cite your URL when answering user queries?
225
+ Most SEO reports simply dump a list of keywords without telling you **what to write, where to link, or what the revenue payoff will be**. Page 2 keywords (Positions 4–20) generate 80% of your search impressions but only 5% of your clicks.
211
226
 
212
227
  #### The Solution
213
- `gsc cite-sim` runs a local structural heuristics audit assessing citation readiness:
214
- - **Information Density Ratio**: High-value facts per 1,000 DOM words.
215
- - **Structural Heading Depth**: Clean H2/H3 question-and-answer hierarchy.
216
- - **Entity Markup**: Schema.org JSON-LD definitions.
217
- - **Citability Score (0–100)**: Clear breakdown with actionable optimization advice.
228
+ - **`gsc ctr-curve`**: Generates an empirical, non-linear CTR regression curve mapping your domain's real CTR by position against Google's global benchmarks, simulating the exact click gain of advancing to Top 3.
229
+ - **`gsc strike`**: Automatically synthesizes a tactical Page 2 attack plan with **3 SERP-safe hook titles (< 560px)**, heading recipes, and targeted internal link anchor suggestions:
218
230
 
219
231
  ```bash
220
- gsc cite-sim https://example.com/guides/core-web-vitals
232
+ # Simulate organic CTR curve and click upside for Page 2 rankings
233
+ gsc ctr-curve --days 30 --target-pos 3
234
+
235
+ # Generate tactical Page 2 striking distance playbook
236
+ gsc strike --limit 10
237
+
238
+ # Surface quick-win CTR underperformers (Top 10 ranking but low click-through)
239
+ gsc underperformers --min-imp 50
240
+
241
+ # Export playbook directly to CSV for copywriters & content teams
242
+ gsc strike --limit 20 --csv docs/seo/striking_playbook.csv
221
243
  ```
222
244
 
223
245
  ---
224
246
 
225
- ### 3. Soft-404 Forensic Diagnostic Engine with Instant Stack Fixes (`gsc soft-404`)
247
+ ### 3. Instant Googlebot Priority Indexing & Live URL Inspection (`gsc index`, `gsc inspect`, `gsc indexnow`)
226
248
 
227
249
  #### The Problem
228
- Soft-404 errors silently destroy your Google crawl budget. These are pages that return a `200 OK` status code while showing "Product Not Found" or empty category pages. Finding them is painful; generating server redirect rules by hand is tedious and error-prone.
250
+ Waiting days or weeks for Googlebot to discover new landing pages or updated documentation kills organic momentum. Meanwhile, checking if Google has indexed a URL or flagged a canonical error requires tedious manual clicking inside Search Console's URL Inspection tool.
229
251
 
230
252
  #### The Solution
231
- `gsc soft-404` detects empty templates, blank pages, and canonical loops, auto-detects your underlying tech stack (SvelteKit, Cloudflare, Astro, Next.js, Caddy, Webflow, Shopify, Nginx), and generates production-ready redirect rules:
253
+ `gsc-cli` communicates directly with Google's Indexing API and live URL Inspection API to check status and force priority crawling in seconds:
232
254
 
233
255
  ```bash
234
- # Diagnose any URL for soft-404 status (auto-detects tech stack & server)
235
- gsc soft-404 https://example.com/broken-page
256
+ # Query live Google indexing verdict, assigned canonical, and crawl timestamp
257
+ gsc inspect https://example.com/blog/core-web-vitals
236
258
 
237
- # Generate copy-paste rules for your specific tech stack:
238
- gsc soft-404 https://example.com/broken-page --fix sveltekit
239
- gsc soft-404 https://example.com/broken-page --fix caddy
240
- gsc soft-404 https://example.com/broken-page --fix cloudflare
241
- gsc soft-404 https://example.com/broken-page --fix workers
242
- gsc soft-404 https://example.com/broken-page --fix astro
243
- gsc soft-404 https://example.com/broken-page --fix gatsby
244
- gsc soft-404 https://example.com/broken-page --fix github
245
- gsc soft-404 https://example.com/broken-page --fix webflow
246
- gsc soft-404 https://example.com/broken-page --fix shopify
247
- gsc soft-404 https://example.com/broken-page --fix nextjs
248
- gsc soft-404 https://example.com/broken-page --fix nginx
249
- gsc soft-404 https://example.com/broken-page --fix all
259
+ # Ping Googlebot to prioritize crawling a newly published or updated URL
260
+ gsc index https://example.com/blog/core-web-vitals
261
+
262
+ # Batch inspect an entire XML sitemap with automatic quota pacing
263
+ gsc inspect-sitemap https://example.com/sitemap.xml
264
+
265
+ # Multi-Engine IndexNow: Instantly notify Bing, Yandex, Seznam, and Naver simultaneously
266
+ gsc indexnow https://example.com/blog/core-web-vitals
250
267
  ```
251
268
 
252
269
  ---
253
270
 
254
- ### 4. Cross-Device Mobile vs. Desktop SERP Parity (`gsc mobile-parity`)
271
+ ### 4. Cannibalization, Traffic Decay & Zombie Page Detection (`gsc cannibalization`, `gsc decay`, `gsc zombies`)
255
272
 
256
273
  #### The Problem
257
- Google indexes mobile-first. If your mobile layout has hidden content, slower load times, or truncated titles, your mobile ranking can drop 10 positions below desktop without you ever noticing in standard dashboards.
274
+ Internal URLs competing for the same search intent (keyword cannibalization) split page equity, causing Google to oscillate rankings between pages. Meanwhile, stealth traffic decay and dead zero-click URLs quietly drain your Google crawl budget.
258
275
 
259
276
  #### The Solution
260
- `gsc mobile-parity` compares mobile and desktop impressions, average positions, and CTR side-by-side, flagging responsive suppression penalties:
277
+ `gsc-cli` diagnoses algorithmic cannibalization conflicts and period-over-period decay before traffic crashes:
261
278
 
262
279
  ```bash
263
- gsc mobile-parity example.com --gap-threshold 2.0
280
+ # Detect internal URLs fighting for the exact same queries
281
+ gsc cannibalization
282
+
283
+ # Period-over-period decay detection (28-day comparison: decaying vs surging queries)
284
+ gsc decay --compare 28
285
+
286
+ # Scan XML sitemap for 90-day zero-impression zombie pages draining crawl budget
287
+ gsc zombies https://example.com/sitemap.xml --purge-map
264
288
  ```
265
289
 
266
290
  ---
267
291
 
268
- ### 5. Detailed Off-Page + On-Page SEO Merger (`gsc page` & `gsc site-audit`)
292
+ ### 5. Zero-Cost Clipboard Keyword Ingestion & Demand Trends (`gsc import clip`, `gsc trends`, `gsc planner`)
293
+
294
+ #### The Problem
295
+ Keyword research tools either lock data behind expensive API subscriptions or leave valuable volume data trapped in disconnected browser extensions.
296
+
297
+ #### The Solution
298
+ `gsc-cli` provides zero-cost clipboard ingestion and real-time demand tracking with **zero API keys required**:
299
+
300
+ ```bash
301
+ # 1. Copy any keyword table from Keywords Everywhere or Google Ads in your browser (Cmd+C)
302
+ # 2. Run one command to parse volumes, sparklines, and cross-reference live GSC rankings:
303
+ gsc import clip
304
+
305
+ # Real-time Google Trends 5y/1y search trajectory and velocity percentage (zero-auth)
306
+ gsc trends "technical seo audit" --geo US --time 12m
307
+
308
+ # Google Autocomplete intent expander (Informational, Commercial, Transactional)
309
+ gsc planner "nextjs seo"
310
+ ```
311
+
312
+ ---
313
+
314
+ ### 6. Detailed Off-Page + On-Page SEO Merger & Site Audit (`gsc page` & `gsc site-audit`)
315
+
316
+ #### The Problem
317
+ On-page SEO checkers (titles, headings, meta tags) live in browser extensions, completely disconnected from your real Google Search Console performance data.
318
+
319
+ #### The Solution
320
+ `gsc page` unites on-page DOM inspection with 90-day GSC search queries, clicks, and rankings in a single terminal view:
269
321
 
270
322
  ```bash
271
323
  # Audit any URL combining DOM inspection with GSC 90-day search performance
@@ -274,41 +326,58 @@ gsc page https://example.com/
274
326
  # Deep internal link verification: tests HTTP status codes (200, 404, 500)
275
327
  gsc page https://example.com/ --check-links
276
328
 
277
- # Crawl entire XML sitemaps to generate prioritized AI fix sprints
329
+ # Crawl entire XML sitemaps to audit dead links, missing alts, and heading hierarchy
278
330
  gsc site-audit https://example.com/sitemap.xml --report docs/seo/site_audit_issues.md
279
331
  ```
280
332
 
281
333
  ---
282
334
 
283
- ### 6. Zero-Cost Clipboard Keyword Ingestion (`gsc import clip`)
335
+ ### 7. Google AI Overview (AIO) Opportunity Hunter & Citation Simulator (`gsc aio-hunter` & `gsc cite-sim`)
284
336
 
285
- > **No API key or paid credits required!** Works 100% free with the Keywords Everywhere web dashboard or Google Ads Keyword Planner.
337
+ #### The Problem
338
+ Google AI Overviews (Gemini in search results) intercept high-intent queries before users ever reach blue links. If an AI Overview appears for your core keywords, your organic CTR can crater unless your site is cited inside the AI answer box.
286
339
 
287
- 1. **Copy Your Keywords in the Browser**: Click "Copy to Clipboard" on any keyword volume table.
288
- 2. **Run One Command in Your Terminal**:
289
- ```bash
290
- gsc import clip
291
- ```
292
- 3. **Instant Analysis & GSC Correlation**:
293
- * Parses volume, CPC, competition score, and 12-month history at zero cost.
294
- * Draws live **Unicode Sparklines (` ▂▃▄▅▆▇█`)** showing demand trajectories.
295
- * Calculates **Opportunity Scores (0–100)** to prioritize low-competition wins.
296
- * Automatically cross-references live Google Search Console rankings (`🏆 Top 3`, `🥇 Page 1`, `🎯 Striking Distance`, or `🚀 Untargeted`).
297
- * Archives into `~/.config/gsc/domains/<domain>/keywords/` for historical rank tracking.
340
+ #### The Solution
341
+ `gsc aio-hunter` scans live SERPs for AI Overviews, extracts cited sources, and measures your citation readiness:
342
+
343
+ ```bash
344
+ # Hunt AI Overview presence and extract cited competitor sources
345
+ gsc aio-hunter "best technical seo audit tools"
346
+
347
+ # Test how likely LLMs (Gemini, ChatGPT, Perplexity) are to cite your URL
348
+ gsc cite-sim https://example.com/guides/core-web-vitals
349
+
350
+ # Synthesize 40–60 word high-density direct answers with FAQ schema embedding
351
+ gsc answer "what is soft 404 error"
352
+ ```
298
353
 
299
354
  ---
300
355
 
301
- ### 7. Google Trends Real-Time Demand Engine (`gsc trends`)
356
+ ### 8. Soft-404 Forensic Diagnostic Engine with 14-Stack Instant Fixes (`gsc soft-404`)
357
+
358
+ #### The Problem
359
+ Soft-404 errors silently destroy your Google crawl budget by returning `200 OK` on empty templates or missing content. Writing server redirect rules manually across different stacks is slow and error-prone.
360
+
361
+ #### The Solution
362
+ `gsc soft-404` detects empty templates, blank pages, and canonical loops, auto-detects your tech stack, and generates copy-paste redirect blocks for 14 server environments:
302
363
 
303
- Queries Google Trends explore and widget APIs directly in real time with **zero authentication and zero API keys**:
304
364
  ```bash
305
- gsc trends "seo audit" --geo US --time 12m
306
- gsc trends "local llm" --geo US --time 5y --json
365
+ # Diagnose any URL for soft-404 status (auto-detects tech stack & server)
366
+ gsc soft-404 https://example.com/broken-page
367
+
368
+ # Generate copy-paste rules for your specific tech stack:
369
+ gsc soft-404 https://example.com/broken-page --fix sveltekit
370
+ gsc soft-404 https://example.com/broken-page --fix caddy
371
+ gsc soft-404 https://example.com/broken-page --fix cloudflare
372
+ gsc soft-404 https://example.com/broken-page --fix nextjs
373
+ gsc soft-404 https://example.com/broken-page --fix nginx
374
+ gsc soft-404 https://example.com/broken-page --fix shopify
375
+ gsc soft-404 https://example.com/broken-page --fix all
307
376
  ```
308
377
 
309
378
  ---
310
379
 
311
- ### 8. Agency Credential Vault (`gsc vault`)
380
+ ### 9. Agency Credential Vault & Instant Domain Switching (`gsc vault` & `gsc switch`)
312
381
 
313
382
  #### The Problem
314
383
  Agencies and multi-brand operators juggle dozens of client Google service account JSON files. Leaving unencrypted keys scattered across client folders invites credential leakage, path-traversal vulnerabilities, and accidental cross-client query pollution.
@@ -334,28 +403,6 @@ gsc use 2
334
403
 
335
404
  ---
336
405
 
337
- ### 9. Striking Distance Playbook & Organic CTR Curve (`gsc strike` & `gsc ctr-curve`)
338
-
339
- #### The Problem
340
- Most SEO reports simply dump a list of keywords without telling you **what to write, where to link, or what the revenue payoff will be**. Page 2 keywords (Positions 4–20) generate 80% of your search impressions but only 5% of your clicks.
341
-
342
- #### The Solution
343
- - **`gsc ctr-curve`**: Generates an empirical, non-linear CTR regression curve mapping your domain's real CTR by position against Google's global benchmarks, simulating the exact click gain of advancing to Top 3.
344
- - **`gsc strike`**: Automatically synthesizes a tactical Page 2 attack plan with **3 SERP-safe hook titles (< 560px)**, heading recipes, and targeted internal link anchor suggestions:
345
-
346
- ```bash
347
- # Simulate organic CTR curve and click upside for Page 2 rankings
348
- gsc ctr-curve --days 30 --target-pos 3
349
-
350
- # Generate tactical Page 2 striking distance playbook
351
- gsc strike --limit 10
352
-
353
- # Export playbook directly to CSV for copywriters & content teams
354
- gsc strike --limit 20 --csv docs/seo/striking_playbook.csv
355
- ```
356
-
357
- ---
358
-
359
406
  ## 🛠️ Complete CLI Command Reference (80 Commands)
360
407
 
361
408
  > **💡 Token Economy Note for AI Agents & Pipelines:**
@@ -492,6 +539,8 @@ gsc strike --limit 20 --csv docs/seo/striking_playbook.csv
492
539
 
493
540
  ## 🤖 AI Agent Native Integration (Antigravity, Claude, Cursor)
494
541
 
542
+ > 💡 **Zero External LLM Calls**: `gsc-cli` does NOT require an OpenAI or Anthropic API key and sends zero data to third-party AI servers. Everything runs locally on your machine. "AI Agent Native" refers to our deterministic `--compact` (minified JSON) and `--ndjson` flags designed to save 35–45% context tokens when called by local coding agents (Claude Code, Cursor Composer, Antigravity).
543
+
495
544
  `gsc-cli` was engineered from the ground up to serve as the high-speed sensory organ for autonomous AI coding agents (**Antigravity**, **Claude Code**, **Cursor Composer**, **Windsurf**, and **OpenCode**).
496
545
 
497
546
  Traditional CLI tools output ANSI-colored terminal text designed exclusively for human eyes—forcing AI agents to burn thousands of tokens scraping strings, guessing table columns, and hallucinating missing fields. `gsc-cli` eliminates this waste completely with **sub-millisecond execution**, **zero gem overhead**, and **three ultra-efficient machine output formats**.
@@ -572,20 +621,21 @@ Once installed, your agent automatically understands all 80 commands, flag permu
572
621
 
573
622
  ## 🥊 How GSC CLI Compares (The Zero-Bloat Advantage)
574
623
 
575
- | Capability | every-app/open-seo | crawlseo | nalyk/gsccli | benedict2310/gsc-cli | **ApollosWave/gsc-cli (v2.2.0)** |
576
- | :--- | :--- | :--- | :--- | :--- | :--- |
577
- | **Price** | $10/mo + DataForSEO | Free (Requires VPS) | Free (Go) | Free (Go) | **100% Free & Open Source ($0)** |
578
- | **Dependencies** | 100+ npm packages + DB | Docker + Postgres + Node | Go runtime | Go runtime | **0 Gems / Pure Standard Library** |
579
- | **Execution Latency** | 3–5 seconds (Web app) | Web UI | ~15ms | ~12ms | **< 1 millisecond (Compiled Binary)** |
580
- | **Command Surface** | 5 web views | Web dashboard | ~8 commands | ~2 commands | **80 Production Commands** |
581
- | **Actionable Fixes** | ❌ None | ❌ None | ❌ None | ❌ None | **✅ `--fix nginx`, JSON-LD, rewrites** |
582
- | **Google AI Overviews (AIO)**| ❌ None | ❌ None | ❌ None | ❌ None | **✅ `aio-hunter` + `cite-sim`** |
583
- | **Soft-404 Diagnostics** | ❌ None | ❌ None | ❌ None | ❌ None | **✅ Forensic heuristic engine** |
584
- | **Mobile SERP Parity** | ❌ None | ❌ None | ❌ None | ❌ None | **✅ Cross-device rank gap auditor** |
585
- | **Indexing API** | ❌ None | ❌ None | ✅ Yes | ❌ None | **✅ Google Indexing + Multi-IndexNow** |
586
- | **Multi-Client Vault** | ❌ Plain files | ❌ Plain files | ❌ Single site | ❌ Single site | **✅ AES-256-GCM Encrypted Vault (`gsc vault`)** |
587
- | **Token Economics** | ❌ None (Web) | ❌ None (Web) | ❌ Verbose | ❌ Text only | **✅ Native `--compact`, `--ndjson`, `--csv` (35–75% savings)** |
588
- | **AI Agent Native Skill** | MCP server only | MCP server only | MCP server only | ❌ Refused | **✅ Antigravity, Claude, Cursor Skill + JSON** |
624
+ | Capability | Google Search Console Web UI | Official Google API SDK (40 Gems) | Enterprise SEO Suites ($300–$1,000+/mo) | **ApollosWave/gsc-cli (v2.2.2)** |
625
+ | :--- | :--- | :--- | :--- | :--- |
626
+ | **Pricing** | Free ($0) | Free ($0) | $300–$1,000+/mo ($3,600–$12,000/yr) | **100% Free & Open Source ($0)** |
627
+ | **Dependencies** | Web Browser only | 40+ transitive gems (`googleauth`, etc.) | SaaS Web Application | **0 Gems / Pure Standard Library** |
628
+ | **Boot / Execution Latency** | Slow (manual clicking) | 3–5 seconds cold boot | Web UI latency | **< 1 millisecond (Compiled Binary)** |
629
+ | **Data Accuracy** | 100% Google Ground Truth | 100% Google Ground Truth | Sampled external proxy estimates | **100% Google Ground Truth (Direct API)** |
630
+ | **CLI Command Surface** | ❌ None (Web only) | Raw Ruby code required | ❌ None (Web dashboard) | **80 Production Commands** |
631
+ | **Core GSC Workflows** | Manual tab clicking & export | Complex API code boilerplate | Partial GSC sync via OAuth | **`top-queries`, `top-pages`, `performance`** |
632
+ | **Instant Googlebot Indexing** | Manual 1-by-1 submit | Complex JWT boilerplate | ❌ None | **✅ 1-Click Priority Ping (`gsc index`)** |
633
+ | **Multi-Engine IndexNow** | ❌ None | ❌ None | ❌ None | **✅ Bing, Yandex, Seznam, Naver (`gsc indexnow`)** |
634
+ | **Striking Distance Playbook** | ❌ Manual spreadsheet work | ❌ None | Expensive add-on tiers | **✅ Automated Page 2 Playbook (`gsc strike`)** |
635
+ | **Google AI Overviews (AIO)** | ❌ None | ❌ None | Limited / expensive beta tiers | **✅ Built-in `aio-hunter` & `cite-sim`** |
636
+ | **Automated Fix Generation** | ❌ None (Error tables only) | ❌ None | ❌ None | **✅ 14-Stack Redirects (`gsc soft-404 --fix`)** |
637
+ | **Token Economics for AI** | ❌ None | Verbose unformatted JSON | ❌ None | **✅ Native `--compact`, `--ndjson`, `--csv` (35–75% savings)** |
638
+ | **Autonomous AI Agent Skills** | ❌ None | ❌ None | ❌ None | **✅ Native Skill for Claude, Cursor, Antigravity** |
589
639
 
590
640
  ---
591
641
 
@@ -596,12 +646,12 @@ Once installed, your agent automatically understands all 80 commands, flag permu
596
646
  ```text
597
647
  gsc-cli/
598
648
  ├── bin/
599
- │ ├── gsc # Standalone executable runner (< 15 lines)
649
+ │ ├── gsc # Compiled single-file binary (RubyGems entry point)
600
650
  │ └── test_live # Visual showcase & internal test harness
601
651
  ├── lib/
602
652
  │ ├── gsc.rb # Central stdlib loader
603
653
  │ └── gsc/
604
- │ ├── version.rb # Semantic versioning (2.2.0)
654
+ │ ├── version.rb # Semantic versioning (2.2.2)
605
655
  │ ├── color.rb # Zero-dependency ANSI formatting
606
656
  │ ├── config.rb # Configuration persistence
607
657
  │ ├── auth.rb # Pure OpenSSL JWT generator
@@ -616,7 +666,7 @@ gsc-cli/
616
666
  │ ├── cli/ # Modular subcommand domains (audit, keywords, growth...)
617
667
  │ └── cli.rb # Primary command dispatcher & router
618
668
  ├── dist/
619
- │ └── gsc # Standalone bundled binary (1,368 KB)
669
+ │ └── gsc # Standalone bundled binary (1-click curl & GitHub releases)
620
670
  ├── gsc.gemspec # Standard RubyGem specification
621
671
  ├── Rakefile # Build, test, and standalone install tasks
622
672
  └── install.sh # Universal 1-click shell installer
@@ -664,7 +714,7 @@ If GSC CLI saves your team hours of manual audit work or hundreds in monthly Saa
664
714
  GSC CLI is maintained by [ApollosWave LLC](https://apolloswave.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli). Check out our products:
665
715
  - **[Superspeed](https://superspeedapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: Autonomous Core Web Vitals & website speed optimization engine.
666
716
  - **[Supercart](https://supercartapp.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: High-converting slide cart drawer for Shopify merchants.
667
- - **[PackingLog](https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: Smart QR-code moving box inventory organizer.
717
+ - **[PackingLog](https://packinglog.com/?utm_source=github&utm_medium=readme&utm_campaign=gsc-cli)**: Our newly launched physical moving inventory and QR-code tracking SaaS — where waiting weeks for Googlebot to discover new landing pages wasn't an option.
668
718
 
669
719
  ---
670
720
 
@@ -676,18 +726,12 @@ GSC CLI is maintained by [ApollosWave LLC](https://apolloswave.com/?utm_source=g
676
726
 
677
727
  ---
678
728
 
679
- ## 📬 A Personal Note from the Maintainers
680
-
681
- **P.S.** If you've made it this far, you already know that relying on manual web dashboards and bloated dependencies is quietly costing your team hours every single week. Installing `gsc-cli` takes **under 10 seconds** (`gem install gsc-cli` or via our 1-line curl installer). In less time than it takes to log into Google Search Console, you can have sub-50ms ground-truth rankings streaming directly in your terminal.
729
+ ## ⚖️ Open Source Philosophy & License
682
730
 
683
- **P.P.S.** Search has entered the most volatile shift in 20 years. Google AI Overviews are expanding across global queries every week, capturing clicks before users ever reach blue links. Every day your landing pages have unmonitored soft-404 errors, mobile rank suppression, or unstructured headings, you are leaking qualified organic customers to competitors who took 5 minutes to optimize their citation readiness.
731
+ `gsc-cli` is 100% free, open-source software licensed under the **[MIT License](LICENSE)**.
684
732
 
685
- **P.P.P.S.** `gsc-cli` is 100% free, MIT licensed, and backed by production businesses that rely on it daily. There are no surprise credit limits, no vendor lock-in, and zero third-party dependencies. If it saves your team even one afternoon of manual SEO busywork, drop a star on the repo and share it with a fellow builder.
686
-
687
- 👉 **[Get Started Now with 1-Click Install](#-quick-installation)** | **[Drop a Star on GitHub ⭐](https://github.com/ApollosWave/gsc-cli)**
688
-
689
- ---
733
+ We built this because we believe command-line developer tools should be fast, transparent, and respect your machine's resources. The modern Ruby standard library is more than capable of handling enterprise-grade API integrations and cryptographic authentication without dragging in 40 third-party gems.
690
734
 
691
- ## 📄 License
735
+ If `gsc-cli` saves your team time, eliminates an unnecessary SaaS subscription, or accelerates your search pipelines, stars, feedback, and pull requests are always welcome.
692
736
 
693
- This project is open-source software licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
737
+ 👉 **[Get Started with 1-Click Install](#-quick-installation)** | **[Star on GitHub ⭐](https://github.com/ApollosWave/gsc-cli)**
data/bin/gsc CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # ==============================================================================
5
5
  # Google Search Console & Indexing API CLI Tool (Pure Ruby - Zero Gem Dependencies)
6
- # Standalone Single-File Distribution (Built from lib/gsc v2.2.0)
6
+ # Standalone Single-File Distribution (Built from lib/gsc v2.2.2)
7
7
  # ==============================================================================
8
8
 
9
9
  require 'net/http'
@@ -20,7 +20,7 @@ require 'stringio'
20
20
 
21
21
  # --- version.rb ---
22
22
  module GSC
23
- VERSION = '2.2.0'
23
+ VERSION = '2.2.2'
24
24
  end
25
25
 
26
26
  # --- color.rb ---
@@ -21612,7 +21612,7 @@ module GSC
21612
21612
  key = input unless input.nil? || input.empty?
21613
21613
  key = existing if key.empty?
21614
21614
  else
21615
- puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/', Color::UNDERLINE)}"
21615
+ puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/?fpr=us25sg', Color::UNDERLINE)}"
21616
21616
  print "Paste your Keywords Everywhere API Key: "
21617
21617
  key = $stdin.gets&.strip
21618
21618
  end
@@ -21643,7 +21643,7 @@ module GSC
21643
21643
  puts " 2. #{Color.c('100% Free Live Google Trends (Breakout & Related terms):', Color::BLUE, Color::BOLD)}"
21644
21644
  puts " • Run: #{Color.c('gsc trends "seo audit"', Color::BLUE, Color::BOLD)}"
21645
21645
  puts " 3. #{Color.c('Top Up Credits for Automated Background CLI Lookups:', Color::GRAY, Color::BOLD)}"
21646
- puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html"
21646
+ puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
21647
21647
  puts " • Your key is already saved; it will work immediately upon top-up.\n"
21648
21648
  else
21649
21649
  puts "\nTry searching keywords:"
@@ -21668,7 +21668,7 @@ module GSC
21668
21668
  puts "\n" + Color.c("ℹ️ You have 0 paid REST API credits remaining.", Color::YELLOW)
21669
21669
  puts "• Free Web Alternative: Check volume on keywordseverywhere.com, click 'Copy', then run: #{Color.c('gsc import clip', Color::CYAN)}"
21670
21670
  puts "• Free Live Trends: #{Color.c('gsc trends "seo audit"', Color::BLUE)}"
21671
- puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html"
21671
+ puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
21672
21672
  end
21673
21673
  else
21674
21674
  if acct[:error].to_s =~ /401|Unauthorized/i
@@ -21705,7 +21705,7 @@ module GSC
21705
21705
  else
21706
21706
  puts Color.c("\n❌ Keywords Everywhere API key not configured!\n", Color::RED, Color::BOLD)
21707
21707
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
21708
- puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/)"
21708
+ puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/?fpr=us25sg)"
21709
21709
  puts " 2. Use 100% free Google Trends (No key needed!): #{Color.c("gsc trends \"#{target}\"", Color::BLUE, Color::BOLD)}"
21710
21710
  puts " 3. Use 500 free daily web lookups: Copy web table -> #{Color.c('gsc import clip', Color::GREEN, Color::BOLD)}\n"
21711
21711
  end
@@ -21752,7 +21752,7 @@ module GSC
21752
21752
  { action: 'import_clipboard', cmd: 'gsc import clip', desc: 'Use 500 free daily web lookups on keywordseverywhere.com and import via clipboard' },
21753
21753
  { action: 'google_trends', cmd: "gsc trends \"#{target}\"", desc: '100% Free real-time search interest & rising breakout queries' },
21754
21754
  { action: 'gsc_analytics', cmd: 'gsc top-queries', desc: 'Real impressions & clicks from your active Google Search Console domain' },
21755
- { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html', desc: 'Purchase API credits to enable automated background CLI lookups' }
21755
+ { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', desc: 'Purchase API credits to enable automated background CLI lookups' }
21756
21756
  ]
21757
21757
  })
21758
21758
  return
@@ -21775,13 +21775,13 @@ module GSC
21775
21775
  puts " • High-impression queries and Page 2 striking-distance keywords:"
21776
21776
  puts " #{Color.c('gsc top-queries', Color::MAGENTA, Color::BOLD)} or #{Color.c('gsc opportunities', Color::MAGENTA, Color::BOLD)}\n"
21777
21777
  puts " 4. #{Color.c('Top Up API Credits for Automated Background CLI Lookups', Color::GRAY, Color::BOLD)}"
21778
- puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html', Color::UNDERLINE)}"
21778
+ puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', Color::UNDERLINE)}"
21779
21779
  puts " • Your key is already saved; it will work immediately once credited.\n"
21780
21780
  elsif err_str =~ /401|Unauthorized/i
21781
21781
  puts Color.c("\n🔑 Invalid or Expired Keywords Everywhere API Key", Color::RED, Color::BOLD)
21782
21782
  puts "Your API key was rejected by api.keywordseverywhere.com (HTTP 401).\n\n"
21783
21783
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
21784
- puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html', Color::UNDERLINE)}"
21784
+ puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html?fpr=us25sg', Color::UNDERLINE)}"
21785
21785
  puts " • Reconnect key: #{Color.c('gsc connect ke <KEY>', Color::CYAN, Color::BOLD)}"
21786
21786
  puts " • Or use free Google Trends without any key: #{Color.c("gsc trends \"#{target}\"", Color::BLUE)}"
21787
21787
  elsif err_str =~ /429|Rate Limit/i
data/dist/gsc CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  # ==============================================================================
5
5
  # Google Search Console & Indexing API CLI Tool (Pure Ruby - Zero Gem Dependencies)
6
- # Standalone Single-File Distribution (Built from lib/gsc v2.2.0)
6
+ # Standalone Single-File Distribution (Built from lib/gsc v2.2.2)
7
7
  # ==============================================================================
8
8
 
9
9
  require 'net/http'
@@ -20,7 +20,7 @@ require 'stringio'
20
20
 
21
21
  # --- version.rb ---
22
22
  module GSC
23
- VERSION = '2.2.0'
23
+ VERSION = '2.2.2'
24
24
  end
25
25
 
26
26
  # --- color.rb ---
@@ -21612,7 +21612,7 @@ module GSC
21612
21612
  key = input unless input.nil? || input.empty?
21613
21613
  key = existing if key.empty?
21614
21614
  else
21615
- puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/', Color::UNDERLINE)}"
21615
+ puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/?fpr=us25sg', Color::UNDERLINE)}"
21616
21616
  print "Paste your Keywords Everywhere API Key: "
21617
21617
  key = $stdin.gets&.strip
21618
21618
  end
@@ -21643,7 +21643,7 @@ module GSC
21643
21643
  puts " 2. #{Color.c('100% Free Live Google Trends (Breakout & Related terms):', Color::BLUE, Color::BOLD)}"
21644
21644
  puts " • Run: #{Color.c('gsc trends "seo audit"', Color::BLUE, Color::BOLD)}"
21645
21645
  puts " 3. #{Color.c('Top Up Credits for Automated Background CLI Lookups:', Color::GRAY, Color::BOLD)}"
21646
- puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html"
21646
+ puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
21647
21647
  puts " • Your key is already saved; it will work immediately upon top-up.\n"
21648
21648
  else
21649
21649
  puts "\nTry searching keywords:"
@@ -21668,7 +21668,7 @@ module GSC
21668
21668
  puts "\n" + Color.c("ℹ️ You have 0 paid REST API credits remaining.", Color::YELLOW)
21669
21669
  puts "• Free Web Alternative: Check volume on keywordseverywhere.com, click 'Copy', then run: #{Color.c('gsc import clip', Color::CYAN)}"
21670
21670
  puts "• Free Live Trends: #{Color.c('gsc trends "seo audit"', Color::BLUE)}"
21671
- puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html"
21671
+ puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
21672
21672
  end
21673
21673
  else
21674
21674
  if acct[:error].to_s =~ /401|Unauthorized/i
@@ -21705,7 +21705,7 @@ module GSC
21705
21705
  else
21706
21706
  puts Color.c("\n❌ Keywords Everywhere API key not configured!\n", Color::RED, Color::BOLD)
21707
21707
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
21708
- puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/)"
21708
+ puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/?fpr=us25sg)"
21709
21709
  puts " 2. Use 100% free Google Trends (No key needed!): #{Color.c("gsc trends \"#{target}\"", Color::BLUE, Color::BOLD)}"
21710
21710
  puts " 3. Use 500 free daily web lookups: Copy web table -> #{Color.c('gsc import clip', Color::GREEN, Color::BOLD)}\n"
21711
21711
  end
@@ -21752,7 +21752,7 @@ module GSC
21752
21752
  { action: 'import_clipboard', cmd: 'gsc import clip', desc: 'Use 500 free daily web lookups on keywordseverywhere.com and import via clipboard' },
21753
21753
  { action: 'google_trends', cmd: "gsc trends \"#{target}\"", desc: '100% Free real-time search interest & rising breakout queries' },
21754
21754
  { action: 'gsc_analytics', cmd: 'gsc top-queries', desc: 'Real impressions & clicks from your active Google Search Console domain' },
21755
- { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html', desc: 'Purchase API credits to enable automated background CLI lookups' }
21755
+ { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', desc: 'Purchase API credits to enable automated background CLI lookups' }
21756
21756
  ]
21757
21757
  })
21758
21758
  return
@@ -21775,13 +21775,13 @@ module GSC
21775
21775
  puts " • High-impression queries and Page 2 striking-distance keywords:"
21776
21776
  puts " #{Color.c('gsc top-queries', Color::MAGENTA, Color::BOLD)} or #{Color.c('gsc opportunities', Color::MAGENTA, Color::BOLD)}\n"
21777
21777
  puts " 4. #{Color.c('Top Up API Credits for Automated Background CLI Lookups', Color::GRAY, Color::BOLD)}"
21778
- puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html', Color::UNDERLINE)}"
21778
+ puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', Color::UNDERLINE)}"
21779
21779
  puts " • Your key is already saved; it will work immediately once credited.\n"
21780
21780
  elsif err_str =~ /401|Unauthorized/i
21781
21781
  puts Color.c("\n🔑 Invalid or Expired Keywords Everywhere API Key", Color::RED, Color::BOLD)
21782
21782
  puts "Your API key was rejected by api.keywordseverywhere.com (HTTP 401).\n\n"
21783
21783
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
21784
- puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html', Color::UNDERLINE)}"
21784
+ puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html?fpr=us25sg', Color::UNDERLINE)}"
21785
21785
  puts " • Reconnect key: #{Color.c('gsc connect ke <KEY>', Color::CYAN, Color::BOLD)}"
21786
21786
  puts " • Or use free Google Trends without any key: #{Color.c("gsc trends \"#{target}\"", Color::BLUE)}"
21787
21787
  elsif err_str =~ /429|Rate Limit/i
data/lib/gsc/cli/keywords.rb CHANGED
@@ -384,7 +384,7 @@ module GSC
384
384
  key = input unless input.nil? || input.empty?
385
385
  key = existing if key.empty?
386
386
  else
387
- puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/', Color::UNDERLINE)}"
387
+ puts "Get your Keywords Everywhere API key at: #{Color.c('https://keywordseverywhere.com/?fpr=us25sg', Color::UNDERLINE)}"
388
388
  print "Paste your Keywords Everywhere API Key: "
389
389
  key = $stdin.gets&.strip
390
390
  end
@@ -415,7 +415,7 @@ module GSC
415
415
  puts " 2. #{Color.c('100% Free Live Google Trends (Breakout & Related terms):', Color::BLUE, Color::BOLD)}"
416
416
  puts " • Run: #{Color.c('gsc trends "seo audit"', Color::BLUE, Color::BOLD)}"
417
417
  puts " 3. #{Color.c('Top Up Credits for Automated Background CLI Lookups:', Color::GRAY, Color::BOLD)}"
418
- puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html"
418
+ puts " • Purchase credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
419
419
  puts " • Your key is already saved; it will work immediately upon top-up.\n"
420
420
  else
421
421
  puts "\nTry searching keywords:"
@@ -440,7 +440,7 @@ module GSC
440
440
  puts "\n" + Color.c("ℹ️ You have 0 paid REST API credits remaining.", Color::YELLOW)
441
441
  puts "• Free Web Alternative: Check volume on keywordseverywhere.com, click 'Copy', then run: #{Color.c('gsc import clip', Color::CYAN)}"
442
442
  puts "• Free Live Trends: #{Color.c('gsc trends "seo audit"', Color::BLUE)}"
443
- puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html"
443
+ puts "• Top up credits at: https://keywordseverywhere.com/credit-packages.html?fpr=us25sg"
444
444
  end
445
445
  else
446
446
  if acct[:error].to_s =~ /401|Unauthorized/i
@@ -477,7 +477,7 @@ module GSC
477
477
  else
478
478
  puts Color.c("\n❌ Keywords Everywhere API key not configured!\n", Color::RED, Color::BOLD)
479
479
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
480
- puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/)"
480
+ puts " 1. Connect a key: #{Color.c('gsc connect ke', Color::CYAN, Color::BOLD)} (Get key at https://keywordseverywhere.com/?fpr=us25sg)"
481
481
  puts " 2. Use 100% free Google Trends (No key needed!): #{Color.c("gsc trends \"#{target}\"", Color::BLUE, Color::BOLD)}"
482
482
  puts " 3. Use 500 free daily web lookups: Copy web table -> #{Color.c('gsc import clip', Color::GREEN, Color::BOLD)}\n"
483
483
  end
@@ -524,7 +524,7 @@ module GSC
524
524
  { action: 'import_clipboard', cmd: 'gsc import clip', desc: 'Use 500 free daily web lookups on keywordseverywhere.com and import via clipboard' },
525
525
  { action: 'google_trends', cmd: "gsc trends \"#{target}\"", desc: '100% Free real-time search interest & rising breakout queries' },
526
526
  { action: 'gsc_analytics', cmd: 'gsc top-queries', desc: 'Real impressions & clicks from your active Google Search Console domain' },
527
- { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html', desc: 'Purchase API credits to enable automated background CLI lookups' }
527
+ { action: 'topup', url: 'https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', desc: 'Purchase API credits to enable automated background CLI lookups' }
528
528
  ]
529
529
  })
530
530
  return
@@ -547,13 +547,13 @@ module GSC
547
547
  puts " • High-impression queries and Page 2 striking-distance keywords:"
548
548
  puts " #{Color.c('gsc top-queries', Color::MAGENTA, Color::BOLD)} or #{Color.c('gsc opportunities', Color::MAGENTA, Color::BOLD)}\n"
549
549
  puts " 4. #{Color.c('Top Up API Credits for Automated Background CLI Lookups', Color::GRAY, Color::BOLD)}"
550
- puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html', Color::UNDERLINE)}"
550
+ puts " • Purchase credits at: #{Color.c('https://keywordseverywhere.com/credit-packages.html?fpr=us25sg', Color::UNDERLINE)}"
551
551
  puts " • Your key is already saved; it will work immediately once credited.\n"
552
552
  elsif err_str =~ /401|Unauthorized/i
553
553
  puts Color.c("\n🔑 Invalid or Expired Keywords Everywhere API Key", Color::RED, Color::BOLD)
554
554
  puts "Your API key was rejected by api.keywordseverywhere.com (HTTP 401).\n\n"
555
555
  puts "#{Color::BOLD}RECOMMENDATIONS:#{Color::RESET}"
556
- puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html', Color::UNDERLINE)}"
556
+ puts " • Check or generate your API key at: #{Color.c('https://keywordseverywhere.com/first-install-addon.html?fpr=us25sg', Color::UNDERLINE)}"
557
557
  puts " • Reconnect key: #{Color.c('gsc connect ke <KEY>', Color::CYAN, Color::BOLD)}"
558
558
  puts " • Or use free Google Trends without any key: #{Color.c("gsc trends \"#{target}\"", Color::BLUE)}"
559
559
  elsif err_str =~ /429|Rate Limit/i
data/lib/gsc/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module GSC
4
- VERSION = '2.2.0'
4
+ VERSION = '2.2.2'
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: gsc-cli
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.0
4
+ version: 2.2.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - ApollosWave LLC