@gurulu/cli 0.4.4 → 0.4.6

package/dist/api-client.d.ts

@@ -12,6 +12,12 @@ export interface CliApiOptions extends RequestInit {
     preloadedProfile?: ActiveProfile;
     /** Disable process.exit for tests. */
     noExitOnError?: boolean;
+    /**
+     * Surface raw error bodies on 5xx instead of the generic "temporarily
+     * unavailable" message. Caller should pass true when --json / --show-sql
+     * / any verbose flag is set. GURULU_DEBUG=1 also forces verbose globally.
+     */
+    verbose?: boolean;
 }
 export declare class CliApiError extends Error {
     status: number;

package/dist/api-client.js

@@ -129,6 +129,31 @@ async function cliApi(path, init = {}) {
         fatal(`Rate limited by Gurulu${retry ? ` — try again in ${retry}s` : ''}. Try again shortly.`, init);
     }
     if (res.status >= 500) {
+        const verbose = init.verbose === true || process.env.GURULU_DEBUG === '1';
+        if (verbose) {
+            let detail = '';
+            try {
+                const body = await res.clone().json();
+                const msg = body?.error || body?.message;
+                if (msg) {
+                    detail = ` ${typeof msg === 'string' ? msg : JSON.stringify(msg)}`;
+                }
+                else {
+                    detail = ` ${JSON.stringify(body)}`;
+                }
+            }
+            catch {
+                try {
+                    const txt = await res.clone().text();
+                    if (txt)
+                        detail = ` ${txt.slice(0, 500)}`;
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            fatal(`Gurulu is temporarily unavailable (HTTP ${res.status}).${detail}`, init);
+        }
         fatal(`Gurulu is temporarily unavailable (HTTP ${res.status}).`, init);
     }
     return res;

package/dist/commands/audiences.d.ts

@@ -15,5 +15,9 @@ export interface AudiencesArgs {
     rules?: string;
     yes?: boolean;
     dryRun?: boolean;
+    format?: 'csv' | 'json' | string;
+    output?: string;
+    preview?: boolean;
+    limit?: number;
 }
 export declare function audiencesCommand(args: AudiencesArgs): Promise<void>;

package/dist/commands/audiences.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.audiencesCommand = audiencesCommand;
+const node_fs_1 = require("node:fs");
 const api_client_1 = require("../api-client");
 const ui_1 = require("../utils/ui");
 const confirm_1 = require("../utils/confirm");
@@ -23,9 +24,11 @@ async function audiencesCommand(args) {
             return updateCmd(args);
         case 'delete':
             return deleteCmd(args);
+        case 'export':
+            return exportCmd(args);
         default:
             (0, ui_1.error)(`Unknown audiences action: ${action}`);
-            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete]');
+            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete|export]');
             process.exit(1);
     }
 }
@@ -205,3 +208,36 @@ async function deleteCmd(args) {
     });
     (0, ui_1.success)(`Deleted audience ${id}`);
 }
+/**
+ * AU5 (audit-2026-04-29-audience.md) — `gurulu audiences export <name-or-id>`.
+ * Streams the current audience membership as CSV (default) or JSON. With
+ * `--output <path>` we write to disk; otherwise the body goes to stdout.
+ */
+async function exportCmd(args) {
+    const target = args.target;
+    if (!target) {
+        (0, ui_1.error)('Usage: gurulu audiences export <name-or-id> [--format csv|json] [--output file]');
+        process.exit(1);
+    }
+    const id = await resolveId(target, args.profile);
+    const format = (args.format || 'csv').toLowerCase();
+    if (format !== 'csv' && format !== 'json') {
+        (0, ui_1.error)('--format must be csv or json');
+        process.exit(1);
+    }
+    const path = `/api/cli/audiences/${encodeURIComponent(id)}/export?format=${format}&destination=download`;
+    const res = await (0, api_client_1.cliApi)(path, { profile: args.profile });
+    const body = await res.text();
+    if (!res.ok) {
+        (0, ui_1.error)(`Export failed (HTTP ${res.status}): ${body.slice(0, 200)}`);
+        process.exit(1);
+    }
+    if (args.output) {
+        (0, node_fs_1.writeFileSync)(args.output, body, 'utf8');
+        (0, ui_1.success)(`Wrote ${body.length} bytes to ${args.output}`);
+        return;
+    }
+    process.stdout.write(body);
+    if (!body.endsWith('\n'))
+        process.stdout.write('\n');
+}

package/dist/commands/auth.js

@@ -54,22 +54,38 @@ const login_1 = require("./login");
 const config_1 = require("../config");
 const api_client_1 = require("../api-client");
 const ui_1 = require("../utils/ui");
+function isHeadless() {
+    if (!process.stdout.isTTY)
+        return true;
+    if (process.env.SSH_CLIENT || process.env.SSH_TTY || process.env.SSH_CONNECTION)
+        return true;
+    if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY)
+        return true;
+    return false;
+}
 function tryOpenBrowser(url) {
     const platform = process.platform;
     const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+    // On Windows the URL goes as a positional after an empty title arg to `start`.
+    const args = platform === 'win32' ? ['', url] : [url];
     try {
-        const child = (0, child_process_1.spawn)(cmd, [url], {
+        const child = (0, child_process_1.spawn)(cmd, args, {
             detached: true,
             stdio: 'ignore',
             shell: platform === 'win32',
         });
+        let errored = false;
         child.on('error', () => {
-            /* ignore — fall back to manual */
+            errored = true;
         });
         child.unref();
+        // spawn() returns synchronously; if the binary is missing on PATH we'll
+        // catch the synchronous throw below. The async 'error' handler covers
+        // post-fork failures but we can't await it here without blocking the flow.
+        return !errored;
     }
     catch {
-        /* ignore — we printed the URL already */
+        return false;
     }
 }
 function sleep(ms) {
@@ -121,8 +137,17 @@ async function authCommand(args) {
     console.log(`  ${(0, ui_1.dim)('Visit:')}         ${verifyUrl}`);
     console.log(`  ${(0, ui_1.dim)('Device:')}        CLI — ${deviceLabel}`);
     console.log('');
-    if (!args.noBrowser) {
-        tryOpenBrowser(verifyUrl);
+    if (args.noBrowser) {
+        (0, ui_1.info)(`Open this URL manually: ${verifyUrl}`);
+    }
+    else if (isHeadless()) {
+        (0, ui_1.info)(`Headless/SSH session detected — open this URL on another device: ${verifyUrl}`);
+    }
+    else {
+        const opened = tryOpenBrowser(verifyUrl);
+        if (!opened) {
+            (0, ui_1.info)(`Could not auto-open the browser. Open this URL manually: ${verifyUrl}`);
+        }
     }
     const expiresAtMs = new Date(expiresAt).getTime();
     const interval = Math.max(1000, pollIntervalMs || 2000);
@@ -195,16 +220,26 @@ async function authCommand(args) {
         process.exit(1);
     }
     const fullKey = approved.secretKey.fullKey;
+    const userRequestedKeychain = args.useKeychain === true;
+    const keychainAvailable = (0, config_1.isKeychainAvailable)();
+    if (userRequestedKeychain && !keychainAvailable) {
+        (0, ui_1.warn)('Keychain requested via --keychain but the optional `keytar` module is not installed. ' +
+            'Falling back to plaintext storage in ~/.gurulu/config.json. ' +
+            'Install `keytar` (`npm i -g keytar`) or unset --keychain to silence this warning.');
+    }
     const { storedInKeychain } = await (0, config_1.saveProfile)(profileName, {
         email: `cli-${deviceLabel}@gurulu.local`,
         secret_key: fullKey,
         api_base: apiBase,
-    }, { useKeychain: args.useKeychain ?? (0, config_1.isKeychainAvailable)() });
+    }, { useKeychain: args.useKeychain ?? keychainAvailable });
     const tail = fullKey.slice(-6);
     (0, ui_1.success)(`Device paired. Key …${tail} saved to profile "${profileName}".`);
     if (storedInKeychain) {
         (0, ui_1.info)(`  Stored in macOS Keychain (${(0, ui_1.dim)('io.gurulu.cli')})`);
     }
+    else if (userRequestedKeychain) {
+        (0, ui_1.info)(`  Stored in plaintext at ~/.gurulu/config.json (keychain unavailable).`);
+    }
     if (approved.secretKey.expiresAt) {
         (0, ui_1.info)(`  Expires: ${approved.secretKey.expiresAt}`);
     }

package/dist/commands/doctor.js

@@ -23,6 +23,9 @@ async function doctorCommand(args) {
     const checks = [];
     // 1. Framework detection
     const framework = (0, detect_1.detectFramework)(projectDir);
+    // If the user explicitly passed --site, the cwd-derived checks should not
+    // imply that the *production site* is broken — they're informational only.
+    const isLocalProjectDetected = framework !== 'unknown';
     checks.push({
         name: 'Framework Detection',
         status: framework !== 'unknown' ? 'pass' : 'warn',
@@ -30,6 +33,7 @@ async function doctorCommand(args) {
             ? `Detected ${(0, detect_1.getFrameworkDisplayName)(framework)}`
             : 'Could not detect framework',
         fix: framework === 'unknown' ? 'Run "gurulu init --framework <name>" to specify manually' : undefined,
+        section: 'local',
     });
     // 2. SDK installed
     const pkgPath = path_1.default.join(projectDir, 'package.json');
@@ -78,18 +82,35 @@ async function doctorCommand(args) {
                     : hasAndroidSDK ? 'Android SDK found in build.gradle'
                         : setupFiles.length > 0 ? `Setup file found: ${setupFiles[0]}`
                             : 'No client SDK detected';
+    // When --site was passed but cwd is not a Gurulu project, downgrade local
+    // SDK failures to "skip" so they don't masquerade as production-site issues.
+    const localChecksAreInformational = !!siteId && !isLocalProjectDetected;
     checks.push({
         name: 'Client SDK',
-        status: hasSetup ? 'pass' : 'fail',
-        message: sdkLabel,
-        fix: !hasSetup ? 'Run "gurulu init" to set up analytics' : undefined,
+        status: hasSetup ? 'pass' : localChecksAreInformational ? 'skip' : 'fail',
+        message: hasSetup
+            ? sdkLabel
+            : localChecksAreInformational
+                ? 'No client SDK detected in this directory (informational — site checks below)'
+                : sdkLabel,
+        fix: !hasSetup && !localChecksAreInformational
+            ? 'Run "gurulu init" to set up analytics'
+            : undefined,
+        section: 'local',
     });
     // 3. Server SDK
     checks.push({
         name: 'Server SDK',
-        status: hasNodeSDK ? 'pass' : 'warn',
-        message: hasNodeSDK ? '@gurulu/node installed' : 'Server SDK not installed (optional)',
-        fix: !hasNodeSDK ? 'Run "gurulu add-server" for server-side tracking' : undefined,
+        status: hasNodeSDK ? 'pass' : localChecksAreInformational ? 'skip' : 'warn',
+        message: hasNodeSDK
+            ? '@gurulu/node installed'
+            : localChecksAreInformational
+                ? 'Server SDK check skipped (no local project detected)'
+                : 'Server SDK not installed (optional)',
+        fix: !hasNodeSDK && !localChecksAreInformational
+            ? 'Run "gurulu add-server" for server-side tracking'
+            : undefined,
+        section: 'local',
     });
     // 4. Site ID configured
     checks.push({
@@ -263,6 +284,7 @@ async function doctorCommand(args) {
             status: envHasSiteId ? 'pass' : 'warn',
             message: envHasSiteId ? 'Site ID found in env file' : 'No GURULU_SITE_ID in env files',
             fix: !envHasSiteId ? 'Run "gurulu init" to auto-configure .env.local' : undefined,
+            section: 'local',
         });
     }
     // Output
@@ -281,16 +303,36 @@ async function doctorCommand(args) {
     };
     let failCount = 0;
     let warnCount = 0;
-    for (const check of checks) {
-        const icon = icons[check.status];
-        console.log(`  ${icon} ${(0, ui_1.bold)(check.name)}: ${check.message}`);
-        if (check.fix) {
-            console.log(`    ${(0, ui_1.dim)('\u2192')} ${(0, ui_1.dim)(check.fix)}`);
+    const localChecks = checks.filter((c) => c.section === 'local');
+    const siteChecks = checks.filter((c) => c.section !== 'local');
+    const printGroup = (title, items, note) => {
+        if (items.length === 0)
+            return;
+        console.log(`  ${(0, ui_1.bold)(title)}`);
+        if (note)
+            console.log(`  ${(0, ui_1.dim)(note)}`);
+        for (const check of items) {
+            const icon = icons[check.status];
+            console.log(`    ${icon} ${(0, ui_1.bold)(check.name)}: ${check.message}`);
+            if (check.fix) {
+                console.log(`      ${(0, ui_1.dim)('\u2192')} ${(0, ui_1.dim)(check.fix)}`);
+            }
+            if (check.status === 'fail')
+                failCount++;
+            if (check.status === 'warn')
+                warnCount++;
         }
-        if (check.status === 'fail')
-            failCount++;
-        if (check.status === 'warn')
-            warnCount++;
+        console.log('');
+    };
+    if (localChecks.length > 0) {
+        const localNote = siteId && !isLocalProjectDetected
+            ? `(Local project not detected \u2014 running site-only checks for ${siteId}.)`
+            : undefined;
+        printGroup('Local Project', localChecks, localNote);
+    }
+    if (siteChecks.length > 0) {
+        const siteTitle = siteId ? `Site (${siteId})` : 'Site';
+        printGroup(siteTitle, siteChecks);
     }
     console.log('');
     if (failCount === 0 && warnCount === 0) {

package/dist/commands/events.js

@@ -76,10 +76,10 @@ async function listCmd(args) {
     process.stdout.write(['TS', 'EVENT', 'SITE', 'URL'].join('\t') + '\n');
     for (const e of events) {
         process.stdout.write([
-            String(e.event_ts || '-'),
+            String(e.timestamp || e.event_ts || '-'),
             String(e.event_name || '-'),
             String(e.site_id || '-'),
-            String(e.url || '-').slice(0, 60),
+            String(e.page_url || e.url || '-').slice(0, 60),
         ].join('\t') + '\n');
     }
 }
@@ -184,7 +184,13 @@ async function defineCmd(args) {
             process.exit(1);
         }
     }
-    const eventName = args.eventName.startsWith('$') ? args.eventName : `$${args.eventName}`;
+    // Use the user-provided name verbatim. The CLI used to force a `$` prefix
+    // because Gurulu's built-ins use one (`$page_view`, `$session_start`), but
+    // built-ins are inconsistent (`click`, `engaged_session` have none) and
+    // mutating the customer's chosen name silently broke schema lookups + made
+    // the generated SDK snippets reference a name that no longer matched the
+    // ingest payload.
+    const eventName = args.eventName;
     const body = {
         siteId: args.site,
         eventName,
@@ -207,10 +213,14 @@ async function verifyCmd(args) {
         (0, ui_1.error)('--site is required.');
         process.exit(1);
     }
+    // Accept both `--event` (verify-original) and `--event-name` (used by
+    // every other events subcommand). Removes the surprising flag-name
+    // inconsistency without breaking existing scripts.
+    const filterEvent = args.event || args.eventName;
     const qs = new URLSearchParams();
     qs.set('siteId', args.site);
-    if (args.event)
-        qs.set('eventName', args.event);
+    if (filterEvent)
+        qs.set('eventName', filterEvent);
     const path = `/api/cli/events/health?${qs.toString()}`;
     const data = await (0, api_client_1.cliApiJson)(path, { profile: args.profile });
     if (args.json) {
@@ -220,7 +230,7 @@ async function verifyCmd(args) {
     console.log((0, ui_1.bold)('\nEvent Health Report'));
     console.log(`Site: ${args.site}`);
     console.log('');
-    if (Array.isArray(data.events)) {
+    if (Array.isArray(data.events) && data.events.length > 0) {
         for (const ev of data.events) {
             const statusIcon = ev.status === 'active'
                 ? (0, ui_1.green)('●')
@@ -237,6 +247,17 @@ async function verifyCmd(args) {
         console.log(`Total events (24h): ${data.total_events}`);
         console.log(`Unique event types: ${data.unique_types ?? 'N/A'}`);
     }
+    else {
+        // Empty: no telemetry yet for the requested filter / definition. Without
+        // this branch the report printed only its header — users couldn't tell
+        // success from "no data found".
+        if (filterEvent) {
+            (0, ui_1.info)(`No telemetry yet for "${filterEvent}". Track it from your app and run verify again.`);
+        }
+        else {
+            (0, ui_1.info)('No telemetry data found for this site in the last 24h.');
+        }
+    }
     console.log('');
 }
 /* ── templates: list vertical event template catalogs ───────────── */

package/dist/commands/heatmap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+export interface HeatmapArgs {
+    action?: string;
+    site?: string;
+    page?: string;
+    pageId?: string;
+    type?: string;
+    range?: string;
+    viewport?: string;
+    json?: boolean;
+    profile?: string;
+}
+export declare function heatmapCommand(args: HeatmapArgs): Promise<void>;

package/dist/commands/heatmap.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.heatmapCommand = heatmapCommand;
+const api_client_1 = require("../api-client");
+const ui_1 = require("../utils/ui");
+async function resolveSiteId(target, profile) {
+    if (!target)
+        throw new Error('--site is required');
+    const body = await (0, api_client_1.cliApiJson)('/api/cli/sites', { profile });
+    const sites = body.sites || [];
+    const byId = sites.find((s) => s.id === target);
+    if (byId)
+        return byId.id;
+    const byName = sites.find((s) => s.name === target);
+    if (byName)
+        return byName.id;
+    const byDomain = sites.find((s) => s.domain === target);
+    if (byDomain)
+        return byDomain.id;
+    const prefix = sites.find((s) => s.id.startsWith(target));
+    if (prefix)
+        return prefix.id;
+    throw new Error(`Site '${target}' not found.`);
+}
+async function heatmapCommand(args) {
+    const action = args.action || 'list';
+    switch (action) {
+        case 'list':
+            return listCmd(args);
+        case 'export':
+            return exportCmd(args);
+        default:
+            (0, ui_1.error)(`Unknown heatmap action: ${action}`);
+            (0, ui_1.info)('Usage: gurulu heatmap [list|export]');
+            process.exit(1);
+    }
+}
+async function listCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/list?siteId=${encodeURIComponent(siteId)}&range=${range}`, {
+        profile: args.profile,
+    });
+    if (args.json) {
+        process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+        return;
+    }
+    const pages = body.pages || [];
+    if (pages.length === 0) {
+        (0, ui_1.info)(`No heatmap data for site '${body.siteName}' (range=${range}).`);
+        return;
+    }
+    process.stdout.write(['CLICKS', 'VISITORS', 'M/T/D', 'LAST SEEN', 'PAGE URL'].join('\t') + '\n');
+    for (const p of pages) {
+        const mtd = `${p.viewportBuckets.mobile}/${p.viewportBuckets.tablet}/${p.viewportBuckets.desktop}`;
+        process.stdout.write([
+            String(p.clickCount),
+            String(p.visitors),
+            mtd,
+            String(p.lastSeen).slice(0, 19),
+            p.pageUrl,
+        ].join('\t') + '\n');
+    }
+}
+async function exportCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    if (!args.page) {
+        (0, ui_1.error)('--page <pageUrl> is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const type = args.type === 'scroll' ? 'scroll' : 'click';
+    const qp = new URLSearchParams({
+        siteId,
+        pageUrl: args.page,
+        range,
+        type,
+    });
+    if (args.pageId)
+        qp.set('pageId', args.pageId);
+    if (args.viewport)
+        qp.set('viewportBucket', args.viewport);
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/get?${qp.toString()}`, {
+        profile: args.profile,
+    });
+    // Export commands always emit machine-readable output by default; the
+    // `--json` flag is accepted for symmetry with the rest of the CLI.
+    process.stdout.write(JSON.stringify(body, null, args.json ? 2 : 0) + '\n');
+}

package/dist/commands/whoami.js

@@ -31,7 +31,10 @@ async function whoamiCommand(args) {
         const sites = (me.sites || []).length;
         const keys = (me.apiKeys || []).length;
         const installs = me.quota?.installsThisMonth ?? 0;
-        const limit = me.quota?.installsLimit ?? '∞';
+        const rawLimit = me.quota?.installsLimit;
+        const limit = rawLimit === -1 || rawLimit === null || rawLimit === undefined
+            ? 'unlimited'
+            : rawLimit;
         process.stdout.write(`${me.user?.email} · ${me.tenant?.name} · ${me.tenant?.plan} plan · ${me.tenant?.id}\n`);
         process.stdout.write(`Sites: ${sites} | API keys: ${keys} | Installs this month: ${installs}/${limit}\n`);
     }

package/dist/index.js

@@ -34,6 +34,8 @@ const audit_1 = require("./commands/audit");
 // Goals & Funnels CRUD
 const goals_1 = require("./commands/goals");
 const funnels_1 = require("./commands/funnels");
+// Sprint J-Heat HM10 — heatmap read surface
+const heatmap_1 = require("./commands/heatmap");
 // Gurulu Chat — NL → SQL analytics
 const chat_1 = require("./commands/chat");
 // Error tracking — source map upload
@@ -97,7 +99,7 @@ const secrets_1 = require("./commands/secrets");
     .option('key', { type: 'string', describe: 'Secret key (gsk_live_... or gsk_test_...) — legacy manual flow' })
     .option('email', { type: 'string', describe: 'Email address (legacy flow)' })
     .option('secret-key', { type: 'string', describe: 'Secret key (legacy flow alias for --key)' })
-    .option('no-browser', { type: 'boolean', describe: 'Do not auto-open the browser' })
+    .option('browser', { type: 'boolean', default: true, describe: 'Auto-open the browser (use --no-browser to disable)' })
     .option('no-interactive', { type: 'boolean', describe: 'Non-interactive mode (legacy flow)' })
     .option('keychain', { type: 'boolean', describe: 'Store secret in macOS Keychain if available' })
     .option('api-base', { type: 'string', describe: 'Override API base URL' }), (args) => (0, auth_1.authCommand)({
@@ -108,7 +110,7 @@ const secrets_1 = require("./commands/secrets");
     noInteractive: args['no-interactive'],
     useKeychain: args.keychain,
     apiBase: args['api-base'],
-    noBrowser: args['no-browser'],
+    noBrowser: args.browser === false ? true : undefined,
 }))
     .command('logout', 'Remove a stored profile', (y) => y
     .option('all', { type: 'boolean', describe: 'Remove all profiles' })
@@ -323,8 +325,11 @@ const secrets_1 = require("./commands/secrets");
     });
 })
     // ── Phase 19.5 W2 — read-surface subcommands ─────────────────────────
-    .command('audiences <action> [target]', 'Manage audiences (list, show, create, update, delete)', (y) => y
-    .positional('action', { type: 'string', describe: 'list | show | create | update | delete' })
+    .command('audiences <action> [target]', 'Manage audiences (list, show, create, update, delete, export)', (y) => y
+    .positional('action', {
+    type: 'string',
+    describe: 'list | show | create | update | delete | export',
+})
     .positional('target', { type: 'string', describe: 'Audience name or id' })
     .option('site', { type: 'string', describe: 'Site ID' })
     .option('id', { type: 'string', describe: 'Audience ID (for update/delete)' })
@@ -334,6 +339,15 @@ const secrets_1 = require("./commands/secrets");
     .option('from-file', { type: 'string', describe: 'Load payload from JSON file' })
     .option('dry-run', { type: 'boolean', describe: 'Show what would be done' })
     .option('yes', { type: 'boolean', alias: 'y', describe: 'Skip confirmation' })
+    // AU5 — export options
+    .option('format', {
+    type: 'string',
+    describe: 'Export format: csv | json (default csv)',
+})
+    .option('output', {
+    type: 'string',
+    describe: 'Write export body to this file (default stdout)',
+})
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, audiences_1.audiencesCommand)({
     action: args.action,
     target: args.target,
@@ -345,6 +359,8 @@ const secrets_1 = require("./commands/secrets");
     fromFile: args['from-file'],
     dryRun: args['dry-run'],
     yes: args.yes,
+    format: args.format,
+    output: args.output,
     json: args.json,
     profile: args.profile,
 }))
@@ -400,6 +416,10 @@ const secrets_1 = require("./commands/secrets");
 }))
     .command('insights <action>', 'View daily insights (today, history, weekly)', (y) => y
     .positional('action', { type: 'string', describe: 'today | history | weekly' })
+    // `--site` is accepted but ignored: insights are computed at tenant
+    // scope (across all sites). Accept it so the flag is consistent with
+    // the rest of the CLI and doesn't reject scripts that pass it.
+    .option('site', { type: 'string', describe: 'Site ID (accepted for consistency, currently tenant-scoped)' })
     .option('days', { type: 'number', describe: 'History window in days (1..30)' })
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, insights_1.insightsCommand)({
     action: args.action,
@@ -494,6 +514,40 @@ const secrets_1 = require("./commands/secrets");
     yes: args.yes,
     json: args.json,
     profile: args.profile,
+}))
+    .command('heatmap <action>', 'Inspect click + scroll heatmaps (list, export)', (y) => y
+    .positional('action', { type: 'string', describe: 'list | export' })
+    .option('site', { type: 'string', describe: 'Site name or id' })
+    .option('page', { type: 'string', describe: 'Page URL (for export)' })
+    .option('page-id', {
+    type: 'string',
+    describe: 'Virtual-page id (HM6, optional)',
+})
+    .option('type', {
+    type: 'string',
+    choices: ['click', 'scroll'],
+    describe: 'Heatmap type for export (default click)',
+})
+    .option('range', {
+    type: 'string',
+    choices: ['7d', '30d'],
+    describe: 'Lookback window (default 7d)',
+})
+    .option('viewport', {
+    type: 'string',
+    choices: ['mobile', 'tablet', 'desktop'],
+    describe: 'Filter to a viewport bucket (HM9)',
+})
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, heatmap_1.heatmapCommand)({
+    action: args.action,
+    site: args.site,
+    page: args.page,
+    pageId: args['page-id'],
+    type: args.type,
+    range: args.range,
+    viewport: args.viewport,
+    json: args.json,
+    profile: args.profile,
 }))
     .command('identity <action> [sub]', 'Identity state + writes (decay stats | transfers list | cdc-sources list | identify | alias | merge | bulk)', (y) => y
     .positional('action', {
@@ -581,8 +635,8 @@ const secrets_1 = require("./commands/secrets");
     // ── Error tracking — source map upload ────────────────────────────────
     .command('sourcemap <action>', 'Upload source maps for error deobfuscation (upload). Supports web/server JS .map and native dSYM/ProGuard.', (y) => y
     .positional('action', { type: 'string', describe: 'upload' })
-    .option('release', { type: 'string', describe: 'Release version (e.g. v1.0.0). Web/server only — alias of --version.' })
-    .option('version', { type: 'string', describe: 'App version (e.g. 1.4.2). Required for native uploads.' })
+    .option('release', { type: 'string', describe: 'Release version (e.g. v1.0.0). Web/server only — alias of --app-version.' })
+    .option('app-version', { type: 'string', describe: 'App version (e.g. 1.4.2). Required for native uploads.' })
     .option('dir', { type: 'string', describe: 'Directory containing .map files (web/server)' })
     .option('file', { type: 'string', describe: 'Path to dSYM zip (iOS) or mapping.txt (Android)' })
     .option('bundle-id', { type: 'string', describe: 'iOS bundleId or Android applicationId (native only)' })
@@ -591,7 +645,7 @@ const secrets_1 = require("./commands/secrets");
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, sourcemap_1.sourcemapCommand)({
     action: args.action,
     release: args.release,
-    version: args.version,
+    version: args['app-version'],
     dir: args.dir,
     file: args.file,
     bundleId: args['bundle-id'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gurulu/cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Gurulu.io CLI — setup analytics in seconds",
   "bin": {
     "gurulu": "bin/gurulu.js"