sublyzer-snapshot 0.3.0 → 0.4.0

package/README.md

@@ -2,35 +2,33 @@
 
 # Sublyzer Snapshot
 
-<img src="./Sublyzer1.png" alt="Sublyzer" width="96" />
+<img src="./Sublyzer1.png" alt="Sublyzer Snapshot" width="96" />
 
-**Turn any codebase into a live Sublyzer dashboard in 30 seconds.**
+**Local project health scanner for any Node.js codebase.**
 
-Scan routes, dependencies, and vulnerabilities locally — get a health score — push everything to [Sublyzer](https://sublyzer.com). No SDK required for your first check.
+Works **standalone** — no account required. Optionally sync to [Sublyzer](https://sublyzer.com) cloud when you want a live dashboard.
 
 <br />
 
-[![npm version](https://img.shields.io/badge/npm-v0.3.0-2563eb?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/sublyzer-snapshot)
+[![npm version](https://img.shields.io/npm/v/sublyzer-snapshot?style=for-the-badge&logo=npm&logoColor=white&label=npm)](https://www.npmjs.com/package/sublyzer-snapshot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![Sublyzer](https://img.shields.io/badge/Powered%20by-Sublyzer-6366f1?style=for-the-badge)](https://sublyzer.com)
 
 <br />
 
-[`Quick Start`](#-quick-start) · [`How It Works`](#-how-it-works) · [`Commands`](#-commands) · [`CI/CD`](#-cicd) · [`Docs`](#-environment-variables) · [Sublyzer Dashboard](https://sublyzer.com/dashboard)
+[`Quick Start`](#-quick-start) · [`Standalone vs Cloud`](#-standalone-vs-cloud) · [`Monorepos`](#-monorepos) · [`Commands`](#-commands) · [`Roadmap`](#-roadmap)
 
 <br />
 
 ```
-  $ npx sublyzer-snapshot init && npx sublyzer-snapshot run
-
-  Project:         my-saas-app
-  Stack:           Next.js (high)
-  Health:          [████████░░] 82/100  grade B
-  Routes:          14
-  Vulnerabilities: 2 (critical 0, high 1)
-  ✓ Sent 6 events → dashboard updated
+  $ npx sublyzer-snapshot scan
+
+  Scan root:     frontend (auto-selected)
+  Stack:         Next.js (high)
+  Health:        [████████░░] 84/100  grade B
+  Routes:        42
+  Build output:  12.4 MB (.next)
+  ✓ Saved to .sublyzer/ (local)
 ```
 
 </div>
@@ -39,268 +37,191 @@ Scan routes, dependencies, and vulnerabilities locally — get a health score
 
 ## ✨ Introduction
 
-**Sublyzer Snapshot** is an open-source CLI that answers one question every developer asks:
+**Sublyzer Snapshot** is an open-source CLI that scans your repo and answers:
 
-> *"How healthy is my project right now?"*
+> *How healthy is this project right now?*
 
-Instead of wiring up three separate tools (dependency scanner, route inventory, monitoring dashboard), you run **one command**. Snapshot scans your repo locally, computes a **health score (0–100)**, and pushes structured events to your **Sublyzer** integration — where you (or an AI agent like Hermes) can read them back.
+It runs **entirely on your machine**: stack detection, routes, dependency audit, outdated packages, build size, git metadata, and a **0–100 health score**.
 
-Built for **indie hackers**, **startup teams**, and **agencies** who want instant project visibility without a week of DevOps setup.
+**Sublyzer cloud is optional** — use it when you want events in a shared dashboard, agents (Hermes), or team visibility. Without cloud, you still get reports, history, CI gates, and compare diffs.
 
 ---
 
-## 🎯 What is it for?
+## 🔀 Standalone vs Cloud
 
-| Use case | What you get |
-|----------|--------------|
-| **First-time project check** | Stack detection, route map, CVE summary in ~30s |
-| **Pre-deploy sanity check** | Health score + vulnerability gate before shipping |
-| **CI/CD pipeline** | `--fail-on high` blocks merges with critical CVEs |
-| **Client / team reports** | `report --out HEALTH.md` — shareable Markdown |
-| **Trend tracking** | `compare` shows what changed since last scan |
-| **Sublyzer onboarding** | Data in your dashboard before installing the browser SDK |
+| | **Standalone (default)** | **Cloud (optional)** |
+|---|--------------------------|----------------------|
+| Account | None | [Sublyzer](https://sublyzer.com) integration code |
+| Command | `npx sublyzer-snapshot scan` | `init --code …` then `run --push` |
+| Output | Terminal + `.sublyzer/` history | + Sublyzer dashboard |
+| CI | `scan --fail-on high` | + optional push via secret |
 
-### Before vs After
-
-| Before | After (Sublyzer Snapshot) |
-|--------|---------------------------|
-| Sentry + Dependabot + manual spreadsheet | One CLI, one dashboard |
-| 45+ min setup | ~30 seconds |
-| No unified health score | 0–100 score with grade A–F |
-| Hard to show clients "project status" | Export `report.md` in one command |
-
----
+```bash
+# Standalone — zero setup
+npx sublyzer-snapshot scan
 
-## ⚙️ How it works
-
-```mermaid
-flowchart LR
-  A[Your repo] --> B[sublyzer-snapshot run]
-  B --> C[Local scan]
-  C --> D[Routes · deps · audit · git]
-  D --> E[Health score 0-100]
-  E --> F[Sublyzer API]
-  F --> G[Dashboard]
-  G --> H[Hermes / agents / team]
-
-  style A fill:#1e293b,stroke:#475569,color:#f8fafc
-  style G fill:#2563eb,stroke:#1d4ed8,color:#fff
-  style E fill:#22c55e,stroke:#16a34a,color:#fff
+# Optional cloud link
+npx sublyzer-snapshot init --code YOUR_24_CHAR_CODE -y
+npx sublyzer-snapshot run --push
 ```
 
-1. **`init`** — Links your project folder to a Sublyzer integration (24-char code).
-2. **`run`** — Scans locally: framework, routes, `npm audit`, outdated packages, git metadata.
-3. **Score** — Computes health grade from vulnerabilities, routes, env hygiene, and more.
-4. **Push** — Sends events to `POST /data-collection/collect-batch` on Sublyzer.
-5. **Dashboard** — Data appears under your integration; optional SDK for live telemetry later.
-
-Scan history is stored in `.sublyzer/` (gitignored automatically) so `compare` can show diffs over time.
-
 ---
 
 ## 🚀 Quick start
 
-### Prerequisites
-
-- **Node.js 18+**
-- **npm** (for audit/outdated; optional with `--skip-audit`)
-- A [Sublyzer](https://sublyzer.com) account + **integration code** (24 chars, from Dashboard → Integrations)
-
-### Install & run
+### Install (use npx — recommended)
 
 ```bash
-# 1. Link your project
-npx sublyzer-snapshot init
-
-# 2. Scan and push
-npx sublyzer-snapshot run
-
-# 3. Open dashboard
-npx sublyzer-snapshot open
+npx sublyzer-snapshot@latest --version
 ```
 
-Non-interactive (CI / scripts):
+Do **not** run `npm i sublyzer-snapshot` in random folders — use `npx` to avoid unrelated peer dependency conflicts.
+
+### Scan any project
 
 ```bash
-export SUBLYZER_INTEGRATION_CODE="YOUR_24_CHAR_CODE"
-npx sublyzer-snapshot init -y
-npx sublyzer-snapshot run --fail-on high
+cd your-project
+npx sublyzer-snapshot scan
+npx sublyzer-snapshot report --out HEALTH.md
+npx sublyzer-snapshot compare
 ```
 
-### Development (this monorepo)
+### Save preferences (local)
 
 ```bash
-cd projects/sublyzer-snapshot
-npm install && npm run build
-node dist/cli.js init --code YOUR_CODE -y
-node dist/cli.js run --dry-run
+npx sublyzer-snapshot init --local
+npx sublyzer-snapshot run
 ```
 
----
-
-## 🧰 Commands
-
-| Command | Description |
-|---------|-------------|
-| `init` | Detect stack, validate code, write `.sublyzer/snapshot.json` |
-| `run` | Full scan + push to Sublyzer |
-| `report` | Generate Markdown health report (`--out report.md`) |
-| `compare` | Diff routes, vulns, and score vs previous scan |
-| `ci` | Print or write GitHub Actions workflow |
-| `status` | Show linked integration + last scan |
-| `doctor` | Verify config, API, integration code, read key |
-| `pull` | Fetch data back via public read API (needs `apiReadKey`) |
-| `open` | Open integration in browser |
-
-### Common flags
+### Optional cloud sync
 
 ```bash
-sublyzer-snapshot run --dry-run          # Local preview, no push
-sublyzer-snapshot run --skip-audit       # Faster scan
-sublyzer-snapshot run --fail-on high     # Exit 1 on high/critical CVEs
-sublyzer-snapshot run --json             # CI-friendly JSON output
-
-sublyzer-snapshot report --out HEALTH.md
-sublyzer-snapshot compare --rescan
-sublyzer-snapshot ci --out .github/workflows/sublyzer-snapshot.yml
+npx sublyzer-snapshot init --code YOUR_24_CHAR_CODE -y
+npx sublyzer-snapshot run --push
+npx sublyzer-snapshot open
 ```
 
 ---
 
-## 📊 Health score
+## 📦 Monorepos
 
-Every scan produces a **0–100 score** and letter grade (**A–F**):
+Snapshot **auto-picks** the best package in monorepos (npm/pnpm workspaces, `frontend/`, `backend/`, etc.).
 
-| Factor | Impact |
-|--------|--------|
-| Critical CVEs | −25 each (max −50) |
-| High CVEs | −10 each (max −30) |
-| Moderate CVEs | −3 each |
-| Web stack with 0 routes detected | −8 |
-| Dirty git working tree | −3 |
-| Missing `.env.example` | −2 |
-| Major outdated packages | −3 each |
-
-Example terminal output:
+```bash
+# From repo root — auto-selects e.g. frontend/
+npx sublyzer-snapshot scan
 
-```
-  Health:        [████████░░] 82/100  grade B
+# Force a subfolder
+npx sublyzer-snapshot scan --path backend
+npx sublyzer-snapshot init --local --path frontend
 ```
 
-The score is also sent to Sublyzer as a `snapshot_health_score` performance metric.
+On `init`, other scannable packages in the repo are listed as hints.
 
 ---
 
-## 🔍 What gets detected
-
-| Stack | Signals |
-|-------|---------|
-| **Next.js** | `next` in package.json, `app/` & `pages/` routes |
-| **NestJS** | `@nestjs/core`, decorator routes |
-| **Express / Fastify** | Route patterns in source |
-| **Remix / Nuxt / SvelteKit** | package.json dependencies |
-| **React / Vue / Node** | Fallback detection |
-| **Monorepos** | npm & pnpm workspaces |
-
-Each `run` sends:
-
-- `custom_event` → `project_snapshot` (stack, routes, git, audit summary)
-- `vulnerability` → top npm audit findings
-- `performance` → health score + route count
-
----
-
-## 🔄 CI/CD
+## 🧰 Commands
 
-### Fail the build on vulnerabilities
+| Command | Description |
+|---------|-------------|
+| **`scan`** | Local scan — **no init, no account** |
+| `init` | Save config — `--local` or `--code` for cloud |
+| `run` | Scan + history (pushes in cloud mode or with `--push`) |
+| `report` | Markdown report (`--out file.md`) |
+| `compare` | Diff vs previous scan |
+| `doctor` | Verify Node, scan target, optional cloud |
+| `status` | Config + last scan |
+| `ci` | GitHub Actions template |
+| `pull` / `open` | Cloud only (read API / dashboard) |
+
+### Flags
 
 ```bash
-sublyzer-snapshot run --fail-on high --json > snapshot-result.json
+npx sublyzer-snapshot scan --path frontend
+npx sublyzer-snapshot scan --fail-on high --json
+npx sublyzer-snapshot run --local              # never push
+npx sublyzer-snapshot run --push               # force cloud push
+npx sublyzer-snapshot run --skip-audit         # faster
 ```
 
-Levels: `critical` · `high` · `moderate` · `any`
+---
 
-### Generate GitHub Actions workflow
+## 📊 What gets scanned
 
-```bash
-sublyzer-snapshot ci --out .github/workflows/sublyzer-snapshot.yml
-```
+- **Stack** — Next.js, NestJS, Express, Fastify, Remix, Nuxt, SvelteKit, React, Vue
+- **Routes** — `app/` / `pages/` or source patterns
+- **Dependencies** + `npm audit` + outdated packages
+- **Build size** — `dist/`, `.next/`, `build/` folders
+- **Git** — branch, commit, dirty state
+- **Health score** — 0–100, grade A–F
 
-Add repository secret: **`SUBLYZER_INTEGRATION_CODE`**
+---
 
-The generated workflow runs on push, PR, and weekly schedule — uploads JSON + Markdown report as artifacts.
+## 🔄 CI/CD
 
----
+Local-only CI (no secrets):
 
-## 🤖 Read data back (agents & API)
+```yaml
+- run: npx sublyzer-snapshot@latest scan --fail-on high --json
+```
 
-Push uses the **integration code**. To **read** snapshot data programmatically (e.g. Hermes):
+Generate full workflow:
 
 ```bash
-# Get read key (authenticated)
-curl "https://api.sublyzer.com/integrations/{id}/read-access" \
-  -H "Authorization: Bearer YOUR_JWT"
-
-# Or via CLI
-sublyzer-snapshot pull --read-key YOUR_READ_KEY
+npx sublyzer-snapshot ci --out .github/workflows/sublyzer-snapshot.yml
 ```
 
-Set `SUBLYZER_READ_KEY` in env or save during `init --read-key ...`.
+Optional cloud push when `SUBLYZER_INTEGRATION_CODE` secret is set.
 
 ---
 
 ## 🔐 Environment variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `SUBLYZER_INTEGRATION_CODE` | For `init` | 24-character integration code |
-| `SUBLYZER_READ_KEY` | For `pull` | Public read API key |
-| `SUBLYZER_API_URL` | No | Default: `https://api.sublyzer.com` |
-| `SUBLYZER_DASHBOARD_URL` | No | Default: `https://sublyzer.com` |
-
-> **Security:** `.sublyzer/snapshot.json` contains your integration code. It is auto-added to `.gitignore` on `init` — never commit it to public repos.
+| Variable | When |
+|----------|------|
+| `SUBLYZER_INTEGRATION_CODE` | Cloud `init` |
+| `SUBLYZER_READ_KEY` | Cloud `pull` |
+| `SUBLYZER_API_URL` | Custom API (default: `https://api.sublyzer.com`) |
 
 ---
 
-## 📁 Project structure (local)
+## 📁 Local data
 
 ```
 your-project/
-├── .sublyzer/
-│   ├── snapshot.json       # Linked integration config
-│   ├── last-snapshot.json  # Latest scan cache
-│   └── history/            # Previous scans (for compare)
-├── src/
-└── package.json
+└── .sublyzer/           # gitignored on init
+    ├── snapshot.json    # config (local or cloud)
+    ├── last-snapshot.json
+    └── history/         # for compare
 ```
 
 ---
 
 ## 🛣️ Roadmap
 
-- [ ] npm publish (`npx sublyzer-snapshot`)
-- [ ] `login` flow (no manual code paste)
-- [ ] Bundle size analysis
-- [ ] PR comment bot (GitHub App)
+- [x] npm publish — [sublyzer-snapshot](https://www.npmjs.com/package/sublyzer-snapshot)
+- [x] Standalone `scan` (no account)
+- [x] Local vs cloud modes
+- [x] Monorepo auto-target (`frontend/`, workspaces)
+- [x] Build output size scan
+- [x] Health score + compare + report + CI template
+- [ ] `login` OAuth (no manual code paste)
+- [ ] SARIF export for GitHub Security
+- [ ] PR comment bot
+- [ ] Python / Go stack detection
 
 ---
 
 ## 📄 License
 
-MIT © [Sublyzer](https://sublyzer.com) — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](./LICENSE).
 
 ---
 
 <div align="center">
 
-**[Sublyzer](https://sublyzer.com)** · **[Documentation](https://sublyzer.com/docs)** · **[Dashboard](https://sublyzer.com/dashboard)**
-
-<br />
-
-If this saved you time, ⭐ star the repo — it helps other devs find it.
-
-<br />
+**[npm](https://www.npmjs.com/package/sublyzer-snapshot)** · **[Sublyzer Cloud](https://sublyzer.com)** · **[Docs](https://sublyzer.com/docs)**
 
-<sub>Built with TypeScript · Powered by <a href="https://sublyzer.com">Sublyzer</a> observability platform</sub>
+<sub>Standalone by default · Cloud when you need it</sub>
 
 </div>

package/dist/cli.js

@@ -8,7 +8,8 @@ import { runInit } from './commands/init.js';
 import { runOpen } from './commands/open.js';
 import { runPull } from './commands/pull.js';
 import { runReport } from './commands/report.js';
-import { runScan } from './commands/run.js';
+import { runRunCommand } from './commands/run.js';
+import { runScanCommand } from './commands/scan.js';
 import { runStatus } from './commands/status.js';
 const program = new Command();
 function handleError(e) {
@@ -17,24 +18,62 @@ function handleError(e) {
     process.exit(1);
 }
 const FAIL_ON_LEVELS = ['critical', 'high', 'moderate', 'any'];
+function sharedScanOptions(cmd) {
+    return cmd
+        .option('--path <dir>', 'Scan a subfolder (e.g. frontend, backend)')
+        .option('--skip-audit', 'Skip npm audit')
+        .option('--skip-outdated', 'Skip npm outdated check')
+        .option('--skip-bundle', 'Skip build output size scan')
+        .option('--json', 'JSON output')
+        .option('--fail-on <level>', 'Exit 1 on vulns: critical|high|moderate|any');
+}
 program
     .name('sublyzer-snapshot')
-    .description('Scan any project and push a health snapshot to Sublyzer')
+    .description('Local project health scanner — optional Sublyzer cloud sync')
     .version(SDK_VERSION);
+sharedScanOptions(program
+    .command('scan')
+    .description('Scan project locally (no account, no init required)')
+    .option('--push', 'Push to Sublyzer if cloud config exists'))
+    .action(async (opts) => {
+    try {
+        const failOn = FAIL_ON_LEVELS.includes(opts.failOn) ? opts.failOn : undefined;
+        const result = await runScanCommand({
+            path: opts.path,
+            push: opts.push,
+            skipAudit: opts.skipAudit,
+            skipOutdated: opts.skipOutdated,
+            skipBundle: opts.skipBundle,
+            json: opts.json,
+            failOn,
+        });
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        if (result.policyFailed)
+            process.exit(1);
+    }
+    catch (e) {
+        handleError(e);
+    }
+});
 program
     .command('init')
-    .description('Detect stack and link this project to your Sublyzer integration')
-    .option('--code <code>', 'Integration code (24 chars); or SUBLYZER_INTEGRATION_CODE')
-    .option('--read-key <key>', 'Optional apiReadKey for pull; or SUBLYZER_READ_KEY')
-    .option('--api-url <url>', 'Sublyzer API base URL')
-    .option('--dashboard-url <url>', 'Dashboard base URL')
-    .option('-y, --yes', 'Non-interactive when code is provided')
+    .description('Save scan preferences — local-only or link Sublyzer cloud')
+    .option('--local', 'Local mode only (no Sublyzer account)')
+    .option('--code <code>', 'Cloud: integration code (24 chars)')
+    .option('--read-key <key>', 'Cloud: apiReadKey for pull')
+    .option('--path <dir>', 'Preferred scan directory in monorepos')
+    .option('--api-url <url>', 'Sublyzer API URL')
+    .option('--dashboard-url <url>', 'Dashboard URL')
+    .option('-y, --yes', 'Non-interactive')
     .option('--skip-gitignore', 'Do not update .gitignore')
     .action(async (opts) => {
     try {
         await runInit({
+            local: opts.local,
             code: opts.code,
             readKey: opts.readKey,
+            path: opts.path,
             apiUrl: opts.apiUrl,
             dashboardUrl: opts.dashboardUrl,
             yes: opts.yes,
@@ -45,21 +84,23 @@ program
         handleError(e);
     }
 });
-program
+sharedScanOptions(program
     .command('run')
-    .description('Scan routes, dependencies, vulnerabilities and push to Sublyzer')
-    .option('--dry-run', 'Scan locally without sending data')
-    .option('--skip-audit', 'Skip npm audit (faster)')
-    .option('--skip-outdated', 'Skip npm outdated check')
-    .option('--json', 'Output machine-readable JSON (CI friendly)')
-    .option('--fail-on <level>', 'Exit 1 if vulns at level: critical|high|moderate|any')
+    .description('Scan + save history (pushes only in cloud mode or with --push)')
+    .option('--dry-run', 'Scan without saving push')
+    .option('--push', 'Force push to Sublyzer cloud')
+    .option('--local', 'Force local-only (no push)'))
     .action(async (opts) => {
     try {
         const failOn = FAIL_ON_LEVELS.includes(opts.failOn) ? opts.failOn : undefined;
-        const result = await runScan({
+        const result = await runRunCommand({
+            path: opts.path,
             dryRun: opts.dryRun,
+            push: opts.push,
+            local: opts.local,
             skipAudit: opts.skipAudit,
             skipOutdated: opts.skipOutdated,
+            skipBundle: opts.skipBundle,
             json: opts.json,
             failOn,
         });
@@ -74,8 +115,8 @@ program
 });
 program
     .command('status')
-    .description('Show linked integration and last scan summary')
-    .option('--json', 'Output machine-readable JSON')
+    .description('Show config and last scan')
+    .option('--json', 'JSON output')
     .action(async (opts) => {
     try {
         const data = await runStatus({ json: opts.json });
@@ -88,8 +129,8 @@ program
 });
 program
     .command('doctor')
-    .description('Verify config, API connectivity, integration code and read key')
-    .option('--json', 'Output machine-readable JSON')
+    .description('Verify Node, scan target, optional cloud link')
+    .option('--json', 'JSON output')
     .action(async (opts) => {
     try {
         const result = await runDoctor({ json: opts.json });
@@ -104,15 +145,17 @@ program
 });
 program
     .command('compare')
-    .description('Diff current vs previous scan (routes, vulns, health score)')
-    .option('--json', 'Output machine-readable JSON')
-    .option('--rescan', 'Run a fresh scan before comparing')
-    .option('--skip-audit', 'Skip audit when using --rescan')
+    .description('Diff vs previous scan')
+    .option('--json', 'JSON output')
+    .option('--rescan', 'Fresh scan before compare')
+    .option('--path <dir>', 'Scan path with --rescan')
+    .option('--skip-audit', 'Skip audit with --rescan')
     .action(async (opts) => {
     try {
         const data = await runCompare({
             json: opts.json,
             rescan: opts.rescan,
+            path: opts.path,
             skipAudit: opts.skipAudit,
         });
         if (opts.json)
@@ -124,16 +167,18 @@ program
 });
 program
     .command('report')
-    .description('Generate a Markdown health report (stdout or --out file)')
-    .option('--out <file>', 'Write report to file (e.g. sublyzer-report.md)')
-    .option('--rescan', 'Run a fresh scan instead of using last cached scan')
-    .option('--skip-audit', 'Skip audit when using --rescan')
-    .option('--json', 'Output JSON wrapper with markdown body')
+    .description('Markdown health report')
+    .option('--out <file>', 'Write to file')
+    .option('--rescan', 'Fresh scan')
+    .option('--path <dir>', 'Scan path with --rescan')
+    .option('--skip-audit', 'Skip audit')
+    .option('--json', 'JSON wrapper')
     .action(async (opts) => {
     try {
         const out = await runReport({
             out: opts.out,
             rescan: opts.rescan,
+            path: opts.path,
             skipAudit: opts.skipAudit,
             json: opts.json,
         });
@@ -146,9 +191,9 @@ program
 });
 program
     .command('ci')
-    .description('Print or write a GitHub Actions workflow for automated snapshots')
-    .option('--out <path>', 'Write workflow file (default: .github/workflows/sublyzer-snapshot.yml)')
-    .option('--print', 'Print template to stdout only')
+    .description('GitHub Actions workflow template')
+    .option('--out <path>', 'Write workflow file')
+    .option('--print', 'Print to stdout')
     .action(async (opts) => {
     try {
         await runCi({ out: opts.out, print: opts.print ?? !opts.out });
@@ -159,12 +204,12 @@ program
 });
 program
     .command('pull')
-    .description('Fetch integration data from Sublyzer (requires apiReadKey)')
-    .option('--read-key <key>', 'apiReadKey; or SUBLYZER_READ_KEY in env/config')
+    .description('Fetch data from Sublyzer cloud (requires apiReadKey)')
+    .option('--read-key <key>', 'apiReadKey')
     .option('--limit <n>', 'Max events', (v) => parseInt(v, 10))
-    .option('--window-days <n>', 'Lookback window in days', (v) => parseInt(v, 10))
-    .option('--include <csv>', 'stats,events,telemetry,performance,sdkStatus,activeErrors')
-    .option('--json', 'Output raw API JSON only')
+    .option('--window-days <n>', 'Lookback days', (v) => parseInt(v, 10))
+    .option('--include <csv>', 'API include list')
+    .option('--json', 'JSON output')
     .action(async (opts) => {
     try {
         const data = await runPull({
@@ -183,7 +228,7 @@ program
 });
 program
     .command('open')
-    .description('Open the Sublyzer dashboard for this integration')
+    .description('Open Sublyzer dashboard (cloud mode only)')
     .action(async () => {
     try {
         await runOpen();