gsc-cli 2.0.1 → 2.1.0

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 (24) hide show
  1. checksums.yaml +4 -4
  2. data/AUTH.md +205 -0
  3. data/FUNDING.md +120 -0
  4. data/README.md +237 -38
  5. data/bin/gsc +2028 -197
  6. data/dist/gsc +167 -5
  7. data/lib/gsc/backlinks_manager.rb +96 -0
  8. data/lib/gsc/cli.rb +156 -3
  9. data/lib/gsc/cli_advanced.rb +570 -0
  10. data/lib/gsc/config.rb +9 -0
  11. data/lib/gsc/content_gap.rb +112 -0
  12. data/lib/gsc/google_suggest.rb +109 -0
  13. data/lib/gsc/internal_links.rb +132 -0
  14. data/lib/gsc/llms_generator.rb +104 -0
  15. data/lib/gsc/network_tracer.rb +86 -0
  16. data/lib/gsc/open_page_rank.rb +72 -0
  17. data/lib/gsc/page_comparator.rb +108 -0
  18. data/lib/gsc/page_speed.rb +110 -0
  19. data/lib/gsc/robots_checker.rb +83 -0
  20. data/lib/gsc/schema_validator.rb +122 -0
  21. data/lib/gsc/serp_preview.rb +66 -0
  22. data/lib/gsc/version.rb +1 -1
  23. data/lib/gsc.rb +26 -0
  24. metadata +33 -6
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2caa7ef6d70b3a937056d9c5b3296a18cbcdaab2137533fe553ca6e06d0db604
4
- data.tar.gz: 77a07b9ac543ac0530fb61dcc25953d0c948f4bb90463f477d08f0ffebe05921
3
+ metadata.gz: 7278e3338526ebd22a07fa284e452db00a738def6c2a4dbfbb4fbeaff3f5d4b3
4
+ data.tar.gz: bfdd760060590b89808a95d1355f4c11aba7e43dc1393f6775e0fcedfec96df2
5
5
  SHA512:
6
- metadata.gz: 1809e1e6e0c9a439894db3c5b8e3107f2ec2669f234e224d433d9d8cadfaa268eebfd632129424e88c85ea4f10664c710374737cb81d3adcfac3a4a8cbd7864c
7
- data.tar.gz: 00ab88895619228527ce0bd3cb8ced18f012610a87449c255dad2ea2cfe5da52f0d0af6f5aae6a5e33491425d893ea1dfb14c317e698f34d36dceac8504b9e4e
6
+ metadata.gz: 3c41ca07104aabff6c25650a117332c14d93cf5977331ee95f93b15a19c2f77bdd518754b5e5e958c2ea1380bfa1b707e9382c801e87ba5ae0a03258798f891e
7
+ data.tar.gz: 5eca0283978fdfd7f8d279a8f4d3a54366a4430b33a3e767ed7e412fae49e6e0c95f2a880175cbccbf9d6d9c804b82429363b8ad0678a1d378a969b2e4038c2c
data/AUTH.md ADDED
@@ -0,0 +1,205 @@
1
+ # 🔑 Authentication & API Key Setup Guide for GSC CLI
2
+
3
+ > **Zero Hidden Costs.** Every feature in `gsc-cli` runs on either zero API keys or completely free tiers provided directly by Google and open graph providers.
4
+ > Follow this master guide to connect Google Search Console, Google Indexing, GA4, Google PageSpeed, OpenPageRank, and Keywords Everywhere in under 3 minutes.
5
+
6
+ ---
7
+
8
+ ## ⚡ Quick Reference: What Requires an API Key
9
+
10
+ | Tool & Command | Setup Required | Cost | How to Configure |
11
+ | :--- | :---: | :---: | :--- |
12
+ | **Google Search Console (`gsc search`, `gsc top`)** | Service Account JSON | **$0 Free** | `gsc connect` |
13
+ | **Google Indexing API (`gsc index`)** | Service Account JSON | **$0 Free** | `gsc connect` |
14
+ | **Google Analytics 4 (`gsc ga4`)** | Service Account + Property ID | **$0 Free** | `gsc config set ga4_property_id <ID>` |
15
+ | **Google Trends (`gsc trends`, `gsc velocity`)** | **Zero Setup / No Keys** | **$0 Free** | Works out of the box |
16
+ | **Google Suggest & PAA (`gsc suggest`, `gsc questions`)** | **Zero Setup / No Keys** | **$0 Free** | Works out of the box |
17
+ | **On-Page & Competitor Gap (`gsc compare`, `gsc content-gap`)** | **Zero Setup / No Keys** | **$0 Free** | Works out of the box |
18
+ | **Schema & AI Search (`gsc schema`, `gsc llms`)** | **Zero Setup / No Keys** | **$0 Free** | Works out of the box |
19
+ | **Network & Crawler Simulator (`gsc trace`, `gsc robots`)** | **Zero Setup / No Keys** | **$0 Free** | Works out of the box |
20
+ | **Google PageSpeed Insights (`gsc speed`)** | Optional Free API Key | **$0 Free** | `gsc config set pagespeed_api_key <KEY>` |
21
+ | **OpenPageRank Authority (`gsc authority`)** | Free API Key (300k calls/mo) | **$0 Free** | `gsc config set openpagerank_api_key <KEY>` |
22
+ | **Keywords Everywhere (`gsc import clip` vs `gsc ke`)** | Clipboard: $0 / API: $1.25 | **Free or Low** | `gsc config set keywords_everywhere_api_key <KEY>` |
23
+
24
+ ---
25
+
26
+ ## 1. Google Search Console & Google Indexing API (Core Setup)
27
+
28
+ The core `gsc` engine connects directly to Google Cloud without any middleman servers or third-party databases.
29
+
30
+ ### Step 1: Create a Free Google Cloud Service Account
31
+ 1. Open the [Google Cloud Console](https://console.cloud.google.com/).
32
+ 2. Create a new project (or select an existing one, e.g. `gsc-tools`).
33
+ 3. Go to **APIs & Services > Library**, search for and **Enable** these two APIs:
34
+ * **Google Search Console API**
35
+ * **Web Search Indexing API**
36
+ 4. Go to **IAM & Admin > Service Accounts** and click **Create Service Account**:
37
+ * Name: `gsc-operator`
38
+ * Click **Create and Continue**, then click **Done**.
39
+ 5. Click on your newly created service account in the table:
40
+ * Navigate to the **Keys** tab.
41
+ * Click **Add Key > Create new key**.
42
+ * Select **JSON** and click **Create**. The key file will download to your computer.
43
+
44
+ ### Step 2: 1-Click Interactive Terminal Connect
45
+ In your terminal, run:
46
+ ```bash
47
+ gsc connect
48
+ ```
49
+ `gsc` automatically inspects your `~/Downloads` folder for the newest Google Cloud JSON key, asks you to confirm with `Y`, moves it securely to `~/.config/gsc/service-account.json`, and displays the service account email.
50
+
51
+ ### Step 3: Grant Access in Google Search Console
52
+ 1. Copy the service account email (e.g. `gsc-operator@your-project.iam.gserviceaccount.com`).
53
+ 2. Go to [Google Search Console](https://search.google.com/search-console/).
54
+ 3. Select your property > **Settings** (bottom left) > **Users and permissions**.
55
+ 4. Click **Add user**:
56
+ * **Email address**: Paste your service account email.
57
+ * **Permission**: **Owner** *(Required for 1-click Googlebot indexing requests)*.
58
+ 5. Verify access immediately:
59
+ ```bash
60
+ # List all verified properties
61
+ gsc domains
62
+
63
+ # Test querying search analytics
64
+ gsc search yourdomain.com
65
+ ```
66
+
67
+ ---
68
+
69
+ ## 2. Google Analytics 4 (GA4 Realtime & Traffic Channels)
70
+
71
+ Query real-time active users, acquisition channels, and Google Ads conversions alongside your Search Console rankings.
72
+
73
+ ### Step 1: Enable the API
74
+ In Google Cloud Console, enable the **Google Analytics Data API**.
75
+
76
+ ### Step 2: Grant Access in GA4
77
+ 1. Open your [Google Analytics 4 Admin Console](https://analytics.google.com/).
78
+ 2. Under **Property settings**, click **Property access management**.
79
+ 3. Click the **+** icon > **Add users**:
80
+ * Paste your service account email (`gsc-operator@your-project.iam.gserviceaccount.com`).
81
+ * Role: **Viewer** or **Analyst**.
82
+ 4. Copy your **Property ID** (found under **Property settings > Property details**).
83
+
84
+ ### Step 3: Save Your Property ID
85
+ ```bash
86
+ # Save to permanent configuration
87
+ gsc config set ga4_property_id 123456789
88
+
89
+ # Or pass via environment variable
90
+ export GA4_PROPERTY_ID=123456789
91
+ ```
92
+
93
+ ---
94
+
95
+ ## 3. Google PageSpeed Insights & Core Web Vitals (`gsc speed`)
96
+
97
+ Audit official mobile and desktop Lighthouse scores and 75th percentile Chrome User Experience Report (CrUX) metrics (LCP, INP, CLS, FCP, TTFB).
98
+
99
+ ### Unauthenticated Mode (Default)
100
+ `gsc speed` works immediately with **zero configuration** for normal development auditing:
101
+ ```bash
102
+ gsc speed https://example.com
103
+ ```
104
+
105
+ ### High-Throughput Mode (Optional Free API Key)
106
+ If you run high-frequency batch audits in CI/CD pipelines (up to 25,000 queries/day free):
107
+ 1. In Google Cloud Console, enable **PageSpeed Insights API**.
108
+ 2. Go to **APIs & Services > Credentials** > **Create Credentials** > **API Key**.
109
+ 3. Save the key:
110
+ ```bash
111
+ gsc config set pagespeed_api_key AIzaSyYourKeyHere
112
+
113
+ # Or pass as environment variable
114
+ export PAGESPEED_API_KEY=AIzaSyYourKeyHere
115
+ ```
116
+
117
+ ---
118
+
119
+ ## 4. OpenPageRank Domain Authority (`gsc authority`)
120
+
121
+ Query true PageRank (0–10) and Global Web Rank computed across Common Crawl's multi-billion page open graph.
122
+
123
+ ### Setup (30 Seconds, 300,000 Free Calls / Month)
124
+ 1. Sign up for a free account at [OpenPageRank (domcop.com)](https://www.domcop.com/openpagerank/).
125
+ 2. Copy your API key from your dashboard.
126
+ 3. Save the key:
127
+ ```bash
128
+ gsc config set openpagerank_api_key opr-your-key-here
129
+
130
+ # Or pass as environment variable
131
+ export OPENPAGERANK_API_KEY=opr-your-key-here
132
+ ```
133
+ 4. Test authority lookup:
134
+ ```bash
135
+ gsc authority github.com apple.com yourdomain.com
136
+ ```
137
+
138
+ ---
139
+
140
+ ## 5. Keywords Everywhere (`gsc import clip` vs `gsc ke`)
141
+
142
+ Get monthly search volume, Cost-Per-Click (CPC), and 12-month historical trend velocity.
143
+
144
+ ### Option A: The 100% Free Clipboard Method (Zero Setup)
145
+ You do not need an API key. Whenever you browse Keywords Everywhere in Chrome/Brave:
146
+ 1. Click **"Copy"** on any keyword widget.
147
+ 2. In your terminal, run:
148
+ ```bash
149
+ gsc import clip
150
+ ```
151
+ `gsc` parses the clipboard text, normalizes search volumes and CPC, and saves it into your local domain archive.
152
+
153
+ ### Option B: Direct API Integration
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).
156
+ 2. Save your key:
157
+ ```bash
158
+ gsc config set keywords_everywhere_api_key your_ke_api_key_here
159
+
160
+ # Or pass as environment variable
161
+ export KEYWORDS_EVERYWHERE_API_KEY=your_ke_api_key_here
162
+ ```
163
+ 3. Query volume directly:
164
+ ```bash
165
+ gsc ke "technical seo" "static site generator"
166
+ ```
167
+
168
+ ---
169
+
170
+ ## 6. Configuration Management Cheatsheet
171
+
172
+ View, set, and manage all your local credentials stored securely in `~/.config/gsc/`:
173
+
174
+ ```bash
175
+ # View active configuration and stored keys
176
+ gsc config
177
+
178
+ # Set a configuration value
179
+ gsc config set <key> <value>
180
+
181
+ # Run interactive connect for Google Service Account
182
+ gsc connect
183
+
184
+ # Set active default domain
185
+ gsc use example.com
186
+ ```
187
+
188
+ ### Supported Environment Variables
189
+ For automated Docker, GitHub Actions, or CI/CD pipelines, all configuration can be passed via environment variables without disk storage:
190
+
191
+ ```bash
192
+ export GSC_KEY_FILE="/path/to/service-account.json"
193
+ export GSC_DEFAULT_DOMAIN="example.com"
194
+ export GA4_PROPERTY_ID="123456789"
195
+ export PAGESPEED_API_KEY="AIzaSy..."
196
+ export OPENPAGERANK_API_KEY="opr-..."
197
+ export KEYWORDS_EVERYWHERE_API_KEY="..."
198
+ ```
199
+
200
+ ---
201
+
202
+ <p align="center">
203
+ <b>Need Help?</b><br>
204
+ If you run into permission errors, verify that your service account email is listed as an <b>Owner</b> in Google Search Console Settings.
205
+ </p>
data/FUNDING.md ADDED
@@ -0,0 +1,120 @@
1
+ # Fuel Independent, Zero-Bloat Developer Tooling While Putting Your Brand in Front of High-Velocity Engineers
2
+
3
+ > **The Sponsorship Prospectus for GSC CLI & The ApollosWave Open Source Ecosystem**
4
+ > Put your company, brand, or agency directly into the daily terminal workflows, CI/CD pipelines, and GitHub READMEs of thousands of software engineers, founders, and technical SEO operators — even if you have never sponsored an open-source tool before or operate with a strict B2B performance marketing budget.
5
+
6
+ [![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-red.svg?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
7
+ [![Gem Version](https://badge.fury.io/rb/gsc-cli.svg)](https://rubygems.org/gems/gsc-cli)
8
+ [![Dependencies](https://img.shields.io/badge/dependencies-0%20gems-brightgreen.svg)](#)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10
+
11
+ ---
12
+
13
+ ## 🎯 The Dilemma: Why Traditional Developer Advertising Fails
14
+
15
+ If you have ever tried to market to developers, engineers, and technical founders, you already know the painful truth:
16
+ - **They use aggressive ad-blockers**: Display ads and programmatic banners are completely invisible to 84% of senior engineers.
17
+ - **They despise corporate sales pitches**: Sponsored blog posts and spammy cold emails get flagged or ignored.
18
+ - **PPC is outrageously expensive**: B2B search terms like *"SEO audit tool"*, *"Google Search Console API"*, or *"SERP tracker"* cost upwards of **$14.50 to $32.00 per single click** on Google Ads — with zero guarantee of conversion.
19
+ - **Conference booths cost a fortune**: Sponsoring a 2-day developer conference costs between **$12,000 and $25,000**, only for the banners to be torn down 48 hours later.
20
+
21
+ ### Sponsoring GSC CLI is Fundamentally Different
22
+ `gsc-cli` is not a weekend hobby script. It is an ultra-fast, zero-dependency, sub-50ms engine adopted by developers, agency owners, and AI builders who run mission-critical Google search intelligence every single day.
23
+
24
+ When you back `gsc-cli`, you are not giving away charity. You are securing **365 days of persistent, high-authority visibility** across GitHub, Google-indexed documentation, terminal releases, and developer mindshare for a tiny fraction of a single PPC campaign.
25
+
26
+ ---
27
+
28
+ ## ⚡ The 6 Sponsorship Tiers
29
+
30
+ Select the tier that aligns with your brand's growth goals. All payments are billed monthly via Stripe with immediate receipt generation and business tax ID support:
31
+
32
+ | Tier | Monthly | Target Audience | Primary Visibility & Deliverables | Checkout |
33
+ | :--- | :---: | :--- | :--- | :---: |
34
+ | **Community Supporter** | **$10 / mo** | Individual Engineers | Name listed in README Backers section + GitHub Supporter badge | [**Subscribe ($10/mo)**](https://buy.stripe.com/fZu6oG4Qz1EucVT4ygbAs00) |
35
+ | **Backer** | **$50 / mo** | Freelancers & Power Users | Hyperlinked name in Backers section + priority triage on GitHub issues | [**Subscribe ($50/mo)**](https://buy.stripe.com/7sY00ier91Eu5tr0i0bAs01) |
36
+ | **Agency Partner / Team** | **$100 / mo** | Boutique Agencies & Dev Shops | Small company logo & link in **Agency Partners** gallery + issue priority | [**Subscribe ($100/mo)**](https://buy.stripe.com/6oU9AS1Engzog853ucbAs02) |
37
+ | **Bronze Sponsor** | **$500 / mo** | Growing B2B SaaS & Tech Brands | Medium logo with **dofollow backlink** in main Sponsor grid in README & docs | [**Subscribe ($500/mo)**](https://buy.stripe.com/eVqdR882LgzobRP9SAbAs03) |
38
+ | **Silver Sponsor** | **$1,500 / mo** | Established Scaleups & Dev Tools | Large logo on **top fold** of README + monthly roadmap feature priority | [**Subscribe ($1,500/mo)**](https://buy.stripe.com/8x2aEWbeX2IybRP1m4bAs04) |
39
+ | **Gold Title Sponsor** | **$2,500 / mo** | Enterprise & Industry Leaders | **Exclusive Title Sponsor banner** at very top of README + 1hr monthly consulting | [**Subscribe ($2,500/mo)**](https://buy.stripe.com/cNi7sK4Qz6YOaNL3ucbAs05) |
40
+
41
+ ---
42
+
43
+ ## 💎 Deep Breakdown: What Each Tier Gets
44
+
45
+ ### 1. Community Supporter ($10 / month)
46
+ *Designed for indie developers and fans who love fast, zero-dependency tools.*
47
+ * **README Recognition**: Your name or GitHub handle listed in the `Backers & Supporters` section.
48
+ * **Community Karma**: Direct satisfaction of knowing you keep open-source developer tooling 100% free from venture bloat.
49
+ * 👉 [**Join as Community Supporter ($10/mo)**](https://buy.stripe.com/fZu6oG4Qz1EucVT4ygbAs00)
50
+
51
+ ### 2. Backer ($50 / month)
52
+ *Designed for power-user consultants, solo technical SEOs, and senior freelancers.*
53
+ * **Hyperlinked Profile**: Your name linked directly to your personal website or GitHub profile.
54
+ * **Priority Issue Triage**: Your bug reports and edge-case questions receive priority attention from the maintainers.
55
+ * 👉 [**Join as Backer ($50/mo)**](https://buy.stripe.com/7sY00ier91Eu5tr0i0bAs01)
56
+
57
+ ### 3. Agency Partner / Team ($100 / month)
58
+ *The no-brainer tier for SEO agencies, digital consultancies, and engineering teams.*
59
+ * **Agency Logo & Dofollow Link**: 32x32px logo and company link featured in the dedicated `Agency Partners & Teams` gallery.
60
+ * **Client Credibility**: Show your clients that your agency actively powers and contributes to leading search intelligence infrastructure.
61
+ * **Priority Feature Consideration**: Suggest new CLI flags, CSV export schemas, or agent prompts tailored to your agency's reporting workflow.
62
+ * 👉 [**Join as Agency Partner ($100/mo)**](https://buy.stripe.com/6oU9AS1Engzog853ucbAs02)
63
+
64
+ ### 4. Bronze Sponsor ($500 / month)
65
+ *High-impact exposure for developer tools, hosting providers, analytics SaaS, and growth services.*
66
+ * **Prominent Medium Logo**: 64px crisp logo in the main `Sponsors` grid at the top of the README.
67
+ * **High-Authority Dofollow Backlink**: Direct link to your homepage, product landing page, or free trial.
68
+ * **Release Changelog Mentions**: Acknowledged in official GitHub releases and gem version release notes.
69
+ * 👉 [**Become a Bronze Sponsor ($500/mo)**](https://buy.stripe.com/eVqdR882LgzobRP9SAbAs03)
70
+
71
+ ### 5. Silver Sponsor ($1,500 / month)
72
+ *Premium placement for established developer platforms, cloud providers, and enterprise software.*
73
+ * **Top-Fold Showcase**: 96px prominent logo displayed above the fold on the repository README and official documentation.
74
+ * **Monthly Feature Priority**: Direct access to request 1 dedicated feature enhancement, export schema, or integration per quarter.
75
+ * **Co-Marketing & Social Shoutout**: Quarterly feature announcement on our official channels and changelog highlighting your brand's support.
76
+ * 👉 [**Become a Silver Sponsor ($1,500/mo)**](https://buy.stripe.com/8x2aEWbeX2IybRP1m4bAs04)
77
+
78
+ ### 6. Gold Title Sponsor ($2,500 / month)
79
+ *Exclusive category exclusivity. Only 1 Gold Title Sponsor slot is available across the entire project.*
80
+ * **Exclusive Hero Banner**: Your custom banner placed at the **very top of the README** right below the primary headline (`"GSC CLI is proudly presented by [Your Company]"`).
81
+ * **1-Hour Monthly Strategy Call**: Direct monthly 60-minute technical consultation with ApollosWave principal engineers regarding search architecture, Core Web Vitals optimization, or AI agent pipelines.
82
+ * **First-Class Ecosystem Integration**: Permanent status as the foundational patron of the ApollosWave open-source stack.
83
+ * 👉 [**Claim Gold Title Sponsorship ($2,500/mo)**](https://buy.stripe.com/cNi7sK4Qz6YOaNL3ucbAs05)
84
+
85
+ ---
86
+
87
+ ## 📊 The Math: Why Sponsoring GSC CLI Destroys Google Ads
88
+
89
+ | Channel | Cost | Duration | Audience Quality | Ad-Block Resistant? |
90
+ | :--- | :---: | :---: | :---: | :---: |
91
+ | **Google Ads (B2B SEO)** | $3,500 / mo | Only while paying | Mixed / Low-intent clicks | ❌ No |
92
+ | **Tech Newsletter Sponsor** | $1,800 | 1 email blast | Ephemeral (archived in 24h) | ⚠️ Partial |
93
+ | **Conference Booth** | $15,000 | 2 days | Local attendees only | N/A |
94
+ | **GSC CLI Bronze Sponsor** | **$500 / mo** | **Continuous 365 Days** | **100% Verified Engineers & Founders** | **✅ 100% Yes** |
95
+
96
+ ---
97
+
98
+ ## 💬 Frequently Asked Questions (B2B & Commercial)
99
+
100
+ ### Can my business write this off as a tax deduction
101
+ **Yes.** All payments are processed commercially by **ApollosWave LLC**. Your checkout confirmation includes a complete, compliant B2B tax invoice with line-item detail, your company name, and your VAT/EIN/Tax ID. Sponsoring an open-source technical tool is fully classified as a **Software & Advertising / Marketing Expense**.
102
+
103
+ ### How quickly will our logo and link appear
104
+ Your logo and backlink are published within **24 hours** of completing checkout. Our team receives an instant automated notification from Stripe and immediately stages your assets.
105
+
106
+ ### What assets do we need to provide
107
+ During Stripe checkout, you can supply your website link. After checkout, simply email your high-resolution SVG or transparent PNG logo to `sponsors@apolloswave.com` (or open a GitHub Issue), and our engineers will format and optimize it for dark and light modes.
108
+
109
+ ### Can we change our destination URL or logo later
110
+ Yes, at any time. Simply send us an email or file a ticket from your account email, and your links or assets will be updated within 1 business day.
111
+
112
+ ### Can we cancel at any time
113
+ Yes. There are no lock-in contracts. You will receive an instant Stripe Customer Portal link where you can update your payment method, download past VAT invoices, or pause/cancel your sponsorship with a single click whenever you wish.
114
+
115
+ ---
116
+
117
+ <p align="center">
118
+ <b>Ready to elevate your engineering brand?</b><br>
119
+ Choose your tier above, or contact our engineering team directly at <a href="mailto:sponsors@apolloswave.com"><b>sponsors@apolloswave.com</b></a> for custom enterprise arrangements.
120
+ </p>