@robinmordasiewicz/f5xc-xcsh 6.37.0 → 6.38.0

package/dist/index.js

@@ -45354,8 +45354,8 @@ function getLogoModeFromEnv(envPrefix) {
 var CLI_NAME = "xcsh";
 var CLI_FULL_NAME = "F5 Distributed Cloud Shell";
 function getVersion() {
-  if ("6.37.0") {
-    return "6.37.0";
+  if ("6.38.0") {
+    return "6.38.0";
   }
   if (process.env.XCSH_VERSION) {
     return process.env.XCSH_VERSION;
@@ -46024,6 +46024,728 @@ var APIClient = class {
   }
 };
 
+// src/output/formatter.ts
+var import_yaml2 = __toESM(require_dist(), 1);
+
+// src/output/types.ts
+var DEFAULT_TABLE_STYLE = {
+  unicode: true,
+  coloredBorders: true,
+  headerStyle: "bold"
+};
+var PLAIN_TABLE_STYLE = {
+  unicode: false,
+  coloredBorders: false,
+  headerStyle: "normal"
+};
+function isValidOutputFormat(format) {
+  return ["json", "yaml", "table", "text", "tsv", "none", "spec"].includes(
+    format.toLowerCase()
+  );
+}
+
+// src/output/resolver.ts
+var OUTPUT_FORMAT_ENV_VAR = `${ENV_PREFIX}_OUTPUT_FORMAT`;
+function getOutputFormatFromEnv() {
+  const envValue = process.env[OUTPUT_FORMAT_ENV_VAR]?.toLowerCase().trim();
+  if (envValue && isValidOutputFormat(envValue)) {
+    return envValue;
+  }
+  return void 0;
+}
+function shouldUseColors(isTTY = process.stdout.isTTY ?? false, noColorFlag = false) {
+  if (noColorFlag) {
+    return false;
+  }
+  if (process.env.NO_COLOR !== void 0) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR !== void 0) {
+    return true;
+  }
+  return isTTY;
+}
+
+// src/output/table.ts
+var UNICODE_BOX = {
+  topLeft: "\u256D",
+  // ╭
+  topRight: "\u256E",
+  // ╮
+  bottomLeft: "\u2570",
+  // ╰
+  bottomRight: "\u256F",
+  // ╯
+  horizontal: "\u2500",
+  // ─
+  vertical: "\u2502",
+  // │
+  leftT: "\u251C",
+  // ├
+  rightT: "\u2524",
+  // ┤
+  topT: "\u252C",
+  // ┬
+  bottomT: "\u2534",
+  // ┴
+  cross: "\u253C"
+  // ┼
+};
+var ASCII_BOX = {
+  topLeft: "+",
+  topRight: "+",
+  bottomLeft: "+",
+  bottomRight: "+",
+  horizontal: "-",
+  vertical: "|",
+  leftT: "+",
+  rightT: "+",
+  topT: "+",
+  bottomT: "+",
+  cross: "+"
+};
+function getBoxCharacters(style) {
+  return style.unicode ? UNICODE_BOX : ASCII_BOX;
+}
+function applyColor(text, color, useColors) {
+  if (!useColors) {
+    return text;
+  }
+  return `${color}${text}${colors.reset}`;
+}
+function wrapText2(text, maxWidth) {
+  if (text.length <= maxWidth) {
+    return [text];
+  }
+  const lines = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxWidth) {
+      lines.push(remaining);
+      break;
+    }
+    let breakPoint = maxWidth;
+    for (let i = maxWidth - 1; i > 0; i--) {
+      if (remaining[i] === " ") {
+        breakPoint = i;
+        break;
+      }
+    }
+    lines.push(remaining.slice(0, breakPoint));
+    remaining = remaining.slice(breakPoint).trimStart();
+  }
+  return lines;
+}
+function getValue(row, accessor) {
+  if (typeof accessor === "function") {
+    return accessor(row);
+  }
+  const value = row[accessor];
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "object") {
+    if (accessor === "labels") {
+      return formatLabelsValue(value);
+    }
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function formatLabelsValue(labels) {
+  const entries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${v}`);
+  if (entries.length === 0) {
+    return "";
+  }
+  return `map[${entries.join(" ")}]`;
+}
+function calculateColumnWidths(columns, rows, maxTableWidth) {
+  const widths = columns.map((col) => {
+    let width = col.header.length;
+    for (const row of rows) {
+      const value = getValue(row, col.accessor);
+      width = Math.max(width, value.length);
+    }
+    if (col.minWidth) {
+      width = Math.max(width, col.minWidth);
+    }
+    if (col.maxWidth) {
+      width = Math.min(width, col.maxWidth);
+    }
+    if (col.width) {
+      width = col.width;
+    }
+    return width;
+  });
+  if (maxTableWidth) {
+    const totalWidth = widths.reduce((a, b) => a + b, 0) + columns.length * 3 + 1;
+    if (totalWidth > maxTableWidth) {
+      const ratio = (maxTableWidth - columns.length * 3 - 1) / totalWidth;
+      for (let i = 0; i < widths.length; i++) {
+        widths[i] = Math.max(5, Math.floor(widths[i] * ratio));
+      }
+    }
+  }
+  return widths;
+}
+function formatBeautifulTable(data, config, noColor = false) {
+  if (data.length === 0) {
+    return "";
+  }
+  const useColors = shouldUseColors(void 0, noColor);
+  const style = useColors ? config.style ?? DEFAULT_TABLE_STYLE : PLAIN_TABLE_STYLE;
+  const box = getBoxCharacters(style);
+  const borderColor = style.borderColor ?? colors.red;
+  const widths = calculateColumnWidths(config.columns, data, config.maxWidth);
+  const lines = [];
+  const colorBorder = (text) => applyColor(text, borderColor, useColors && style.coloredBorders);
+  const buildHorizontalLine = (left, mid, right, fill) => {
+    const segments = widths.map((w) => fill.repeat(w + 2));
+    return colorBorder(left + segments.join(mid) + right);
+  };
+  if (config.title) {
+    const title = ` ${config.title} `;
+    const totalWidth = widths.reduce((a, b) => a + b, 0) + widths.length * 3 - 1;
+    const remainingWidth = totalWidth - title.length;
+    const leftDashes = 1;
+    const rightDashes = Math.max(0, remainingWidth - leftDashes);
+    lines.push(
+      colorBorder(box.topLeft + box.horizontal.repeat(leftDashes)) + title + colorBorder(box.horizontal.repeat(rightDashes) + box.topRight)
+    );
+  } else {
+    lines.push(
+      buildHorizontalLine(
+        box.topLeft,
+        box.topT,
+        box.topRight,
+        box.horizontal
+      )
+    );
+  }
+  const headerCells = config.columns.map((col, i) => {
+    const padding = widths[i] - col.header.length;
+    const leftPad = Math.floor(padding / 2);
+    const rightPad = padding - leftPad;
+    const content = " ".repeat(leftPad) + col.header + " ".repeat(rightPad);
+    return ` ${content} `;
+  });
+  lines.push(
+    colorBorder(box.vertical) + headerCells.join(colorBorder(box.vertical)) + colorBorder(box.vertical)
+  );
+  lines.push(
+    buildHorizontalLine(box.leftT, box.cross, box.rightT, box.horizontal)
+  );
+  for (let rowIndex = 0; rowIndex < data.length; rowIndex++) {
+    const row = data[rowIndex];
+    const cellValues = config.columns.map((col, i) => {
+      const value = getValue(row, col.accessor) || "<None>";
+      return config.wrapText !== false ? wrapText2(value, widths[i]) : [value.slice(0, widths[i])];
+    });
+    const maxLines = Math.max(...cellValues.map((c) => c.length));
+    for (let lineIndex = 0; lineIndex < maxLines; lineIndex++) {
+      const cells = cellValues.map((cellLines, i) => {
+        const text = cellLines[lineIndex] ?? "";
+        const padding = widths[i] - text.length;
+        const align = config.columns[i]?.align ?? "left";
+        let content;
+        if (align === "center") {
+          const leftPad = Math.floor(padding / 2);
+          const rightPad = padding - leftPad;
+          content = " ".repeat(leftPad) + text + " ".repeat(rightPad);
+        } else if (align === "right") {
+          content = " ".repeat(padding) + text;
+        } else {
+          content = text + " ".repeat(padding);
+        }
+        return ` ${content} `;
+      });
+      lines.push(
+        colorBorder(box.vertical) + cells.join(colorBorder(box.vertical)) + colorBorder(box.vertical)
+      );
+    }
+    if (rowIndex < data.length - 1 && config.rowSeparators) {
+      lines.push(
+        buildHorizontalLine(
+          box.leftT,
+          box.cross,
+          box.rightT,
+          box.horizontal
+        )
+      );
+    }
+  }
+  lines.push(
+    buildHorizontalLine(
+      box.bottomLeft,
+      box.bottomT,
+      box.bottomRight,
+      box.horizontal
+    )
+  );
+  return lines.join("\n");
+}
+var DEFAULT_RESOURCE_COLUMNS = [
+  { header: "NAMESPACE", accessor: "namespace", minWidth: 9 },
+  { header: "NAME", accessor: "name", minWidth: 10, maxWidth: 40 },
+  { header: "LABELS", accessor: "labels", minWidth: 10, maxWidth: 35 }
+];
+function formatResourceTable(data, noColor = false) {
+  const items = extractItems(data);
+  if (items.length === 0) {
+    return "";
+  }
+  return formatBeautifulTable(
+    items,
+    {
+      columns: DEFAULT_RESOURCE_COLUMNS,
+      wrapText: true
+    },
+    noColor
+  );
+}
+function extractItems(data) {
+  if (data && typeof data === "object" && "items" in data) {
+    const items = data.items;
+    if (Array.isArray(items)) {
+      return items.filter(
+        (item) => item !== null && typeof item === "object"
+      );
+    }
+  }
+  if (Array.isArray(data)) {
+    return data.filter(
+      (item) => item !== null && typeof item === "object"
+    );
+  }
+  if (data && typeof data === "object") {
+    return [data];
+  }
+  return [];
+}
+
+// src/output/formatter.ts
+function formatOutput(data, format = "table", noColor = false) {
+  if (format === "none") {
+    return "";
+  }
+  const useNoColor = noColor || !shouldUseColors();
+  switch (format) {
+    case "json":
+      return formatJSON(data);
+    case "yaml":
+      return formatYAML(data);
+    case "table":
+    case "text":
+      return formatTable(data, useNoColor);
+    case "tsv":
+      return formatTSV(data);
+    case "spec":
+      return formatJSON(data);
+    default:
+      return formatTable(data, useNoColor);
+  }
+}
+function formatJSON(data) {
+  return JSON.stringify(data, null, 2);
+}
+function formatYAML(data) {
+  return import_yaml2.default.stringify(data, { indent: 2 });
+}
+function extractItems2(data) {
+  if (data && typeof data === "object" && "items" in data) {
+    const items = data.items;
+    if (Array.isArray(items)) {
+      return items.filter(
+        (item) => item !== null && typeof item === "object"
+      );
+    }
+  }
+  if (Array.isArray(data)) {
+    return data.filter(
+      (item) => item !== null && typeof item === "object"
+    );
+  }
+  if (data && typeof data === "object") {
+    return [data];
+  }
+  return [];
+}
+function formatTable(data, noColor = false) {
+  return formatResourceTable(data, noColor);
+}
+function formatTSV(data) {
+  const items = extractItems2(data);
+  if (items.length === 0) {
+    return "";
+  }
+  const allKeys = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    Object.keys(item).forEach((k) => allKeys.add(k));
+  }
+  const priority = ["name", "namespace", "status", "created", "modified"];
+  const headers = [
+    ...priority.filter((p) => allKeys.has(p)),
+    ...[...allKeys].filter((k) => !priority.includes(k)).sort()
+  ];
+  const lines = [];
+  for (const item of items) {
+    const values = headers.map((h) => {
+      const val = item[h];
+      if (val === null || val === void 0) return "";
+      if (typeof val === "object") return JSON.stringify(val);
+      return String(val);
+    });
+    lines.push(values.join("	"));
+  }
+  return lines.join("\n");
+}
+function parseOutputFormat(format) {
+  switch (format.toLowerCase()) {
+    case "json":
+      return "json";
+    case "yaml":
+      return "yaml";
+    case "table":
+    case "text":
+    case "":
+      return "table";
+    case "tsv":
+      return "tsv";
+    case "none":
+      return "none";
+    default:
+      return "table";
+  }
+}
+function formatAPIError(statusCode, body, operation) {
+  const lines = [];
+  lines.push(`ERROR: ${operation} failed (HTTP ${statusCode})`);
+  if (body && typeof body === "object") {
+    const errResp = body;
+    if (errResp.message) {
+      lines.push(`  Message: ${errResp.message}`);
+    }
+    if (errResp.code) {
+      lines.push(`  Code: ${errResp.code}`);
+    }
+    if (errResp.details) {
+      lines.push(`  Details: ${errResp.details}`);
+    }
+  }
+  switch (statusCode) {
+    case 401:
+      lines.push(
+        "\nHint: Authentication failed. Check your credentials with 'login profile show'"
+      );
+      break;
+    case 403:
+      lines.push(
+        "\nHint: Permission denied. You may not have access to this resource."
+      );
+      break;
+    case 404:
+      lines.push(
+        "\nHint: Resource not found. Verify the name and namespace are correct."
+      );
+      break;
+    case 409:
+      lines.push(
+        "\nHint: Conflict - resource may already exist or be in a conflicting state."
+      );
+      break;
+    case 429:
+      lines.push("\nHint: Rate limited. Please wait and try again.");
+      break;
+    case 500:
+    case 502:
+    case 503:
+      lines.push(
+        "\nHint: Server error. Please try again later or contact support."
+      );
+      break;
+  }
+  return lines.join("\n");
+}
+
+// src/output/spec.ts
+function buildCommandSpec(options) {
+  const spec = {
+    command: options.command,
+    description: options.description,
+    usage: options.usage ?? `xcsh ${options.command} [options]`,
+    flags: options.flags ?? [],
+    examples: options.examples ?? [],
+    outputFormats: options.outputFormats ?? ["table", "json", "yaml"]
+  };
+  if (options.related !== void 0) {
+    spec.related = options.related;
+  }
+  if (options.category !== void 0) {
+    spec.category = options.category;
+  }
+  return spec;
+}
+function formatSpec(spec) {
+  return JSON.stringify(spec, null, 2);
+}
+function buildCloudstatusSpecs() {
+  return {
+    status: buildCommandSpec({
+      command: "cloudstatus status",
+      description: "Get the overall health indicator for F5 Distributed Cloud services. Returns status level (operational, degraded, major outage) with description.",
+      usage: "xcsh cloudstatus status [--quiet]",
+      flags: [
+        {
+          name: "--quiet",
+          alias: "-q",
+          description: "Return exit code only (0=operational, 1=degraded, 2=outage)",
+          type: "boolean"
+        }
+      ],
+      examples: [
+        {
+          command: "xcsh cloudstatus status",
+          description: "Check current F5 XC service status"
+        },
+        {
+          command: "xcsh cloudstatus status --quiet && echo 'All systems operational'",
+          description: "Use in scripts for health checks"
+        },
+        {
+          command: "xcsh cloudstatus status --output json",
+          description: "Get status as JSON for automation"
+        }
+      ],
+      category: "cloudstatus",
+      related: [
+        "cloudstatus summary",
+        "cloudstatus components",
+        "cloudstatus incidents"
+      ]
+    }),
+    summary: buildCommandSpec({
+      command: "cloudstatus summary",
+      description: "Get complete status summary including overall health, component status, and active incidents.",
+      usage: "xcsh cloudstatus summary",
+      examples: [
+        {
+          command: "xcsh cloudstatus summary",
+          description: "View full infrastructure health overview"
+        },
+        {
+          command: "xcsh cloudstatus summary --output json",
+          description: "Get complete summary as JSON"
+        }
+      ],
+      category: "cloudstatus",
+      related: ["cloudstatus status", "cloudstatus components"]
+    }),
+    components: buildCommandSpec({
+      command: "cloudstatus components",
+      description: "List all infrastructure components and their current operational status.",
+      usage: "xcsh cloudstatus components",
+      examples: [
+        {
+          command: "xcsh cloudstatus components",
+          description: "List all components with status"
+        },
+        {
+          command: "xcsh cloudstatus components --output json",
+          description: "Get components as JSON for monitoring integration"
+        }
+      ],
+      category: "cloudstatus",
+      related: ["cloudstatus status", "cloudstatus summary"]
+    }),
+    incidents: buildCommandSpec({
+      command: "cloudstatus incidents",
+      description: "List active and recent incidents affecting F5 Distributed Cloud services.",
+      usage: "xcsh cloudstatus incidents",
+      examples: [
+        {
+          command: "xcsh cloudstatus incidents",
+          description: "View active incidents"
+        },
+        {
+          command: "xcsh cloudstatus incidents --output json",
+          description: "Get incidents as JSON for alerting systems"
+        }
+      ],
+      category: "cloudstatus",
+      related: ["cloudstatus status", "cloudstatus maintenance"]
+    }),
+    maintenance: buildCommandSpec({
+      command: "cloudstatus maintenance",
+      description: "List scheduled maintenance windows for F5 Distributed Cloud services.",
+      usage: "xcsh cloudstatus maintenance",
+      examples: [
+        {
+          command: "xcsh cloudstatus maintenance",
+          description: "View upcoming maintenance windows"
+        },
+        {
+          command: "xcsh cloudstatus maintenance --output json",
+          description: "Get maintenance schedule as JSON"
+        }
+      ],
+      category: "cloudstatus",
+      related: ["cloudstatus status", "cloudstatus incidents"]
+    })
+  };
+}
+function buildLoginSpecs() {
+  return {
+    banner: buildCommandSpec({
+      command: "login banner",
+      description: "Display xcsh banner with logo and connection information.",
+      usage: "xcsh login banner",
+      examples: [
+        {
+          command: "xcsh login banner",
+          description: "Show the xcsh welcome banner"
+        }
+      ],
+      category: "login",
+      related: ["login profile show"]
+    }),
+    "profile list": buildCommandSpec({
+      command: "login profile list",
+      description: "List all saved connection profiles.",
+      usage: "xcsh login profile list",
+      examples: [
+        {
+          command: "xcsh login profile list",
+          description: "List saved profiles"
+        },
+        {
+          command: "xcsh login profile list --output json",
+          description: "Get profiles as JSON"
+        }
+      ],
+      category: "login",
+      related: [
+        "login profile show",
+        "login profile create",
+        "login profile use"
+      ]
+    }),
+    "profile show": buildCommandSpec({
+      command: "login profile show",
+      description: "Show current connection profile and authentication status.",
+      usage: "xcsh login profile show [name]",
+      flags: [
+        {
+          name: "name",
+          description: "Profile name to show (optional, defaults to active)",
+          type: "string"
+        }
+      ],
+      examples: [
+        {
+          command: "xcsh login profile show",
+          description: "Show active profile"
+        },
+        {
+          command: "xcsh login profile show production",
+          description: "Show specific profile"
+        }
+      ],
+      category: "login",
+      related: ["login profile list", "login profile use"]
+    }),
+    "profile create": buildCommandSpec({
+      command: "login profile create",
+      description: "Create a new connection profile with URL and credentials.",
+      usage: "xcsh login profile create <name>",
+      flags: [
+        {
+          name: "name",
+          description: "Profile name",
+          type: "string",
+          required: true
+        }
+      ],
+      examples: [
+        {
+          command: "xcsh login profile create production",
+          description: "Create a new profile named 'production'"
+        }
+      ],
+      category: "login",
+      related: ["login profile list", "login profile use"]
+    }),
+    "profile use": buildCommandSpec({
+      command: "login profile use",
+      description: "Switch to a different connection profile.",
+      usage: "xcsh login profile use <name>",
+      flags: [
+        {
+          name: "name",
+          description: "Profile name to activate",
+          type: "string",
+          required: true
+        }
+      ],
+      examples: [
+        {
+          command: "xcsh login profile use staging",
+          description: "Switch to staging profile"
+        }
+      ],
+      category: "login",
+      related: ["login profile list", "login profile show"]
+    }),
+    "context show": buildCommandSpec({
+      command: "login context show",
+      description: "Show the current default namespace context.",
+      usage: "xcsh login context show",
+      examples: [
+        {
+          command: "xcsh login context show",
+          description: "Display current namespace"
+        }
+      ],
+      category: "login",
+      related: ["login context set", "login context list"]
+    }),
+    "context set": buildCommandSpec({
+      command: "login context set",
+      description: "Set the default namespace for subsequent operations.",
+      usage: "xcsh login context set <namespace>",
+      flags: [
+        {
+          name: "namespace",
+          description: "Namespace to set as default",
+          type: "string",
+          required: true
+        }
+      ],
+      examples: [
+        {
+          command: "xcsh login context set production",
+          description: "Set production as default namespace"
+        }
+      ],
+      category: "login",
+      related: ["login context show", "login context list"]
+    })
+  };
+}
+function getCommandSpec(commandPath) {
+  const cloudstatusSpecs = buildCloudstatusSpecs();
+  const loginSpecs = buildLoginSpecs();
+  const normalized = commandPath.toLowerCase().trim();
+  if (normalized.startsWith("cloudstatus ")) {
+    const subcommand = normalized.replace("cloudstatus ", "");
+    return cloudstatusSpecs[subcommand];
+  }
+  if (normalized.startsWith("login ")) {
+    const subcommand = normalized.replace("login ", "");
+    return loginSpecs[subcommand];
+  }
+  return void 0;
+}
+
 // src/repl/session.ts
 var NAMESPACE_CACHE_TTL = 5 * 60 * 1e3;
 var REPLSession = class {
@@ -46037,7 +46759,7 @@ var REPLSession = class {
   _serverUrl = "";
   _apiToken = "";
   _apiClient = null;
-  _outputFormat = "yaml";
+  _outputFormat = "table";
   _debug = false;
   _profileManager;
   _activeProfile = null;
@@ -46051,7 +46773,7 @@ var REPLSession = class {
     this._profileManager = getProfileManager();
     this._serverUrl = config.serverUrl ?? process.env[`${ENV_PREFIX}_API_URL`] ?? "";
     this._apiToken = config.apiToken ?? process.env[`${ENV_PREFIX}_API_TOKEN`] ?? "";
-    this._outputFormat = config.outputFormat ?? "yaml";
+    this._outputFormat = config.outputFormat ?? getOutputFormatFromEnv() ?? "table";
     this._debug = config.debug ?? process.env[`${ENV_PREFIX}_DEBUG`] === "true";
     if (this._serverUrl) {
       this._tenant = this.extractTenant(this._serverUrl);
@@ -46900,7 +47622,7 @@ function formatConfigSection() {
 }
 
 // src/repl/help.ts
-function wrapText2(text, width, indent) {
+function wrapText3(text, width, indent) {
   const prefix = " ".repeat(indent);
   const words = text.split(/\s+/);
   const lines = [];
@@ -46924,7 +47646,7 @@ function formatRootHelp() {
     colorBoldWhite(`${CLI_NAME} - ${CLI_FULL_NAME} v${CLI_VERSION}`),
     "",
     "DESCRIPTION",
-    ...wrapText2(CLI_DESCRIPTION_LONG, 80, 2),
+    ...wrapText3(CLI_DESCRIPTION_LONG, 80, 2),
     "",
     "USAGE",
     `  ${CLI_NAME}                              Enter interactive REPL mode`,
@@ -46968,7 +47690,8 @@ function formatGlobalFlags() {
     "  -h, --help            Show this help",
     "  --no-color            Disable color output",
     "  -o, --output <fmt>    Output format (json, yaml, table)",
-    "  -ns, --namespace <ns> Target namespace"
+    "  -ns, --namespace <ns> Target namespace",
+    "  --spec                Output command specification as JSON (for AI)"
   ];
 }
 function formatEnvironmentVariables() {
@@ -47233,7 +47956,7 @@ function formatDomainsSection() {
 function formatCustomDomainHelp(domain) {
   const output = ["", colorBoldWhite(domain.name), ""];
   output.push("DESCRIPTION");
-  output.push(...wrapText2(domain.description, 80, 2));
+  output.push(...wrapText3(domain.description, 80, 2));
   output.push("");
   output.push("USAGE");
   output.push(`  ${CLI_NAME} ${domain.name} <command> [options]`);
@@ -47263,7 +47986,7 @@ function formatSubcommandHelp(domainName, subcommand) {
     ""
   ];
   output.push("DESCRIPTION");
-  output.push(...wrapText2(subcommand.description, 80, 2));
+  output.push(...wrapText3(subcommand.description, 80, 2));
   output.push("");
   output.push("USAGE");
   output.push(
@@ -47982,7 +48705,7 @@ var contextSubcommands = {
 };
 
 // src/config/settings.ts
-var import_yaml2 = __toESM(require_dist(), 1);
+var import_yaml3 = __toESM(require_dist(), 1);
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
 var LOGO_MODES = [
@@ -48013,7 +48736,7 @@ function loadSettingsSync() {
       configPath,
       "utf-8"
     );
-    const parsed = import_yaml2.default.parse(content);
+    const parsed = import_yaml3.default.parse(content);
     return {
       ...DEFAULT_SETTINGS,
       ...validateSettings(parsed)
@@ -48880,6 +49603,34 @@ function calculateRegionalStatus(components) {
 }
 
 // src/domains/cloudstatus/index.ts
+function parseOutputArgs(args, session) {
+  let format;
+  let spec = false;
+  const filteredArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? "";
+    const nextArg = args[i + 1];
+    if (arg === "--output" || arg === "-o") {
+      if (nextArg) {
+        format = parseOutputFormat(nextArg);
+        i++;
+      }
+    } else if (arg === "--spec") {
+      spec = true;
+    } else if (arg.startsWith("--output=")) {
+      format = parseOutputFormat(arg.split("=")[1] ?? "table");
+    } else if (arg.startsWith("-o=")) {
+      format = parseOutputFormat(arg.split("=")[1] ?? "table");
+    } else {
+      filteredArgs.push(arg);
+    }
+  }
+  return {
+    format: format ?? session.getOutputFormat(),
+    spec,
+    filteredArgs
+  };
+}
 var cloudstatusClient = null;
 function getClient() {
   if (!cloudstatusClient) {
@@ -48895,8 +49646,14 @@ var statusCommand = {
   usage: "[--quiet]",
   aliases: ["st"],
   async execute(args, session) {
-    const quiet = args.includes("--quiet") || args.includes("-q");
-    const format = session.getOutputFormat();
+    const { format, spec, filteredArgs } = parseOutputArgs(args, session);
+    const quiet = filteredArgs.includes("--quiet") || filteredArgs.includes("-q");
+    if (spec) {
+      const cmdSpec = getCommandSpec("cloudstatus status");
+      if (cmdSpec) {
+        return successResult([formatSpec(cmdSpec)]);
+      }
+    }
     try {
       const client = getClient();
       const response = await client.getStatus();
@@ -48946,8 +49703,14 @@ var summaryCommand = {
   usage: "[--brief]",
   aliases: ["sum"],
   async execute(args, session) {
-    const brief = args.includes("--brief") || args.includes("-b");
-    const format = session.getOutputFormat();
+    const { format, spec, filteredArgs } = parseOutputArgs(args, session);
+    const brief = filteredArgs.includes("--brief") || filteredArgs.includes("-b");
+    if (spec) {
+      const cmdSpec = getCommandSpec("cloudstatus summary");
+      if (cmdSpec) {
+        return successResult([formatSpec(cmdSpec)]);
+      }
+    }
     try {
       const client = getClient();
       const response = await client.getSummary();
@@ -48975,8 +49738,14 @@ var componentsCommand = {
   usage: "[--degraded-only]",
   aliases: ["comp"],
   async execute(args, session) {
-    const degradedOnly = args.includes("--degraded-only") || args.includes("-d");
-    const format = session.getOutputFormat();
+    const { format, spec, filteredArgs } = parseOutputArgs(args, session);
+    const degradedOnly = filteredArgs.includes("--degraded-only") || filteredArgs.includes("-d");
+    if (spec) {
+      const cmdSpec = getCommandSpec("cloudstatus components");
+      if (cmdSpec) {
+        return successResult([formatSpec(cmdSpec)]);
+      }
+    }
     try {
       const client = getClient();
       const response = await client.getComponents();
@@ -49018,8 +49787,14 @@ var incidentsCommand = {
   usage: "[--active-only]",
   aliases: ["inc"],
   async execute(args, session) {
-    const activeOnly = args.includes("--active-only") || args.includes("-a");
-    const format = session.getOutputFormat();
+    const { format, spec, filteredArgs } = parseOutputArgs(args, session);
+    const activeOnly = filteredArgs.includes("--active-only") || filteredArgs.includes("-a");
+    if (spec) {
+      const cmdSpec = getCommandSpec("cloudstatus incidents");
+      if (cmdSpec) {
+        return successResult([formatSpec(cmdSpec)]);
+      }
+    }
     try {
       const client = getClient();
       const response = activeOnly ? await client.getUnresolvedIncidents() : await client.getIncidents();
@@ -49059,8 +49834,14 @@ var maintenanceCommand = {
   usage: "[--upcoming]",
   aliases: ["maint"],
   async execute(args, session) {
-    const upcomingOnly = args.includes("--upcoming") || args.includes("-u");
-    const format = session.getOutputFormat();
+    const { format, spec, filteredArgs } = parseOutputArgs(args, session);
+    const upcomingOnly = filteredArgs.includes("--upcoming") || filteredArgs.includes("-u");
+    if (spec) {
+      const cmdSpec = getCommandSpec("cloudstatus maintenance");
+      if (cmdSpec) {
+        return successResult([formatSpec(cmdSpec)]);
+      }
+    }
     try {
       const client = getClient();
       const response = upcomingOnly ? await client.getUpcomingMaintenances() : await client.getMaintenances();
@@ -49532,7 +50313,7 @@ _xcsh_completions() {
   local commands="${domainNames} ${allAliases.join(" ")} help quit exit clear history"
   local actions="${actions}"
   local builtins="help quit exit clear history context ctx"
-  local global_flags="--help -h --version -v --no-color --output -o --namespace -ns"
+  local global_flags="--help -h --version -v --no-color --output -o --namespace -ns --spec"
 
   # Handle completion based on position
   case \${cword} in
@@ -49563,7 +50344,7 @@ ${customDomainCompletions.join("\n")}
     *)
       # Third+ word: flags
       if [[ "\${cur}" == -* ]]; then
-        local action_flags="--name -n --namespace -ns --output -o --json --yaml --limit --label"
+        local action_flags="--name -n --namespace -ns --output -o --json --yaml --limit --label --spec"
         COMPREPLY=($(compgen -W "\${action_flags}" -- "\${cur}"))
       fi
       return 0
@@ -49617,6 +50398,7 @@ _xcsh() {
         '--no-color[Disable color output]'
         '(-o --output)'{-o,--output}'[Output format]:format:(json yaml table)'
         '(-ns --namespace)'{-ns,--namespace}'[Namespace]:namespace:_xcsh_namespaces'
+        '--spec[Output command specification as JSON for AI assistants]'
     )
 
     _arguments -C \\
@@ -49667,6 +50449,7 @@ ${customDomainCompletions.join("\n")}
                 '--limit[Maximum results]:limit:'
                 '--label[Filter by label]:label:'
                 '(-f --file)'{-f,--file}'[Configuration file]:file:_files'
+                '--spec[Output command specification as JSON for AI assistants]'
             )
             _arguments "\${action_opts[@]}"
             ;;
@@ -49730,6 +50513,7 @@ complete -c xcsh -s v -l version -d 'Show version number'
 complete -c xcsh -l no-color -d 'Disable color output'
 complete -c xcsh -s o -l output -d 'Output format' -xa 'json yaml table'
 complete -c xcsh -l namespace -s ns -d 'Namespace' -xa 'default system shared'
+complete -c xcsh -l spec -d 'Output command specification as JSON for AI assistants'
 
 # Builtin commands
 complete -c xcsh -n "__fish_use_subcommand" -a "help" -d 'Show help information'
@@ -49759,6 +50543,7 @@ complete -c xcsh -l label -d 'Filter by label'
 complete -c xcsh -s f -l file -d 'Configuration file' -r
 complete -c xcsh -l force -d 'Force deletion'
 complete -c xcsh -l cascade -d 'Cascade delete'
+complete -c xcsh -l spec -d 'Output command specification as JSON for AI assistants'
 `;
 }
 
@@ -50925,219 +51710,6 @@ function useCompletion(options) {
   };
 }
 
-// src/output/formatter.ts
-var import_yaml3 = __toESM(require_dist(), 1);
-function formatOutput(data, format = "yaml") {
-  if (format === "none") {
-    return "";
-  }
-  switch (format) {
-    case "json":
-      return formatJSON(data);
-    case "yaml":
-      return formatYAML(data);
-    case "table":
-    case "text":
-      return formatTable(data);
-    case "tsv":
-      return formatTSV(data);
-    default:
-      return formatYAML(data);
-  }
-}
-function formatJSON(data) {
-  return JSON.stringify(data, null, 2);
-}
-function formatYAML(data) {
-  return import_yaml3.default.stringify(data, { indent: 2 });
-}
-function extractItems(data) {
-  if (data && typeof data === "object" && "items" in data) {
-    const items = data.items;
-    if (Array.isArray(items)) {
-      return items.filter(
-        (item) => item !== null && typeof item === "object"
-      );
-    }
-  }
-  if (Array.isArray(data)) {
-    return data.filter(
-      (item) => item !== null && typeof item === "object"
-    );
-  }
-  if (data && typeof data === "object") {
-    return [data];
-  }
-  return [];
-}
-function getStringField(obj, key) {
-  const value = obj[key];
-  if (typeof value === "string") {
-    return value;
-  }
-  if (value !== null && value !== void 0) {
-    return String(value);
-  }
-  return "";
-}
-function formatLabels(obj) {
-  const labels = obj["labels"];
-  if (!labels || typeof labels !== "object") {
-    return "";
-  }
-  const labelMap = labels;
-  const entries = Object.entries(labelMap).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${v}`);
-  if (entries.length === 0) {
-    return "";
-  }
-  return `map[${entries.join(" ")}]`;
-}
-function wrapText3(text, maxWidth) {
-  if (text.length <= maxWidth) {
-    return [text];
-  }
-  const lines = [];
-  let remaining = text;
-  while (remaining.length > 0) {
-    if (remaining.length <= maxWidth) {
-      lines.push(remaining);
-      break;
-    }
-    let breakPoint = maxWidth;
-    for (let i = maxWidth - 1; i > 0; i--) {
-      if (remaining[i] === " ") {
-        breakPoint = i;
-        break;
-      }
-    }
-    lines.push(remaining.slice(0, breakPoint));
-    remaining = remaining.slice(breakPoint).trimStart();
-  }
-  return lines;
-}
-function formatTable(data) {
-  const items = extractItems(data);
-  if (items.length === 0) {
-    return "";
-  }
-  const headers = ["NAMESPACE", "NAME", "LABELS"];
-  const widths = [9, 27, 30];
-  const rows = [];
-  for (const item of items) {
-    const row = [
-      getStringField(item, "namespace") || "<None>",
-      getStringField(item, "name") || "<None>",
-      formatLabels(item) || "<None>"
-    ];
-    const wrappedCells = row.map((cell, i) => wrapText3(cell, widths[i]));
-    const maxLines = Math.max(...wrappedCells.map((c) => c.length));
-    const wrappedRows = [];
-    for (let line = 0; line < maxLines; line++) {
-      wrappedRows.push(wrappedCells.map((c) => c[line] ?? ""));
-    }
-    rows.push(wrappedRows);
-  }
-  const lines = [];
-  const boxLine = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
-  lines.push(boxLine);
-  lines.push(
-    "|" + headers.map((h, i) => {
-      const padding = widths[i] - h.length;
-      const leftPad = Math.floor(padding / 2);
-      const rightPad = padding - leftPad;
-      return " " + " ".repeat(leftPad) + h + " ".repeat(rightPad) + " ";
-    }).join("|") + "|"
-  );
-  lines.push(boxLine);
-  for (const wrappedRows of rows) {
-    for (const row of wrappedRows) {
-      lines.push(
-        "|" + row.map((cell, i) => {
-          const padding = widths[i] - cell.length;
-          return " " + cell + " ".repeat(padding) + " ";
-        }).join("|") + "|"
-      );
-    }
-    lines.push(boxLine);
-  }
-  return lines.join("\n");
-}
-function formatTSV(data) {
-  const items = extractItems(data);
-  if (items.length === 0) {
-    return "";
-  }
-  const allKeys = /* @__PURE__ */ new Set();
-  for (const item of items) {
-    Object.keys(item).forEach((k) => allKeys.add(k));
-  }
-  const priority = ["name", "namespace", "status", "created", "modified"];
-  const headers = [
-    ...priority.filter((p) => allKeys.has(p)),
-    ...[...allKeys].filter((k) => !priority.includes(k)).sort()
-  ];
-  const lines = [];
-  for (const item of items) {
-    const values = headers.map((h) => {
-      const val = item[h];
-      if (val === null || val === void 0) return "";
-      if (typeof val === "object") return JSON.stringify(val);
-      return String(val);
-    });
-    lines.push(values.join("	"));
-  }
-  return lines.join("\n");
-}
-function formatAPIError(statusCode, body, operation) {
-  const lines = [];
-  lines.push(`ERROR: ${operation} failed (HTTP ${statusCode})`);
-  if (body && typeof body === "object") {
-    const errResp = body;
-    if (errResp.message) {
-      lines.push(`  Message: ${errResp.message}`);
-    }
-    if (errResp.code) {
-      lines.push(`  Code: ${errResp.code}`);
-    }
-    if (errResp.details) {
-      lines.push(`  Details: ${errResp.details}`);
-    }
-  }
-  switch (statusCode) {
-    case 401:
-      lines.push(
-        "\nHint: Authentication failed. Check your credentials with 'login profile show'"
-      );
-      break;
-    case 403:
-      lines.push(
-        "\nHint: Permission denied. You may not have access to this resource."
-      );
-      break;
-    case 404:
-      lines.push(
-        "\nHint: Resource not found. Verify the name and namespace are correct."
-      );
-      break;
-    case 409:
-      lines.push(
-        "\nHint: Conflict - resource may already exist or be in a conflicting state."
-      );
-      break;
-    case 429:
-      lines.push("\nHint: Rate limited. Please wait and try again.");
-      break;
-    case 500:
-    case 502:
-    case 503:
-      lines.push(
-        "\nHint: Server error. Please try again later or contact support."
-      );
-      break;
-  }
-  return lines.join("\n");
-}
-
 // src/repl/executor.ts
 var BUILTIN_COMMANDS = /* @__PURE__ */ new Set([
   "help",
@@ -51687,34 +52259,66 @@ function domainToResourcePath(domain) {
 function parseCommandArgs(args) {
   let name;
   let namespace;
+  let outputFormat;
+  let spec = false;
+  let noColor = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i] ?? "";
     if (arg.startsWith("--")) {
-      const flagName = arg.slice(2);
+      const flagName = arg.slice(2).toLowerCase();
       const nextArg = args[i + 1];
-      if (flagName === "namespace" || flagName === "ns") {
-        namespace = nextArg;
-        i++;
-      } else if (flagName === "name") {
-        name = nextArg;
-        i++;
-      } else if (nextArg && !nextArg.startsWith("--")) {
-        i++;
+      switch (flagName) {
+        case "namespace":
+        case "ns":
+          namespace = nextArg;
+          i++;
+          break;
+        case "name":
+          name = nextArg;
+          i++;
+          break;
+        case "output":
+          if (nextArg) {
+            outputFormat = parseOutputFormat(nextArg);
+            i++;
+          }
+          break;
+        case "spec":
+          spec = true;
+          break;
+        case "no-color":
+          noColor = true;
+          break;
+        default:
+          if (nextArg && !nextArg.startsWith("--")) {
+            i++;
+          }
       }
     } else if (arg.startsWith("-")) {
       const flagName = arg.slice(1);
       const nextArg = args[i + 1];
-      if (flagName === "n") {
-        namespace = nextArg;
-        i++;
-      } else if (nextArg && !nextArg.startsWith("-")) {
-        i++;
+      switch (flagName) {
+        case "n":
+        case "ns":
+          namespace = nextArg;
+          i++;
+          break;
+        case "o":
+          if (nextArg) {
+            outputFormat = parseOutputFormat(nextArg);
+            i++;
+          }
+          break;
+        default:
+          if (nextArg && !nextArg.startsWith("-")) {
+            i++;
+          }
       }
     } else if (!name) {
       name = arg;
     }
   }
-  return { name, namespace };
+  return { name, namespace, outputFormat, spec, noColor };
 }
 async function executeAPICommand(session, ctx, cmd) {
   const client = session.getAPIClient();
@@ -51763,8 +52367,51 @@ async function executeAPICommand(session, ctx, cmd) {
     }
   }
   const canonicalDomain = resolveDomain(domain) ?? domain;
-  const { name, namespace } = parseCommandArgs(args);
+  const { name, namespace, outputFormat, spec, noColor } = parseCommandArgs(args);
   const effectiveNamespace = namespace ?? session.getNamespace();
+  if (spec) {
+    const commandPath = `${canonicalDomain} ${action}`;
+    const cmdSpec = getCommandSpec(commandPath);
+    if (cmdSpec) {
+      return {
+        output: [formatSpec(cmdSpec)],
+        shouldExit: false,
+        shouldClear: false,
+        contextChanged: false
+      };
+    }
+    const basicSpec = {
+      command: `${CLI_NAME} ${canonicalDomain} ${action}`,
+      description: `Execute ${action} on ${canonicalDomain} resources`,
+      usage: `${CLI_NAME} ${canonicalDomain} ${action} [name] [options]`,
+      flags: [
+        {
+          name: "--namespace",
+          alias: "-ns",
+          type: "string",
+          description: "Target namespace"
+        },
+        {
+          name: "--output",
+          alias: "-o",
+          type: "string",
+          description: "Output format (json, yaml, table)"
+        },
+        {
+          name: "--name",
+          type: "string",
+          description: "Resource name"
+        }
+      ],
+      outputFormats: ["table", "json", "yaml"]
+    };
+    return {
+      output: [JSON.stringify(basicSpec, null, 2)],
+      shouldExit: false,
+      shouldClear: false,
+      contextChanged: false
+    };
+  }
   const resourcePath = domainToResourcePath(canonicalDomain);
   let apiPath = `/api/config/namespaces/${effectiveNamespace}/${resourcePath}`;
   try {
@@ -51849,8 +52496,8 @@ async function executeAPICommand(session, ctx, cmd) {
         };
       }
     }
-    const outputFormat = session.getOutputFormat();
-    const formatted = formatOutput(result, outputFormat);
+    const effectiveFormat = outputFormat ?? session.getOutputFormat();
+    const formatted = formatOutput(result, effectiveFormat, noColor);
     return {
       output: formatted ? [formatted] : ["(no output)"],
       shouldExit: false,
@@ -52241,7 +52888,7 @@ var program2 = new Command();
 program2.configureHelp({
   formatHelp: () => formatRootHelp().join("\n")
 });
-program2.name(CLI_NAME).description("F5 Distributed Cloud Shell - Interactive CLI for F5 XC").version(CLI_VERSION, "-v, --version", "Show version number").option("--no-color", "Disable color output").option("--logo <mode>", "Logo display mode: image, ascii, none").option("-h, --help", "Show help").argument("[command...]", "Command to execute non-interactively").allowUnknownOption(true).helpOption(false).action(
+program2.name(CLI_NAME).description("F5 Distributed Cloud Shell - Interactive CLI for F5 XC").version(CLI_VERSION, "-v, --version", "Show version number").option("--no-color", "Disable color output").option("--logo <mode>", "Logo display mode: image, ascii, none").option("-o, --output <format>", "Output format (json, yaml, table)").option("--spec", "Output command specification as JSON (for AI)").option("-h, --help", "Show help").argument("[command...]", "Command to execute non-interactively").allowUnknownOption(true).helpOption(false).action(
   async (commandArgs, options) => {
     if (options.help && commandArgs.length === 0) {
       formatRootHelp().forEach((line) => console.log(line));
@@ -52253,6 +52900,12 @@ program2.name(CLI_NAME).description("F5 Distributed Cloud Shell - Interactive CL
     if (options.logo && commandArgs.length > 0) {
       commandArgs.push("--logo", options.logo);
     }
+    if (options.output && commandArgs.length > 0) {
+      commandArgs.push("--output", options.output);
+    }
+    if (options.spec && commandArgs.length > 0) {
+      commandArgs.push("--spec");
+    }
     if (commandArgs.length === 0) {
       if (!process.stdin.isTTY) {
         console.error(