@zeroxyz/cli 0.0.25 → 0.0.27

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/app.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.25",
+  version: "0.0.27",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -24,8 +24,8 @@ var package_default = {
     build: "tsup src/index.ts --format esm --out-dir dist --clean",
     "build:binary": "tsup --config tsup.binary.ts && cp -r skills hooks dist/pkg/ && pnpm exec pkg dist/pkg/index.cjs --config pkg.json --targets node24-macos-arm64,node24-macos-x64,node24-linux-x64 --output dist/bin/zero",
     prepublishOnly: "pnpm run build",
-    dev: "tsx src/index.ts",
-    cli: "ZERO_API_URL=http://localhost:1111 tsx src/index.ts",
+    dev: "ZERO_ENV=development tsx src/index.ts",
+    cli: "ZERO_ENV=development ZERO_API_URL=http://localhost:1111 tsx src/index.ts",
     "test:integration": "vitest run --project integration",
     "test:online": "vitest run --project online",
     "test:unit": "vitest run --project unit",
@@ -380,7 +380,10 @@ Categories the classifier picks from:
 ).option("--idempotency-key <key>", "Override the auto-generated dedup key").option(
   "--from-file <path>",
   "Submit bug reports in bulk from a JSONL file (one report per line)"
-).option("--json", "Emit the API result as JSON on stdout (for batch use)").action(
+).option("--json", "Emit the API result as JSON on stdout (for batch use)").option(
+  "--agent <name>",
+  "Identify your agent host for this invocation. Overrides auto-detect for this call only."
+).action(
   async (description, options) => {
     try {
       const { analyticsService, apiService, stateService } = appContext.services;
@@ -421,7 +424,10 @@ Categories the classifier picks from:
               category: result2.category,
               severity: parsed.severity ?? 2,
               bulk: true,
-              deduped: result2.deduped
+              deduped: result2.deduped,
+              hasCapability: !!result2.attached.capabilityId,
+              hasRun: !!result2.attached.runId,
+              hasSearch: !!result2.attached.searchId
             });
           } catch (err) {
             failed += 1;
@@ -506,9 +512,15 @@ Bulk bug-report complete: ${ok} ok, ${failed} failed`
       }
       analyticsService.capture("bug_report_submitted", {
         category: result.category,
+        categoryOverridden: !!options.category,
         severity: options.severity ?? 2,
         deduped: result.deduped,
-        autoContext: useAutoContext
+        autoContext: useAutoContext,
+        hasCapability: !!result.attached.capabilityId,
+        hasRun: !!result.attached.runId,
+        hasSearch: !!result.attached.searchId,
+        hasTitle: !!options.title,
+        hasReproduction: !!options.reproduction
       });
     } catch (err) {
       console.error(
@@ -1078,6 +1090,18 @@ var PaymentService = class {
     const raw = await this.getBalanceRaw(chain);
     return { amount: formatUnits(raw, 6), asset: "USDC" };
   };
+  /**
+   * Total spendable USDC across Base and Tempo. Users (and their agents)
+   * shouldn't need to know which chain holds funds — the CLI bridges to
+   * Tempo on demand, so the reported balance sums both sides.
+   */
+  getTotalBalance = async () => {
+    const [baseRaw, tempoRaw] = await Promise.all([
+      this.getBalanceRaw("base"),
+      this.getBalanceRaw("tempo")
+    ]);
+    return { amount: formatUnits(baseRaw + tempoRaw, 6), asset: "USDC" };
+  };
 };
 
 // src/util/infer-schema.ts
@@ -1116,10 +1140,41 @@ var tryParseJson = (text) => {
   }
 };
 
+// src/util/redact.ts
+var ERROR_MAX = 500;
+var QUERY_MAX = 200;
+var redactUrl = (raw) => {
+  try {
+    const parsed = new URL(raw);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return raw;
+  }
+};
+var truncateQuery = (raw) => raw.length > QUERY_MAX ? `${raw.slice(0, QUERY_MAX)}\u2026` : raw;
+var truncateError = (raw) => raw.length > ERROR_MAX ? `${raw.slice(0, ERROR_MAX)}\u2026` : raw;
+
 // src/commands/fetch-command.ts
-var detectPaymentRequirement = (headers, status) => {
-  if (status !== 402) return null;
-  const x402Header = headers.get("payment-required") ?? headers.get("x-payment-required");
+var isTextContentType = (contentType) => {
+  if (!contentType) return true;
+  const ct = contentType.toLowerCase().split(";")[0]?.trim() ?? "";
+  if (ct.startsWith("text/")) return true;
+  if (ct === "application/json" || ct.endsWith("+json")) return true;
+  if (ct === "application/xml" || ct.endsWith("+xml")) return true;
+  if (ct === "application/javascript" || ct === "application/ecmascript") {
+    return true;
+  }
+  if (ct === "application/x-www-form-urlencoded") return true;
+  return false;
+};
+var looksLikeX402V1Body = (body) => {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  return b.x402Version === 1 && Array.isArray(b.accepts) && b.accepts.length > 0;
+};
+var detectPaymentRequirement = async (response) => {
+  if (response.status !== 402) return null;
+  const x402Header = response.headers.get("payment-required") ?? response.headers.get("x-payment-required");
   if (x402Header) {
     try {
       const decoded = JSON.parse(
@@ -1130,10 +1185,20 @@ var detectPaymentRequirement = (headers, status) => {
       return { protocol: "x402", raw: { encoded: x402Header } };
     }
   }
-  const wwwAuth = headers.get("www-authenticate");
+  const wwwAuth = response.headers.get("www-authenticate");
   if (wwwAuth?.toLowerCase().includes("payment")) {
     return { protocol: "mpp", raw: { "www-authenticate": wwwAuth } };
   }
+  try {
+    const text = await response.clone().text();
+    if (text) {
+      const parsed = JSON.parse(text);
+      if (looksLikeX402V1Body(parsed)) {
+        return { protocol: "x402", raw: parsed };
+      }
+    }
+  } catch {
+  }
   return { protocol: "unknown", raw: {} };
 };
 var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a capability URL with automatic payment handling").argument("<url>", "URL to fetch").option(
@@ -1145,6 +1210,9 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
 ).option(
   "--json",
   "Emit {runId, status, latencyMs, payment, body} as JSON on stdout (for batch/non-TTY use)"
+).option(
+  "--agent <name>",
+  "Identify your agent host for this invocation (e.g. claude-web, codex). Overrides auto-detect for this call only."
 ).action(
   async (url, options) => {
     try {
@@ -1196,17 +1264,16 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
         );
       }
       let finalResponse;
+      let bodyBytes;
       let body = "";
+      let bodyIsBinary = false;
       let paymentMeta;
       let sessionMeta;
       let fetchError;
       try {
         log(`Calling ${url}...`);
         const response = await fetch(url, requestInit);
-        const paymentReq = detectPaymentRequirement(
-          response.headers,
-          response.status
-        );
+        const paymentReq = await detectPaymentRequirement(response);
         if (paymentReq) {
           log(
             `Payment required (${paymentReq.protocol}) \u2014 preparing payment...`
@@ -1239,11 +1306,25 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
         } else {
           finalResponse = response;
         }
-        body = await finalResponse.text();
+        const buf = Buffer.from(await finalResponse.arrayBuffer());
+        bodyBytes = buf;
+        bodyIsBinary = !isTextContentType(
+          finalResponse.headers.get("content-type")
+        );
+        body = bodyIsBinary ? "" : buf.toString("utf8");
       } catch (err) {
         if (err instanceof SessionCloseFailedError) {
           finalResponse = err.response;
-          body = await err.response.text().catch(() => "");
+          try {
+            const buf = Buffer.from(await err.response.arrayBuffer());
+            bodyBytes = buf;
+            bodyIsBinary = !isTextContentType(
+              err.response.headers.get("content-type")
+            );
+            body = bodyIsBinary ? "" : buf.toString("utf8");
+          } catch {
+            body = "";
+          }
           paymentMeta = {
             protocol: "mpp",
             chain: "tempo",
@@ -1271,16 +1352,12 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
       }
       const latencyMs = Date.now() - startTime;
       if (finalResponse && !options.json) {
-        console.log(body);
+        if (bodyIsBinary && bodyBytes) {
+          process.stdout.write(bodyBytes);
+        } else {
+          console.log(body);
+        }
       }
-      analyticsService.capture("fetch_executed", {
-        url,
-        status: finalResponse?.status,
-        hasPayment: !!paymentMeta,
-        paymentProtocol: paymentMeta?.protocol,
-        paymentAmount: paymentMeta?.amount,
-        ...fetchError && { error: fetchError.message }
-      });
       if (paymentMeta) {
         try {
           const balance = await walletService.getBalance();
@@ -1293,6 +1370,11 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
   Warning: Balance is $${balance.amount} \u2014 run \`zero wallet fund\` soon.
 `
               );
+              analyticsService.capture("low_balance_warning_shown", {
+                balance: balance.amount,
+                threshold,
+                paymentProtocol: paymentMeta.protocol
+              });
             }
           }
         } catch {
@@ -1338,17 +1420,35 @@ var fetchCommand = (appContext) => new Command3("fetch").description("Fetch a ca
           );
         }
       }
+      const status = finalResponse?.status;
+      const outcome = !finalResponse ? "network_error" : status === 402 && !paymentMeta ? "payment_failed" : status !== void 0 && status >= 400 && status !== 402 ? "server_error" : "success";
+      analyticsService.capture("fetch_executed", {
+        url: redactUrl(url),
+        status,
+        outcome,
+        latencyMs,
+        hasPayment: !!paymentMeta,
+        paymentProtocol: paymentMeta?.protocol,
+        paymentAmount: paymentMeta?.amount,
+        capabilityId: capabilityId ?? void 0,
+        searchId: searchId ?? void 0,
+        runId: runId ?? void 0,
+        runTracked: !!runId,
+        ...fetchError && { error: truncateError(fetchError.message) }
+      });
       if (fetchError && !options.json) {
         console.error(`  Fetch failed: ${fetchError.message}`);
       }
       if (options.json) {
+        const jsonBody = !finalResponse ? null : bodyIsBinary ? (bodyBytes ?? Buffer.alloc(0)).toString("base64") : body;
         console.log(
           JSON.stringify({
             runId,
             status: finalResponse?.status ?? null,
             latencyMs,
             payment: paymentMeta ?? null,
-            body: finalResponse ? body : null,
+            body: jsonBody,
+            ...bodyIsBinary && { bodyEncoding: "base64" },
             ...fetchError && { error: fetchError.message },
             ...skipReasons.length > 0 && {
               runTrackingSkipped: skipReasons
@@ -1453,7 +1553,10 @@ var getCommand = (appContext) => new Command4("get").description(
 ).argument(
   "<identifier>",
   "Position number from search results, or a capability slug"
-).option("--formatted", "Output formatted trust breakdown").action(async (identifier, options) => {
+).option("--formatted", "Output formatted trust breakdown").option(
+  "--agent <name>",
+  "Identify your agent host for this invocation. Overrides auto-detect for this call only."
+).action(async (identifier, options) => {
   try {
     const { analyticsService, apiService, stateService } = appContext.services;
     const position = Number.parseInt(identifier, 10);
@@ -1493,7 +1596,9 @@ var getCommand = (appContext) => new Command4("get").description(
     }
     analyticsService.capture("capability_viewed", {
       capabilityId,
-      ...isPosition ? { position } : {}
+      fromLastSearch: isPosition,
+      ...isPosition ? { position } : {},
+      ...searchId ? { searchId } : {}
     });
   } catch (err) {
     console.error(err instanceof Error ? err.message : "Get failed");
@@ -1716,108 +1821,129 @@ var installSkills = (home) => {
   }
   return installed;
 };
-var initCommand = (appContext) => new Command5("init").description("Initialize Zero CLI for usage").option("--force", "Overwrite existing configuration").action(async (options) => {
-  const home = homedir2();
-  const zeroDir = join2(home, ".zero");
-  const configPath = join2(zeroDir, "config.json");
-  let walletCreated = false;
-  let walletAddress = null;
-  const walletExists = (() => {
-    if (!existsSync2(configPath)) return false;
-    try {
-      const existing = JSON.parse(readFileSync3(configPath, "utf8"));
-      return !!existing.privateKey;
-    } catch {
-      return false;
-    }
-  })();
-  if (!walletExists || options.force) {
-    const privateKey = generatePrivateKey();
-    const account = privateKeyToAccount(privateKey);
-    mkdirSync2(zeroDir, { recursive: true });
-    const existing = existsSync2(configPath) ? JSON.parse(readFileSync3(configPath, "utf8")) : {};
-    writeFileSync2(
-      configPath,
-      JSON.stringify(
-        { ...existing, privateKey, lowBalanceWarning: 1 },
-        null,
-        2
-      )
-    );
-    walletCreated = true;
-    walletAddress = account.address;
-    console.log(`Wallet address: ${account.address}`);
-  } else {
-    try {
-      const existing = JSON.parse(readFileSync3(configPath, "utf8"));
-      const account = privateKeyToAccount(existing.privateKey);
+var runInit = async (appContext, options = {}) => {
+  appContext.services.analyticsService.capture("init_started", {
+    force: options.force ?? false
+  });
+  let currentStep = "wallet";
+  try {
+    const home = homedir2();
+    const zeroDir = join2(home, ".zero");
+    const configPath = join2(zeroDir, "config.json");
+    let walletCreated = false;
+    let walletAddress = null;
+    const walletExists = (() => {
+      if (!existsSync2(configPath)) return false;
+      try {
+        const existing = JSON.parse(readFileSync3(configPath, "utf8"));
+        return !!existing.privateKey;
+      } catch {
+        return false;
+      }
+    })();
+    if (!walletExists || options.force) {
+      const privateKey = generatePrivateKey();
+      const account = privateKeyToAccount(privateKey);
+      mkdirSync2(zeroDir, { recursive: true });
+      const existing = existsSync2(configPath) ? JSON.parse(readFileSync3(configPath, "utf8")) : {};
+      writeFileSync2(
+        configPath,
+        JSON.stringify(
+          { ...existing, privateKey, lowBalanceWarning: 1 },
+          null,
+          2
+        )
+      );
+      walletCreated = true;
       walletAddress = account.address;
-    } catch {
+      console.log(`Wallet address: ${account.address}`);
+    } else {
+      try {
+        const existing = JSON.parse(readFileSync3(configPath, "utf8"));
+        const account = privateKeyToAccount(existing.privateKey);
+        walletAddress = account.address;
+      } catch {
+      }
     }
-  }
-  const agentsDetected = [];
-  const agentsWithSkills = [];
-  let skillsError = null;
-  let hookInstalled = false;
-  let hookError = null;
-  for (const tool of AGENT_TOOLS) {
-    if (existsSync2(join2(home, tool.configDir))) {
-      agentsDetected.push(tool.name);
+    const agentsDetected = [];
+    const agentsWithSkills = [];
+    let skillsError = null;
+    let hookInstalled = false;
+    let hookError = null;
+    for (const tool of AGENT_TOOLS) {
+      if (existsSync2(join2(home, tool.configDir))) {
+        agentsDetected.push(tool.name);
+      }
     }
-  }
-  try {
-    const installed = installSkills(home);
-    for (const entry of installed) {
-      const toolName = entry.split(":")[0];
-      if (toolName && !agentsWithSkills.includes(toolName)) {
-        agentsWithSkills.push(toolName);
+    currentStep = "skills";
+    try {
+      const installed = installSkills(home);
+      for (const entry of installed) {
+        const toolName = entry.split(":")[0];
+        if (toolName && !agentsWithSkills.includes(toolName)) {
+          agentsWithSkills.push(toolName);
+        }
       }
+    } catch (err) {
+      skillsError = err instanceof Error ? err.message : "unknown skills error";
     }
-  } catch (err) {
-    skillsError = err instanceof Error ? err.message : "unknown skills error";
-  }
-  try {
-    hookInstalled = installHook(home);
-  } catch (err) {
-    hookError = err instanceof Error ? err.message : "unknown hook error";
-  }
-  const conflictingSkills = findConflictingSkills(home);
-  if (conflictingSkills.length > 0) {
-    const skillList = conflictingSkills.map((s) => `  - ${s.tool}: ${s.skillName}`).join("\n");
-    console.error(
-      `
+    currentStep = "hook";
+    try {
+      hookInstalled = installHook(home);
+    } catch (err) {
+      hookError = err instanceof Error ? err.message : "unknown hook error";
+    }
+    currentStep = "cleanup_scan";
+    const conflictingSkills = findConflictingSkills(home);
+    if (conflictingSkills.length > 0) {
+      const skillList = conflictingSkills.map((s) => `  - ${s.tool}: ${s.skillName}`).join("\n");
+      console.error(
+        `
 Found deprecated skills that may conflict with Zero:
 ${skillList}
 
 To remove them, run: zero init cleanup`
+      );
+    }
+    console.error(
+      'Zero is ready! Run `zero search` to find capabilities.\n\nBy using Zero, you agree to our Terms of Service:\n  https://zero.xyz/terms-of-service\n\nRun `zero terms` to view the full terms.\n\nTry:\n  zero search "translate text to Spanish"\n  zero search "generate an image"\n  zero search "weather forecast"'
     );
+    currentStep = "complete";
+    appContext.services.analyticsService.capture("wallet_initialized", {
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      wallet_created: walletCreated,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      wallet_address: walletAddress,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      agents_detected: agentsDetected,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      agents_detected_count: agentsDetected.length,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      skills_installed: agentsWithSkills.length > 0,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      skills_installed_for: agentsWithSkills,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      skills_error: skillsError,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      hook_installed: hookInstalled,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      hook_error: hookError,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      conflicting_skills_found: conflictingSkills.length,
+      force: options.force ?? false
+    });
+    return { walletAddress, walletCreated };
+  } catch (err) {
+    appContext.services.analyticsService.capture("init_failed", {
+      step: currentStep,
+      error: truncateError(err instanceof Error ? err.message : String(err)),
+      force: options.force ?? false
+    });
+    throw err;
   }
-  console.error(
-    'Zero is ready! Run `zero search` to find capabilities.\n\nBy using Zero, you agree to our Terms of Service:\n  https://zero.xyz/terms-of-service\n\nRun `zero terms` to view the full terms.\n\nTry:\n  zero search "translate text to Spanish"\n  zero search "generate an image"\n  zero search "weather forecast"'
-  );
-  appContext.services.analyticsService.capture("wallet_initialized", {
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    wallet_created: walletCreated,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    wallet_address: walletAddress,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    agents_detected: agentsDetected,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    agents_detected_count: agentsDetected.length,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    skills_installed: agentsWithSkills.length > 0,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    skills_installed_for: agentsWithSkills,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    skills_error: skillsError,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    hook_installed: hookInstalled,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    hook_error: hookError,
-    // biome-ignore lint/style/useNamingConvention: snake_case for analytics
-    conflicting_skills_found: conflictingSkills.length,
-    force: options.force ?? false
-  });
+};
+var initCommand = (appContext) => new Command5("init").description("Initialize Zero CLI for usage").option("--force", "Overwrite existing configuration").action(async (options) => {
+  await runInit(appContext, options);
 }).addCommand(
   new Command5("cleanup").description(
     "Remove deprecated skills (zam, tempo) that conflict with Zero"
@@ -1831,7 +1957,7 @@ To remove them, run: zero init cleanup`
     const removedList = removed.map((s) => `  - ${s}`).join("\n");
     console.error(`Removed deprecated skills:
 ${removedList}`);
-    appContext.services.analyticsService.capture("skills_cleanup", {
+    appContext.services.analyticsService.capture("skills_cleaned_up", {
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
       skills_removed: removed,
       // biome-ignore lint/style/useNamingConvention: snake_case for analytics
@@ -1875,6 +2001,9 @@ Examples:
 ).option("--success", "The capability succeeded").option("--no-success", "The capability failed").option("--accuracy <n>", "Accuracy rating (1-5)", Number.parseInt).option("--value <n>", "Value rating (1-5)", Number.parseInt).option("--reliability <n>", "Reliability rating (1-5)", Number.parseInt).option("--content <text>", "Optional review text").option(
   "--from-file <path>",
   "Submit reviews in bulk from a JSONL file (one review object per line: {runId, success, accuracy, value, reliability, content?})"
+).option(
+  "--agent <name>",
+  "Identify your agent host for this invocation. Overrides auto-detect for this call only."
 ).action(
   async (runId, options) => {
     try {
@@ -1896,6 +2025,10 @@ Examples:
             analyticsService.capture("review_submitted", {
               runId: parsed.runId,
               success: parsed.success,
+              accuracy: parsed.accuracy,
+              value: parsed.value,
+              reliability: parsed.reliability,
+              hasContent: !!parsed.content,
               bulk: true
             });
           } catch (err) {
@@ -1978,7 +2111,12 @@ Bulk review complete: ${ok} ok, ${failed} failed`);
       console.log(`Review submitted: ${result.reviewId}`);
       analyticsService.capture("review_submitted", {
         runId,
-        success: options.success
+        success: options.success,
+        accuracy,
+        value,
+        reliability,
+        hasContent: !!options.content,
+        resolvedByCapability: !!options.capability
       });
     } catch (err) {
       console.error(err instanceof Error ? err.message : "Review failed");
@@ -2003,6 +2141,9 @@ Examples:
   "--limit <n>",
   "Max rows (1-100, default 25)",
   (v) => Number.parseInt(v, 10)
+).option(
+  "--agent <name>",
+  "Identify your agent host for this invocation. Overrides auto-detect for this call only."
 ).action(
   async (options) => {
     try {
@@ -2084,6 +2225,9 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
 ).option(
   "--exclude-source <source>",
   "Exclude results from this crawl source"
+).option(
+  "--agent <name>",
+  "Identify your agent host for this invocation (e.g. claude-web, codex). Overrides auto-detect for this call only."
 ).action(
   async (query, options) => {
     try {
@@ -2118,8 +2262,24 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         excludeSource: options.excludeSource
       });
       analyticsService.capture("search_executed", {
-        query,
-        resultCount: result.capabilities.length
+        query: truncateQuery(query),
+        queryLength: query.length,
+        resultCount: result.capabilities.length,
+        searchId: result.searchId,
+        total: result.total,
+        hasMore: result.hasMore,
+        offset: options.offset,
+        limit: options.limit,
+        freeOnly: options.free ?? false,
+        maxCost: options.maxCost,
+        minRating: options.minRating,
+        protocol: options.protocol,
+        minTrust: options.minTrust,
+        availabilityStatus: options.status,
+        includeAll: options.all ?? false,
+        source: options.source,
+        excludeSource: options.excludeSource,
+        json: options.json ?? false
       });
       if (options.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -2309,10 +2469,79 @@ var walletCommand = (appContext) => {
   return cmd;
 };
 
+// src/commands/welcome-command.ts
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join4 } from "path";
+import { Command as Command11 } from "commander";
+import open2 from "open";
+import { getAddress } from "viem";
+import { privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
+var readPrivateKey = () => {
+  const configPath = join4(homedir4(), ".zero", "config.json");
+  if (!existsSync4(configPath)) return null;
+  try {
+    const config = JSON.parse(readFileSync6(configPath, "utf8"));
+    if (typeof config.privateKey === "string") {
+      return config.privateKey;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+};
+var welcomeCommand = (appContext) => new Command11("welcome").description("Claim your $5 welcome bonus.").action(async () => {
+  const { analyticsService } = appContext.services;
+  analyticsService.capture("welcome_started", {});
+  try {
+    let privateKey = readPrivateKey();
+    if (!privateKey) {
+      await runInit(appContext);
+      privateKey = readPrivateKey();
+      if (!privateKey) {
+        throw new Error("Wallet initialization failed");
+      }
+    }
+    const account = privateKeyToAccount3(privateKey);
+    const walletAddress = getAddress(account.address);
+    const walletSignature = await account.signMessage({
+      message: walletAddress
+    });
+    const url = new URL("/welcome", appContext.env.ZERO_WEB_URL);
+    url.searchParams.set("wallet", walletAddress);
+    url.searchParams.set("walletSignature", walletSignature);
+    console.log(
+      `Opening ${url.toString()}
+
+If your browser didn't open, paste the URL above.`
+    );
+    await open2(url.toString());
+    analyticsService.capture("welcome_link_opened", {
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      wallet_address: walletAddress
+    });
+  } catch (err) {
+    analyticsService.capture("welcome_failed", {
+      error: truncateError(
+        err instanceof Error ? err.message : String(err)
+      )
+    });
+    throw err;
+  }
+});
+
 // src/app.ts
 var createApp = (appContext) => {
   const { analyticsService } = appContext.services;
-  const program = new Command11().name("zero").description("Zero CLI \u2014 Search engine and payment platform for AI agents").version(package_default.version, "-v, --version").exitOverride().hook("preAction", async (_thisCommand, actionCommand) => {
+  const program = new Command12().name("zero").description("Zero CLI \u2014 Search engine and payment platform for AI agents").version(package_default.version, "-v, --version").exitOverride().hook("preAction", async (_thisCommand, actionCommand) => {
+    const agentFlag = actionCommand.opts().agent;
+    if (typeof agentFlag === "string" && agentFlag.trim().length > 0) {
+      analyticsService.setAgentHost(agentFlag.trim());
+    }
+    appContext.invocation.current = {
+      command: actionCommand.name(),
+      startMs: Date.now()
+    };
     analyticsService.capture("command_executed", {
       command: actionCommand.name()
     });
@@ -2327,6 +2556,7 @@ var createApp = (appContext) => {
   program.addCommand(walletCommand(appContext));
   program.addCommand(configCommand(appContext));
   program.addCommand(termsCommand(appContext));
+  program.addCommand(welcomeCommand(appContext));
   return program;
 };
 
@@ -2334,7 +2564,9 @@ var createApp = (appContext) => {
 import z4 from "zod";
 var envSchema = z4.object({
   ZERO_API_URL: z4.string().default("https://api.zero.xyz"),
-  ZERO_PRIVATE_KEY: z4.string().optional()
+  ZERO_WEB_URL: z4.string().default("https://zero.xyz"),
+  ZERO_PRIVATE_KEY: z4.string().optional(),
+  ZERO_ENV: z4.enum(["development", "production"]).default("production")
 });
 var getEnv = () => {
   try {
@@ -2347,14 +2579,15 @@ var getEnv = () => {
 };
 
 // src/app/app-services.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
-import { privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
+import { randomUUID as randomUUID2 } from "crypto";
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join6 } from "path";
+import { privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
 
 // src/services/analytics-service.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname2 } from "path";
 import { PostHog } from "posthog-node";
 var POSTHOG_API_KEY = "phc_B2vLyNxAf2mnqvdPQajf4d4b2iXc35dep2ZrvebMJLuX";
@@ -2362,14 +2595,22 @@ var POSTHOG_HOST = "https://us.i.posthog.com";
 var AnalyticsService = class {
   posthog;
   distinctId;
+  walletAddress;
   cliVersion;
+  environment;
+  requestId;
+  agentHost;
   constructor(opts) {
     this.cliVersion = opts.cliVersion;
+    this.environment = opts.environment;
+    this.walletAddress = opts.walletAddress;
+    this.requestId = opts.requestId;
+    this.agentHost = opts.agentHost;
     let telemetryEnabled = true;
     let persistedAnonId;
     try {
-      if (existsSync4(opts.configPath)) {
-        const config = JSON.parse(readFileSync6(opts.configPath, "utf8"));
+      if (existsSync5(opts.configPath)) {
+        const config = JSON.parse(readFileSync7(opts.configPath, "utf8"));
         if (config.telemetry === false) {
           telemetryEnabled = false;
         }
@@ -2394,7 +2635,7 @@ var AnalyticsService = class {
       try {
         const dir = dirname2(opts.configPath);
         mkdirSync4(dir, { recursive: true });
-        const existing = existsSync4(opts.configPath) ? JSON.parse(readFileSync6(opts.configPath, "utf8")) : {};
+        const existing = existsSync5(opts.configPath) ? JSON.parse(readFileSync7(opts.configPath, "utf8")) : {};
         writeFileSync4(
           opts.configPath,
           JSON.stringify({ ...existing, anonId: newAnonId }, null, 2)
@@ -2417,6 +2658,40 @@ var AnalyticsService = class {
     });
     this.posthog.on("error", () => {
     });
+    if (opts.walletAddress && persistedAnonId) {
+      this.maybeAliasAnonToWallet(
+        opts.configPath,
+        persistedAnonId,
+        opts.walletAddress
+      );
+    }
+  }
+  maybeAliasAnonToWallet(configPath, anonId, walletAddress) {
+    if (!this.posthog) return;
+    if (anonId === walletAddress) return;
+    let aliasedTo;
+    try {
+      const config = JSON.parse(readFileSync7(configPath, "utf8"));
+      if (typeof config.aliasedTo === "string") {
+        aliasedTo = config.aliasedTo;
+      }
+    } catch {
+    }
+    if (aliasedTo === walletAddress) return;
+    this.posthog.alias({ distinctId: walletAddress, alias: anonId });
+    try {
+      const config = existsSync5(configPath) ? JSON.parse(readFileSync7(configPath, "utf8")) : {};
+      writeFileSync4(
+        configPath,
+        JSON.stringify({ ...config, aliasedTo: walletAddress }, null, 2)
+      );
+    } catch {
+    }
+  }
+  // Per-invocation override applied by the preAction hook when `--agent`
+  // is passed. Stateless — affects only this process.
+  setAgentHost(next) {
+    this.agentHost = next;
   }
   capture(event, properties) {
     if (!this.posthog) return;
@@ -2427,6 +2702,13 @@ var AnalyticsService = class {
         source: "cli",
         // biome-ignore lint/style/useNamingConvention: snake_case is standard for analytics event properties
         cli_version: this.cliVersion,
+        environment: this.environment,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        wallet_address: this.walletAddress,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        request_id: this.requestId,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        agent_host: this.agentHost,
         ...properties
       }
     });
@@ -2441,12 +2723,12 @@ var AnalyticsService = class {
 };
 
 // src/services/state-service.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
+import { join as join5 } from "path";
 var StateService = class {
   constructor(zeroDir) {
     this.zeroDir = zeroDir;
-    this.lastSearchPath = join4(zeroDir, "last_search.json");
+    this.lastSearchPath = join5(zeroDir, "last_search.json");
   }
   lastSearchPath;
   saveLastSearch = (data) => {
@@ -2455,8 +2737,8 @@ var StateService = class {
   };
   loadLastSearch = () => {
     try {
-      if (!existsSync5(this.lastSearchPath)) return null;
-      const raw = readFileSync7(this.lastSearchPath, "utf8");
+      if (!existsSync6(this.lastSearchPath)) return null;
+      const raw = readFileSync8(this.lastSearchPath, "utf8");
       return JSON.parse(raw);
     } catch {
       return null;
@@ -2476,7 +2758,7 @@ var WalletService = class {
     if (!this.address) return null;
     if (this.balanceGetter) {
       try {
-        const result = await this.balanceGetter("base");
+        const result = await this.balanceGetter();
         return { amount: result.amount, asset: result.asset };
       } catch {
         return {
@@ -2491,16 +2773,25 @@ var WalletService = class {
   getLowBalanceWarning = () => this.config.lowBalanceWarning;
 };
 
+// src/util/agent-host.ts
+var detectAgentHost = (env = process.env) => {
+  if (env.ZERO_AGENT) return env.ZERO_AGENT;
+  if (env.CLAUDECODE === "1") return "claude-code";
+  if (env.CURSOR_TRACE_ID) return "cursor";
+  if (env.TERM_PROGRAM === "vscode") return "vscode";
+  return "unknown";
+};
+
 // src/app/app-services.ts
 var CLI_VERSION = package_default.version;
 var getServices = (env) => {
   let privateKey = env.ZERO_PRIVATE_KEY ? env.ZERO_PRIVATE_KEY : null;
-  const zeroDir = join5(homedir4(), ".zero");
-  const configPath = join5(zeroDir, "config.json");
+  const zeroDir = join6(homedir5(), ".zero");
+  const configPath = join6(zeroDir, "config.json");
   if (!privateKey) {
     try {
-      if (existsSync6(configPath)) {
-        const config = JSON.parse(readFileSync8(configPath, "utf8"));
+      if (existsSync7(configPath)) {
+        const config = JSON.parse(readFileSync9(configPath, "utf8"));
         if (typeof config.privateKey === "string") {
           privateKey = config.privateKey;
         }
@@ -2508,11 +2799,11 @@ var getServices = (env) => {
     } catch {
     }
   }
-  const account = privateKey ? privateKeyToAccount3(privateKey) : null;
+  const account = privateKey ? privateKeyToAccount4(privateKey) : null;
   let lowBalanceWarning = 1;
   try {
-    if (existsSync6(configPath)) {
-      const config = JSON.parse(readFileSync8(configPath, "utf8"));
+    if (existsSync7(configPath)) {
+      const config = JSON.parse(readFileSync9(configPath, "utf8"));
       if (typeof config.lowBalanceWarning === "number") {
         lowBalanceWarning = config.lowBalanceWarning;
       }
@@ -2527,12 +2818,15 @@ var getServices = (env) => {
     {
       lowBalanceWarning
     },
-    paymentService.getBalance
+    paymentService.getTotalBalance
   );
   const analyticsService = new AnalyticsService({
     walletAddress: account?.address ?? null,
     configPath,
-    cliVersion: CLI_VERSION
+    cliVersion: CLI_VERSION,
+    environment: env.ZERO_ENV,
+    requestId: randomUUID2(),
+    agentHost: detectAgentHost()
   });
   return {
     analyticsService,
@@ -2551,7 +2845,8 @@ var createAppContext = () => {
   }
   return {
     env,
-    services: getServices(env)
+    services: getServices(env),
+    invocation: { current: null }
   };
 };
 
@@ -2563,15 +2858,27 @@ var main = async () => {
     process.exit(1);
   }
   const app = createApp(appContext);
+  let caughtError = null;
   try {
     await app.parseAsync(process.argv);
   } catch (err) {
     const isCommanderExit = err instanceof Error && "exitCode" in err && err.exitCode === 0;
     if (!isCommanderExit) {
-      console.error(err instanceof Error ? err.message : "Unexpected error");
+      caughtError = err instanceof Error ? err : new Error(String(err));
+      console.error(caughtError.message);
       process.exitCode = 1;
     }
   } finally {
+    const invocation = appContext.invocation.current;
+    if (invocation) {
+      appContext.services.analyticsService.capture("command_completed", {
+        command: invocation.command,
+        success: !caughtError && process.exitCode !== 1,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        duration_ms: Date.now() - invocation.startMs,
+        ...caughtError && { error: truncateError(caughtError.message) }
+      });
+    }
     await appContext.services.analyticsService.shutdown();
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "0.0.25",
+	"version": "0.0.27",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",
@@ -18,8 +18,8 @@
 		"build": "tsup src/index.ts --format esm --out-dir dist --clean",
 		"build:binary": "tsup --config tsup.binary.ts && cp -r skills hooks dist/pkg/ && pnpm exec pkg dist/pkg/index.cjs --config pkg.json --targets node24-macos-arm64,node24-macos-x64,node24-linux-x64 --output dist/bin/zero",
 		"prepublishOnly": "pnpm run build",
-		"dev": "tsx src/index.ts",
-		"cli": "ZERO_API_URL=http://localhost:1111 tsx src/index.ts",
+		"dev": "ZERO_ENV=development tsx src/index.ts",
+		"cli": "ZERO_ENV=development ZERO_API_URL=http://localhost:1111 tsx src/index.ts",
 		"test:integration": "vitest run --project integration",
 		"test:online": "vitest run --project online",
 		"test:unit": "vitest run --project unit",

package/skills/zero/SKILL.md

@@ -43,6 +43,16 @@ Run these commands in order. Do not skip steps.
 
 **Prefer `zero init` or `zero wallet set` for local/interactive use** so the wallet persists across shells. Use `ZERO_PRIVATE_KEY` only when persisting to disk is undesirable — CI jobs, containers, one-off scripts, or secrets-manager-injected environments.
 
+**Identify yourself (if your platform isn't auto-detected).** Zero auto-detects Claude Code, Cursor, and VSCode via their session env vars. For platforms without a signature (Claude Web, Managed Agents, Codex, OpenCode, or anything else), pass your identity on every call — either flag or env var:
+
+```
+zero search --agent claude-web "translate hello world"
+# or
+ZERO_AGENT=claude-web zero search "translate hello world"
+```
+
+Both are per-invocation and stateless — there's no persistent config to go stale if you move between sandboxes. Resolution order: `--agent` flag > `ZERO_AGENT` env var > host-specific env signals (`CLAUDECODE`, `CURSOR_TRACE_ID`, `TERM_PROGRAM=vscode`) > `unknown`. Canonical names: `claude-code`, `cursor`, `vscode`, `claude-web`, `codex`, `opencode`. Any string is accepted.
+
 **Step 3 — Fund wallet:** `zero wallet fund` — opens browser to add USDC (Base). For manual transfer: `zero wallet fund --manual`.
 
 **Step 4 — Confirm readiness:** `zero wallet balance`