@owlmetry/cli 0.1.6 → 0.1.8

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,11 @@ 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("List apps").enablePositionalOptions().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 +6454,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 +6462,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 +6529,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 +6540,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 +6782,14 @@ 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("List metric definitions").enablePositionalOptions().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 +6797,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 +6816,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 +6829,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 +6838,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 +6953,65 @@ 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("List funnel definitions").enablePositionalOptions().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 +7027,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 +7035,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 +7065,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 +7077,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 +7088,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 +7195,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.6").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.8").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,10 +1,12 @@
 ---
 name: owlmetry-cli
-version: 0.1.6
+version: 0.1.8
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
   analytics, or when another OwlMetry skill needs CLI setup as a prerequisite.
+  IMPORTANT: You MUST load this skill before running ANY `owlmetry` CLI
+  command. The CLI has non-obvious subcommand syntax and flags — do not guess.
 allowed-tools: Bash
 ---
 
@@ -14,11 +16,13 @@ OwlMetry is a self-hosted analytics platform for mobile and backend apps. It cap
 
 The **CLI** is the management and query tool — it does not ingest events. You use it to create projects and apps, define metrics and funnels, query event data, and view analytics. SDKs handle event ingestion using client keys (`owl_client_...`). The CLI uses agent keys (`owl_agent_...`) for reading data and managing resources.
 
+> **Do not guess CLI syntax.** The `owlmetry` command has specific subcommand patterns (e.g., `owlmetry apps` not `owlmetry apps list`, flags like `--format json` not `--message`). Always reference the command documentation in this skill file before running a command. If you haven't loaded this skill yet, load it first.
+
 ## Version Check
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update the local skill file.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update the local skill file.
 2. **CLI version** (if installed): compare `owlmetry --version` to `npm view @owlmetry/cli version 2>/dev/null`. If a newer version exists, offer `npm install -g @owlmetry/cli@latest`.
 
 If everything is current or the remote is unreachable, continue silently.
@@ -131,7 +135,7 @@ An app represents a single deployable target. The `client_key` returned on creat
 
 ```bash
 owlmetry apps --format json                                            # List all
-owlmetry apps --project <id> --format json                             # List by project
+owlmetry apps --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
@@ -151,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 --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-]+$/`).
@@ -173,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 --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
@@ -189,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
 ```
 
@@ -221,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
@@ -230,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).
@@ -240,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.6
+version: 0.1.8
 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
@@ -18,7 +18,7 @@ The SDK has zero runtime dependencies. All calls are non-blocking — events are
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: `npm ls @owlmetry/node --json 2>/dev/null` for current version, `npm view @owlmetry/node version 2>/dev/null` for latest. If newer, offer `npm install @owlmetry/node@latest`.
 
 ## Prerequisite
@@ -27,6 +27,8 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for a ba
 
 If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Install
 
 ```bash
@@ -62,13 +64,24 @@ Owl.configure({
 **Serverless (Firebase Cloud Functions, AWS Lambda, Vercel):** After adding `Owl.configure()`, also wrap your exported handler functions with `Owl.wrapHandler()` to guarantee events are flushed before the runtime freezes. This is essential boilerplate for serverless — without it, buffered events are lost:
 
 ```typescript
-// Before:
-export const myFunction = onCall(async (request) => { ... });
-
-// After:
-export const myFunction = onCall(Owl.wrapHandler(async (request) => { ... }));
+// AWS Lambda / generic serverless:
+export const handler = Owl.wrapHandler(async (event, context) => { ... });
+
+// Firebase Cloud Functions v2:
+// IMPORTANT: Explicitly type the request parameter — TypeScript cannot infer
+// the CallableRequest type through wrapHandler's generics.
+import { onCall, type CallableRequest } from 'firebase-functions/v2/https';
+
+export const myFunction = onCall(
+  Owl.wrapHandler(async (request: CallableRequest) => {
+    const { data, auth } = request;  // works — TypeScript knows the type
+    // ...
+  })
+);
 ```
 
+**TypeScript note:** `wrapHandler()` uses generic rest parameters (`<TArgs extends unknown[]>`), which means TypeScript sometimes infers handler parameters as `unknown` when the outer function (like Firebase's `onCall`) expects a specific callback type. If you see type errors like `Property 'data' does not exist on type 'unknown'`, explicitly annotate the handler's parameters (e.g., `request: CallableRequest`, `event: APIGatewayEvent`).
+
 ## Next Steps — Codebase Instrumentation
 
 Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these three options:
@@ -97,16 +110,21 @@ Events are the core data unit. Use the four log levels to capture different kind
 
 - **`info`** — normal operations: server started, request handled, job completed, user action processed.
 - **`debug`** — verbose detail for development: cache lookups, query plans, config loading, intermediate state.
-- **`warn`** — recoverable problems: slow queries, rate limits approaching, fallback paths, deprecated API usage.
-- **`error`** — failures: database connection errors, external API failures, unhandled rejections, missing resources.
+- **`warn`** — something didn't go as expected but the process can continue: failed validation, precondition checks that fail, slow queries, rate limits approaching, fallback paths, deprecated API usage, missing optional config.
+- **`error`** — a caught exception or hard failure inside a `try`/`catch`: database connection errors, external API timeouts, unhandled rejections, file system errors. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Payment processing failed"` over `"error occurred"`. Use attributes for structured data you'll filter on later.
 
 ```typescript
 Owl.info('Server started', { port: 4000 });
 Owl.debug('Cache miss', { key: 'user:123' });
-Owl.warn('Slow query', { duration_ms: 2500, table: 'events' });
-Owl.error('Database connection failed', { host: 'db.example.com' });
+Owl.warn('Invalid request payload', { field: 'email', reason: 'missing' });
+
+try {
+  await db.connect();
+} catch (err) {
+  Owl.error('Database connection failed', { host: 'db.example.com', error: String(err) });
+}
 ```
 
 All methods: `Owl.info/debug/warn/error(message: string, attrs?: Record<string, unknown>)`.
@@ -118,7 +136,12 @@ Source module (file:line) is auto-captured from the call stack.
 Owl.info('Request handled', { method: 'POST', path: '/api/orders', status: 201 });
 Owl.info('Background job completed', { job: 'send-emails', processed: 150 });
 Owl.warn('Rate limit approaching', { current: 95, limit: 100, client_id: 'abc' });
-Owl.error('External API timeout', { service: 'stripe', endpoint: '/charges', timeout_ms: 10000 });
+
+try {
+  await stripe.charges.create(params);
+} catch (err) {
+  Owl.error('Stripe charge failed', { endpoint: '/charges', error: String(err) });
+}
 ```
 
 ## Per-Request User Scoping
@@ -183,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
@@ -339,7 +362,8 @@ When instrumenting a backend service, follow this priority:
 **Always instrument (events — no CLI setup needed):**
 - Server startup and shutdown (`info`)
 - Request handling: key route hits, responses sent (`info` with method/path/status)
-- Errors and failures: catch blocks, unhandled rejections, external API failures (`error`)
+- Caught exceptions: catch blocks, unhandled rejections, external API failures (`error`)
+- Validation failures and pre-checks: bad input, missing optional config, rate limits (`warn`)
 - Authentication events: login, logout, token refresh (`info`)
 - Core business actions: order placed, payment processed, email sent (`info`)
 - Background jobs: started, completed, failed (`info`/`error`)

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.6
+version: 0.1.8
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -18,7 +18,7 @@ The SDK is a static `Owl` enum with no external dependencies. All calls are non-
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: Read `Package.resolved` for the current resolved revision, then compare against `curl -sf https://api.github.com/repos/Jasonvdb/owlmetry/releases/latest | jq -r .tag_name`. If newer, inform the user.
 
 ## Prerequisite
@@ -27,9 +27,16 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for an A
 
 If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Add Swift Package
 
-**Swift Package Manager (Package.swift):**
+**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+
+### Option A — Package.swift projects
+
+If the project has a `Package.swift`, add the dependency there:
+
 ```swift
 dependencies: [
     .package(url: "https://github.com/Jasonvdb/owlmetry.git", branch: "main")
@@ -42,29 +49,31 @@ Add to your target:
 ])
 ```
 
-**Xcode:** File > Add Package Dependencies > enter `https://github.com/Jasonvdb/owlmetry.git`, select branch `main`, add `OwlMetry` to your target.
+Then run `swift package resolve` to fetch the dependency.
 
-**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+### Option B — Xcode projects (.xcodeproj)
 
-## Verify Package Integration
+For `.xcodeproj`-based projects with no `Package.swift`, add the OwlMetry Swift package by editing `<Project>.xcodeproj/project.pbxproj` directly to add a remote Swift package reference for `https://github.com/Jasonvdb/owlmetry.git` (branch: `main`, product: `OwlMetry`). Do not ask the user to add it manually in Xcode.
 
-After adding the package, build the project to verify the dependency resolves and `import OwlMetry` compiles. Do not proceed with configuration until the build succeeds.
+### Option C — Ask the user (last resort)
 
-If the build fails with a "No such module 'OwlMetry'" error, ask the user to add the package manually in Xcode:
+If pbxproj editing fails or the project structure is too complex, ask the user to add the package in Xcode:
 
-1. Open the `.xcodeproj` or `.xcworkspace` in Xcode
-2. Select the project in the navigator (blue icon at the top)
-3. Select the app target under "Targets"
-4. Go to the "General" tab
-5. Scroll to "Frameworks, Libraries, and Embedded Content"
-6. Click the **+** button
-7. Click "Add Other…" > "Add Package Dependency…"
-8. Enter the URL: `https://github.com/Jasonvdb/owlmetry.git`
-9. Set "Dependency Rule" to **Branch** → `main`
-10. Click "Add Package"
-11. Select the **OwlMetry** library and click "Add Package"
+1. File > Add Package Dependencies
+2. Enter URL: `https://github.com/Jasonvdb/owlmetry.git`
+3. Set rule to **Branch** > `main`
+4. Add **OwlMetry** to the app target
 
-Once the user confirms the package is added, retry the build to verify, then proceed with configuration.
+## Verify Package Integration
+
+After adding the package, resolve dependencies and build:
+
+```bash
+xcodebuild -resolvePackageDependencies -project <path>.xcodeproj -quiet
+xcodebuild -project <path>.xcodeproj -scheme <SchemeName> -destination 'platform=iOS Simulator,name=iPhone 16' build -quiet
+```
+
+If the build succeeds, proceed with configuration. The "No such module 'OwlMetry'" warning in editors (SourceKit) is expected and resolves during a real `xcodebuild`.
 
 ## Configure
 
@@ -187,16 +196,26 @@ Events are the core unit of data in OwlMetry. Use the four log levels to capture
 
 - **`info`** — normal operations worth recording: screen views, user actions, feature usage, successful completions. This is your default level.
 - **`debug`** — verbose detail useful only during development: cache hits, state transitions, intermediate values. These are filtered out in production data mode.
-- **`warn`** — something unexpected that the app recovered from: slow responses, fallback paths taken, retries needed.
-- **`error`** — something failed: network errors, parse failures, missing data, caught exceptions.
+- **`warn`** — something didn't go as expected but the app can continue: failed validation, precondition checks that fail, slow responses, fallback paths taken, deprecated API usage, missing optional data.
+- **`error`** — a caught exception or hard failure inside a `do`/`catch` block: network errors, JSON decode failures, file I/O errors, keychain access failures. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Failed to load profile image"` over `"error"`. Use `screenName` to tie events to where they happened in the UI. Use `customAttributes` for structured data you'll want to filter or search on later.
 
 ```swift
+// In a screen context — pass screenName to tie the event to the screen
 Owl.info("User opened settings", screenName: "SettingsView")
 Owl.debug("Cache hit", screenName: "HomeView", customAttributes: ["key": "user_prefs"])
-Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200"])
-Owl.error("Failed to load profile", screenName: "ProfileView")
+Owl.warn("Invalid email format", screenName: "SignUpView", customAttributes: ["input": email])
+
+do {
+    let profile = try await api.loadProfile(id: userId)
+} catch {
+    Owl.error("Failed to load profile", screenName: "ProfileView", customAttributes: ["error": "\(error)"])
+}
+
+// Outside a screen context — omit screenName entirely
+Owl.info("Background sync completed", customAttributes: ["items": "\(count)"])
+Owl.error("Keychain write failed", customAttributes: ["error": "\(error)"])
 ```
 
 All logging methods share the same signature:
@@ -204,6 +223,8 @@ All logging methods share the same signature:
 Owl.info(_ message: String, screenName: String? = nil, customAttributes: [String: String]? = nil)
 ```
 
+**`screenName` is optional.** Only pass it when the event originates from a specific screen in the UI (e.g., a button tap handler inside a view). **Do NOT pass `screenName`** when logging from utility functions, services, managers, network layers, background tasks, or anywhere that isn't directly tied to a visible screen. Passing a fabricated or guessed screen name is worse than omitting it — it pollutes screen-level analytics.
+
 Source file, function, and line are auto-captured.
 
 **Avoid logging PII** (emails, phone numbers, passwords) or high-frequency events (every frame, every scroll position). Focus on actions and outcomes.
@@ -251,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
@@ -283,7 +313,7 @@ op.cancel(attributes: ["reason": "user_cancelled"])
 
 `duration_ms` and `tracking_id` (UUID) are auto-added. 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
@@ -328,7 +358,8 @@ When instrumenting a new app, follow this priority:
 - Screen views (`.owlScreen("ScreenName")` on every distinct screen)
 - App launch / cold start (`info` in `init()` or `didFinishLaunching`)
 - Authentication events (login, logout, signup)
-- Errors and failures (`error` in `catch` blocks, error handlers)
+- Caught exceptions (`error` in `catch` blocks, error handlers)
+- Validation failures and pre-checks (`warn` for bad input, missing optional data, fallback paths)
 - Core business actions (purchase, share, create, delete)
 
 **Instrument when relevant (metrics — requires CLI `owlmetry metrics create` first):**
@@ -341,8 +372,9 @@ When instrumenting a new app, follow this priority:
 
 **Where to place calls:**
 - Screen views: `.owlScreen("Name")` on the outermost view of each screen (SwiftUI), `viewDidAppear` in UIKit
-- User actions: button action handlers, gesture callbacks
-- Errors: `catch` blocks, `Result.failure` handlers
+- User actions: button action handlers, gesture callbacks — pass `screenName` since you know which screen the user is on
+- Errors: `catch` blocks, `Result.failure` handlers — pass `screenName` only if the error is caught inside a view; omit it if caught in a service, manager, or utility
+- Services, utilities, background tasks: log freely but **never pass `screenName`** — these are not screen-bound
 - Metrics: wrap the async operation between `startOperation()` and `complete()`/`fail()`
 
 **What NOT to instrument:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",