@owlmetry/cli 0.1.7 → 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adapted Hub LLC
+
+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/dist/index.cjs

@@ -1169,7 +1169,7 @@ var require_command = __commonJS({
     var EventEmitter = require("events").EventEmitter;
     var childProcess = require("child_process");
     var path = require("path");
-    var fs = require("fs");
+    var fs2 = require("fs");
     var process3 = require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -2150,7 +2150,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs.existsSync(executableFile)) return;
+        if (fs2.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -2169,10 +2169,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path.resolve(baseDir, baseName);
-          if (fs.existsSync(localBin)) return localBin;
+          if (fs2.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs.existsSync(`${localBin}${ext}`)
+            (ext) => fs2.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -2184,7 +2184,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs2.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
@@ -6360,11 +6360,12 @@ var METRIC_PHASES = ["start", "complete", "fail", "cancel", "record"];
 init_cjs_shims();
 
 // src/commands/apps.ts
-var appsCommand = new Command("apps").description("List apps").option("--project <id>", "Filter by project ID").action(async (opts, cmd) => {
+var appsCommand = new Command("apps").description("Manage apps");
+appsCommand.command("list").description("List apps").option("--project-id <id>", "Filter by project ID").action(async (opts, cmd) => {
   const { client, globals } = createClient(cmd);
   let apps = await client.listApps();
-  if (opts.project) {
-    apps = apps.filter((a) => a.project_id === opts.project);
+  if (opts.projectId) {
+    apps = apps.filter((a) => a.project_id === opts.projectId);
   }
   output(globals.format, apps, () => formatAppsTable(apps));
 });
@@ -6454,6 +6455,7 @@ function formatMetricEventsLog(events, slug) {
 
 // src/utils/parse.ts
 init_cjs_shims();
+var import_node_fs2 = __toESM(require("fs"), 1);
 function parsePositiveInt(value, flagName) {
   const n = parseInt(value, 10);
   if (Number.isNaN(n) || n <= 0) {
@@ -6461,6 +6463,34 @@ function parsePositiveInt(value, flagName) {
   }
   return n;
 }
+function resolveJsonArray(inline, filePath, opts) {
+  if (inline && filePath) {
+    return "Error: --steps and --steps-file are mutually exclusive";
+  }
+  if (!inline && !filePath) {
+    return opts.required ? "Error: either --steps or --steps-file is required" : "";
+  }
+  let json;
+  if (filePath) {
+    try {
+      json = import_node_fs2.default.readFileSync(filePath, "utf-8");
+    } catch (err) {
+      return `Error reading --steps-file: ${err.message}`;
+    }
+  } else {
+    json = inline;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return "Error: steps must be valid JSON";
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    return "Error: steps must be a non-empty JSON array";
+  }
+  return parsed;
+}
 
 // src/utils/time.ts
 init_cjs_shims();
@@ -6500,9 +6530,9 @@ ${source_default.dim(`More results available. Use --cursor ${result.cursor}`)}`;
 }
 
 // src/commands/events.ts
-var eventsCommand = new Command("events").description("Query events").option("--project <id>", "Filter by project ID").option("--app <id>", "Filter by app ID").option("--since <time>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <time>", "End time").addOption(
+var eventsCommand = new Command("events").description("Query events").option("--project-id <id>", "Filter by project ID").option("--app-id <id>", "Filter by app ID").option("--since <time>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <time>", "End time").addOption(
   new Option("--level <level>", "Filter by log level").choices(LOG_LEVELS)
-).option("--user <id>", "Filter by user ID").option("--session <id>", "Filter by session ID").option("--screen <name>", "Filter by screen name").addOption(
+).option("--user-id <id>", "Filter by user ID").option("--session-id <id>", "Filter by session ID").option("--screen-name <name>", "Filter by screen name").addOption(
   new Option("--limit <n>", "Max events to return").argParser((v) => parsePositiveInt(v, "--limit"))
 ).option("--cursor <cursor>", "Pagination cursor").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
@@ -6511,14 +6541,14 @@ var eventsCommand = new Command("events").description("Query events").option("--
   const since = opts.since ? parseTimeInput(opts.since) : !opts.until ? parseTimeInput("24h") : void 0;
   const until = opts.until ? parseTimeInput(opts.until) : void 0;
   const result = await client.queryEvents({
-    project_id: opts.project,
-    app_id: opts.app,
+    project_id: opts.projectId,
+    app_id: opts.appId,
     since,
     until,
     level: opts.level,
-    user_id: opts.user,
-    session_id: opts.session,
-    screen_name: opts.screen,
+    user_id: opts.userId,
+    session_id: opts.sessionId,
+    screen_name: opts.screenName,
     limit: opts.limit,
     cursor: opts.cursor,
     data_mode: opts.dataMode
@@ -6753,14 +6783,15 @@ function formatQueryResult(result) {
   }
   return lines.join("\n");
 }
-var metricsCommand = new Command("metrics").description("List metric definitions").requiredOption("--project <id>", "Project ID").action(async (opts, cmd) => {
+var metricsCommand = new Command("metrics").description("Manage metric definitions");
+metricsCommand.command("list").description("List metric definitions").requiredOption("--project-id <id>", "Project ID").action(async (opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const metrics = await client.listMetrics(opts.project);
+  const metrics = await client.listMetrics(opts.projectId);
   output(globals.format, metrics, () => formatMetricsTable(metrics));
 });
-metricsCommand.command("events <slug>").description("Query raw metric events for a metric").requiredOption("--project <id>", "Project ID").addOption(
+metricsCommand.command("events <slug>").description("Query raw metric events for a metric").requiredOption("--project-id <id>", "Project ID").addOption(
   new Option("--phase <phase>", "Filter by phase").choices(METRIC_PHASES)
-).option("--tracking-id <id>", "Filter by tracking ID").option("--user <id>", "Filter by user ID").option("--since <time>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <time>", "End time").addOption(
+).option("--tracking-id <id>", "Filter by tracking ID").option("--user-id <id>", "Filter by user ID").option("--since <time>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <time>", "End time").addOption(
   new Option("--limit <n>", "Max events to return").argParser((v) => parsePositiveInt(v, "--limit"))
 ).option("--cursor <cursor>", "Pagination cursor").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
@@ -6768,10 +6799,10 @@ metricsCommand.command("events <slug>").description("Query raw metric events for
   const { client, globals } = createClient(cmd);
   const since = opts.since ? parseTimeInput(opts.since) : !opts.until ? parseTimeInput("24h") : void 0;
   const until = opts.until ? parseTimeInput(opts.until) : void 0;
-  const result = await client.queryMetricEvents(slug, opts.project, {
+  const result = await client.queryMetricEvents(slug, opts.projectId, {
     phase: opts.phase,
     tracking_id: opts.trackingId,
-    user_id: opts.user,
+    user_id: opts.userId,
     environment: opts.environment,
     since,
     until,
@@ -6787,12 +6818,12 @@ metricsCommand.command("events <slug>").description("Query raw metric events for
     () => formatMetricEventsLog(result.events, slug) + hint
   );
 });
-metricsCommand.command("view <slug>").description("View metric definition details").requiredOption("--project <id>", "Project ID").action(async (slug, opts, cmd) => {
+metricsCommand.command("view <slug>").description("View metric definition details").requiredOption("--project-id <id>", "Project ID").action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const metric = await client.getMetric(slug, opts.project);
+  const metric = await client.getMetric(slug, opts.projectId);
   output(globals.format, metric, () => formatMetricDetail(metric));
 });
-metricsCommand.command("create").description("Create a new metric definition").requiredOption("--project <id>", "Project ID").requiredOption("--name <name>", "Metric name").requiredOption("--slug <slug>", "Metric slug").option("--description <desc>", "Description").option("--docs <markdown>", "Documentation (markdown)").option("--lifecycle", "Mark as lifecycle metric (has start/complete/fail phases)").action(async (opts, cmd) => {
+metricsCommand.command("create").description("Create a new metric definition").requiredOption("--project-id <id>", "Project ID").requiredOption("--name <name>", "Metric name").requiredOption("--slug <slug>", "Metric slug").option("--description <desc>", "Description").option("--docs <markdown>", "Documentation (markdown)").option("--lifecycle", "Mark as lifecycle metric (has start/complete/fail phases)").action(async (opts, cmd) => {
   const slugError = validateMetricSlug(opts.slug);
   if (slugError) {
     console.error(source_default.red(`Error: ${slugError}`));
@@ -6800,7 +6831,7 @@ metricsCommand.command("create").description("Create a new metric definition").r
     return;
   }
   const { client, globals } = createClient(cmd);
-  const metric = await client.createMetric(opts.project, {
+  const metric = await client.createMetric(opts.projectId, {
     name: opts.name,
     slug: opts.slug,
     description: opts.description,
@@ -6809,36 +6840,36 @@ metricsCommand.command("create").description("Create a new metric definition").r
   });
   output(globals.format, metric, () => formatMetricDetail(metric));
 });
-metricsCommand.command("query <slug>").description("Query metric aggregation").requiredOption("--project <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--app <id>", "Filter by app ID").option("--app-version <version>", "Filter by app version").option("--device-model <model>", "Filter by device model").option("--os-version <version>", "Filter by OS version").option("--user <id>", "Filter by user ID").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--group-by <field>", "Group by: app_id, app_version, device_model, os_version, environment, time:hour, time:day, time:week").addOption(
+metricsCommand.command("query <slug>").description("Query metric aggregation").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--app-id <id>", "Filter by app ID").option("--app-version <version>", "Filter by app version").option("--device-model <model>", "Filter by device model").option("--os-version <version>", "Filter by OS version").option("--user-id <id>", "Filter by user ID").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--group-by <field>", "Group by: app_id, app_version, device_model, os_version, environment, time:hour, time:day, time:week").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const result = await client.queryMetric(slug, opts.project, {
+  const result = await client.queryMetric(slug, opts.projectId, {
     since: opts.since,
     until: opts.until,
-    app_id: opts.app,
+    app_id: opts.appId,
     app_version: opts.appVersion,
     device_model: opts.deviceModel,
     os_version: opts.osVersion,
-    user_id: opts.user,
+    user_id: opts.userId,
     environment: opts.environment,
     data_mode: opts.dataMode,
     group_by: opts.groupBy
   });
   output(globals.format, result, () => formatQueryResult(result));
 });
-metricsCommand.command("update <slug>").description("Update a metric definition").requiredOption("--project <id>", "Project ID").option("--name <name>", "New name").option("--description <desc>", "New description").option("--status <status>", "active or paused").action(async (slug, opts, cmd) => {
+metricsCommand.command("update <slug>").description("Update a metric definition").requiredOption("--project-id <id>", "Project ID").option("--name <name>", "New name").option("--description <desc>", "New description").option("--status <status>", "active or paused").action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const metric = await client.updateMetric(slug, opts.project, {
+  const metric = await client.updateMetric(slug, opts.projectId, {
     name: opts.name,
     description: opts.description,
     status: opts.status
   });
   output(globals.format, metric, () => formatMetricDetail(metric));
 });
-metricsCommand.command("delete <slug>").description("Delete a metric definition").requiredOption("--project <id>", "Project ID").action(async (slug, opts, cmd) => {
+metricsCommand.command("delete <slug>").description("Delete a metric definition").requiredOption("--project-id <id>", "Project ID").action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  await client.deleteMetric(slug, opts.project);
+  await client.deleteMetric(slug, opts.projectId);
   console.log(source_default.green(`Metric "${slug}" deleted.`));
 });
 
@@ -6924,82 +6955,66 @@ function formatQueryResult2(result) {
   }
   return lines.join("\n");
 }
-var funnelsCommand = new Command("funnels").description("List funnel definitions").option("--project <id>", "Project ID").action(async (opts, cmd) => {
-  if (!opts.project) {
-    console.error(source_default.red("Error: --project is required"));
-    process.exitCode = 1;
-    return;
-  }
+var funnelsCommand = new Command("funnels").description("Manage funnel definitions");
+funnelsCommand.command("list").description("List funnel definitions").requiredOption("--project-id <id>", "Project ID").action(async (opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const result = await client.listFunnels(opts.project);
+  const result = await client.listFunnels(opts.projectId);
   output(globals.format, result.funnels, () => formatFunnelsTable(result.funnels));
 });
-funnelsCommand.command("view <slug>").description("View funnel definition details").requiredOption("--project <id>", "Project ID").action(async (slug, opts, cmd) => {
+funnelsCommand.command("view <slug>").description("View funnel definition details").requiredOption("--project-id <id>", "Project ID").action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const funnel = await client.getFunnel(slug, opts.project);
+  const funnel = await client.getFunnel(slug, opts.projectId);
   output(globals.format, funnel, () => formatFunnelDetail(funnel));
 });
-funnelsCommand.command("create").description("Create a new funnel definition").requiredOption("--project <id>", "Project ID").requiredOption("--name <name>", "Funnel name").requiredOption("--slug <slug>", "Funnel slug").option("--description <desc>", "Description").requiredOption("--steps <json>", "Steps as JSON array").action(async (opts, cmd) => {
+funnelsCommand.command("create").description("Create a new funnel definition").requiredOption("--project-id <id>", "Project ID").requiredOption("--name <name>", "Funnel name").requiredOption("--slug <slug>", "Funnel slug").option("--description <desc>", "Description").option("--steps <json>", "Steps as JSON array").option("--steps-file <path>", "Read steps from a JSON file").action(async (opts, cmd) => {
   const slugError = validateFunnelSlug(opts.slug);
   if (slugError) {
     console.error(source_default.red(`Error: ${slugError}`));
     process.exitCode = 1;
     return;
   }
-  let steps;
-  try {
-    steps = JSON.parse(opts.steps);
-  } catch {
-    console.error(source_default.red("Error: --steps must be valid JSON"));
-    process.exitCode = 1;
-    return;
-  }
-  if (!Array.isArray(steps) || steps.length === 0) {
-    console.error(source_default.red("Error: --steps must be a non-empty JSON array"));
+  const stepsResult = resolveJsonArray(opts.steps, opts.stepsFile, { required: true });
+  if (typeof stepsResult === "string") {
+    console.error(source_default.red(stepsResult));
     process.exitCode = 1;
     return;
   }
   const { client, globals } = createClient(cmd);
-  const funnel = await client.createFunnel(opts.project, {
+  const funnel = await client.createFunnel(opts.projectId, {
     name: opts.name,
     slug: opts.slug,
     description: opts.description,
-    steps
+    steps: stepsResult
   });
   output(globals.format, funnel, () => formatFunnelDetail(funnel));
 });
-funnelsCommand.command("update <slug>").description("Update a funnel definition").requiredOption("--project <id>", "Project ID").option("--name <name>", "New name").option("--description <desc>", "New description").option("--steps <json>", "New steps as JSON array").action(async (slug, opts, cmd) => {
+funnelsCommand.command("update <slug>").description("Update a funnel definition").requiredOption("--project-id <id>", "Project ID").option("--name <name>", "New name").option("--description <desc>", "New description").option("--steps <json>", "New steps as JSON array").option("--steps-file <path>", "Read steps from a JSON file").action(async (slug, opts, cmd) => {
   const body = {};
   if (opts.name !== void 0) body.name = opts.name;
   if (opts.description !== void 0) body.description = opts.description;
-  if (opts.steps !== void 0) {
-    try {
-      body.steps = JSON.parse(opts.steps);
-    } catch {
-      console.error(source_default.red("Error: --steps must be valid JSON"));
-      process.exitCode = 1;
-      return;
-    }
-    if (!Array.isArray(body.steps) || body.steps.length === 0) {
-      console.error(source_default.red("Error: --steps must be a non-empty JSON array"));
+  if (opts.steps || opts.stepsFile) {
+    const stepsResult = resolveJsonArray(opts.steps, opts.stepsFile, { required: false });
+    if (typeof stepsResult === "string") {
+      console.error(source_default.red(stepsResult));
       process.exitCode = 1;
       return;
     }
+    body.steps = stepsResult;
   }
   const { client, globals } = createClient(cmd);
-  const funnel = await client.updateFunnel(slug, opts.project, body);
+  const funnel = await client.updateFunnel(slug, opts.projectId, body);
   output(globals.format, funnel, () => formatFunnelDetail(funnel));
 });
-funnelsCommand.command("delete <slug>").description("Delete a funnel definition").requiredOption("--project <id>", "Project ID").action(async (slug, opts, cmd) => {
+funnelsCommand.command("delete <slug>").description("Delete a funnel definition").requiredOption("--project-id <id>", "Project ID").action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  await client.deleteFunnel(slug, opts.project);
+  await client.deleteFunnel(slug, opts.projectId);
   console.log(source_default.green(`Funnel "${slug}" deleted.`));
 });
-funnelsCommand.command("query <slug>").description("Query funnel analytics").requiredOption("--project <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--open", "Make this an open funnel. In an open funnel, users don't have to complete a previous step in order to be included in a subsequent step.").option("--app-version <version>", "Filter by app version").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--experiment <name:variant>", "Filter by experiment (format: name:variant)").option("--group-by <field>", "Group by: environment, app_version, or experiment:<name>").addOption(
+funnelsCommand.command("query <slug>").description("Query funnel analytics").requiredOption("--project-id <id>", "Project ID").option("--since <date>", "Start date (ISO)").option("--until <date>", "End date (ISO)").option("--open", "Make this an open funnel. In an open funnel, users don't have to complete a previous step in order to be included in a subsequent step.").option("--app-version <version>", "Filter by app version").option("--environment <env>", "Filter by environment (ios, ipados, macos, android, web, backend)").option("--experiment <name:variant>", "Filter by experiment (format: name:variant)").option("--group-by <field>", "Group by: environment, app_version, or experiment:<name>").addOption(
   new Option("--data-mode <mode>", "Data mode: production, development, or all").choices(["production", "development", "all"]).default("production")
 ).action(async (slug, opts, cmd) => {
   const { client, globals } = createClient(cmd);
-  const result = await client.queryFunnel(slug, opts.project, {
+  const result = await client.queryFunnel(slug, opts.projectId, {
     since: opts.since,
     until: opts.until,
     mode: opts.open ? "open" : "closed",
@@ -7015,7 +7030,7 @@ funnelsCommand.command("query <slug>").description("Query funnel analytics").req
 // src/commands/audit-logs.ts
 init_cjs_shims();
 var auditLogCommand = new Command("audit-log").description("View audit logs");
-auditLogCommand.command("list").description("List audit log entries").requiredOption("--team <id>", "Team ID").option("--resource-type <type>", "Filter by resource type").option("--resource-id <id>", "Filter by resource ID").option("--actor <id>", "Filter by actor ID").addOption(
+auditLogCommand.command("list").description("List audit log entries").requiredOption("--team-id <id>", "Team ID").option("--resource-type <type>", "Filter by resource type").option("--resource-id <id>", "Filter by resource ID").option("--actor-id <id>", "Filter by actor ID").addOption(
   new Option("--action <action>", "Filter by action").choices(["create", "update", "delete"])
 ).option("--since <time>", "Start time (e.g. 1h, 30m, 7d, or ISO 8601)").option("--until <time>", "End time").addOption(
   new Option("--limit <n>", "Max entries to return").argParser((v) => parsePositiveInt(v, "--limit"))
@@ -7023,10 +7038,10 @@ auditLogCommand.command("list").description("List audit log entries").requiredOp
   const { client, globals } = createClient(cmd);
   const since = opts.since ? parseTimeInput(opts.since) : void 0;
   const until = opts.until ? parseTimeInput(opts.until) : void 0;
-  const result = await client.queryAuditLogs(opts.team, {
+  const result = await client.queryAuditLogs(opts.teamId, {
     resource_type: opts.resourceType,
     resource_id: opts.resourceId,
-    actor_id: opts.actor,
+    actor_id: opts.actorId,
     action: opts.action,
     since,
     until,
@@ -7053,7 +7068,7 @@ auditLogCommand.command("list").description("List audit log entries").requiredOp
 
 // src/commands/skills.ts
 init_cjs_shims();
-var import_node_fs2 = require("fs");
+var import_node_fs3 = require("fs");
 var import_node_path2 = require("path");
 var import_node_url = require("url");
 var SKILLS = [
@@ -7065,7 +7080,7 @@ var skillsCommand = new Command("skills").description("Show paths to AI skill fi
   const __filename2 = (0, import_node_url.fileURLToPath)(importMetaUrl);
   const __dirname = (0, import_node_path2.dirname)(__filename2);
   const skillsDir = (0, import_node_path2.resolve)(__dirname, "skills");
-  if (!(0, import_node_fs2.existsSync)(skillsDir)) {
+  if (!(0, import_node_fs3.existsSync)(skillsDir)) {
     console.error(
       source_default.red("Skills directory not found. This may indicate a broken installation.")
     );
@@ -7076,7 +7091,7 @@ var skillsCommand = new Command("skills").description("Show paths to AI skill fi
   for (const skill of SKILLS) {
     const skillPath = (0, import_node_path2.join)(skillsDir, skill.dir, "SKILL.md");
     const label = skill.label.padEnd(maxLabelLen);
-    if ((0, import_node_fs2.existsSync)(skillPath)) {
+    if ((0, import_node_fs3.existsSync)(skillPath)) {
       console.log(`  ${source_default.cyan(label)}  ${skillPath}`);
     } else {
       console.log(`  ${source_default.cyan(label)}  ${source_default.dim("(not found)")}`);
@@ -7183,7 +7198,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.7").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.9").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
   new Option("--format <format>", "Output format").choices(["table", "json", "log"]).default("table")
 ).option("--endpoint <url>", "OwlMetry API server URL").option("--api-key <key>", "API key").option("--ingest-endpoint <url>", "OwlMetry ingest endpoint URL (for SDKs; defaults to API endpoint for self-hosted)").option("--team <name-or-id>", "Use a specific team profile for this command");
 program2.addCommand(authCommand);

package/dist/skills/owlmetry-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-cli
-version: 0.1.7
+version: 0.1.9
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
@@ -134,8 +134,8 @@ owlmetry projects update <id> --name <new-name> --format json
 An app represents a single deployable target. The `client_key` returned on creation is what SDKs use for event ingestion. The `bundle_id` is **immutable after creation** — to change it, delete and recreate the app. Backend apps have no bundle_id.
 
 ```bash
-owlmetry apps --format json                                            # List all
-owlmetry apps --project <id> --format json                             # List by project
+owlmetry apps list --format json                                       # List all
+owlmetry apps list --project-id <id> --format json                     # List by project
 owlmetry apps view <id> --format json                                  # View details
 owlmetry apps create --project-id <id> --name <name> --platform <platform> [--bundle-id <id>] --format json
 owlmetry apps update <id> --name <new-name> --format json
@@ -155,11 +155,11 @@ Metrics are project-scoped definitions that tell OwlMetry what structured data t
 The metric definition must exist on the server **before** the SDK emits events for that slug, otherwise the server will reject the events.
 
 ```bash
-owlmetry metrics --project <id> --format json                          # List all
-owlmetry metrics view <slug> --project <id> --format json              # View details
-owlmetry metrics create --project <id> --name <name> --slug <slug> [--lifecycle] [--description <desc>] --format json
-owlmetry metrics update <slug> --project <id> [--name <name>] [--status active|paused] --format json
-owlmetry metrics delete <slug> --project <id>
+owlmetry metrics list --project-id <id> --format json                   # List all
+owlmetry metrics view <slug> --project-id <id> --format json           # View details
+owlmetry metrics create --project-id <id> --name <name> --slug <slug> [--lifecycle] [--description <desc>] --format json
+owlmetry metrics update <slug> --project-id <id> [--name <name>] [--status active|paused] --format json
+owlmetry metrics delete <slug> --project-id <id>
 ```
 
 Slugs: lowercase letters, numbers, hyphens only (`/^[a-z0-9-]+$/`).
@@ -177,13 +177,34 @@ Funnels support two analysis modes:
 Maximum 20 steps per funnel.
 
 ```bash
-owlmetry funnels --project <id> --format json                          # List all
-owlmetry funnels view <slug> --project <id> --format json              # View details
-owlmetry funnels create --project <id> --name <name> --slug <slug> --steps '<json>' [--description <desc>] --format json
-owlmetry funnels update <slug> --project <id> [--name <name>] [--steps '<json>'] --format json
-owlmetry funnels delete <slug> --project <id>
+owlmetry funnels list --project-id <id> --format json                   # List all
+owlmetry funnels view <slug> --project-id <id> --format json           # View details
+owlmetry funnels delete <slug> --project-id <id>
 ```
 
+**Creating funnels** — use `--steps-file` to avoid shell quoting issues with JSON:
+
+```bash
+# 1. Write steps to a JSON file
+cat > /tmp/funnel-steps.json << 'EOF'
+[
+  {"name": "Step Name", "event_filter": {"message": "track:step-name"}},
+  {"name": "Next Step", "event_filter": {"message": "track:next-step"}}
+]
+EOF
+
+# 2. Create the funnel referencing the file
+owlmetry funnels create --project-id <id> --name <name> --slug <slug> \
+  --steps-file /tmp/funnel-steps.json [--description <desc>] --format json
+```
+
+**Updating funnel steps** — same pattern:
+```bash
+owlmetry funnels update <slug> --project-id <id> --steps-file /tmp/updated-steps.json --format json
+```
+
+Inline `--steps '<json>'` also works but is error-prone in shell environments due to JSON quoting. Prefer `--steps-file`.
+
 Steps JSON format: `[{"name":"Step Name","event_filter":{"message":"track:step-name"}}]`
 
 ## Querying
@@ -193,7 +214,7 @@ Steps JSON format: `[{"name":"Step Name","event_filter":{"message":"track:step-n
 Events are the raw log records emitted by SDKs — every `Owl.info()`, `Owl.error()`, `Owl.track()`, etc. Query events when debugging specific issues, investigating user behavior, or reviewing what happened in a time window.
 
 ```bash
-owlmetry events [--project <id>] [--app <id>] [--since <time>] [--until <time>] [--level info|debug|warn|error] [--user <id>] [--session <id>] [--screen <name>] [--limit <n>] [--cursor <cursor>] [--data-mode production|development|all] --format json
+owlmetry events [--project-id <id>] [--app-id <id>] [--since <time>] [--until <time>] [--level info|debug|warn|error] [--user-id <id>] [--session-id <id>] [--screen-name <name>] [--limit <n>] [--cursor <cursor>] [--data-mode production|development|all] --format json
 owlmetry events view <id> --format json
 ```
 
@@ -225,8 +246,8 @@ There are two ways to look at metric data:
 - **`metrics query`** — aggregated statistics (count, avg/p50/p95/p99 duration, error rate), useful for spotting trends and regressions. Supports grouping by app, version, environment, device, or time bucket.
 
 ```bash
-owlmetry metrics events <slug> --project <id> [--phase start|complete|fail|cancel|record] [--tracking-id <id>] [--user <id>] [--since <time>] [--until <time>] [--environment <env>] [--data-mode <mode>] --format json
-owlmetry metrics query <slug> --project <id> [--since <date>] [--until <date>] [--app <id>] [--app-version <v>] [--environment <env>] [--user <id>] [--group-by app_id|app_version|device_model|os_version|environment|time:hour|time:day|time:week] [--data-mode <mode>] --format json
+owlmetry metrics events <slug> --project-id <id> [--phase start|complete|fail|cancel|record] [--tracking-id <id>] [--user-id <id>] [--since <time>] [--until <time>] [--environment <env>] [--data-mode <mode>] --format json
+owlmetry metrics query <slug> --project-id <id> [--since <date>] [--until <date>] [--app-id <id>] [--app-version <v>] [--environment <env>] [--user-id <id>] [--group-by app_id|app_version|device_model|os_version|environment|time:hour|time:day|time:week] [--data-mode <mode>] --format json
 ```
 
 ### Funnel Analytics
@@ -234,7 +255,7 @@ owlmetry metrics query <slug> --project <id> [--since <date>] [--until <date>] [
 Funnel queries return conversion rates and drop-off between steps. The output shows how many users entered each step and what percentage continued to the next. Use `--group-by` to segment results and compare conversion across environments, app versions, or A/B experiment variants.
 
 ```bash
-owlmetry funnels query <slug> --project <id> [--since <date>] [--until <date>] [--open] [--app-version <v>] [--environment <env>] [--experiment <name:variant>] [--group-by environment|app_version|experiment:<name>] [--data-mode <mode>] --format json
+owlmetry funnels query <slug> --project-id <id> [--since <date>] [--until <date>] [--open] [--app-version <v>] [--environment <env>] [--experiment <name:variant>] [--group-by environment|app_version|experiment:<name>] [--data-mode <mode>] --format json
 ```
 
 `--open` = open funnel mode (steps evaluated independently, not sequentially).
@@ -244,7 +265,7 @@ owlmetry funnels query <slug> --project <id> [--since <date>] [--until <date>] [
 Audit logs record who performed what action on which resource — creating an app, revoking an API key, changing a team member's role, etc. Query them when investigating configuration changes or tracking administrative activity. Requires `audit_logs:read` permission on the agent key (included in default agent key permissions).
 
 ```bash
-owlmetry audit-log list --team <id> [--resource-type <type>] [--resource-id <id>] [--actor <id>] [--action create|update|delete] [--since <time>] [--until <time>] [--limit <n>] --format json
+owlmetry audit-log list --team-id <id> [--resource-type <type>] [--resource-id <id>] [--actor-id <id>] [--action create|update|delete] [--since <time>] [--until <time>] [--limit <n>] --format json
 ```
 
 ## Key Notes

package/dist/skills/owlmetry-node/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.7
+version: 0.1.9
 description: >-
   Integrate the OwlMetry Node.js SDK into a backend service for server-side
   analytics, event tracking, metrics, funnels, and A/B experiments. Use when
@@ -206,7 +206,7 @@ op.cancel({ reason: 'timeout' });
 
 `duration_ms` and `tracking_id` (UUID) are auto-added. Create the metric definition first:
 ```bash
-owlmetry metrics create --project <id> --name "Database Query" --slug database-query --lifecycle --format json
+owlmetry metrics create --project-id <id> --name "Database Query" --slug database-query --lifecycle --format json
 ```
 
 ### Single-shot measurements

package/dist/skills/owlmetry-swift/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.7
+version: 0.1.9
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -272,9 +272,18 @@ Owl.track("first-post")
 
 Each `track()` call emits an info-level event with message `"track:<stepName>"`. Define matching funnel definitions via `/owlmetry-cli`:
 ```bash
-owlmetry funnels create --project <id> --name "Onboarding" --slug onboarding \
-  --steps '[{"name":"Welcome","event_filter":{"message":"track:welcome-screen"}},{"name":"Account","event_filter":{"message":"track:create-account"}},{"name":"Profile","event_filter":{"message":"track:complete-profile"}},{"name":"First Post","event_filter":{"message":"track:first-post"}}]' \
-  --format json
+# Write steps to a JSON file (avoids shell quoting issues)
+cat > /tmp/funnel-steps.json << 'EOF'
+[
+  {"name": "Welcome", "event_filter": {"message": "track:welcome-screen"}},
+  {"name": "Account", "event_filter": {"message": "track:create-account"}},
+  {"name": "Profile", "event_filter": {"message": "track:complete-profile"}},
+  {"name": "First Post", "event_filter": {"message": "track:first-post"}}
+]
+EOF
+
+owlmetry funnels create --project-id <id> --name "Onboarding" --slug onboarding \
+  --steps-file /tmp/funnel-steps.json --format json
 ```
 
 ## Structured Metrics
@@ -302,9 +311,47 @@ op.fail(error: "timeout", attributes: ["retry_count": "3"])
 op.cancel(attributes: ["reason": "user_cancelled"])
 ```
 
-`duration_ms` and `tracking_id` (UUID) are auto-added. Create the metric definition first:
+`duration_ms` and `tracking_id` (UUID) are auto-added.
+
+**Rules for lifecycle operations:**
+
+- **Every `startOperation()` must end** with exactly one `.complete()`, `.fail()`, or `.cancel()`. An operation that starts but never ends creates orphaned metric data with no duration.
+- **`.complete()`** — the operation succeeded and produced its intended result.
+- **`.fail(error:)`** — the operation attempted work but encountered an error.
+- **`.cancel()`** — the operation was intentionally stopped before completion (user cancelled, view disappeared, became irrelevant).
+- **Don't start for no-ops** — if the operation is skipped entirely (cache hit, dedup, precondition not met), don't call `startOperation()` at all. Only start when actual work begins.
+- **Don't track duration manually** — `duration_ms` is auto-calculated from start to complete/fail/cancel. Never pass a manual duration attribute.
+- **Long-lived operations** — if the operation outlives the scope where it was started (e.g., recording that spans a view lifecycle), store the `OwlOperation` handle as a property. Cancel it on cleanup (`.onDisappear`, `deinit`) if it hasn't ended yet:
+
+```swift
+// Store handle for operations that span a lifecycle
+@State private var recordingOp: OwlOperation?
+
+func startRecording() {
+    recordingOp = Owl.startOperation("video-recording")
+    // ... begin recording
+}
+
+func stopRecording(url: URL) {
+    recordingOp?.complete(attributes: ["format": "mp4"])
+    recordingOp = nil
+}
+
+func onError(_ error: Error) {
+    recordingOp?.fail(error: error.localizedDescription)
+    recordingOp = nil
+}
+
+// Safety net: cancel if view disappears mid-operation
+.onDisappear {
+    recordingOp?.cancel()
+    recordingOp = nil
+}
+```
+
+Create the metric definition first:
 ```bash
-owlmetry metrics create --project <id> --name "Photo Upload" --slug photo-upload --lifecycle --format json
+owlmetry metrics create --project-id <id> --name "Photo Upload" --slug photo-upload --lifecycle --format json
 ```
 
 ### Single-shot measurements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "OwlMetry CLI — manage projects, apps, metrics, funnels, and events from the terminal. Includes AI skill files for agent-assisted development.",
   "type": "module",
   "license": "MIT",