@agent-nexus/cli 0.1.11 → 0.1.13

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.11",
+      version: "0.1.13",
       description: "Official CLI for the Nexus AI agent platform.",
       license: "MIT",
       keywords: [
@@ -695,6 +695,24 @@ var AgentsResource = class extends BaseResource {
     return this.http.request("POST", `/agents/${agentId}/generate-profile-picture`, { body });
   }
 };
+var AnalyticsResource = class extends BaseResource {
+  async getOverview(params) {
+    return this.http.request("GET", "/analytics/overview", {
+      query: params
+    });
+  }
+  async exportCsv(params) {
+    return this.http.requestRaw("GET", "/analytics/export", {
+      query: params
+    });
+  }
+  async listFeedback(params) {
+    const { data, meta } = await this.http.requestWithMeta("GET", "/analytics/feedback", {
+      query: params
+    });
+    return { data, meta };
+  }
+};
 var ChannelsResource = class extends BaseResource {
   // ===========================================================================
   // Setup Orchestrator
@@ -748,23 +766,37 @@ var ChannelsResource = class extends BaseResource {
   async getWhatsAppSender(senderId) {
     return this.http.request("GET", `/channels/whatsapp-senders/${senderId}`);
   }
-};
-var AnalyticsResource = class extends BaseResource {
-  async getOverview(params) {
-    return this.http.request("GET", "/analytics/overview", {
+  // ===========================================================================
+  // WhatsApp Templates
+  // ===========================================================================
+  async listWhatsAppTemplates(params) {
+    return this.http.request("GET", "/channels/whatsapp-templates", {
       query: params
     });
   }
-  async exportCsv(params) {
-    return this.http.requestRaw("GET", "/analytics/export", {
-      query: params
-    });
+  async createWhatsAppTemplate(body) {
+    return this.http.request("POST", "/channels/whatsapp-templates", { body });
   }
-  async listFeedback(params) {
-    const { data, meta } = await this.http.requestWithMeta("GET", "/analytics/feedback", {
+  async getWhatsAppTemplate(templateId) {
+    return this.http.request("GET", `/channels/whatsapp-templates/${templateId}`);
+  }
+  async deleteWhatsAppTemplate(templateId) {
+    return this.http.request(
+      "DELETE",
+      `/channels/whatsapp-templates/${templateId}`
+    );
+  }
+  async listTemplateApprovals(params) {
+    return this.http.request("GET", "/channels/whatsapp-templates/approvals", {
       query: params
     });
-    return { data, meta };
+  }
+  async submitTemplateApproval(body) {
+    return this.http.request(
+      "POST",
+      "/channels/whatsapp-templates/approvals",
+      { body }
+    );
   }
 };
 var CloudImportsResource = class extends BaseResource {
@@ -898,6 +930,42 @@ var DeploymentsResource = class extends BaseResource {
   async updateEmbedConfig(deploymentId, body) {
     return this.http.request("PATCH", `/deployments/${deploymentId}/embed-config`, { body });
   }
+  // ===========================================================================
+  // WhatsApp Deployment Templates
+  // ===========================================================================
+  async listDeploymentTemplates(deploymentId) {
+    return this.http.request(
+      "GET",
+      `/deployments/${deploymentId}/whatsapp-templates`
+    );
+  }
+  async attachDeploymentTemplate(deploymentId, body) {
+    return this.http.request(
+      "POST",
+      `/deployments/${deploymentId}/whatsapp-templates`,
+      { body }
+    );
+  }
+  async updateDeploymentTemplate(deploymentId, templateId, body) {
+    return this.http.request(
+      "PATCH",
+      `/deployments/${deploymentId}/whatsapp-templates/${templateId}`,
+      { body }
+    );
+  }
+  async detachDeploymentTemplate(deploymentId, templateId) {
+    return this.http.request(
+      "DELETE",
+      `/deployments/${deploymentId}/whatsapp-templates/${templateId}`
+    );
+  }
+  async updateDeploymentTemplateSettings(deploymentId, body) {
+    return this.http.request(
+      "PATCH",
+      `/deployments/${deploymentId}/whatsapp-templates/settings`,
+      { body }
+    );
+  }
 };
 var DocumentTemplateFoldersResource = class extends BaseResource {
   async list() {
@@ -1988,6 +2056,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", {
@@ -2460,6 +2586,7 @@ var NexusClient = class {
     this.phoneNumbers = new PhoneNumbersResource(http);
     this.tickets = new TicketsResource(http);
     this.channels = new ChannelsResource(http);
+    this.tracing = new TracingResource(http);
   }
 };
 
@@ -2471,6 +2598,10 @@ var URL_MAP = {
   production: "https://api.nexusgpt.io",
   dev: "http://localhost:3001"
 };
+var DASHBOARD_URL_MAP = {
+  production: "https://gpt.nexus",
+  dev: "http://localhost:3000"
+};
 var CONFIG_DIR = import_node_path.default.join(import_node_os.default.homedir(), ".nexus-mcp");
 var CONFIG_FILE = import_node_path.default.join(CONFIG_DIR, "config.json");
 var NEXUSRC_FILENAME = ".nexusrc";
@@ -2657,6 +2788,17 @@ function resolveBaseUrl(override) {
   const env = process.env.NEXUS_ENV ?? "production";
   return URL_MAP[env] ?? URL_MAP.production;
 }
+function resolveDashboardUrl(override) {
+  if (override) return override;
+  if (process.env.NEXUS_DASHBOARD_URL) return process.env.NEXUS_DASHBOARD_URL;
+  try {
+    const resolved = resolveProfile();
+    if (resolved.profile.dashboardUrl) return resolved.profile.dashboardUrl;
+  } catch {
+  }
+  const env = process.env.NEXUS_ENV ?? "production";
+  return DASHBOARD_URL_MAP[env] ?? DASHBOARD_URL_MAP.production;
+}
 
 // src/client.ts
 var _lastResolved = null;
@@ -3275,8 +3417,10 @@ Notes:
   Run "nexus auth list" to see all profiles, "nexus auth switch <name>" to change active.`
   ).action(async (opts) => {
     let baseUrl;
+    let dashboardUrl;
     if (opts.env === "dev") {
       baseUrl = "http://localhost:3001";
+      dashboardUrl = "http://localhost:3000";
     }
     const resolvedBaseUrl = baseUrl ?? resolveBaseUrl();
     let apiKey = opts.apiKey;
@@ -3368,6 +3512,7 @@ Notes:
     saveProfile(profileName, {
       apiKey,
       ...baseUrl ? { baseUrl } : {},
+      ...dashboardUrl ? { dashboardUrl } : {},
       ...orgName ? { orgName } : {},
       ...orgId ? { orgId } : {}
     });
@@ -3570,7 +3715,43 @@ function openUrl(url) {
 
 // src/commands/channel.ts
 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";
@@ -3578,7 +3759,10 @@ function openUrl2(url) {
 }
 function registerChannelCommands(program2) {
   const channel = program2.command("channel").description("Set up deployment channels: connections, phone numbers, WhatsApp senders");
-  channel.command("setup").description("Check or auto-provision channel setup prerequisites").requiredOption("--type <type>", "Deployment type (WHATSAPP, TWILIO_SMS, TWILIO_VOICE, EMBED, etc.)").option("--auto", "Auto-provision what is possible (e.g., create messaging connection)").option("--region <region>", "Region for auto-provisioning (us1 or ie1)", "us1").addHelpText(
+  channel.command("setup").description("Check or auto-provision channel setup prerequisites").requiredOption(
+    "--type <type>",
+    "Deployment type (WHATSAPP, TWILIO_SMS, TWILIO_VOICE, EMBED, etc.)"
+  ).option("--auto", "Auto-provision what is possible (e.g., create messaging connection)").option("--region <region>", "Region for auto-provisioning (us1 or ie1)", "us1").addHelpText(
     "after",
     `
 Examples:
@@ -3622,8 +3806,8 @@ Examples:
   $ nexus channel connect-waba`
   ).action(async () => {
     try {
-      const dashboardUrl = process.env.NEXUS_DASHBOARD_URL ?? "https://gpt.nexus";
-      const url = `${dashboardUrl}/app/settings/phone-number`;
+      const dashboardUrl = resolveDashboardUrl(program2.optsWithGlobals().dashboardUrl);
+      const url = `${dashboardUrl}/app/connect-waba`;
       console.log(`Opening ${color.cyan(url)} ...`);
       console.log("");
       console.log('Complete the "Connect with Meta" flow in your browser, then verify:');
@@ -3727,6 +3911,292 @@ Examples:
       process.exitCode = handleError(err);
     }
   });
+  const waTemplate = channel.command("whatsapp-template").description("Manage WhatsApp message templates (Twilio Content API)");
+  waTemplate.command("list").description("List WhatsApp message templates").option("--connection-id <id>", "Filter by messaging connection ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus channel whatsapp-template list
+  $ nexus channel whatsapp-template list --connection-id abc --json`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.channels.listWhatsAppTemplates({
+        connectionId: opts.connectionId
+      });
+      const data = result?.data ?? result;
+      printTable(Array.isArray(data) ? data : [data], [
+        { key: "id", label: "ID", width: 38 },
+        { key: "friendly_name", label: "FRIENDLY NAME", width: 25 },
+        { key: "language", label: "LANG", width: 8 }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  waTemplate.command("get").description("Get WhatsApp template details").argument("<templateId>", "Template ID (Twilio SID)").action(async (templateId) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.channels.getWhatsAppTemplate(templateId);
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "id", label: "ID" },
+        { key: "friendly_name", label: "Friendly Name" },
+        { key: "language", label: "Language" },
+        { key: "types", label: "Types" },
+        { key: "variables", label: "Variables" },
+        { key: "created_at", label: "Created At" }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  waTemplate.command("create").description("Create a WhatsApp message template").requiredOption("--connection-id <id>", "Messaging connection ID").requiredOption("--friendly-name <name>", "Template name (e.g., order_confirmation)").requiredOption("--language <lang>", "Language code (e.g., en, en_US)").option("--body <text>", "Template body text (auto-wraps as twilio/text type)").option("--body-file <path>", "Path to JSON file with full Twilio Types object").option("--type <type>", "Twilio type key when using --body", "twilio/text").option("--variables <json>", `Template variables as JSON (e.g., '{"1":"default"}')`).option("--submit", "Also submit for Meta approval after creation").option(
+    "--category <category>",
+    "Approval category (required with --submit): UTILITY, MARKETING, AUTHENTICATION"
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus channel whatsapp-template create --connection-id abc --friendly-name welcome --language en --body "Hello {{1}}, welcome!"
+  $ nexus channel whatsapp-template create --connection-id abc --friendly-name promo --language en --body-file template.json
+  $ nexus channel whatsapp-template create --connection-id abc --friendly-name order --language en --body "Order {{1}} confirmed" --submit --category UTILITY`
+  ).action(async (opts) => {
+    try {
+      if (!opts.body && !opts.bodyFile) {
+        console.error("Error: Either --body or --body-file is required.");
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.body && opts.bodyFile) {
+        console.error("Error: Cannot use both --body and --body-file.");
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.submit && !opts.category) {
+        console.error("Error: --category is required when using --submit.");
+        process.exitCode = 1;
+        return;
+      }
+      let types;
+      if (opts.bodyFile) {
+        try {
+          const content = (0, import_node_fs2.readFileSync)(opts.bodyFile, "utf-8");
+          types = JSON.parse(content);
+        } catch (e) {
+          console.error(
+            `Error reading --body-file: ${e instanceof Error ? e.message : String(e)}`
+          );
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        types = { [opts.type]: { body: opts.body } };
+      }
+      let variables;
+      if (opts.variables) {
+        try {
+          variables = JSON.parse(opts.variables);
+        } catch {
+          console.error("Error: --variables must be valid JSON.");
+          process.exitCode = 1;
+          return;
+        }
+      }
+      warnIfHighVariableDensity(types);
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.channels.createWhatsAppTemplate({
+        connectionId: opts.connectionId,
+        friendlyName: opts.friendlyName,
+        language: opts.language,
+        types,
+        variables
+      });
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "id", label: "ID" },
+        { key: "friendly_name", label: "Friendly Name" },
+        { key: "language", label: "Language" },
+        { key: "created_at", label: "Created At" }
+      ]);
+      printSuccess("WhatsApp template created.");
+      if (opts.submit) {
+        console.log("");
+        console.log("Submitting for Meta approval...");
+        const approval = await client.channels.submitTemplateApproval({
+          connectionId: opts.connectionId,
+          templateId: data.id,
+          name: opts.friendlyName,
+          category: opts.category
+        });
+        const approvalData = approval?.data ?? approval;
+        printRecord(approvalData, [
+          { key: "sid", label: "Approval SID" },
+          { 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);
+    }
+  });
+  waTemplate.command("delete").description("Delete a WhatsApp template").argument("<templateId>", "Template ID (Twilio SID)").option("--yes", "Skip confirmation prompt").action(async (templateId, opts) => {
+    try {
+      if (!opts.yes && process.stdin.isTTY) {
+        const readline2 = await import("readline");
+        const rl = readline2.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        const answer = await new Promise((resolve) => {
+          rl.question(`Delete template ${templateId}? (y/N) `, resolve);
+        });
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Cancelled.");
+          return;
+        }
+      }
+      const client = createClient(program2.optsWithGlobals());
+      await client.channels.deleteWhatsAppTemplate(templateId);
+      printSuccess("WhatsApp template deleted.", { id: templateId });
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  waTemplate.command("approvals").description("List template approval status from Meta").option("--connection-id <id>", "Filter by messaging connection ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus channel whatsapp-template approvals
+  $ nexus channel whatsapp-template approvals --json`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.channels.listTemplateApprovals({
+        connectionId: opts.connectionId
+      });
+      const data = result?.data ?? result;
+      const items = Array.isArray(data) ? data : [data];
+      const rows = items.map((item) => ({
+        sid: item.sid,
+        name: item.approvalRequests?.name ?? "",
+        category: item.approvalRequests?.category ?? "",
+        status: item.approvalRequests?.status ?? "",
+        rejection_reason: item.approvalRequests?.rejection_reason ?? ""
+      }));
+      printTable(rows, [
+        { key: "sid", label: "SID", width: 38 },
+        { key: "name", label: "NAME", width: 20 },
+        { key: "category", label: "CATEGORY", width: 15 },
+        { key: "status", label: "STATUS", width: 12 },
+        { key: "rejection_reason", label: "REJECTION REASON", width: 30 }
+      ]);
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  waTemplate.command("submit-approval").description("Submit a template for Meta WhatsApp approval").requiredOption("--connection-id <id>", "Messaging connection ID").requiredOption("--template-id <id>", "Template ID (Twilio SID)").requiredOption("--name <name>", "Template name for approval").requiredOption(
+    "--category <category>",
+    "Approval category: UTILITY, MARKETING, or AUTHENTICATION"
+  ).option("--wait", "Poll approval status until resolved (up to 2 minutes)").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus channel whatsapp-template submit-approval --connection-id abc --template-id HX123 --name welcome --category UTILITY
+  $ nexus channel whatsapp-template submit-approval --connection-id abc --template-id HX123 --name promo --category MARKETING --wait`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.channels.submitTemplateApproval({
+        connectionId: opts.connectionId,
+        templateId: opts.templateId,
+        name: opts.name,
+        category: opts.category
+      });
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "sid", label: "Approval SID" },
+        { key: "status", label: "Status" }
+      ]);
+      printSuccess("Template submitted for Meta approval.");
+      if (opts.wait) {
+        const maxWaitMs = 12e4;
+        const intervalMs = 5e3;
+        const startTime = Date.now();
+        let finalStatus = data.status;
+        console.log("Waiting for approval...");
+        while (Date.now() - startTime < maxWaitMs) {
+          await new Promise((r) => setTimeout(r, intervalMs));
+          const approvals = await client.channels.listTemplateApprovals({
+            connectionId: opts.connectionId
+          });
+          const approvalsData = approvals?.data ?? approvals;
+          const items = Array.isArray(approvalsData) ? approvalsData : [approvalsData];
+          const match = items.find((a) => a.sid === opts.templateId);
+          if (match?.approvalRequests?.status) {
+            finalStatus = match.approvalRequests.status;
+            if (finalStatus !== "pending" && finalStatus !== "unsubmitted") {
+              console.log(`Approval resolved: ${color.cyan(finalStatus)}`);
+              if (finalStatus === "rejected" && match.approvalRequests.rejection_reason) {
+                console.log(`Reason: ${match.approvalRequests.rejection_reason}`);
+              }
+              break;
+            }
+          }
+        }
+        if (finalStatus === "pending" || finalStatus === "unsubmitted") {
+          console.log(
+            `Still ${finalStatus} after 2m. Check again: ${color.dim("nexus channel whatsapp-template approvals")}`
+          );
+        }
+      }
+      console.log(
+        `
+Next: Attach to deployment: ${color.dim("nexus deployment template attach <depId> --template-id ...")}`
+      );
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
 }
 
 // src/commands/collection.ts
@@ -4371,57 +4841,294 @@ Examples:
   ).action(async (id, opts) => {
     try {
       const client = createClient(program2.optsWithGlobals());
-      const base = await resolveBody(opts.body);
-      const body = mergeBodyWithFlags(base, {
-        ...opts.name !== void 0 && { name: opts.name }
+      const base = await resolveBody(opts.body);
+      const body = mergeBodyWithFlags(base, {
+        ...opts.name !== void 0 && { name: opts.name }
+      });
+      await client.deploymentFolders.update(id, body);
+      printSuccess("Deployment folder updated.", { id });
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  depFolder.command("delete").description("Delete a deployment folder").argument("<id>", "Folder ID").option("--yes", "Skip confirmation").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus deployment folder delete fld-123
+  $ nexus deployment folder delete fld-123 --yes`
+  ).action(async (id, opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      if (!opts.yes && process.stdout.isTTY) {
+        const readline2 = await import("readline/promises");
+        const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await rl.question(`Delete deployment folder ${id}? [y/N] `);
+        rl.close();
+        if (answer.toLowerCase() !== "y") {
+          console.log("Aborted.");
+          return;
+        }
+      }
+      await client.deploymentFolders.delete(id);
+      printSuccess("Deployment folder deleted.", { id });
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  depFolder.command("assign").description("Assign a deployment to a folder").requiredOption("--deployment-id <id>", "Deployment ID").requiredOption("--folder-id <id>", "Folder ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus deployment folder assign --deployment-id dep-123 --folder-id fld-456`
+  ).action(async (opts) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      await client.deploymentFolders.assign({
+        deploymentId: opts.deploymentId,
+        folderId: opts.folderId
+      });
+      printSuccess("Deployment assigned to folder.", {
+        deploymentId: opts.deploymentId,
+        folderId: opts.folderId
+      });
+    } catch (err) {
+      process.exitCode = handleError(err);
+    }
+  });
+  const depTemplate = deployment.command("template").description("Manage WhatsApp templates attached to a deployment");
+  depTemplate.command("list").description("List templates attached to a WhatsApp deployment").argument("<deploymentId>", "Deployment ID").addHelpText(
+    "after",
+    `
+Examples:
+  $ nexus deployment template list dep-123
+  $ nexus deployment template list dep-123 --json`
+  ).action(async (deploymentId) => {
+    try {
+      const client = createClient(program2.optsWithGlobals());
+      const result = await client.deployments.listDeploymentTemplates(deploymentId);
+      const data = result?.data ?? result;
+      const items = Array.isArray(data) ? data : [data];
+      const rows = items.map((t) => ({
+        templateId: t.templateId,
+        name: t.name,
+        type: t.type ?? "template",
+        variables: Object.keys(t.variables ?? {}).length,
+        multiLang: t.enableMultiLanguage ? "yes" : "no"
+      }));
+      printTable(rows, [
+        { key: "templateId", label: "TEMPLATE ID", width: 38 },
+        { key: "name", label: "NAME", width: 20 },
+        { key: "type", label: "TYPE", width: 10 },
+        { key: "variables", label: "VARS", width: 6 },
+        { key: "multiLang", label: "MULTI-LANG", width: 10 }
+      ]);
+    } catch (err) {
+      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").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 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;
+      if (opts.variables) {
+        try {
+          variables = JSON.parse(opts.variables);
+        } catch {
+          console.error("Error: --variables must be valid JSON.");
+          process.exitCode = 1;
+          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,
+        name: opts.name,
+        description: opts.description,
+        variables,
+        type: opts.type,
+        enableMultiLanguage: opts.enableMultiLanguage,
+        enableDynamicSize: opts.enableDynamicSize,
+        carouselTemplateGroup,
+        singleItemCardTemplateId: opts.singleItemCardTemplateId,
+        singleItemCardTemplateGroup
       });
-      await client.deploymentFolders.update(id, body);
-      printSuccess("Deployment folder updated.", { id });
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "templateId", label: "Template ID" },
+        { key: "name", label: "Name" },
+        { key: "description", label: "Description" },
+        { key: "type", label: "Type" }
+      ]);
+      printSuccess("Template attached to deployment.");
+    } catch (err) {
+      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").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 --enable-dynamic-size --carousel-template-group '{"baseName":"products","availableTemplates":[...]}'`
+  ).action(async (deploymentId, templateId, opts) => {
+    try {
+      const body = {};
+      if (opts.name !== void 0) body.name = opts.name;
+      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);
+        } catch {
+          console.error("Error: --variables must be valid JSON.");
+          process.exitCode = 1;
+          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,
+        templateId,
+        body
+      );
+      const data = result?.data ?? result;
+      printRecord(data, [
+        { key: "templateId", label: "Template ID" },
+        { key: "name", label: "Name" },
+        { key: "description", label: "Description" }
+      ]);
+      printSuccess("Deployment template updated.");
     } catch (err) {
       process.exitCode = handleError(err);
     }
   });
-  depFolder.command("delete").description("Delete a deployment folder").argument("<id>", "Folder ID").option("--yes", "Skip confirmation").addHelpText(
-    "after",
-    `
-Examples:
-  $ nexus deployment folder delete fld-123
-  $ nexus deployment folder delete fld-123 --yes`
-  ).action(async (id, opts) => {
+  depTemplate.command("detach").description("Detach a template from a deployment").argument("<deploymentId>", "Deployment ID").argument("<templateId>", "Template ID (Twilio SID)").option("--yes", "Skip confirmation prompt").action(async (deploymentId, templateId, opts) => {
     try {
-      const client = createClient(program2.optsWithGlobals());
-      if (!opts.yes && process.stdout.isTTY) {
-        const readline2 = await import("readline/promises");
-        const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
-        const answer = await rl.question(`Delete deployment folder ${id}? [y/N] `);
+      if (!opts.yes && process.stdin.isTTY) {
+        const readline2 = await import("readline");
+        const rl = readline2.createInterface({
+          input: process.stdin,
+          output: process.stdout
+        });
+        const answer = await new Promise((resolve) => {
+          rl.question(
+            `Detach template ${templateId} from deployment ${deploymentId}? (y/N) `,
+            resolve
+          );
+        });
         rl.close();
         if (answer.toLowerCase() !== "y") {
-          console.log("Aborted.");
+          console.log("Cancelled.");
           return;
         }
       }
-      await client.deploymentFolders.delete(id);
-      printSuccess("Deployment folder deleted.", { id });
+      const client = createClient(program2.optsWithGlobals());
+      await client.deployments.detachDeploymentTemplate(deploymentId, templateId);
+      printSuccess("Template detached from deployment.", { templateId });
     } catch (err) {
       process.exitCode = handleError(err);
     }
   });
-  depFolder.command("assign").description("Assign a deployment to a folder").requiredOption("--deployment-id <id>", "Deployment ID").requiredOption("--folder-id <id>", "Folder ID").addHelpText(
+  depTemplate.command("settings").description("View or update deployment template settings").argument("<deploymentId>", "Deployment ID").option(
+    "--allow-dynamic-templates <bool>",
+    "Allow agent to dynamically create and send templates (true/false)"
+  ).addHelpText(
     "after",
     `
 Examples:
-  $ nexus deployment folder assign --deployment-id dep-123 --folder-id fld-456`
-  ).action(async (opts) => {
+  $ nexus deployment template settings dep-123
+  $ nexus deployment template settings dep-123 --allow-dynamic-templates true`
+  ).action(async (deploymentId, opts) => {
     try {
       const client = createClient(program2.optsWithGlobals());
-      await client.deploymentFolders.assign({
-        deploymentId: opts.deploymentId,
-        folderId: opts.folderId
-      });
-      printSuccess("Deployment assigned to folder.", {
-        deploymentId: opts.deploymentId,
-        folderId: opts.folderId
-      });
+      if (opts.allowDynamicTemplates !== void 0) {
+        const value = opts.allowDynamicTemplates === "true";
+        await client.deployments.updateDeploymentTemplateSettings(deploymentId, {
+          allowAgentToCreateAndSendTemplates: value
+        });
+        printSuccess(
+          `Dynamic template creation ${value ? "enabled" : "disabled"} for deployment.`
+        );
+      } else {
+        const result = await client.deployments.listDeploymentTemplates(deploymentId);
+        const data = result?.data ?? result;
+        console.log(`Templates attached: ${Array.isArray(data) ? data.length : 0}`);
+        console.log(
+          `Tip: Use --allow-dynamic-templates true/false to toggle agent template creation.`
+        );
+      }
     } catch (err) {
       process.exitCode = handleError(err);
     }
@@ -4905,7 +5612,7 @@ All commands follow the pattern: \`nexus <group> <action> [arguments] [options]\
 | [\`eval\`](docs/command-reference.md#nexus-eval)                         | (subgroups: \`session\`, \`dataset\`, \`execute\`, \`judge\`, \`results\`, \`formats\`, \`judges\`) | AI task evaluation         |
 | [\`ticket\`](docs/command-reference.md#nexus-ticket)                     | \`list\` \`get\` \`create\` \`update\` \`comment\` \`comments\`                                   | Bug and feature tracking   |
 | [\`phone-number\`](docs/command-reference.md#nexus-phone-number)         | \`search\` \`buy\` \`list\` \`get\` \`release\`                                                 | Phone number management    |
-| [\`channel\`](docs/command-reference.md#nexus-channel)                   | \`setup\` \`connection list\\|create\` \`whatsapp-sender list\\|create\\|get\`                  | Channel setup orchestrator |
+| [\`channel\`](docs/command-reference.md#nexus-channel)                   | \`setup\` \`connection list\\|create\` \`whatsapp-sender list\\|create\\|get\`                 | Channel setup orchestrator |
 | [\`prompt-assistant\`](docs/command-reference.md#nexus-prompt-assistant) | \`chat\` \`get-thread\` \`delete-thread\`                                                   | AI-assisted prompt writing |
 
 ### Utility
@@ -5933,12 +6640,12 @@ List deployments.
 nexus deployment list [options]
 \`\`\`
 
-| Option             | Description                                   |
-| ------------------ | --------------------------------------------- |
-| \`--agent-id <id>\`  | Filter by agent ID                            |
+| Option             | Description                                                     |
+| ------------------ | --------------------------------------------------------------- |
+| \`--agent-id <id>\`  | Filter by agent ID                                              |
 | \`--type <type>\`    | Filter by type (\`EMBED\`, \`API\`, \`WHATSAPP\`, \`TWILIO_SMS\`, etc.) |
-| \`--page <number>\`  | Page number                                   |
-| \`--limit <number>\` | Items per page                                |
+| \`--page <number>\`  | Page number                                                     |
+| \`--limit <number>\` | Items per page                                                  |
 
 \`\`\`bash
 nexus deployment list
@@ -5975,13 +6682,13 @@ Create a new deployment.
 nexus deployment create [options]
 \`\`\`
 
-| Option                 | Required | Description                                                                 |
-| ---------------------- | -------- | --------------------------------------------------------------------------- |
-| \`--name <name>\`        | Yes      | Deployment name                                                             |
+| Option                 | Required | Description                                                                                                                 |
+| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| \`--name <name>\`        | Yes      | Deployment name                                                                                                             |
 | \`--type <type>\`        | Yes      | Deployment type: \`EMBED\`, \`API\`, \`WHATSAPP\`, \`TWILIO_SMS\`, \`TWILIO_VOICE\`, \`TELEGRAM\`, \`SLACK\`, \`GMAIL\`, \`OUTLOOK\`, \`TEAMS\` |
-| \`--agent-id <id>\`      | No       | Agent ID                                                                    |
-| \`--description <text>\` | No       | Deployment description                                                      |
-| \`--body <json>\`        | No       | Request body as JSON, \`.json\` file, or \`-\` for stdin                        |
+| \`--agent-id <id>\`      | No       | Agent ID                                                                                                                    |
+| \`--description <text>\` | No       | Deployment description                                                                                                      |
+| \`--body <json>\`        | No       | Request body as JSON, \`.json\` file, or \`-\` for stdin                                                                        |
 
 **Important:** Channel deployments (WhatsApp, SMS, Voice, etc.) have prerequisites. Run \`nexus channel setup --type <TYPE>\` first to see what's needed.
 
@@ -8697,11 +9404,11 @@ Check or auto-provision channel setup prerequisites. Returns a step-by-step chec
 nexus channel setup [options]
 \`\`\`
 
-| Option            | Required | Description                                                      |
-| ----------------- | -------- | ---------------------------------------------------------------- |
-| \`--type <type>\`   | Yes      | Deployment type (\`WHATSAPP\`, \`TWILIO_SMS\`, \`TWILIO_VOICE\`, etc.) |
-| \`--auto\`          | No       | Auto-provision what is possible (e.g., create messaging connection) |
-| \`--region <region>\` | No    | Region for auto-provisioning: \`us1\` or \`ie1\` (default: \`us1\`)   |
+| Option              | Required | Description                                                         |
+| ------------------- | -------- | ------------------------------------------------------------------- |
+| \`--type <type>\`     | Yes      | Deployment type (\`WHATSAPP\`, \`TWILIO_SMS\`, \`TWILIO_VOICE\`, etc.)    |
+| \`--auto\`            | No       | Auto-provision what is possible (e.g., create messaging connection) |
+| \`--region <region>\` | No       | Region for auto-provisioning: \`us1\` or \`ie1\` (default: \`us1\`)       |
 
 \`\`\`bash
 nexus channel setup --type WHATSAPP
@@ -8719,7 +9426,7 @@ Open the browser to connect your WhatsApp Business Account via Meta's Embedded S
 nexus channel connect-waba
 \`\`\`
 
-Opens \`{NEXUS_DASHBOARD_URL}/app/settings/phone-number\` in your default browser. Complete the "Connect with Meta" flow, then verify with \`nexus channel setup --type WHATSAPP\`.
+Opens \`{NEXUS_DASHBOARD_URL}/app/connect-waba\` in your default browser \u2014 a dedicated page with a single "Connect with Meta" button. Complete the flow, then verify with \`nexus channel setup --type WHATSAPP\`.
 
 \`\`\`bash
 nexus channel connect-waba
@@ -8749,8 +9456,8 @@ Create a messaging connection (max 1 per organization via the API).
 nexus channel connection create [options]
 \`\`\`
 
-| Option             | Description                     |
-| ------------------ | ------------------------------- |
+| Option              | Description                             |
+| ------------------- | --------------------------------------- |
 | \`--region <region>\` | Region: \`us1\` or \`ie1\` (default: \`us1\`) |
 
 \`\`\`bash
@@ -8782,12 +9489,12 @@ Create a WhatsApp sender (registers a phone number with WhatsApp Business via Me
 nexus channel whatsapp-sender create [options]
 \`\`\`
 
-| Option                     | Required | Description                                           |
-| -------------------------- | -------- | ----------------------------------------------------- |
-| \`--connection-id <id>\`     | Yes      | Messaging connection ID                               |
-| \`--phone-number-id <id>\`   | Yes      | Phone number ID                                       |
-| \`--sender-name <name>\`     | Yes      | Display name for the WhatsApp sender                  |
-| \`--waba-id <id>\`           | No       | WhatsApp Business Account ID (reads from connection if omitted) |
+| Option                   | Required | Description                                                     |
+| ------------------------ | -------- | --------------------------------------------------------------- |
+| \`--connection-id <id>\`   | Yes      | Messaging connection ID                                         |
+| \`--phone-number-id <id>\` | Yes      | Phone number ID                                                 |
+| \`--sender-name <name>\`   | Yes      | Display name for the WhatsApp sender                            |
+| \`--waba-id <id>\`         | No       | WhatsApp Business Account ID (reads from connection if omitted) |
 
 \`\`\`bash
 nexus channel whatsapp-sender create \\
@@ -10257,7 +10964,7 @@ ${"\u2550".repeat(72)}`);
 }
 
 // src/commands/document.ts
-var import_node_fs2 = __toESM(require("fs"));
+var import_node_fs3 = __toESM(require("fs"));
 var import_node_path2 = __toESM(require("path"));
 init_output();
 function registerDocumentCommands(program2) {
@@ -10323,12 +11030,12 @@ Examples:
     try {
       const client = createClient(program2.optsWithGlobals());
       const absPath = import_node_path2.default.resolve(filePath);
-      if (!import_node_fs2.default.existsSync(absPath)) {
+      if (!import_node_fs3.default.existsSync(absPath)) {
         console.error(`Error: File not found: ${absPath}`);
         process.exitCode = 1;
         return;
       }
-      const buffer = import_node_fs2.default.readFileSync(absPath);
+      const buffer = import_node_fs3.default.readFileSync(absPath);
       const blob = new Blob([buffer]);
       const fileName = import_node_path2.default.basename(absPath);
       const doc = await client.documents.uploadFile(blob, fileName, opts.description);
@@ -11626,7 +12333,7 @@ Notes:
 }
 
 // src/commands/template.ts
-var import_node_fs3 = __toESM(require("fs"));
+var import_node_fs4 = __toESM(require("fs"));
 var import_node_path3 = __toESM(require("path"));
 init_output();
 function registerTemplateCommands(program2) {
@@ -11712,12 +12419,12 @@ Examples:
     try {
       const client = createClient(program2.optsWithGlobals());
       const absPath = import_node_path3.default.resolve(opts.file);
-      if (!import_node_fs3.default.existsSync(absPath)) {
+      if (!import_node_fs4.default.existsSync(absPath)) {
         console.error(`Error: File not found: ${absPath}`);
         process.exitCode = 1;
         return;
       }
-      const buffer = import_node_fs3.default.readFileSync(absPath);
+      const buffer = import_node_fs4.default.readFileSync(absPath);
       const blob = new Blob([buffer]);
       const fileName = import_node_path3.default.basename(absPath);
       const result = await client.skills.uploadDocumentTemplateFile(id, blob, fileName);
@@ -12030,15 +12737,387 @@ 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").option("--start-date <iso>", "Filter from date (ISO 8601)").option("--end-date <iso>", "Filter to date (ISO 8601)").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").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").option("--end-date <iso>", "Filter to date").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();
 
 // src/util/package-manager.ts
-var import_node_fs4 = __toESM(require("fs"));
+var import_node_fs5 = __toESM(require("fs"));
 function detectPackageManager() {
   try {
-    const resolved = import_node_fs4.default.realpathSync(process.argv[1]).replace(/\\/g, "/");
+    const resolved = import_node_fs5.default.realpathSync(process.argv[1]).replace(/\\/g, "/");
     if (/[/]\.?pnpm[/]/.test(resolved)) return "pnpm";
     if (/[/]\.yarn[/]/.test(resolved)) return "yarn";
   } catch {
@@ -12069,7 +13148,7 @@ function getGlobalUpdateHint(pkg) {
 }
 
 // src/util/version-check.ts
-var import_node_fs5 = __toESM(require("fs"));
+var import_node_fs6 = __toESM(require("fs"));
 var import_node_os2 = __toESM(require("os"));
 var import_node_path4 = __toESM(require("path"));
 var PACKAGE_NAME = "@agent-nexus/cli";
@@ -12078,7 +13157,7 @@ var FETCH_TIMEOUT_MS = 3e3;
 var CACHE_FILE = import_node_path4.default.join(import_node_os2.default.homedir(), ".nexus-mcp", "version-check.json");
 function loadCache() {
   try {
-    return JSON.parse(import_node_fs5.default.readFileSync(CACHE_FILE, "utf-8"));
+    return JSON.parse(import_node_fs6.default.readFileSync(CACHE_FILE, "utf-8"));
   } catch {
     return null;
   }
@@ -12086,8 +13165,8 @@ function loadCache() {
 function saveCache(cache) {
   try {
     const dir = import_node_path4.default.dirname(CACHE_FILE);
-    import_node_fs5.default.mkdirSync(dir, { recursive: true, mode: 448 });
-    import_node_fs5.default.writeFileSync(CACHE_FILE, JSON.stringify(cache), { mode: 384 });
+    import_node_fs6.default.mkdirSync(dir, { recursive: true, mode: 448 });
+    import_node_fs6.default.writeFileSync(CACHE_FILE, JSON.stringify(cache), { mode: 384 });
   } catch {
   }
 }
@@ -12174,11 +13253,29 @@ async function autoUpdate(currentVersion) {
 
 // src/commands/upgrade.ts
 var PACKAGE_NAME2 = "@agent-nexus/cli";
+var UPGRADE_ALIASES = [
+  "update",
+  "latest",
+  "up",
+  "install",
+  "reinstall",
+  "refresh",
+  "fetch",
+  "pull",
+  "sync",
+  "get",
+  "download",
+  "self-update",
+  "selfupdate",
+  "self-upgrade",
+  "selfupgrade",
+  "new",
+  "patch",
+  "bump"
+];
 function registerUpgradeCommand(program2) {
   const currentVersion = require_package().version;
-  program2.command("upgrade").description("Upgrade the Nexus CLI to the latest version").addHelpText("after", `
-Examples:
-  $ nexus upgrade`).action(async () => {
+  const upgradeAction = async () => {
     process.stderr.write(`Current version: ${color.cyan(currentVersion)}
 `);
     process.stderr.write("Checking for updates\u2026\n");
@@ -12208,7 +13305,13 @@ Upgrade failed. Try running manually:
       );
       process.exitCode = 1;
     }
-  });
+  };
+  program2.command("upgrade").description("Upgrade the Nexus CLI to the latest version").addHelpText("after", `
+Examples:
+  $ nexus upgrade`).action(upgradeAction);
+  for (const alias of UPGRADE_ALIASES) {
+    program2.command(alias, { hidden: true }).action(upgradeAction);
+  }
 }
 
 // src/commands/version.ts
@@ -12993,7 +14096,7 @@ Examples:
 // src/index.ts
 init_output();
 var { version: VERSION } = require_package();
-var program = new import_commander.Command().name("nexus").description("Official CLI for the Nexus AI agent platform").version(VERSION, "-v, --version").option("--json", "Output as JSON").option("--api-key <key>", "Override API key for this invocation").option("--base-url <url>", "Override API base URL").option("--profile <name>", "Use a specific named profile").option("--no-auto-update", "Disable automatic updates when a new version is detected").hook("preAction", (thisCommand) => {
+var program = new import_commander.Command().name("nexus").description("Official CLI for the Nexus AI agent platform").version(VERSION, "-v, --version").option("--json", "Output as JSON").option("--api-key <key>", "Override API key for this invocation").option("--base-url <url>", "Override API base URL").option("--dashboard-url <url>", "Override dashboard URL (for browser links)").option("--profile <name>", "Use a specific named profile").option("--no-auto-update", "Disable automatic updates when a new version is detected").hook("preAction", (thisCommand) => {
   const opts = thisCommand.optsWithGlobals();
   if (opts.json) setJsonMode(true);
   const cmdName = thisCommand.name();
@@ -13009,7 +14112,8 @@ var program = new import_commander.Command().name("nexus").description("Official
     "pin",
     "unpin",
     "status",
-    "docs"
+    "docs",
+    ...UPGRADE_ALIASES
   ].includes(cmdName);
   if (!skipBanner && !isJsonMode()) {
     try {
@@ -13054,6 +14158,7 @@ registerModelCommands(program);
 registerCustomModelCommands(program);
 registerPhoneNumberCommands(program);
 registerChannelCommands(program);
+registerTracingCommands(program);
 registerUpgradeCommand(program);
 registerDocsCommand(program);
 if (process.argv.length <= 2) {
@@ -13062,7 +14167,7 @@ if (process.argv.length <= 2) {
 program.parseAsync(process.argv).then(async () => {
   if (isJsonMode()) return;
   const ranCommand = process.argv[2];
-  if (ranCommand === "upgrade") return;
+  if (ranCommand === "upgrade" || UPGRADE_ALIASES.includes(ranCommand)) return;
   const opts = program.opts();
   if (opts.autoUpdate) {
     const msg = await autoUpdate(VERSION);