@owlmetry/cli 0.1.8 → 0.1.10

package/dist/index.cjs

@@ -6360,7 +6360,8 @@ var METRIC_PHASES = ["start", "complete", "fail", "cancel", "record"];
 init_cjs_shims();
 
 // src/commands/apps.ts
-var appsCommand = new Command("apps").description("List apps").enablePositionalOptions().option("--project-id <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.projectId) {
@@ -6782,7 +6783,8 @@ function formatQueryResult(result) {
   }
   return lines.join("\n");
 }
-var metricsCommand = new Command("metrics").description("List metric definitions").enablePositionalOptions().requiredOption("--project-id <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.projectId);
   output(globals.format, metrics, () => formatMetricsTable(metrics));
@@ -6953,7 +6955,8 @@ function formatQueryResult2(result) {
   }
   return lines.join("\n");
 }
-var funnelsCommand = new Command("funnels").description("List funnel definitions").enablePositionalOptions().requiredOption("--project-id <id>", "Project ID").action(async (opts, cmd) => {
+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.projectId);
   output(globals.format, result.funnels, () => formatFunnelsTable(result.funnels));
@@ -7195,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.8").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.10").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.8
+version: 0.1.10
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
@@ -116,6 +116,59 @@ OwlMetry organises resources in a `Team → Project → Apps` hierarchy:
 
 Projects group apps cross-platform: an iOS app and its backend API can share the same project, enabling unified funnel and metric analysis across both.
 
+## Command Quick Reference
+
+Copy-paste ready. All commands support `--format json` for machine-readable output. Global flags: `--endpoint <url>`, `--api-key <key>`, `--team <name-or-id>`.
+
+```
+# Auth
+owlmetry auth send-code --email <email>
+owlmetry auth verify --email <email> --code <code> --format json
+owlmetry whoami --format json
+owlmetry switch [<name-or-slug>]
+owlmetry setup --endpoint <url> --api-key <key> [--ingest-endpoint <url>]
+
+# Projects
+owlmetry projects --format json
+owlmetry projects view <id> --format json
+owlmetry projects create --name <name> --slug <slug> [--team-id <id>] --format json
+owlmetry projects update <id> --name <name> --format json
+
+# Apps
+owlmetry apps list [--project-id <id>] --format json
+owlmetry apps view <id> --format json
+owlmetry apps create --project-id <id> --name <name> --platform <platform> [--bundle-id <id>] --format json
+owlmetry apps update <id> --name <name> --format json
+
+# Metrics
+owlmetry metrics list --project-id <id> --format json
+owlmetry metrics view <slug> --project-id <id> --format json
+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>
+owlmetry metrics events <slug> --project-id <id> [--phase <phase>] [--user-id <id>] [--since <time>] [--until <time>] --format json
+owlmetry metrics query <slug> --project-id <id> [--since <date>] [--until <date>] [--app-id <id>] [--user-id <id>] [--group-by <field>] --format json
+
+# Funnels
+owlmetry funnels list --project-id <id> --format json
+owlmetry funnels view <slug> --project-id <id> --format json
+owlmetry funnels create --project-id <id> --name <name> --slug <slug> --steps-file <path> [--description <desc>] --format json
+owlmetry funnels update <slug> --project-id <id> --steps-file <path> --format json
+owlmetry funnels delete <slug> --project-id <id>
+owlmetry funnels query <slug> --project-id <id> [--since <date>] [--until <date>] [--open] [--group-by <field>] --format json
+
+# Events
+owlmetry events [--project-id <id>] [--app-id <id>] [--level <level>] [--user-id <id>] [--session-id <id>] [--since <time>] [--limit <n>] --format json
+owlmetry events view <id> --format json
+owlmetry investigate <eventId> [--window <minutes>] --format json
+
+# Users
+owlmetry users <app-id> [--anonymous] [--real] [--search <query>] [--limit <n>] --format json
+
+# Audit Logs
+owlmetry audit-log list --team-id <id> [--resource-type <type>] [--actor-id <id>] [--action <action>] [--since <time>] --format json
+```
+
 ## Resource Management
 
 ### Projects
@@ -134,8 +187,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 <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,7 +208,7 @@ 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 <id> --format json                       # List all
+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
@@ -177,7 +230,7 @@ Funnels support two analysis modes:
 Maximum 20 steps per funnel.
 
 ```bash
-owlmetry funnels --project-id <id> --format json                       # List all
+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>
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.8
+version: 0.1.10
 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

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.8
+version: 0.1.10
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -311,7 +311,45 @@ 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 <id> --name "Photo Upload" --slug photo-upload --lifecycle --format json
 ```

package/package.json

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