@agent-nexus/cli 0.1.12 → 0.1.14

package/dist/index.js

@@ -166,7 +166,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@agent-nexus/cli",
-      version: "0.1.12",
+      version: "0.1.14",
       description: "Official CLI for the Nexus AI agent platform.",
       license: "MIT",
       keywords: [
@@ -778,10 +778,7 @@ var ChannelsResource = class extends BaseResource {
     return this.http.request("POST", "/channels/whatsapp-templates", { body });
   }
   async getWhatsAppTemplate(templateId) {
-    return this.http.request(
-      "GET",
-      `/channels/whatsapp-templates/${templateId}`
-    );
+    return this.http.request("GET", `/channels/whatsapp-templates/${templateId}`);
   }
   async deleteWhatsAppTemplate(templateId) {
     return this.http.request(
@@ -790,19 +787,34 @@ var ChannelsResource = class extends BaseResource {
     );
   }
   async listTemplateApprovals(params) {
+    return this.http.request("GET", "/channels/whatsapp-templates/approvals", {
+      query: params
+    });
+  }
+  async submitTemplateApproval(body) {
     return this.http.request(
-      "GET",
+      "POST",
       "/channels/whatsapp-templates/approvals",
-      { query: params }
+      { body }
     );
   }
-  async submitTemplateApproval(body) {
+  // ===========================================================================
+  // WhatsApp Template Test-Send
+  // ===========================================================================
+  async testSendWhatsAppTemplate(templateId, body) {
     return this.http.request(
       "POST",
-      "/channels/whatsapp-templates/approvals",
+      `/channels/whatsapp-templates/${templateId}/test-send`,
       { body }
     );
   }
+  async getTestSendStatus(templateId, messageSid, params) {
+    return this.http.request(
+      "GET",
+      `/channels/whatsapp-templates/${templateId}/test-send/${messageSid}/status`,
+      { query: params }
+    );
+  }
 };
 var CloudImportsResource = class extends BaseResource {
   // Google Drive
@@ -2061,6 +2073,64 @@ var ToolDiscoveryResource = class extends BaseResource {
     );
   }
 };
+var TracingResource = class extends BaseResource {
+  // ── Traces ──────────────────────────────────────────────────────────────
+  async listTraces(params) {
+    const { data, meta } = await this.http.requestWithMeta(
+      "GET",
+      "/tracing/traces",
+      { query: params }
+    );
+    return { data, meta };
+  }
+  async getTrace(traceId) {
+    return this.http.request("GET", `/tracing/traces/${traceId}`);
+  }
+  async deleteTrace(traceId) {
+    return this.http.request("DELETE", `/tracing/traces/${traceId}`);
+  }
+  // ── Generations ─────────────────────────────────────────────────────────
+  async listGenerations(params) {
+    const { data, meta } = await this.http.requestWithMeta(
+      "GET",
+      "/tracing/generations",
+      { query: params }
+    );
+    return { data, meta };
+  }
+  async getGeneration(generationId) {
+    return this.http.request("GET", `/tracing/generations/${generationId}`);
+  }
+  // ── Models ──────────────────────────────────────────────────────────────
+  async listModels() {
+    return this.http.request("GET", "/tracing/models");
+  }
+  // ── Analytics ───────────────────────────────────────────────────────────
+  async getSummary(params) {
+    return this.http.request("GET", "/tracing/analytics/summary", {
+      query: params
+    });
+  }
+  async getCostBreakdown(params) {
+    return this.http.request("GET", "/tracing/analytics/cost-breakdown", {
+      query: params
+    });
+  }
+  async getTimeline(params) {
+    return this.http.request("GET", "/tracing/analytics/timeline", {
+      query: params
+    });
+  }
+  // ── Export ──────────────────────────────────────────────────────────────
+  async exportTrace(traceId, params) {
+    return this.http.request("POST", `/tracing/traces/${traceId}/export`, {
+      body: params
+    });
+  }
+  async bulkExport(params) {
+    return this.http.request("POST", "/tracing/export", { body: params });
+  }
+};
 var WorkflowExecutionsResource = class extends BaseResource {
   async list(params) {
     const { data, meta } = await this.http.requestWithMeta("GET", "/workflows/executions", {
@@ -2533,6 +2603,7 @@ var NexusClient = class {
     this.phoneNumbers = new PhoneNumbersResource(http);
     this.tickets = new TicketsResource(http);
     this.channels = new ChannelsResource(http);
+    this.tracing = new TracingResource(http);
   }
 };
 
@@ -3663,6 +3734,41 @@ function openUrl(url) {
 var import_node_child_process2 = require("child_process");
 var import_node_fs2 = require("fs");
 init_output();
+var VARIABLE_PATTERN = /\{\{\d+\}\}/g;
+function warnIfHighVariableDensity(types) {
+  let warned = false;
+  function checkField(text, fieldLabel) {
+    const matches = text.match(VARIABLE_PATTERN) ?? [];
+    if (matches.length === 0) return;
+    const variableCharsLength = matches.reduce((sum, m) => sum + m.length, 0);
+    const staticLength = text.length - variableCharsLength;
+    if (staticLength < matches.length * 3) {
+      console.warn(
+        color.yellow("\u26A0 Warning:") + ` ${fieldLabel} has very high variable density (${staticLength} static chars, ${matches.length} variable(s)). Meta may reject this with "too many variables for its length."`
+      );
+      warned = true;
+    }
+  }
+  for (const [typeKey, typeValue] of Object.entries(types)) {
+    if (!typeValue || typeof typeValue !== "object") continue;
+    const tv = typeValue;
+    if (typeof tv.body === "string") checkField(tv.body, `${typeKey} body`);
+    if (typeof tv.title === "string") checkField(tv.title, `${typeKey} title`);
+    if (typeof tv.subtitle === "string") checkField(tv.subtitle, `${typeKey} subtitle`);
+    if (Array.isArray(tv.cards)) {
+      tv.cards.forEach((card, i) => {
+        if (typeof card?.body === "string") checkField(card.body, `${typeKey} card[${i}] body`);
+        if (typeof card?.title === "string") checkField(card.title, `${typeKey} card[${i}] title`);
+      });
+    }
+  }
+  if (warned) {
+    console.warn(
+      color.yellow("  Tip:") + " Add more descriptive static text around {{N}} placeholders to avoid Meta rejection.\n"
+    );
+  }
+  return warned;
+}
 function openUrl2(url) {
   const platform = process.platform;
   const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
@@ -3914,6 +4020,7 @@ Examples:
           return;
         }
       }
+      warnIfHighVariableDensity(types);
       const client = createClient(program2.optsWithGlobals());
       const result = await client.channels.createWhatsAppTemplate({
         connectionId: opts.connectionId,
@@ -3945,6 +4052,44 @@ Examples:
           { key: "status", label: "Status" }
         ]);
         printSuccess("Template submitted for Meta approval.");
+        const pollMaxMs = 3e4;
+        const pollIntervalMs = 5e3;
+        const pollStart = Date.now();
+        let resolved = false;
+        console.log("Checking approval status...");
+        while (Date.now() - pollStart < pollMaxMs) {
+          await new Promise((r) => setTimeout(r, pollIntervalMs));
+          try {
+            const approvals = await client.channels.listTemplateApprovals({
+              connectionId: opts.connectionId
+            });
+            const approvalsArr = approvals?.data ?? approvals;
+            const items = Array.isArray(approvalsArr) ? approvalsArr : [approvalsArr];
+            const match = items.find((a) => a.sid === data.id);
+            if (match?.approvalRequests?.status) {
+              const status = match.approvalRequests.status;
+              if (status === "rejected") {
+                console.log(color.red(`\u2717 Template rejected by Meta: ${status}`));
+                if (match.approvalRequests.rejection_reason) {
+                  console.log(`  Reason: ${match.approvalRequests.rejection_reason}`);
+                }
+                resolved = true;
+                process.exitCode = 1;
+                break;
+              } else if (status === "approved") {
+                console.log(color.green(`\u2713 Template approved by Meta.`));
+                resolved = true;
+                break;
+              }
+            }
+          } catch {
+          }
+        }
+        if (!resolved) {
+          console.log(
+            `Status still pending. Check later: ${color.dim("nexus channel whatsapp-template approvals")}`
+          );
+        }
       }
     } catch (err) {
       process.exitCode = handleError(err);
@@ -4069,6 +4214,83 @@ Next: Attach to deployment: ${color.dim("nexus deployment template attach <depId
       process.exitCode = handleError(err);
     }
   });
+  waTemplate.command("test-send").description(
+    "Test-send a WhatsApp template to a phone number via the real Twilio/Meta pipeline"
+  ).requiredOption("--connection-id <id>", "Messaging connection ID").requiredOption("--template-id <id>", "Template ID (Twilio content SID)").requiredOption("--to <phone>", "Recipient phone number in E.164 format (e.g., +1234567890)").option("--variables <json>", `Template variables as JSON (e.g., '{"1": "Hello"}')`).option("--wait", "Poll delivery status until resolved (up to 2 minutes)").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus channel whatsapp-template test-send --connection-id abc --template-id HX123 --to +1234567890
+  $ nexus channel whatsapp-template test-send --connection-id abc --template-id HX123 --to +1234567890 --variables '{"1": "Sneakers"}' --wait`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      let variables;
+      if (opts.variables) {
+        try {
+          variables = JSON.parse(opts.variables);
+        } catch {
+          console.error(`Invalid JSON for --variables. Example: '{"1": "Hello"}'`);
+          process.exitCode = 1;
+          return;
+        }
+      }
+      const result = await client.channels.testSendWhatsAppTemplate(opts.templateId, {
+        connectionId: opts.connectionId,
+        to: opts.to,
+        variables
+      });
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "messageSid", label: "Message SID" },
+        { key: "status", label: "Status" },
+        { key: "to", label: "To" },
+        { key: "from", label: "From" },
+        { key: "sentAt", label: "Sent At" }
+      ]);
+      printSuccess("Template test-send initiated.");
+      if (opts.wait) {
+        const maxWaitMs = 12e4;
+        const intervalMs = 5e3;
+        const startTime = Date.now();
+        let lastStatus = data.status;
+        console.log("Polling delivery status...");
+        while (Date.now() - startTime < maxWaitMs) {
+          await new Promise((r) => setTimeout(r, intervalMs));
+          try {
+            const statusResult = await client.channels.getTestSendStatus(
+              opts.templateId,
+              data.messageSid,
+              { connectionId: opts.connectionId }
+            );
+            const statusData = statusResult?.data ?? statusResult;
+            lastStatus = statusData.status;
+            if (["delivered", "read"].includes(lastStatus)) {
+              console.log(color.green(`\u2713 Message ${lastStatus}.`));
+              break;
+            } else if (["failed", "undelivered"].includes(lastStatus)) {
+              console.log(color.red(`\u2717 Message ${lastStatus}.`));
+              if (statusData.errorCode) {
+                console.log(
+                  `  Error ${statusData.errorCode}: ${statusData.errorMessage ?? "Unknown error"}`
+                );
+              }
+              process.exitCode = 1;
+              break;
+            }
+          } catch {
+          }
+        }
+        if (!["delivered", "read", "failed", "undelivered"].includes(lastStatus)) {
+          console.log(
+            `Status still '${lastStatus}' after 2m. The message may still be in transit.`
+          );
+        }
+      }
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
 }
 
 // src/commands/collection.ts
@@ -4799,12 +5021,25 @@ Examples:
       process.exitCode = handleError(err);
     }
   });
-  depTemplate.command("attach").description("Attach a WhatsApp template to a deployment").argument("<deploymentId>", "Deployment ID").requiredOption("--template-id <id>", "Template ID (Twilio SID)").requiredOption("--name <name>", "Display name for this template").requiredOption("--description <text>", "Description of what this template does").option("--variables <json>", 'Variables JSON: {"1":{"description":"Name","isBodyVariable":true}}').option("--type <type>", "Template type: template, card, or carousel", "template").option("--enable-multi-language", "Enable multi-language support").addHelpText(
+  depTemplate.command("attach").description("Attach a WhatsApp template to a deployment").argument("<deploymentId>", "Deployment ID").requiredOption("--template-id <id>", "Template ID (Twilio SID)").requiredOption("--name <name>", "Display name for this template").requiredOption("--description <text>", "Description of what this template does").option(
+    "--variables <json>",
+    'Variables JSON: {"1":{"description":"Name","isBodyVariable":true}}'
+  ).option("--type <type>", "Template type: template, card, or carousel", "template").option("--enable-multi-language", "Enable multi-language support").option("--enable-dynamic-size", "Enable dynamic carousel size (carousel only)").option(
+    "--carousel-template-group <json>",
+    "Carousel template group JSON with size variants (carousel only)"
+  ).option(
+    "--single-item-card-template-id <id>",
+    "Fallback card template ID for single-item carousels"
+  ).option(
+    "--single-item-card-template-group <json>",
+    "Single-item card template group JSON for multi-language fallback"
+  ).addHelpText(
     "after",
     `
 Examples:
   $ nexus deployment template attach dep-123 --template-id HX456 --name welcome --description "Welcome message"
-  $ nexus deployment template attach dep-123 --template-id HX456 --name order --description "Order confirmation" --variables '{"1":{"description":"Customer name","isBodyVariable":true}}'`
+  $ nexus deployment template attach dep-123 --template-id HX456 --name order --description "Order confirmation" --variables '{"1":{"description":"Customer name","isBodyVariable":true}}'
+  $ nexus deployment template attach dep-123 --template-id HX456 --name products --description "Product carousel" --type carousel --enable-dynamic-size --carousel-template-group '{"baseName":"products","availableTemplates":[{"language":"en","carouselSize":3,"templateId":"HX111"},{"language":"en","carouselSize":5,"templateId":"HX222"}],"minCarouselSize":3,"maxCarouselSize":5}'`
   ).action(async (deploymentId, opts) => {
     try {
       let variables;
@@ -4817,6 +5052,26 @@ Examples:
           return;
         }
       }
+      let carouselTemplateGroup;
+      if (opts.carouselTemplateGroup) {
+        try {
+          carouselTemplateGroup = JSON.parse(opts.carouselTemplateGroup);
+        } catch {
+          console.error("Error: --carousel-template-group must be valid JSON.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      let singleItemCardTemplateGroup;
+      if (opts.singleItemCardTemplateGroup) {
+        try {
+          singleItemCardTemplateGroup = JSON.parse(opts.singleItemCardTemplateGroup);
+        } catch {
+          console.error("Error: --single-item-card-template-group must be valid JSON.");
+          process.exitCode = 1;
+          return;
+        }
+      }
       const client = createClient(program2.optsWithGlobals());
       const result = await client.deployments.attachDeploymentTemplate(deploymentId, {
         templateId: opts.templateId,
@@ -4824,7 +5079,11 @@ Examples:
         description: opts.description,
         variables,
         type: opts.type,
-        enableMultiLanguage: opts.enableMultiLanguage
+        enableMultiLanguage: opts.enableMultiLanguage,
+        enableDynamicSize: opts.enableDynamicSize,
+        carouselTemplateGroup,
+        singleItemCardTemplateId: opts.singleItemCardTemplateId,
+        singleItemCardTemplateGroup
       });
       const data = result?.data ?? result;
       printRecord(data, [
@@ -4838,12 +5097,22 @@ Examples:
       process.exitCode = handleError(err);
     }
   });
-  depTemplate.command("update").description("Update a template's configuration on a deployment").argument("<deploymentId>", "Deployment ID").argument("<templateId>", "Template ID (Twilio SID)").option("--name <name>", "New display name").option("--description <text>", "New description").option("--variables <json>", "Updated variables JSON").option("--enable-multi-language", "Enable multi-language support").option("--no-multi-language", "Disable multi-language support").addHelpText(
+  depTemplate.command("update").description("Update a template's configuration on a deployment").argument("<deploymentId>", "Deployment ID").argument("<templateId>", "Template ID (Twilio SID)").option("--name <name>", "New display name").option("--description <text>", "New description").option("--variables <json>", "Updated variables JSON").option("--enable-multi-language", "Enable multi-language support").option("--no-multi-language", "Disable multi-language support").option("--enable-dynamic-size", "Enable dynamic carousel size (carousel only)").option("--no-dynamic-size", "Disable dynamic carousel size").option(
+    "--carousel-template-group <json>",
+    "Carousel template group JSON with size variants (carousel only)"
+  ).option(
+    "--single-item-card-template-id <id>",
+    "Fallback card template ID for single-item carousels"
+  ).option(
+    "--single-item-card-template-group <json>",
+    "Single-item card template group JSON for multi-language fallback"
+  ).addHelpText(
     "after",
     `
 Examples:
   $ nexus deployment template update dep-123 HX456 --name "Updated Welcome"
-  $ nexus deployment template update dep-123 HX456 --variables '{"1":{"description":"Full name"}}'`
+  $ nexus deployment template update dep-123 HX456 --variables '{"1":{"description":"Full name"}}'
+  $ nexus deployment template update dep-123 HX456 --enable-dynamic-size --carousel-template-group '{"baseName":"products","availableTemplates":[...]}'`
   ).action(async (deploymentId, templateId, opts) => {
     try {
       const body = {};
@@ -4851,6 +5120,9 @@ Examples:
       if (opts.description !== void 0) body.description = opts.description;
       if (opts.enableMultiLanguage !== void 0)
         body.enableMultiLanguage = opts.enableMultiLanguage;
+      if (opts.enableDynamicSize !== void 0) body.enableDynamicSize = opts.enableDynamicSize;
+      if (opts.singleItemCardTemplateId !== void 0)
+        body.singleItemCardTemplateId = opts.singleItemCardTemplateId;
       if (opts.variables) {
         try {
           body.variables = JSON.parse(opts.variables);
@@ -4860,6 +5132,24 @@ Examples:
           return;
         }
       }
+      if (opts.carouselTemplateGroup) {
+        try {
+          body.carouselTemplateGroup = JSON.parse(opts.carouselTemplateGroup);
+        } catch {
+          console.error("Error: --carousel-template-group must be valid JSON.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      if (opts.singleItemCardTemplateGroup) {
+        try {
+          body.singleItemCardTemplateGroup = JSON.parse(opts.singleItemCardTemplateGroup);
+        } catch {
+          console.error("Error: --single-item-card-template-group must be valid JSON.");
+          process.exitCode = 1;
+          return;
+        }
+      }
       const client = createClient(program2.optsWithGlobals());
       const result = await client.deployments.updateDeploymentTemplate(
         deploymentId,
@@ -4886,7 +5176,10 @@ Examples:
           output: process.stdout
         });
         const answer = await new Promise((resolve) => {
-          rl.question(`Detach template ${templateId} from deployment ${deploymentId}? (y/N) `, resolve);
+          rl.question(
+            `Detach template ${templateId} from deployment ${deploymentId}? (y/N) `,
+            resolve
+          );
         });
         rl.close();
         if (answer.toLowerCase() !== "y") {
@@ -12537,6 +12830,390 @@ Examples:
   });
 }
 
+// src/commands/tracing.ts
+init_output();
+function registerTracingCommands(program2) {
+  const tracing = program2.command("tracing").description("View LLM traces and analytics");
+  addPaginationOptions(
+    tracing.command("traces").description("List LLM traces").option("--status <status>", "Filter by status (IN_PROGRESS, COMPLETED, FAILED)").option("--agent-id <id>", "Filter by agent ID").option("--workflow-id <id>", "Filter by workflow ID").option("--model <name>", "Filter by model name (max 255 chars)").option("--start-date <iso>", "Filter from date (ISO 8601, e.g. 2026-03-01)").option("--end-date <iso>", "Filter to date (ISO 8601, e.g. 2026-03-01)").option(
+      "--sort-by <field>",
+      "Sort by field (startedAt, totalCostUsd, totalDurationMs)",
+      "startedAt"
+    ).option("--order <dir>", "Sort order (asc, desc)", "desc").addHelpText(
+      "after",
+      `
+Examples:
+  $ nexus tracing traces
+  $ nexus tracing traces --status FAILED --limit 10
+  $ nexus tracing traces --agent-id abc --start-date 2026-03-01 --json`
+    )
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const { data, meta } = await client.tracing.listTraces({
+        ...getPaginationParams(opts),
+        status: opts.status,
+        agentId: opts.agentId,
+        workflowId: opts.workflowId,
+        model: opts.model,
+        startDate: opts.startDate,
+        endDate: opts.endDate,
+        sortBy: opts.sortBy,
+        order: opts.order
+      });
+      printList(
+        data,
+        meta,
+        [
+          { key: "id", label: "ID", width: 36 },
+          { key: "status", label: "STATUS", width: 12, format: formatStatus },
+          { key: "agentName", label: "AGENT", width: 20 },
+          { key: "workflowName", label: "WORKFLOW", width: 20 },
+          {
+            key: "totalCostUsd",
+            label: "COST ($)",
+            width: 10,
+            format: (v) => v != null ? `$${Number(v).toFixed(4)}` : "-"
+          },
+          {
+            key: "totalDurationMs",
+            label: "DURATION",
+            width: 10,
+            format: (v) => v != null ? `${Number(v)}ms` : "-"
+          },
+          { key: "generationCount", label: "GENS", width: 5 },
+          { key: "startedAt", label: "STARTED", width: 20 }
+        ]
+      );
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("trace").description("Get trace details with generations").argument("<id>", "Trace ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing trace abc-123
+  $ nexus tracing trace abc-123 --json`
+  ).action(async (id) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const trace = await client.tracing.getTrace(id);
+      printRecord(trace, [
+        { key: "id", label: "ID" },
+        { key: "status", label: "Status" },
+        { key: "agentName", label: "Agent" },
+        { key: "workflowName", label: "Workflow" },
+        {
+          key: "totalCostUsd",
+          label: "Cost ($)",
+          format: (v) => v != null ? `$${Number(v).toFixed(4)}` : "-"
+        },
+        { key: "totalInputTokens", label: "Input Tokens" },
+        { key: "totalOutputTokens", label: "Output Tokens" },
+        { key: "totalDurationMs", label: "Duration (ms)" },
+        { key: "startedAt", label: "Started" },
+        { key: "completedAt", label: "Completed" }
+      ]);
+      const gens = trace.generations;
+      if (gens && gens.length > 0) {
+        console.log(`
+${color.bold("Generations")} (${gens.length}):
+`);
+        printList(gens, void 0, [
+          { key: "id", label: "ID", width: 36 },
+          { key: "modelName", label: "MODEL", width: 25 },
+          { key: "status", label: "STATUS", width: 12, format: formatStatus },
+          {
+            key: "costUsd",
+            label: "COST ($)",
+            width: 10,
+            format: (v) => v != null ? `$${Number(v).toFixed(6)}` : "-"
+          },
+          {
+            key: "durationMs",
+            label: "DURATION",
+            width: 10,
+            format: (v) => v != null ? `${v}ms` : "-"
+          }
+        ]);
+      }
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("delete").description("Delete a trace and its generations").argument("<id>", "Trace ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing delete abc-123`
+  ).action(async (id) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      await client.tracing.deleteTrace(id);
+      printSuccess("Trace deleted.", { id });
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  addPaginationOptions(
+    tracing.command("generations").description("List LLM generations across traces").option("--trace-id <id>", "Filter by trace ID").option("--provider <provider>", "Filter by provider (OPEN_AI, ANTHROPIC, GOOGLE_AI)").option("--model <name>", "Filter by model name (max 255 chars)").option("--status <status>", "Filter by status (PENDING, RUNNING, COMPLETED, FAILED)").option("--agent-id <id>", "Filter by agent ID").option("--task-id <id>", "Filter by task ID").option("--start-date <iso>", "Filter from date (ISO 8601, e.g. 2026-03-01)").option("--end-date <iso>", "Filter to date (ISO 8601, e.g. 2026-03-01)").option("--min-cost <usd>", "Minimum cost in USD").option("--max-cost <usd>", "Maximum cost in USD").addHelpText(
+      "after",
+      `
+Examples:
+  $ nexus tracing generations
+  $ nexus tracing generations --provider ANTHROPIC --status FAILED
+  $ nexus tracing generations --trace-id abc-123 --json`
+    )
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const { data, meta } = await client.tracing.listGenerations({
+        ...getPaginationParams(opts),
+        traceId: opts.traceId,
+        provider: opts.provider,
+        modelName: opts.model,
+        status: opts.status,
+        agentId: opts.agentId,
+        taskId: opts.taskId,
+        startDate: opts.startDate,
+        endDate: opts.endDate,
+        minCostUsd: opts.minCost ? parseFloat(opts.minCost) : void 0,
+        maxCostUsd: opts.maxCost ? parseFloat(opts.maxCost) : void 0
+      });
+      printList(
+        data,
+        meta,
+        [
+          { key: "id", label: "ID", width: 36 },
+          { key: "traceId", label: "TRACE", width: 36 },
+          { key: "modelName", label: "MODEL", width: 25 },
+          { key: "status", label: "STATUS", width: 12, format: formatStatus },
+          {
+            key: "costUsd",
+            label: "COST ($)",
+            width: 10,
+            format: (v) => v != null ? `$${Number(v).toFixed(6)}` : "-"
+          },
+          {
+            key: "durationMs",
+            label: "DURATION",
+            width: 10,
+            format: (v) => v != null ? `${v}ms` : "-"
+          }
+        ]
+      );
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("generation").description("Get generation details including prompt and response").argument("<id>", "Generation ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing generation gen-123
+  $ nexus tracing generation gen-123 --json`
+  ).action(async (id) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const gen = await client.tracing.getGeneration(id);
+      printRecord(gen, [
+        { key: "id", label: "ID" },
+        { key: "traceId", label: "Trace ID" },
+        { key: "provider", label: "Provider" },
+        { key: "modelName", label: "Model" },
+        { key: "status", label: "Status" },
+        { key: "inputTokens", label: "Input Tokens" },
+        { key: "outputTokens", label: "Output Tokens" },
+        {
+          key: "costUsd",
+          label: "Cost ($)",
+          format: (v) => v != null ? `$${Number(v).toFixed(6)}` : "-"
+        },
+        { key: "durationMs", label: "Duration (ms)" },
+        { key: "temperature", label: "Temperature" },
+        { key: "taskName", label: "Task" },
+        { key: "startedAt", label: "Started" },
+        { key: "completedAt", label: "Completed" },
+        { key: "errorMessage", label: "Error" }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("models").description("List distinct model names used in traces").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing models`
+  ).action(async () => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const models = await client.tracing.listModels();
+      if (Array.isArray(models) && models.length > 0) {
+        for (const m of models) console.log(m);
+      } else {
+        console.log("No models found.");
+      }
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("summary").description("Get tracing analytics summary").option("--start-date <iso>", "Period start (ISO 8601)").option("--end-date <iso>", "Period end (ISO 8601)").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing summary
+  $ nexus tracing summary --start-date 2026-03-01 --end-date 2026-03-30
+  $ nexus tracing summary --json`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const summary = await client.tracing.getSummary({
+        startDate: opts.startDate,
+        endDate: opts.endDate
+      });
+      printRecord(summary, [
+        { key: "totalTraces", label: "Total Traces" },
+        { key: "completedTraces", label: "Completed" },
+        { key: "failedTraces", label: "Failed" },
+        { key: "inProgressTraces", label: "In Progress" },
+        {
+          key: "totalCostUsd",
+          label: "Total Cost ($)",
+          format: (v) => `$${Number(v).toFixed(4)}`
+        },
+        { key: "totalInputTokens", label: "Input Tokens" },
+        { key: "totalOutputTokens", label: "Output Tokens" },
+        {
+          key: "avgDurationMs",
+          label: "Avg Duration",
+          format: (v) => v != null ? `${Number(v).toFixed(0)}ms` : "-"
+        },
+        { key: "distinctModelCount", label: "Distinct Models" }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("cost-breakdown").description("Get cost breakdown by model, agent, or workflow").option("--group-by <key>", "Group by (model, agent, workflow)", "model").option("--start-date <iso>", "Period start").option("--end-date <iso>", "Period end").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing cost-breakdown
+  $ nexus tracing cost-breakdown --group-by agent
+  $ nexus tracing cost-breakdown --group-by workflow --json`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.tracing.getCostBreakdown({
+        groupBy: opts.groupBy,
+        startDate: opts.startDate,
+        endDate: opts.endDate
+      });
+      const entries = result.entries ?? [];
+      printList(entries, void 0, [
+        { key: "groupKey", label: "KEY", width: 36 },
+        { key: "groupLabel", label: "LABEL", width: 25 },
+        {
+          key: "totalCostUsd",
+          label: "COST ($)",
+          width: 12,
+          format: (v) => `$${Number(v).toFixed(4)}`
+        },
+        { key: "traceCount", label: "TRACES", width: 8 },
+        { key: "generationCount", label: "GENS", width: 8 },
+        { key: "totalInputTokens", label: "IN TOKENS", width: 12 },
+        { key: "totalOutputTokens", label: "OUT TOKENS", width: 12 }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("timeline").description("Get tracing timeline data").option("--granularity <g>", "Granularity (hour, day, week)", "day").option("--start-date <iso>", "Period start").option("--end-date <iso>", "Period end").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing timeline
+  $ nexus tracing timeline --granularity hour --start-date 2026-03-29 --json`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.tracing.getTimeline({
+        granularity: opts.granularity,
+        startDate: opts.startDate,
+        endDate: opts.endDate
+      });
+      const points = result.points ?? [];
+      printList(points, void 0, [
+        { key: "date", label: "DATE", width: 22 },
+        { key: "traceCount", label: "TRACES", width: 8 },
+        { key: "generationCount", label: "GENS", width: 8 },
+        {
+          key: "totalCostUsd",
+          label: "COST ($)",
+          width: 12,
+          format: (v) => `$${Number(v).toFixed(4)}`
+        },
+        {
+          key: "avgDurationMs",
+          label: "AVG DUR",
+          width: 10,
+          format: (v) => v != null ? `${Number(v).toFixed(0)}ms` : "-"
+        }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("export").description("Export a single trace").argument("<id>", "Trace ID").option("--format <fmt>", "Output format (json, csv)", "json").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing export abc-123
+  $ nexus tracing export abc-123 --format csv > trace.csv`
+  ).action(async (id, opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.tracing.exportTrace(id, { format: opts.format });
+      console.log(result.content);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  tracing.command("export-bulk").description("Bulk export traces (max 1000)").option("--format <fmt>", "Output format (json, csv)", "json").option("--status <status>", "Filter by status").option("--agent-id <id>", "Filter by agent ID").option("--workflow-id <id>", "Filter by workflow ID").option("--start-date <iso>", "Filter from date").option("--end-date <iso>", "Filter to date").option("--limit <n>", "Max traces to export", "100").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus tracing export-bulk --format csv > traces.csv
+  $ nexus tracing export-bulk --status FAILED --limit 50`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.tracing.bulkExport({
+        format: opts.format,
+        status: opts.status,
+        agentId: opts.agentId,
+        workflowId: opts.workflowId,
+        startDate: opts.startDate,
+        endDate: opts.endDate,
+        limit: parseInt(opts.limit, 10)
+      });
+      console.log(result.content);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+}
+function formatStatus(v) {
+  const s = String(v);
+  if (s === "COMPLETED") return color.green(s);
+  if (s === "FAILED") return color.red(s);
+  if (s === "IN_PROGRESS" || s === "RUNNING") return color.yellow(s);
+  if (s === "PENDING") return color.dim(s);
+  return s;
+}
+
 // src/commands/upgrade.ts
 var import_node_child_process3 = require("child_process");
 init_output();
@@ -13586,6 +14263,7 @@ registerModelCommands(program);
 registerCustomModelCommands(program);
 registerPhoneNumberCommands(program);
 registerChannelCommands(program);
+registerTracingCommands(program);
 registerUpgradeCommand(program);
 registerDocsCommand(program);
 if (process.argv.length <= 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-nexus/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Official CLI for the Nexus AI agent platform.",
   "license": "MIT",
   "keywords": [
@@ -35,7 +35,7 @@
     "@types/node": "24.6.2",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "@agent-nexus/sdk": "0.1.13"
+    "@agent-nexus/sdk": "0.1.16"
   },
   "scripts": {
     "gen:docs": "tsx scripts/bundle-docs.ts",