@revturbine/cli 0.17.1 → 0.18.0

package/README.md

@@ -63,7 +63,7 @@ Commands that read a config name the version explicitly — there is no default:
 
 | Command | What it does |
 |---|---|
-| `init` (alias `create`) | Scaffold RevTurbine into this app: detect the package manager and stack, install the SDK, pin the CLI exactly, drop a starter Playbook, and install the Agent Skills. In a directory with no `package.json` it offers to start a new project (`--yes` to skip the prompt); `--dir`, `--dry-run`, `--no-skills`, `--json`. Runs the invoked CLI even inside a repo that pins a different one — setup establishes the pin, so it never delegates. |
+| `init` (alias `create`) | Set up RevTurbine while preserving existing integrations: install missing packages, pin the CLI exactly, create a starter for a fresh integration, and install skills for one agent. Use `--scaffold` to create a missing root starter explicitly; existing files are never overwritten. `--agent claude-code\|cursor\|codex` overrides environment detection; an unknown agent skips skills and prints the selection command. Also supports `--dir`, `--dry-run`, `--no-skills`, `--json`. With no `package.json`, offers a new project (`--yes` for noninteractive creation). Runs the invoked CLI even inside a repo that pins a different one. |
 | `signup` | Create an account headlessly: email + password, then an emailed one-time code to verify, then a token is stored. |
 | `login` / `logout` | Device-flow auth; tokens stored at `~/.revturbine/credentials.json` (mode 0600). |
 | `whoami` | The resolved instance, tenant, credentials source, and whether the stored token works. |
@@ -83,10 +83,54 @@ Commands that read a config name the version explicitly — there is no default:
 | `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. |
 | `generate types` | Generate a TypeScript module of typed Playbook handles from any config version — `Entitlements` (namespaced by type, with the `EntitlementHandle` union for type-safe `can()`/`gate()`/`checkEntitlement()` call sites), plus `Plans`, `Segments`, `SurfaceTemplates`, and `UiPathActionTypes`. Const objects + literal-union types (erasable — no enums). `--out <path>` writes the file; the generated header records the exact command to regenerate it. `--json` for the raw handle map. |
 | `analytics catalog\|templates\|views\|view\|create\|preview\|query` | Work with the hosted Semantic Catalog and canonical analytics-view documents. Create and preview pass the document through unchanged to the same server contract used by the web editor and MCP tools; preview remains subject to the server's query limits. |
+| `ingest-keys create` (alias `mint`) | Mint a tenant-bound public ingest token for browser SDK use. Requires one or more `--origin` values; optional `--ip` restrictions. The full token is returned once. `ingest-keys list` shows ids/previews and `ingest-keys revoke <id>` invalidates one. |
+| `events track` | Send analytics events to the ingest pipeline with your own login — no ingest key and no browser origin required. Takes `--file <path>` (JSON array, `{ "events": [...] }` envelope, or NDJSON) or `--event <json>`. Batches over 500 events are chunked automatically. Reports accepted, quarantined, rejected and dropped counts separately. |
+
+`init` preserves declared SDK/CLI versions and application code. It skips a new root
+Playbook when the SDK is already declared in `dependencies` or `devDependencies`,
+or project source imports the SDK, or a non-root canonical Playbook is found.
+Detection ignores hidden directories, symlinks, dependencies and build outputs.
+If the integration is intentionally incomplete, `--scaffold` creates only the missing
+`revturbine.playbook.json`; it never replaces an existing one. `--dry-run --json`
+reports `playbook: "present"`, `"skipped"`, or the filename to create, and
+`skills_agent` identifies the single installer target (or `null` when skipped).
+`--no-skills` takes precedence over a detected or explicitly selected valid agent.
 
 `--json` on read commands emits machine-readable output. Results go to stdout,
 diagnostics to stderr.
 
+### Send analytics events
+
+```bash
+revturbine login
+revturbine events track --file ./events.ndjson
+
+# or a single event inline
+revturbine events track --event '{"environment_id":"production","user_id":"u-1","account_id":"a-1","event_name":"product_used","event_ts":"2026-09-10T00:00:00.000Z"}'
+```
+
+Every event needs `environment_id`, `user_id`, `account_id`, `event_name` and
+`event_ts`; anything else you include is carried through. Local validation
+reports every malformed event at once and sends nothing until they are fixed.
+
+This authenticates with your device-auth token rather than an ingest key, so
+it works from a terminal or CI where there is no browser origin to allowlist.
+Quarantined and rejected counts are reported separately from accepted — a
+load is not clean merely because the server returned `202`.
+
+### Mint a publishable ingest token
+
+```bash
+revturbine login
+revturbine ingest-keys mint --origin https://app.example.com --json
+# Store the once-only token, then use the returned id when it is no longer needed:
+revturbine ingest-keys revoke <ingest-key-id> --yes
+```
+
+Public ingest tokens are intentionally embeddable but remain tenant-bound,
+origin-restricted, and optionally IP-restricted. They cannot mint other tokens
+or access private control-plane APIs.
+
 ## Exit-code classes
 
 ```

package/dist/cli.js

@@ -10981,6 +10981,130 @@ function formatIngestKeyLine(key2) {
   return `${key2.id}  ${key2.tokenPreview}  origins: ${origins}${ips}${last}`;
 }
 
+// src/lib/events-ingest.ts
+var MAX_EVENTS_PER_BATCH = 500;
+var REQUIRED_FIELDS = [
+  "environment_id",
+  "user_id",
+  "account_id",
+  "event_name",
+  "event_ts"
+];
+function parseEventBatch(text) {
+  const trimmed = text.trim();
+  if (trimmed === "") return { events: [], errors: ["input is empty"] };
+  const errors = [];
+  let raw;
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      return parseNdjson(trimmed);
+    }
+    if (Array.isArray(parsed)) {
+      raw = parsed;
+    } else if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.events)) {
+      raw = parsed.events;
+    } else if (parsed !== null && typeof parsed === "object") {
+      raw = [parsed];
+    } else {
+      return { events: [], errors: ["input must be an object, an array, or an { events: [...] } envelope"] };
+    }
+  } else {
+    return parseNdjson(trimmed);
+  }
+  const events2 = validateAll(raw, errors);
+  return { events: events2, errors };
+}
+function parseNdjson(text) {
+  const errors = [];
+  const raw = [];
+  text.split("\n").forEach((line, i) => {
+    const t = line.trim();
+    if (t === "") return;
+    try {
+      raw.push(JSON.parse(t));
+    } catch {
+      errors.push(`line ${i + 1}: not valid JSON`);
+    }
+  });
+  const events2 = validateAll(raw, errors);
+  return { events: events2, errors };
+}
+function validateAll(raw, errors) {
+  const events2 = [];
+  raw.forEach((item, i) => {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      errors.push(`event ${i}: not a JSON object`);
+      return;
+    }
+    const bag = item;
+    const missing = REQUIRED_FIELDS.filter(
+      (f) => typeof bag[f] !== "string" || bag[f].trim() === ""
+    );
+    if (missing.length > 0) {
+      errors.push(`event ${i}: missing or empty ${missing.join(", ")}`);
+      return;
+    }
+    events2.push(bag);
+  });
+  return events2;
+}
+function chunkEvents(events2, size = MAX_EVENTS_PER_BATCH) {
+  const limit = Math.max(1, Math.min(size, MAX_EVENTS_PER_BATCH));
+  const out = [];
+  for (let i = 0; i < events2.length; i += limit) out.push(events2.slice(i, i + limit));
+  return out;
+}
+function readResult(json) {
+  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+  return {
+    accepted: num(json.accepted),
+    quarantined: num(json.quarantined),
+    dropped_unscoped: num(json.dropped_unscoped),
+    rejected: Array.isArray(json.rejected) ? json.rejected : [],
+    request_id: typeof json.request_id === "string" ? json.request_id : null
+  };
+}
+async function postBatch(baseUrl, headers, events2, fetchImpl = fetch) {
+  const res = await fetchImpl(`${baseUrl}/api/track`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ events: events2 })
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) return { ok: false, status: res.status, result: null, error: json };
+  return { ok: true, status: res.status, result: readResult(json), error: {} };
+}
+function summarize(results, eventCount) {
+  return {
+    batches: results.length,
+    // @revturbine-graph gref:3f4d51af0a0af98edea0
+    events: eventCount,
+    accepted: results.reduce((n, r) => n + r.accepted, 0),
+    quarantined: results.reduce((n, r) => n + r.quarantined, 0),
+    dropped_unscoped: results.reduce((n, r) => n + r.dropped_unscoped, 0),
+    rejected: results.reduce((n, r) => n + r.rejected.length, 0),
+    results
+  };
+}
+function formatSummary(summary) {
+  const lines = [
+    `ingested ${summary.accepted}/${summary.events} event(s) in ${summary.batches} batch(es)`
+  ];
+  if (summary.quarantined > 0) {
+    lines.push(`  quarantined: ${summary.quarantined} (payload failed its platform contract)`);
+  }
+  if (summary.rejected > 0) {
+    lines.push(`  rejected: ${summary.rejected} (malformed on the wire)`);
+  }
+  if (summary.dropped_unscoped > 0) {
+    lines.push(`  dropped (unscoped): ${summary.dropped_unscoped} (simulation rows without a dataset id)`);
+  }
+  return lines.join("\n");
+}
+
 // src/lib/delegate.ts
 var DELEGATION_ENV = "REVTURBINE_DELEGATED";
 var NO_LOCAL_FLAG = "--no-local";
@@ -11116,6 +11240,29 @@ function detectStack(signals) {
 }
 var SDK_PACKAGE = "@revturbine/sdk";
 var CLI_PACKAGE = "@revturbine/cli";
+function declaredSdk(manifest) {
+  return Boolean(manifest.dependencies?.[SDK_PACKAGE] || manifest.devDependencies?.[SDK_PACKAGE]);
+}
+function integrationFileReason(file, content) {
+  if (file.endsWith("revturbine.playbook.json")) return `existing Playbook (${file})`;
+  if (/\.[cm]?[jt]sx?$/.test(file) && /['"]@revturbine\/sdk(?:\/[^'"]*)?['"]/.test(content)) {
+    return `SDK integration (${file})`;
+  }
+  if (file.endsWith(".json")) {
+    try {
+      const value = JSON.parse(content);
+      if (value && typeof value === "object" && "artifact_type" in value && value.artifact_type === "playbook") {
+        return `existing Playbook (${file})`;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function planStarter(params) {
+  if (params.rootExists) return "present";
+  return params.integrationReason && !params.scaffold ? "skipped" : "create";
+}
 function projectNameFromDir(dirName) {
   const slug = dirName.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-_.]+|[-_.]+$/g, "");
   return slug || "my-app";
@@ -11208,20 +11355,34 @@ function validatePlaybook(config) {
 // src/lib/init-skills.ts
 var SKILLS_SOURCE = "revt-eng/revturbine-skills";
 var START_HERE_SKILL = "revturbine-start-here";
-function detectHarness(env) {
-  if (env["CLAUDECODE"] || env["CLAUDE_CODE_SESSION_ID"] || env["CLAUDE_CODE_ENTRYPOINT"]) {
-    return { label: "Claude Code", invocation: `Run the skill:  /${START_HERE_SKILL}` };
+var SUPPORTED_AGENTS = ["claude-code", "cursor", "codex"];
+function isAgentId(value) {
+  return SUPPORTED_AGENTS.some((id) => id === value);
+}
+function detectHarness(env, explicit) {
+  let agentId = explicit;
+  if (!agentId) {
+    if (env["CLAUDECODE"] || env["CLAUDE_CODE_SESSION_ID"] || env["CLAUDE_CODE_ENTRYPOINT"]) agentId = "claude-code";
+    else if (env["CURSOR_TRACE_ID"] || env["CURSOR"]) agentId = "cursor";
+    else if (env["CODEX_THREAD_ID"]) agentId = "codex";
   }
-  if (env["CURSOR_TRACE_ID"] || env["CURSOR"]) {
-    return { label: "Cursor", invocation: `Mention the skill:  @${START_HERE_SKILL}` };
+  if (agentId === "claude-code") {
+    return { agentId, label: "Claude Code", invocation: `Run the skill:  /${START_HERE_SKILL}` };
+  }
+  if (agentId === "cursor") {
+    return { agentId, label: "Cursor", invocation: `Mention the skill:  @${START_HERE_SKILL}` };
+  }
+  if (agentId === "codex") {
+    return { agentId, label: "Codex", invocation: `Run the skill:  $${START_HERE_SKILL}` };
   }
   return {
+    agentId: null,
     label: null,
     invocation: `Ask your coding agent to run the "${START_HERE_SKILL}" skill.`
   };
 }
-function skillsAddArgs(source = SKILLS_SOURCE) {
-  return ["--yes", "skills", "add", source, "-y", "--copy"];
+function skillsAddArgs(agent) {
+  return ["--yes", "skills", "add", SKILLS_SOURCE, "-y", "--copy", "-a", agent];
 }
 function finalOutputLines(params) {
   const lines = ["", "RevTurbine is set up.", ""];
@@ -11235,12 +11396,14 @@ function finalOutputLines(params) {
     lines.push("  \u2713 Installed the Agent Skills");
   } else if (params.skills === "skipped") {
     lines.push("  \u2022 Skipped the Agent Skills (--no-skills)");
+  } else if (params.skills === "unknown") {
+    lines.push("  \u2022 Agent Skills not installed \u2014 select a target with --agent");
   } else {
     lines.push("  \u26A0 Agent Skills not installed \u2014 see above to add them by hand");
   }
   lines.push("", "Next step:");
   lines.push(`  ${params.harness.invocation}`);
-  if (params.harness.label) lines.push(`  (detected ${params.harness.label})`);
+  if (params.harness.label) lines.push(`  (${params.harness.label})`);
   lines.push("", "Your setup path:");
   lines.push("  create playbook \u2192 app wiring \u2192 billing \u2192 verify \u2192 launch");
   lines.push("", "Docs: https://revturbine.com/docs", "");
@@ -11878,7 +12041,8 @@ Command groups:
   Inspect       status, history, preview, evaluate
   Codegen       generate types
   Analytics     analytics catalog|templates|views|view|create|preview|query
-  Keys          ingest-keys create|list|revoke
+  Keys          ingest-keys create (alias: mint)|list|revoke
+  Events        events track
 
 Version selectors (no defaults \u2014 a command that reads a config requires one):
   <file>            a local Playbook file (positional, or --file <path>)
@@ -11889,6 +12053,10 @@ Version selectors (no defaults \u2014 a command that reads a config requires one
 Common workflows:
   # Add RevTurbine to an app (same routine as \`npm create revturbine@latest\`)
   revturbine init
+  # Preserve an existing integration; select one skills target explicitly
+  revturbine init --agent codex
+  # Opt into a missing root starter; existing Playbooks are never overwritten
+  revturbine init --scaffold --no-skills
 
   # Author, validate, and ship against the default instance (revturbine.com/app)
   revturbine login
@@ -11908,6 +12076,14 @@ Common workflows:
   revturbine history
   revturbine restore <playbook-version-id> --launch
 
+  # Mint an origin-restricted browser token (shown once), then revoke it
+  revturbine ingest-keys mint --origin https://app.example.com --json
+
+  # Send analytics events with your own login (no ingest key, no browser origin)
+  revturbine events track --file ./events.ndjson
+  revturbine ingest-keys list
+  revturbine ingest-keys revoke <ingest-key-id> --yes
+
 Exit-code classes: 0 ok \xB7 1 unexpected \xB7 2 usage \xB7 3 auth \xB7 4 validation
 blocked \xB7 5 conflict/stale \xB7 6 network \xB7 7 server error.
 
@@ -11936,7 +12112,26 @@ function runInstall(manager, args, cwd) {
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
-program.command("init").alias("create").description("Scaffold RevTurbine into this app: detect the stack, install the SDK, pin the CLI, drop a starter Playbook, and install the Agent Skills. Offers to start a new project when the directory has no package.json.").option("-d, --dir <path>", "Target directory (defaults to the current directory)").option("-y, --yes", "Skip prompts \u2014 create a new project non-interactively when the directory has none").option("--dry-run", "Report what would be installed without running the package manager").option("--no-skills", "Do not install the RevTurbine Agent Skills").option("--json", "Emit the scaffold plan as JSON").action(async (opts) => {
+function findIntegration(dir, root = dir) {
+  if (!existsSync2(dir)) return void 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || ["node_modules", "dist", "build", "coverage", "target"].includes(entry.name)) continue;
+    const file = path2.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const reason = findIntegration(file, root);
+      if (reason) return reason;
+    } else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|json)$/.test(entry.name) && !entry.name.endsWith("lock.json")) {
+      const reason = integrationFileReason(path2.relative(root, file), readFileSync2(file, "utf8"));
+      if (reason) return reason;
+    }
+  }
+  return void 0;
+}
+program.command("init").alias("create").description("Set up RevTurbine while preserving existing integrations: install missing packages, create a starter for a fresh integration, and install skills for one selected agent. Offers to start a new project when no package.json exists.").option("-d, --dir <path>", "Target directory (defaults to the current directory)").option("-y, --yes", "Skip prompts \u2014 create a new project non-interactively when the directory has none").option("--dry-run", "Report what would be installed without running the package manager").option("--no-skills", "Do not install the RevTurbine Agent Skills").option("--scaffold", "Create a missing root starter Playbook even when an integration exists; never overwrite a file").option("--agent <id>", `Install skills for one agent (${SUPPORTED_AGENTS.join(", ")}); overrides environment detection`).option("--json", "Emit the scaffold plan as JSON").action(async (opts) => {
+  if (opts.agent !== void 0 && !isAgentId(opts.agent)) {
+    fail(EXIT.USAGE, `unknown skills agent '${opts.agent}' \u2014 choose ${SUPPORTED_AGENTS.join(", ")}.`);
+  }
+  const harness = detectHarness(process.env, opts.agent !== void 0 && isAgentId(opts.agent) ? opts.agent : void 0);
   const dir = path2.resolve(opts.dir ?? process.cwd());
   const manifestPath = path2.join(dir, "package.json");
   let manifest;
@@ -11974,8 +12169,14 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
   for (const note of plan.skipped) diag(`\u2022 ${note}`);
   const playbookPath = path2.join(dir, STARTER_PLAYBOOK_FILENAME);
   const playbookExists = existsSync2(playbookPath);
-  if (playbookExists) diag(`\u2022 ${STARTER_PLAYBOOK_FILENAME} already present \u2014 left as-is`);
-  const installSkills = opts.skills !== false;
+  const integrationReason = playbookExists || opts.scaffold ? void 0 : declaredSdk(manifest) ? "@revturbine/sdk already declared" : findIntegration(dir);
+  const starter = planStarter({ rootExists: playbookExists, integrationReason, scaffold: opts.scaffold === true });
+  if (starter === "present") diag(`\u2022 ${STARTER_PLAYBOOK_FILENAME} already present \u2014 left as-is`);
+  if (starter === "skipped") diag(`\u2022 Skipping starter Playbook: ${integrationReason}. Use --scaffold to create a missing ${STARTER_PLAYBOOK_FILENAME}.`);
+  const skillsArgs = opts.skills !== false && harness.agentId ? skillsAddArgs(harness.agentId) : null;
+  if (opts.skills !== false && !harness.agentId) {
+    diag(`\u2022 Skipping Agent Skills: no supported agent detected. Choose a target, for example: revturbine init --agent codex (${SUPPORTED_AGENTS.join(", ")}).`);
+  }
   if (opts.json) {
     emit(
       {
@@ -11985,8 +12186,9 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
         stack,
         install: plan.install,
         skipped: plan.skipped,
-        playbook: playbookExists ? "present" : STARTER_PLAYBOOK_FILENAME,
-        skills: installSkills ? SKILLS_SOURCE : "skipped"
+        playbook: starter === "create" ? STARTER_PLAYBOOK_FILENAME : starter,
+        skills: skillsArgs ? SKILLS_SOURCE : "skipped",
+        skills_agent: skillsArgs ? harness.agentId : null
       },
       true
     );
@@ -11996,9 +12198,9 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
     for (const step of plan.install) {
       diag(`would run: ${manager.name} ${installArgs(manager.name, step).join(" ")}`);
     }
-    if (!playbookExists) diag(`would write: ${STARTER_PLAYBOOK_FILENAME}`);
-    if (installSkills) diag(`would run: npx ${skillsAddArgs().join(" ")}`);
-    if (plan.install.length === 0 && playbookExists) diag("\u2713 Already set up \u2014 nothing to do.");
+    if (starter === "create") diag(`would write: ${STARTER_PLAYBOOK_FILENAME}`);
+    if (skillsArgs) diag(`would run: npx ${skillsArgs.join(" ")}`);
+    if (plan.install.length === 0 && starter !== "create" && !skillsArgs) diag("\u2713 No setup changes planned.");
     return;
   }
   for (const step of plan.install) {
@@ -12015,7 +12217,7 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
   if (plan.install.length > 0) {
     diag(`\u2713 Installed the RevTurbine SDK and CLI (CLI pinned to ${pkgVersion})`);
   }
-  const playbookAdded = !playbookExists;
+  const playbookAdded = starter === "create";
   if (playbookAdded) {
     const check = validatePlaybook(STARTER_PLAYBOOK);
     if (!check.ok) {
@@ -12025,13 +12227,13 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
       );
     }
     writeFileSync2(playbookPath, `${JSON.stringify(STARTER_PLAYBOOK, null, 2)}
-`, "utf8");
+`, { encoding: "utf8", flag: "wx" });
     diag(`\u2713 Added a starter playbook (${STARTER_PLAYBOOK_FILENAME} \u2014 local mode, no account needed)`);
   }
-  let skillsOutcome = installSkills ? "installed" : "skipped";
-  if (installSkills) {
+  let skillsOutcome = skillsArgs ? "installed" : opts.skills === false ? "skipped" : "unknown";
+  if (skillsArgs) {
     diag("Installing the RevTurbine Agent Skills (npx skills)\u2026");
-    const args = skillsAddArgs();
+    const args = skillsArgs;
     let code;
     try {
       code = await runInstall("npx", args, dir);
@@ -12045,7 +12247,7 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
       diag("\u26A0 Could not install the Agent Skills automatically. Add them by hand:");
       diag(`    npx ${args.join(" ")}`);
     }
-  } else {
+  } else if (opts.skills === false) {
     diag("\u2022 Skipping the Agent Skills (--no-skills)");
   }
   if (!opts.json) {
@@ -12055,7 +12257,7 @@ program.command("init").alias("create").description("Scaffold RevTurbine into th
       cliVersion: pkgVersion,
       playbookAdded,
       skills: skillsOutcome,
-      harness: detectHarness(process.env)
+      harness
     });
     process.stdout.write(`${lines.join("\n")}
 `);
@@ -12579,7 +12781,18 @@ analyticsConnectionOptions(
   emitAnalyticsResult(conn, "analytics query", result, opts.json);
 });
 var ingestKeys = program.command("ingest-keys").description("Manage public ingest keys (embeddable SDK telemetry credentials) for the tenant.");
-ingestKeys.command("create").description("Mint a public ingest key. The full token is printed ONCE and cannot be retrieved again.").requiredOption("--origin <url...>", "Allowed browser origin(s), e.g. https://app.example.com (repeatable; at least one required)").option("--ip <cidr...>", "Optional IP / CIDR allowlist (empty = no IP restriction)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output (token on stdout for scripted capture)").action(async (opts) => {
+ingestKeys.command("create").alias("mint").description("Mint a public ingest key. The full token is printed ONCE and cannot be retrieved again.").requiredOption("--origin <url...>", "Allowed browser origin(s), e.g. https://app.example.com (repeatable; at least one required)").option("--ip <cidr...>", "Optional IP / CIDR allowlist (empty = no IP restriction)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output (token on stdout for scripted capture)").addHelpText(
+  "after",
+  [
+    "",
+    "Examples:",
+    "  revturbine ingest-keys mint --origin https://app.example.com",
+    "  revturbine ingest-keys create --origin https://app.example.com --ip 203.0.113.0/24 --json",
+    "",
+    "The full token is returned only by this command. Store it securely or",
+    "capture --json output, and revoke it by id when the integration or test ends."
+  ].join("\n")
+).action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
   const result = await createIngestKey(conn.url, conn.headers, { originAllowlist: opts.origin, ipAllowlist: opts.ip });
   if (!result.ok || !result.key) httpFail(conn, "ingest-keys create", result.status, result.error);
@@ -12617,6 +12830,69 @@ ingestKeys.command("revoke").description("Revoke a public ingest key by id. The
   if (!result.ok) httpFail(conn, "ingest-keys revoke", result.status);
   diag(`\u2713 Revoked ingest key ${id}.`);
 });
+var events = program.command("events").description("Send analytics events to the RevTurbine ingest pipeline.");
+events.command("track").description("Ingest a batch of analytics events from a file or inline JSON.").option("-f, --file <path>", 'Batch file: JSON array, { "events": [...] } envelope, or NDJSON').option("-e, --event <json>", "A single event as inline JSON").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (selects among your tenants; defaults to the stored token tenant)").option("--json", "Machine-readable per-batch results").addHelpText(
+  "after",
+  [
+    "",
+    "Examples:",
+    "  revturbine events track --file ./events.ndjson",
+    "  revturbine events track --file ./batch.json --json",
+    `  revturbine events track --event '{"environment_id":"production","user_id":"u1","account_id":"a1","event_name":"product_used","event_ts":"2026-09-10T00:00:00.000Z"}'`,
+    "",
+    `Every event needs environment_id, user_id, account_id, event_name and`,
+    `event_ts. Batches larger than ${MAX_EVENTS_PER_BATCH} are chunked automatically.`,
+    "",
+    "This authenticates with your device-auth token, so it needs no ingest key",
+    "and no browser origin. Quarantined and rejected counts are always reported",
+    'separately from accepted \u2014 a load is not "clean" because it returned 202.'
+  ].join("\n")
+).action(async (opts) => {
+  if (!opts.file && !opts.event) fail(EXIT.USAGE, "events track needs --file <path> or --event <json>");
+  if (opts.file && opts.event) fail(EXIT.USAGE, "events track takes --file or --event, not both");
+  let text;
+  if (opts.file) {
+    try {
+      text = readFileSync2(path2.resolve(opts.file), "utf8");
+    } catch (err) {
+      fail(EXIT.USAGE, `cannot read ${opts.file}: ${err.message}`);
+    }
+  } else {
+    text = opts.event;
+  }
+  const parsed = parseEventBatch(text);
+  if (parsed.errors.length > 0) {
+    for (const e of parsed.errors) diagRaw(`  ${e}`);
+    fail(EXIT.VALIDATION, `${parsed.errors.length} event(s) failed local validation; nothing was sent`);
+  }
+  if (parsed.events.length === 0) fail(EXIT.VALIDATION, "no events to send");
+  const conn = connect(opts.url, opts.tenantId);
+  const chunks = chunkEvents(parsed.events);
+  const results = [];
+  for (const [i, chunk] of chunks.entries()) {
+    if (chunks.length > 1 && !opts.json) {
+      diag(`sending batch ${i + 1}/${chunks.length} (${chunk.length} event(s))\u2026`);
+    }
+    let posted;
+    try {
+      posted = await postBatch(conn.url, conn.headers, chunk);
+    } catch (err) {
+      if (isNetworkError(err)) {
+        fail(EXIT.NETWORK, `network failure reaching ${conn.url}: ${err.message}`);
+      }
+      throw err;
+    }
+    if (!posted.ok || !posted.result) {
+      if (results.length > 0) {
+        diag(`${summarize(results, parsed.events.length).accepted} event(s) were accepted before this failure.`);
+      }
+      httpFail(conn, `events track (batch ${i + 1}/${chunks.length})`, posted.status, posted.error);
+    }
+    results.push(posted.result);
+  }
+  const summary = summarize(results, parsed.events.length);
+  emit(summary, !!opts.json, formatSummary(summary));
+});
 var COMMAND_EXAMPLES = {
   download: [
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "revturbine — validate RevTurbine Playbooks and ship them to a RevTurbine instance through the playbook-version lifecycle (draft → Release).",
   "license": "MIT",
   "repository": {