indxel-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Indxel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# indxel-cli
+
+> 30 seconds. Zero config. Your SEO score, in the terminal.
+
+[![npm version](https://img.shields.io/npm/v/indxel-cli)](https://www.npmjs.com/package/indxel-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+npm install -D indxel-cli
+```
+
+Or run directly:
+
+```bash
+npx indxel-cli check
+```
+
+---
+
+## Quick Start
+
+```bash
+# Initialize config and boilerplate files
+npx indxel-cli init
+
+# Audit all pages
+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.
+
+---
+
+## Commands
+
+### `indxel init`
+
+Scaffold SEO boilerplate in your Next.js project.
+
+```bash
+npx indxel-cli init
+```
+
+Creates:
+- `seo.config.ts` -- Global SEO configuration using `defineSEO()`
+- `app/sitemap.ts` -- Next.js dynamic sitemap
+- `app/robots.ts` -- Next.js robots configuration
+
+Options:
+- `--cwd <path>` -- Project directory (default: current directory)
+- `--force` -- Overwrite existing files
+
+```
+$ npx indxel-cli init
+
+  ✓ Detected Next.js 15 (App Router)
+  ✓ Generated seo.config.ts
+  ✓ Generated src/app/sitemap.ts
+  ✓ Generated src/app/robots.ts
+
+  3 files created.
+
+  Next steps:
+    1. Edit seo.config.ts with your site details
+    2. Run npx indxel check to audit your pages
+```
+
+### `indxel check`
+
+Audit SEO metadata for all pages in your project.
+
+```bash
+npx indxel-cli check
+```
+
+Options:
+- `--ci` -- CI/CD mode: strict validation, exits with code 1 on any error
+- `--diff` -- Compare results with previous check run
+- `--json` -- Output results as JSON (for tooling integration)
+- `--strict` -- Treat warnings as errors
+- `--cwd <path>` -- Project directory
+
+```
+$ npx indxel-cli check
+
+  Found 5 pages
+
+  Checking 5 pages...
+
+  ✓ /                 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)
+  ✓ /about            90/100
+
+  ─────────────────────────────────────
+
+  Score: 83/100 (B)
+  Pages: 4/5 pass SEO validation
+
+  1 critical issue. Fix before deploying.
+```
+
+### `indxel check --diff`
+
+Track SEO score changes between runs. Results are stored in `.indxel/last-check.json`.
+
+```
+$ npx indxel-cli check --diff
+
+  ...
+
+  SEO Diff:
+
+  Score: 78 -> 83 (+5)
+
+  IMPROVEMENTS (2):
+    + /pricing  82 -> 88
+    + /about    85 -> 90
+
+  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>`
+
+Crawl a live website, audit every page, check sitemap, robots.txt, and assets. Cross-page analysis included.
+
+```bash
+npx indxel-cli crawl https://yoursite.com
+```
+
+Options:
+- `--max-pages <n>` -- Maximum pages to crawl (default: 50)
+- `--max-depth <n>` -- Maximum link depth (default: 5)
+- `--delay <ms>` -- Delay between requests (default: 200ms)
+- `--push` -- Push results to the Indxel dashboard
+- `--api-key <key>` -- API key for `--push` (or set `INDXEL_API_KEY`)
+- `--ignore <patterns>` -- Comma-separated path patterns to exclude (e.g. `/app/*,/admin/*`)
+- `--strict` -- Treat warnings as errors
+- `--json` -- Output results as JSON
+- `--skip-assets` -- Skip asset verification
+- `--skip-sitemap` -- Skip sitemap check
+- `--skip-robots` -- Skip robots.txt check
+
+```
+$ npx indxel-cli crawl https://mysite.com --push
+
+  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
+  ✓ 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
+```
+
+#### 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
+
+# Or using environment variable
+export INDXEL_API_KEY=ix_your_key
+npx indxel-cli crawl https://yoursite.com --push
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: SEO Check
+on: [push, pull_request]
+
+jobs:
+  seo:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx indxel-cli check --ci
+```
+
+### Vercel (build command)
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "npx indxel-cli check --ci && next build"
+  }
+}
+```
+
+If any page has a critical SEO error, the build fails. Broken SEO never reaches production.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Next.js App Router project (`app/` or `src/app/` directory)
+
+---
+
+## Related
+
+- [`indxel`](https://www.npmjs.com/package/indxel) -- The SDK. Define metadata, generate JSON-LD, validate.
+
+---
+
+## License
+
+[MIT](./LICENSE)