indxel-cli 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@
 ## Install
 
 ```bash
-npm install -D indxel-cli
+npm install -g indxel-cli
 ```
 
 Or run directly:
@@ -27,11 +27,18 @@ npx indxel-cli check
 # Initialize config and boilerplate files
 npx indxel-cli init
 
-# Audit all pages
+# Audit all pages (static analysis)
 npx indxel-cli check
-```
 
-The CLI scans your Next.js App Router pages, extracts metadata, and validates it against 15 SEO rules using the [`indxel`](https://www.npmjs.com/package/indxel) SDK.
+# Crawl a live site
+npx indxel-cli crawl https://yoursite.com
+
+# Research keywords
+npx indxel-cli keywords "nextjs seo"
+
+# Check indexation status
+npx indxel-cli index https://yoursite.com
+```
 
 ---
 
@@ -43,35 +50,39 @@ Scaffold SEO boilerplate in your Next.js project.
 
 ```bash
 npx indxel-cli init
+npx indxel-cli init --hook   # + install git pre-push guard
 ```
 
 Creates:
 - `seo.config.ts` -- Global SEO configuration using `defineSEO()`
 - `app/sitemap.ts` -- Next.js dynamic sitemap
 - `app/robots.ts` -- Next.js robots configuration
+- `.git/hooks/pre-push` -- (with `--hook`) SEO guard that blocks pushes on critical errors
 
 Options:
 - `--cwd <path>` -- Project directory (default: current directory)
 - `--force` -- Overwrite existing files
+- `--hook` -- Install git pre-push hook
 
 ```
-$ npx indxel-cli init
+$ npx indxel-cli init --hook
 
   ✓ Detected Next.js 15 (App Router)
   ✓ Generated seo.config.ts
   ✓ Generated src/app/sitemap.ts
   ✓ Generated src/app/robots.ts
+  ✓ Installed git pre-push hook
 
-  3 files created.
-
-  Next steps:
-    1. Edit seo.config.ts with your site details
-    2. Run npx indxel check to audit your pages
+  4 files created.
 ```
 
+The pre-push hook runs `npx indxel-cli check --ci` before every `git push`. If critical SEO errors are found, the push is blocked.
+
+---
+
 ### `indxel check`
 
-Audit SEO metadata for all pages in your project.
+Audit SEO metadata for all pages in your project (static analysis of source code).
 
 ```bash
 npx indxel-cli check
@@ -94,16 +105,13 @@ $ npx indxel-cli check
   ✓ /                 92/100
   ✓ /pricing          88/100
   ✓ /blog             85/100
-  x /blog/my-post     62/100
-    x Missing og:image — social shares will look broken
-    ! Title is 42 characters — slightly short (aim for 50-60)
+  ✗ /blog/my-post     62/100
+    ✗ Missing og:image -- social shares will look broken
+    ⚠ Title is 42 characters -- slightly short (aim for 50-60)
   ✓ /about            90/100
 
-  ─────────────────────────────────────
-
   Score: 83/100 (B)
   Pages: 4/5 pass SEO validation
-
   1 critical issue. Fix before deploying.
 ```
 
@@ -114,8 +122,6 @@ Track SEO score changes between runs. Results are stored in `.indxel/last-check.
 ```
 $ npx indxel-cli check --diff
 
-  ...
-
   SEO Diff:
 
   Score: 78 -> 83 (+5)
@@ -126,42 +132,9 @@ $ npx indxel-cli check --diff
 
   REGRESSIONS (1):
     - /blog/my-post  70 -> 62
-
-  NEW PAGES (1):
-    + /changelog  [new]
-```
-
-### `indxel check --ci`
-
-Strict mode for CI/CD pipelines. Warnings become errors. Exits with code 1 if any page has critical issues.
-
-```bash
-npx indxel-cli check --ci
 ```
 
-### `indxel check --json`
-
-Machine-readable output for custom tooling.
-
-```json
-{
-  "score": 83,
-  "grade": "B",
-  "totalPages": 5,
-  "passedPages": 4,
-  "criticalErrors": 1,
-  "pages": [
-    {
-      "route": "/",
-      "file": "src/app/page.tsx",
-      "score": 92,
-      "grade": "A",
-      "errors": [],
-      "warnings": [{ "id": "twitter-card", "message": "..." }]
-    }
-  ]
-}
-```
+---
 
 ### `indxel crawl <url>`
 
@@ -187,43 +160,28 @@ Options:
 ```
 $ npx indxel-cli crawl https://mysite.com --push
 
-  indxel crawl — https://mysite.com
+  indxel crawl -- https://mysite.com
 
   ✓ robots.txt found
   ✓ Crawled 47 pages in 12.3s
-
-  ✓ https://mysite.com                      95/100
-  ✓ https://mysite.com/pricing              88/100
-  ✗ https://mysite.com/blog/new-post        62/100
-    ✗ Missing meta description
-    ⚠ Title is 42 characters — slightly short
-
-  ✓ sitemap.xml found — 52 URLs
+  ✓ sitemap.xml found -- 52 URLs
   ✓ Verified 94 assets
 
   - Duplicate titles
     ✗ "My Site" (3 pages)
-  - Structured data (JSON-LD)
-    ✓ Organization — 47 pages
-    ✓ Article — 12 pages
-
-  ─── Summary ───
 
   Pages crawled:  47
   Average score:  86/100 (B)
   Errors:         3
   Warnings:       8
 
-  ✓ Pushed to dashboard — check clxyz123
+  ✓ Pushed to dashboard -- check clxyz123
 ```
 
 #### Push to Dashboard
 
 The `--push` flag sends results to the [Indxel dashboard](https://indxel.com/dashboard) where you can track score evolution between crawls.
 
-1. Get your API key from **Dashboard > Settings**
-2. Run:
-
 ```bash
 # Using --api-key flag
 npx indxel-cli crawl https://yoursite.com --push --api-key ix_your_key
@@ -233,6 +191,111 @@ export INDXEL_API_KEY=ix_your_key
 npx indxel-cli crawl https://yoursite.com --push
 ```
 
+Get your API key from **Dashboard > Settings > API Keys**.
+
+---
+
+### `indxel keywords <seed>`
+
+Research keyword opportunities using Google Autocomplete. No API key required.
+
+```bash
+npx indxel-cli keywords "nextjs seo"
+npx indxel-cli keywords "nextjs seo" --site mysite.com   # + content gap analysis
+```
+
+Options:
+- `--locale <locale>` -- Language locale (default: en)
+- `--country <country>` -- Country code (default: us)
+- `--site <url>` -- Site URL to analyze content gaps against
+- `--max-pages <n>` -- Max pages to crawl for gap analysis (default: 30)
+- `--json` -- Output as JSON
+
+```
+$ npx indxel-cli keywords "nextjs seo"
+
+  indxel keywords -- "nextjs seo"
+
+  ✓ Found 156 keywords
+
+  Direct suggestions (8)
+    nextjs seo best practices
+    nextjs seo metadata
+    nextjs seo optimization
+    ...
+
+  Questions (24)
+    ? how to improve seo in nextjs
+    ? what is nextjs metadata
+    ...
+
+  Long-tail (124)
+    nextjs seo plugin
+    nextjs seo analyzer
+    ...
+```
+
+With `--site`, it crawls your site and identifies which keywords you already cover and which ones are content gaps:
+
+```
+$ npx indxel-cli keywords "nextjs seo" --site mysite.com
+
+  ✓ Found 156 keywords
+  ✓ Crawled 28 pages
+
+  Content coverage: 42/156 keywords (27%)
+
+  High priority gaps (18)
+    ✗ "nextjs seo best practices" -> guide at /blog/nextjs-seo-best-practices
+    ✗ "nextjs metadata tutorial" -> guide at /blog/nextjs-metadata-tutorial
+
+  Medium priority gaps (34)
+    ⚠ "nextjs seo vs gatsby" -> comparison at /compare/nextjs-seo-vs-gatsby
+```
+
+---
+
+### `indxel index <url>`
+
+Check indexation readiness and submit pages to search engines.
+
+```bash
+npx indxel-cli index https://yoursite.com                     # free diagnostic
+npx indxel-cli index https://yoursite.com --check             # check indexation (Pro)
+npx indxel-cli index https://yoursite.com --indexnow-key KEY  # submit IndexNow (Pro)
+```
+
+Options:
+- `--check` -- Check which pages are indexed in Google cache (requires Pro plan + API key)
+- `--indexnow-key <key>` -- Submit URLs via IndexNow to Bing/Yandex/DuckDuckGo (requires Pro plan + API key)
+- `--api-key <key>` -- Indxel API key (required for `--check` and `--indexnow-key`)
+- `--json` -- Output as JSON
+
+The free diagnostic checks your sitemap and robots.txt, then provides setup instructions for Google Search Console and IndexNow.
+
+```
+$ npx indxel-cli index mysite.com
+
+  indxel index -- https://mysite.com
+
+  ✓ Found sitemap -- 52 URLs
+  ✓ robots.txt references sitemap
+
+  IndexNow (Bing, Yandex, DuckDuckGo)
+    1. Generate a key at https://www.bing.com/indexnow
+    2. Host the key file at https://mysite.com/{key}.txt
+    3. Run: npx indxel index mysite.com --indexnow-key YOUR_KEY
+
+  Google Search Console
+    1. Go to https://search.google.com/search-console
+    2. Add & verify mysite.com
+    3. Submit your sitemap: Sitemaps > Add > sitemap.xml
+
+  Sitemap:     52 URLs
+  robots.txt:  ✓ references sitemap
+  IndexNow:    not configured (use --indexnow-key)
+```
+
 ---
 
 ## CI/CD Integration
@@ -257,8 +320,6 @@ jobs:
 
 ### Vercel (build command)
 
-Add to your `package.json`:
-
 ```json
 {
   "scripts": {
@@ -267,20 +328,28 @@ Add to your `package.json`:
 }
 ```
 
-If any page has a critical SEO error, the build fails. Broken SEO never reaches production.
+### Git pre-push hook
+
+```bash
+npx indxel-cli init --hook
+```
+
+Blocks `git push` if critical SEO errors are found. No CI setup required.
 
 ---
 
 ## Requirements
 
 - Node.js >= 18
-- Next.js App Router project (`app/` or `src/app/` directory)
+- Next.js App Router project (`app/` or `src/app/` directory) for `check` and `init`
+- Any website for `crawl`, `index`, and `keywords`
 
 ---
 
 ## Related
 
-- [`indxel`](https://www.npmjs.com/package/indxel) -- The SDK. Define metadata, generate JSON-LD, validate.
+- [`indxel`](https://www.npmjs.com/package/indxel) -- The SDK. Define metadata, generate JSON-LD, validate, crawl.
+- [indxel.com](https://indxel.com) -- Dashboard for monitoring SEO over time.
 
 ---