@zeroxyz/cli 0.0.33 → 0.0.34

package/README.md

@@ -48,6 +48,16 @@ zero search "image classification"
 
 Results are numbered. Use `zero get <number>` to view details.
 
+**Cost filtering.** By default, results are filtered to capabilities priced **≤ $30/call** as a wallet-safety cap. Override per-call:
+
+```bash
+zero search "image classification" --max-cost 5      # cap at $5/call
+zero search "expensive deep research" --max-cost 100 # raise the cap for hard tasks
+zero search "image classification" --free            # only free capabilities
+```
+
+Other useful filters: `--min-rating <1-5>`, `--min-trust <0-100>`, `--protocol x402|mpp`, `--status healthy|degraded|down`, `--source <name>`, `--all` (no trust/health filtering).
+
 ### `zero get <position>`
 
 Get full details for a capability from the last search results.

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command as Command12 } from "commander";
 // package.json
 var package_default = {
   name: "@zeroxyz/cli",
-  version: "0.0.33",
+  version: "0.0.34",
   type: "module",
   bin: {
     zero: "dist/index.js",
@@ -146,7 +146,10 @@ var capabilityResponseSchema = z.object({
     blockchainActivity: z.number().nullable(),
     performance: z.number().nullable()
   }).nullable().optional(),
-  availabilityStatus: z.enum(["healthy", "degraded", "down", "unknown"]).nullable().optional()
+  availabilityStatus: z.enum(["healthy", "degraded", "down", "unknown"]).nullable().optional(),
+  activationCount: z.number().optional(),
+  lastUsedAt: z.string().nullable().optional(),
+  lastSuccessfullyRanAt: z.string().nullable().optional()
 });
 var createRunResponseSchema = z.object({
   runId: z.string()
@@ -1285,7 +1288,10 @@ var detectPaymentRequirement = async (response) => {
 };
 var fetchCommand = (appContext) => new Command3("fetch").description(
   "Fetch a capability URL, handling 402 challenges automatically"
-).argument("<url>", "URL to fetch").option(
+).argument(
+  "[url]",
+  "URL to fetch. Optional when --capability is provided \u2014 the URL is resolved from the capability."
+).option(
   "-X, --method <method>",
   "HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to POST when -d is set, otherwise GET"
 ).option(
@@ -1317,6 +1323,30 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         walletService
       } = appContext.services;
       const startTime = Date.now();
+      let resolvedUrl;
+      let resolvedMethodFromCapability;
+      if (!url) {
+        if (!options.capability) {
+          console.error(
+            "Missing URL. Pass a URL argument or --capability <uid|slug> so the URL can be resolved from the capability."
+          );
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          const cap = await apiService.getCapability(options.capability);
+          resolvedUrl = cap.url;
+          resolvedMethodFromCapability = cap.method;
+        } catch (err) {
+          console.error(
+            `Failed to resolve --capability ${options.capability}: ${err instanceof Error ? err.message : String(err)}`
+          );
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        resolvedUrl = url;
+      }
       let resolvedBody;
       try {
         resolvedBody = resolveRequestBody(
@@ -1346,7 +1376,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
         headers["content-type"] = Buffer.isBuffer(resolvedBody) ? "application/octet-stream" : "application/json";
       }
       const log = (msg) => console.error(`  ${msg}`);
-      const method = options.method ? options.method.toUpperCase() : resolvedBody ? "POST" : "GET";
+      const method = options.method ? options.method.toUpperCase() : resolvedMethodFromCapability && !resolvedBody ? resolvedMethodFromCapability.toUpperCase() : resolvedBody ? "POST" : "GET";
       const requestInit = {
         method,
         headers,
@@ -1354,7 +1384,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       };
       const lastSearch = stateService.loadLastSearch();
       const matchedCapability = lastSearch?.capabilities.find(
-        (c) => url.startsWith(c.url)
+        (c) => resolvedUrl.startsWith(c.url)
       );
       const capabilityId = options.capability ?? matchedCapability?.id ?? null;
       const searchId = matchedCapability ? lastSearch?.searchId : void 0;
@@ -1377,15 +1407,15 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       let sessionMeta;
       let fetchError;
       try {
-        log(`Calling ${url}...`);
-        const response = await fetch(url, requestInit);
+        log(`Calling ${resolvedUrl}...`);
+        const response = await fetch(resolvedUrl, requestInit);
         const paymentReq = await detectPaymentRequirement(response);
         if (paymentReq) {
           log(
             `Payment required (${paymentReq.protocol}) \u2014 preparing payment...`
           );
           const result = await paymentService.handlePayment(
-            url,
+            resolvedUrl,
             requestInit,
             paymentReq,
             options.maxPay,
@@ -1530,7 +1560,7 @@ var fetchCommand = (appContext) => new Command3("fetch").description(
       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),
+        url: redactUrl(resolvedUrl),
         status,
         outcome,
         latencyMs,
@@ -1621,6 +1651,22 @@ var formatReviewCount = (count) => {
   if (count >= 1e3) return `${(count / 1e3).toFixed(1)}k`;
   return count.toString();
 };
+var formatRelativeTimestamp = (iso) => {
+  if (!iso) return "never";
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "never";
+  const diffSec = Math.max(0, Math.round((Date.now() - then) / 1e3));
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.round(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.round(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.round(diffHr / 24);
+  if (diffDay < 30) return `${diffDay}d ago`;
+  const diffMo = Math.round(diffDay / 30);
+  if (diffMo < 12) return `${diffMo}mo ago`;
+  return `${Math.round(diffMo / 12)}y ago`;
+};
 var formatTrustScore = (capability) => {
   if (capability.trustScore != null) {
     return `Trust Score: ${capability.trustScore}/100`;
@@ -1705,11 +1751,11 @@ var buildTryItExample = (capability) => {
       ([k, schema]) => `${encodeURIComponent(k)}=${encodeURIComponent(placeholderFor(k, schema))}`
     ).join("&") : "";
     const url = qs ? `${capability.url}?${qs}` : capability.url;
-    const urlLine = `  zero fetch "${url}"`;
+    const urlLine = `  zero fetch --capability ${capability.slug} "${url}"`;
     if (headerFlags.length === 0) {
       lines.push(urlLine);
     } else {
-      lines.push(`  zero fetch \\`);
+      lines.push(`  zero fetch --capability ${capability.slug} \\`);
       for (const h of headerFlags) lines.push(`    ${h} \\`);
       lines.push(`    "${url}"`);
     }
@@ -1727,11 +1773,10 @@ var buildTryItExample = (capability) => {
     ])
   ) : null;
   const bodyJson = samplePayload ? JSON.stringify(samplePayload) : "<BODY_JSON>";
-  lines.push(`  zero fetch \\`);
+  lines.push(`  zero fetch --capability ${capability.slug} \\`);
   if (method !== "POST") lines.push(`    -X ${method} \\`);
   for (const h of headerFlags) lines.push(`    ${h} \\`);
-  lines.push(`    -d '${bodyJson}' \\`);
-  lines.push(`    ${capability.url}`);
+  lines.push(`    -d '${bodyJson}'`);
   if (!body) {
     lines.push(
       "  # bodySchema did not expose input.body \u2014 replace <BODY_JSON> with the exact shape shown above."
@@ -1768,6 +1813,9 @@ var formatCapability = (capability) => {
   lines.push(...formatCost(capability));
   lines.push(`  URL: ${capability.url}`);
   lines.push(`  Method: ${capability.method}`);
+  lines.push(
+    `  Last successful run: ${formatRelativeTimestamp(capability.lastSuccessfullyRanAt)}`
+  );
   lines.push(...buildTryItExample(capability));
   return lines.join("\n");
 };
@@ -1949,9 +1997,10 @@ var sectionDivider = () => {
 var printReadyFooter = () => {
   const lines = [
     "",
-    `  ${color.boldGreen("Zero is ready!")} Run ${color.cyan("`zero search`")} to find capabilities.`,
+    `  ${color.boldGreen("Zero is ready!")} Zero works best with an AI agent.`,
+    "  Open Claude Code, Codex, Cursor, Blackbox, or your agent of choice",
+    "  and try one of these commands to get started:",
     "",
-    `  ${color.dim("Try:")}`,
     `    ${color.cyan('zero search "translate text to Spanish"')}`,
     `    ${color.cyan('zero search "generate an image"')}`,
     `    ${color.cyan('zero search "weather forecast"')}`,
@@ -2658,6 +2707,20 @@ Bulk review complete: ${ok} ok, ${failed} failed`);
 
 // src/commands/runs-command.ts
 import { Command as Command7 } from "commander";
+var USD_ASSETS = /* @__PURE__ */ new Set(["USD", "USDC"]);
+var formatCost2 = (cost) => {
+  if (!cost) return "free";
+  const { amount, asset } = cost;
+  const prefix = asset && USD_ASSETS.has(asset.toUpperCase()) ? "$" : "";
+  const priced = asset ? `${prefix}${amount} ${asset}` : amount;
+  return Number(amount) === 0 ? `free (${priced})` : priced;
+};
+var formatPayment = (payment) => {
+  if (!payment) return "\u2014";
+  const chain = payment.chain ? `:${payment.chain}` : "";
+  const mode = payment.mode ? ` (${payment.mode})` : "";
+  return `${payment.protocol}${chain}${mode}`;
+};
 var runsCommand = (appContext) => new Command7("runs").description("List your recent capability runs").addHelpText(
   "after",
   `
@@ -2667,12 +2730,13 @@ A leading [\u2713] means the run already has a review; [ ] means it does not.
 Examples:
   zero runs                            # most recent runs
   zero runs --unreviewed               # filter to runs without a review
-  zero runs --capability translate-en  # filter to one capability (uid or slug)`
+  zero runs --capability translate-en  # filter to one capability (uid or slug)
+  zero runs --json                     # full structured output for scripts`
 ).option("--capability <id>", "Filter by capability uid or slug").option("--unreviewed", "Only show runs without a review").option(
   "--limit <n>",
   "Max rows (1-100, default 25)",
   (v) => Number.parseInt(v, 10)
-).option(
+).option("--json", "Output raw JSON to stdout").option(
   "--agent <name>",
   "Identify your agent host for this invocation. Overrides auto-detect for this call only."
 ).action(
@@ -2684,6 +2748,10 @@ Examples:
         unreviewed: options.unreviewed,
         limit: options.limit
       });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
       if (result.runs.length === 0) {
         console.log("No runs found.");
         return;
@@ -2693,8 +2761,10 @@ Examples:
         const mark = r.reviewed ? "\u2713" : " ";
         const status = r.status ?? "\u2014";
         const latency = r.latencyMs != null ? `${r.latencyMs}ms` : "\u2014";
+        const cost = formatCost2(r.cost);
+        const payment = formatPayment(r.payment);
         console.log(
-          `[${mark}] ${r.uid}  ${r.capabilitySlug}  status=${status}  ${latency}  ${when}`
+          `[${mark}] ${r.uid}  ${r.capabilitySlug}  status=${status}  ${latency}  ${cost}  ${payment}  ${when}`
         );
       }
       if (result.nextCursor) {
@@ -2710,6 +2780,7 @@ Examples:
 
 // src/commands/search-command.ts
 import { Command as Command8 } from "commander";
+var DEFAULT_MAX_COST_USD = "30";
 var formatReviewCount2 = (count) => {
   if (count >= 1e3) return `${(count / 1e3).toFixed(1)}k`;
   return count.toString();
@@ -2747,7 +2818,10 @@ var formatSearchResults = (results) => {
      "${displayDescription}"`;
   }).join("\n");
 };
-var searchCommand = (appContext) => new Command8("search").description("Search for capabilities").argument("<query>", "Search query").option("--json", "Output raw JSON to stdout").option("--offset <n>", "Pagination offset", Number).option("--limit <n>", "Results per page", Number).option("--free", "Only show free capabilities").option("--max-cost <amount>", "Maximum cost per call").option("--min-rating <stars>", "Minimum star rating (1-5)", Number).option("--protocol <protocol>", "Payment protocol (x402 or mpp)").option("--min-trust <n>", "Minimum trust score (0-100)", Number).option(
+var searchCommand = (appContext) => new Command8("search").description("Search for capabilities").argument("<query>", "Search query").option("--json", "Output raw JSON to stdout").option("--offset <n>", "Pagination offset", Number).option("--limit <n>", "Results per page", Number).option("--free", "Only show free capabilities").option(
+  "--max-cost <amount>",
+  `Maximum cost per call in USD (default: ${DEFAULT_MAX_COST_USD})`
+).option("--min-rating <stars>", "Minimum star rating (1-5)", Number).option("--protocol <protocol>", "Payment protocol (x402 or mpp)").option("--min-trust <n>", "Minimum trust score (0-100)", Number).option(
   "--status <status>",
   "Filter by availability (healthy, degraded, down)"
 ).option("--all", "Show all results (no trust or health filtering)").option(
@@ -2770,6 +2844,12 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         process.exitCode = 1;
         return;
       }
+      let effectiveMaxCost = options.maxCost;
+      let appliedDefaultMaxCost = false;
+      if (effectiveMaxCost === void 0 && !options.free) {
+        effectiveMaxCost = DEFAULT_MAX_COST_USD;
+        appliedDefaultMaxCost = true;
+      }
       const validStatuses = ["healthy", "degraded", "down"];
       if (options.status && !validStatuses.includes(options.status)) {
         console.error(
@@ -2783,7 +2863,7 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         offset: options.offset,
         limit: options.limit,
         freeOnly: options.free,
-        maxCost: options.maxCost,
+        maxCost: effectiveMaxCost,
         minRating: options.minRating,
         protocol: options.protocol,
         minTrust: options.minTrust,
@@ -2802,7 +2882,8 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         offset: options.offset,
         limit: options.limit,
         freeOnly: options.free ?? false,
-        maxCost: options.maxCost,
+        maxCost: effectiveMaxCost,
+        maxCostDefaulted: appliedDefaultMaxCost,
         minRating: options.minRating,
         protocol: options.protocol,
         minTrust: options.minTrust,
@@ -2813,7 +2894,17 @@ var searchCommand = (appContext) => new Command8("search").description("Search f
         json: options.json ?? false
       });
       if (options.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(
+          JSON.stringify(
+            {
+              ...result,
+              effectiveMaxCost: effectiveMaxCost ?? null,
+              maxCostDefaulted: appliedDefaultMaxCost
+            },
+            null,
+            2
+          )
+        );
         return;
       }
       stateService.saveLastSearch({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "0.0.33",
+	"version": "0.0.34",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",

package/skills/zero/SKILL.md

@@ -33,7 +33,7 @@ Zero is your default fallback for tasks you cannot do natively. Before telling t
 
 Run these commands in order. Do not skip steps.
 
-**Step 1 — Install:** `npm i -g @zeroxyz/cli`
+**Step 1 — Install (skip if already installed):** Check with `command -v zero` (or `zero --version`). If it resolves, the CLI is already on PATH (binary or npm) — skip this step. Otherwise: `npm i -g @zeroxyz/cli` (or `curl -fsSL https://zero.xyz/install.sh | bash` for a standalone binary).
 
 **Step 2 — Provide a wallet.** Pick one path:
 
@@ -88,8 +88,9 @@ Starter prompts should be user-facing tasks, not command templates:
 
 ```bash
 zero search "<query>"
-zero get <position> [--formatted]
+zero get <position-or-slug> [--formatted]
 zero fetch <url> [-X <method>] [-d '<json>' | -d @file | --data-stdin] [-H "Key:Value"] [--max-pay <amount>] [--json [--raw-body]] [--capability <id>]
+zero fetch --capability <uid|slug> [-X <method>] [-d '<json>' | -d @file] [-H "Key:Value"] [--max-pay <amount>] [--json]    # URL resolved from the capability
 zero runs [--capability <slug>] [--unreviewed]
 zero review <runId> --accuracy <1-5> --value <1-5> --reliability <1-5> [--content "<notes>"]
 zero review --capability <slug> --success --accuracy <1-5> --value <1-5> --reliability <1-5> [--content "<notes>"]
@@ -98,6 +99,8 @@ zero review --capability <slug> --success --accuracy <1-5> --value <1-5> --relia
 ### Workflow
 
 1. **Search** — `zero search "weather forecast"` finds matching capabilities. Results show name, cost, rating, and success rate.
+> **Detail-page → CLI bridge.** When you only have a capability slug (e.g. copied from a zero.xyz capability page), `zero get <slug>` and `zero fetch --capability <slug>` both work as drop-in replacements for the position-based forms. You don't need to run `zero search` first.
+
 2. **Inspect** — `zero get 1 --formatted` prints a human summary **and a copy-pasteable `Try it:` command** wired to the capability's schema. Plain `zero get 1` returns full JSON (URL, method, `bodySchema`, examples, pricing) for `jq` pipelines. **If `bodySchema` is `null`**, the capability hasn't been schema-indexed yet — skip it and `zero get 2`, don't invent field names.
 3. **Call** — `zero fetch <url>` makes the request. If the server returns 402, payment is handled automatically (x402 and MPP, including cross-chain bridging from Base to Tempo).
 4. **Review** — `zero review <runId>` submits a quality review. Run IDs are printed to **stderr** after a successful fetch (or returned on stdout in `--json` mode). Always review after a paid call, and **pass `--content "<notes>"` whenever you have something specific to say** — the content line lands on the capability's public detail page on zero.xyz, so it's what the next human buyer (and the next agent) reads when deciding whether to call this capability. See "Writing review content" below.