gsc-cli 2.2.0 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfc89a987633cd3ebe87687aeb568bf3e580dff0dceda12bbda364858ec1e09e
-  data.tar.gz: 12553e6e7e33cc33fcc2fd83a003e27bf6b81a56525104a1d9a8fa07fc69b3ad
+  metadata.gz: c6cfd0972501711b114e27b2a286612efcfe85bd51aaf91947bc44b8fdfd9aff
+  data.tar.gz: 5bd6e630844f13a3115bbb4c54deda04f7f3e1585c79ac4d9037dd7c216d02a1
 SHA512:
-  metadata.gz: b37602987f85a260627f8f2dcd1f82516d9974ff4290ed2f37b939ff2e32c0d1f7f4a366985d85cba373f9a20071452c73fd3e3676a6f8a98f49a852a0095140
-  data.tar.gz: 0ca4aac728ab0b2a53f8e95c17d81109ca8104c02eee3dc96e4524eb8467fe10b3d29bb5c23e88eec4a837108a7741b547d6e151f29c775f832b7143661133d2
+  metadata.gz: ab41e83aa4f41ca0d296218f288cb2291275c893cf60347d6cbc7083371430e06feebf00aa084d5c5978fd0bd0bd5a35f29a1beaf5839f322f2efc629bf38429
+  data.tar.gz: 50ea5330dee9bae3b09570be862e69c3b4ec5e1aafc7126525bdd2dbe1a894c2392204749b5c7f187d32c0273530cc55f6ba66599502068b8870f1a7bdcd3f6b

data/AUTH.md

@@ -96,23 +96,50 @@ export GA4_PROPERTY_ID=123456789
 
 Audit official mobile and desktop Lighthouse scores and 75th percentile Chrome User Experience Report (CrUX) metrics (LCP, INP, CLS, FCP, TTFB).
 
-### Unauthenticated Mode (Default)
-`gsc speed` works immediately with **zero configuration** for normal development auditing:
-```bash
-gsc speed https://example.com
-```
-
-### High-Throughput Mode (Optional Free API Key)
-If you run high-frequency batch audits in CI/CD pipelines (up to 25,000 queries/day free):
-1. In Google Cloud Console, enable **PageSpeed Insights API**.
-2. Go to **APIs & Services > Credentials** > **Create Credentials** > **API Key**.
-3. Save the key:
-```bash
-gsc config set pagespeed_api_key AIzaSyYourKeyHere
-
-# Or pass as environment variable
-export PAGESPEED_API_KEY=AIzaSyYourKeyHere
-```
+### Understanding Lab vs. Field (CrUX) Data:
+* **🔬 Lighthouse Lab Data (Synthetic Simulation):** Evaluated instantaneously in a headless Chrome environment under fixed 4G mobile or desktop throttling. Ideal for immediate debugging and identifying optimization opportunities (LCP, FCP, CLS, TBT, Speed Index).
+* **🌐 CrUX Field Data (28-Day Real User Monitoring):** Aggregated 75th percentile measurements collected from real Google Chrome users over a rolling 28-day window. This is the **actual telemetry Google Search uses for Core Web Vitals ranking signals** (LCP, INP, CLS, FCP, TTFB).
+* **Traffic Thresholds:** For new or low-traffic pages, Google does not have enough real-user Chrome sessions to publish CrUX data. In those cases, `gsc speed` automatically displays the instantaneous Lighthouse Lab audit and flags that CrUX field data is pending sufficient 28-day visitor volume.
+
+> 💡 **Why an API Key is Recommended:**  
+> While Google technically permits unauthenticated queries, Google's public unauthenticated IP pool frequently hits `429 Quota Exceeded (RESOURCE_EXHAUSTED)`. Generating a personal API key in Google Cloud gives you **25,000 queries per day at $0 cost**.
+
+### 1-Minute API Key Setup
+
+1. **Enable the API:**
+   * Open [Google Cloud Console: PageSpeed Insights API](https://console.cloud.google.com/apis/library/pagespeedonline.googleapis.com).
+   * Ensure your active project is selected in the top bar.
+   * Click **Enable** (if not already enabled, Google will return a `403 SERVICE_DISABLED` error).
+
+2. **Create the API Key:**
+   * In the left sidebar, navigate to **APIs & Services > Credentials**.
+   * Click **+ Create Credentials** at the top → select **API Key**.
+   * In the side panel:
+     * **Name:** `gsc-pagespeed-key` (or default `API key 1`).
+     * **Application restrictions:** Keep **None** (since `gsc` is a local command-line tool).
+     * **API restrictions:** (Optional) Select **Restrict key** → check **PageSpeed Insights API**.
+     * Click the blue **Create** button.
+   * Copy the generated key (`AIzaSy...`).
+
+3. **Save Your Key:**
+   ```bash
+   gsc config set pagespeed_api_key AIzaSyYourKeyHere
+
+   # Or pass as environment variable
+   export PAGESPEED_API_KEY=AIzaSyYourKeyHere
+   ```
+
+4. **Run Speed Audits:**
+   ```bash
+   # Mobile Core Web Vitals (Default)
+   gsc speed https://example.com
+
+   # Desktop Core Web Vitals
+   gsc speed https://example.com --strategy desktop
+
+   # Correlate CWV with Google Search Console traffic
+   gsc speed-correlate https://example.com
+   ```
 
 ---
 
@@ -152,9 +179,12 @@ gsc import clip
 
 ### Option B: Direct API Integration
 If you prefer automated terminal lookups without using the browser extension:
-1. Get an API key from [Keywords Everywhere](https://keywordseverywhere.com/) ($1.25 one-time for 100,000 credits).
+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).
 2. Save your key:
 ```bash
+gsc connect ke <YOUR_API_KEY>
+
+# Or manually:
 gsc config set keywords_everywhere_api_key your_ke_api_key_here
 
 # Or pass as environment variable