@ricsam/r5dctl 0.0.49 → 0.0.51

package/README.md

@@ -50,6 +50,8 @@ r5dctl delete project <namespace/name|id>
 r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
 r5dctl -p <project> get envs
+r5dctl -p <project> get envs --show-values
+r5dctl -p <project> get env API_KEY
 r5dctl -p <project> set envs --from-env-file ~/.env --only-missing
 r5dctl -p <project> set envs -e API_KEY=value --description "API credential"
 r5dctl -p <project> get sessions --branch <branch>
@@ -79,13 +81,27 @@ r5dctl ps list
 r5dctl -p <project> -b <branch> ps list --worker <label>
 r5dctl -s <session-id> ps list --json
 r5dctl ps stop <run-id>
+
+r5dctl k8s usage
+r5dctl k8s usage --namespace default --workload api --container server
+r5dctl k8s usage --window 7d
+r5dctl k8s usage --workload default/api --window 7d --json
 ```
 
 `shell` connects to the same live worker PTY as the web Shell tab. Without `-c` it attaches the local terminal interactively. With `-c`/`--command`, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.
 
 `ps list` shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while `--worker` selects a worker label. `ps stop` sends `SIGTERM` to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.
 
-`get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
+`k8s usage` shows current and rolling CPU and memory usage for every workload container in your managed vCluster. The default window is `24h`; pass `--window 7d` for seven days. Filter with `--namespace`, `--workload`, or `--container`; a workload may be identified by name, `namespace/name`, or Kubernetes UID. Human-readable output shows current totals across sampled replicas and the selected window's maximum. Global `--json` includes min/max summaries, the complete five-minute history envelope, per-pod series, coverage, and freshness metadata.
+
+`get envs` reports names and whether values are set without revealing the values by default. Add `--show-values` to reveal every value; multiline and control characters are escaped for readable output. Without the global `--json` flag, `get env <name>` writes only that value to stdout, with no added newline or labels, so it works directly with command substitution and pipelines:
+
+```bash
+export API_KEY="$(r5dctl -p <project> get env API_KEY)"
+r5dctl -p <project> get env PRIVATE_KEY | openssl pkey -check -noout
+```
+
+An undeclared or unset variable makes `get env` fail with a nonzero exit status. An explicitly configured empty value succeeds and writes zero bytes. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
 
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.
 

package/dist/cjs/cli.cjs

@@ -28,8 +28,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var cli_exports = {};
 __export(cli_exports, {
+  collectK8sUsage: () => collectK8sUsage,
+  formatK8sCpu: () => formatK8sCpu,
+  formatK8sMemory: () => formatK8sMemory,
   formatProcessAge: () => formatProcessAge,
   getCliHelpText: () => getCliHelpText,
+  getK8sUsageState: () => getK8sUsageState,
+  getProjectEnvValue: () => getProjectEnvValue,
   getR5dctlVersion: () => getR5dctlVersion,
   main: () => main,
   parseAnswerFlags: () => parseAnswerFlags,
@@ -37,7 +42,9 @@ __export(cli_exports, {
   parseConversationWorkDetailArgs: () => parseConversationWorkDetailArgs,
   parseEnvFlags: () => parseEnvFlags,
   parseEnvRequestResponseArgs: () => parseEnvRequestResponseArgs,
+  parseGetEnvsArgs: () => parseGetEnvsArgs,
   parseGlobalArgs: () => parseGlobalArgs,
+  parseK8sUsageArgs: () => parseK8sUsageArgs,
   parsePromptArgs: () => parsePromptArgs,
   parsePsHistoryArgs: () => parsePsHistoryArgs,
   parsePsListArgs: () => parsePsListArgs,
@@ -48,6 +55,8 @@ __export(cli_exports, {
   renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
   renderConversationWorkResponse: () => renderConversationWorkResponse,
+  renderEnvValues: () => renderEnvValues,
+  renderK8sUsageReport: () => renderK8sUsageReport,
   renderProcessHistory: () => renderProcessHistory,
   renderProcessInspection: () => renderProcessInspection,
   renderProcessList: () => renderProcessList,
@@ -126,6 +135,13 @@ const PS_HELP_TEXT = [
   "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
+const K8S_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+  "",
+  "Show current and rolling CPU and memory usage for managed-vCluster workload containers.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -155,8 +171,13 @@ const SHARED_HELP_ENTRIES = [
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
   {
     section: "envs",
-    usage: "-p <project> get envs",
-    description: "List declared envs and whether each has a value, without revealing values."
+    usage: "-p <project> get envs [--show-values]",
+    description: "List declared envs; use --show-values to reveal their values."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> get env <name>",
+    description: "Write one env value exactly to stdout for command substitution or piping."
   },
   {
     section: "envs",
@@ -221,6 +242,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> answer-env-request [-e KEY=value] [--context <text>]",
     description: "Answer a pending environment variable request with values, context, or both."
   },
+  {
+    section: "kubernetes",
+    usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+    description: "Show current and rolling CPU and memory usage for managed-vCluster workload containers."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -259,6 +285,7 @@ const HELP_SECTION_ORDER = [
   "branches",
   "envs",
   "sessions",
+  "kubernetes",
   "processes",
   "shell",
   "agents",
@@ -271,6 +298,7 @@ const HELP_SECTION_TITLES = {
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  kubernetes: "Kubernetes",
   processes: "Processes",
   shell: "Shell",
   agents: "Agents",
@@ -935,6 +963,36 @@ function parseRecentSessionArgs(args) {
   if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error("--limit must be an integer between 1 and 200");
   return { limit };
 }
+function parseK8sUsageArgs(args) {
+  const parsed = { window: "24h" };
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const option = ["--namespace", "--workload", "--container", "--window"].find(
+      (candidate) => arg === candidate || arg.startsWith(`${candidate}=`)
+    );
+    if (!option) throw new Error(`Unknown k8s usage argument: ${arg}`);
+    if (seen.has(option)) throw new Error(`Use ${option} only once`);
+    seen.add(option);
+    const inlineValue = parseLongOptionWithEquals(arg, option);
+    const candidateValue = inlineValue ?? args[index + 1];
+    if (!candidateValue || candidateValue.startsWith("--")) throw new Error(`Missing value for ${option}`);
+    const value = candidateValue;
+    if (inlineValue === void 0) index += 1;
+    if (option === "--window") {
+      if (value !== "24h" && value !== "7d") throw new Error("--window must be 24h or 7d");
+      parsed.window = value;
+    } else if (option === "--namespace") {
+      parsed.namespace = value;
+    } else if (option === "--workload") {
+      parsed.workload = value;
+    } else {
+      parsed.container = value;
+    }
+  }
+  return parsed;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1096,6 +1154,171 @@ Error: ${result.error}` : "";
   return `Workspace sync ${result.outcome} on ${result.workerLabel}; HEAD ${head}; ${result.diffSizeBytes} bytes.${discarded}${error}
 `;
 }
+function summarizeK8sHistory(history) {
+  if (history.envelope.length === 0) {
+    return {
+      cpuMinNanoCores: null,
+      cpuMaxNanoCores: null,
+      memoryMinBytes: null,
+      memoryMaxBytes: null,
+      sampleCount: 0
+    };
+  }
+  return {
+    cpuMinNanoCores: Math.min(...history.envelope.map((point) => point.cpuMinNanoCores)),
+    cpuMaxNanoCores: Math.max(...history.envelope.map((point) => point.cpuMaxNanoCores)),
+    memoryMinBytes: Math.min(...history.envelope.map((point) => point.memoryMinBytes)),
+    memoryMaxBytes: Math.max(...history.envelope.map((point) => point.memoryMaxBytes)),
+    sampleCount: history.envelope.reduce((total, point) => total + point.sampleCount, 0)
+  };
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex++;
+        const item = items[index];
+        if (item !== void 0) results[index] = await fn(item);
+      }
+    })
+  );
+  return results;
+}
+async function collectK8sUsage(client, options) {
+  const resources = await client.k8s.resources();
+  const candidates = resources.workloads.flatMap((workload) => workload.containers.map((container) => ({ workload, container }))).filter(({ workload, container }) => {
+    const workloadMatches = !options.workload || options.workload === workload.name || options.workload === `${workload.namespace}/${workload.name}` || options.workload === workload.uid;
+    return (!options.namespace || options.namespace === workload.namespace) && workloadMatches && (!options.container || options.container === container.name);
+  }).sort(
+    (left, right) => left.workload.namespace.localeCompare(right.workload.namespace) || left.workload.name.localeCompare(right.workload.name) || left.container.name.localeCompare(right.container.name)
+  );
+  if (candidates.length === 0 && (options.namespace || options.workload || options.container)) {
+    throw new Error("No managed-vCluster workload containers matched the requested filters");
+  }
+  const entries = await mapWithConcurrency(candidates, 8, async ({ workload, container }) => {
+    const history = await client.k8s.resourceHistory({ workloadUid: workload.uid, containerName: container.name, window: options.window });
+    return {
+      workload: {
+        uid: workload.uid,
+        kind: workload.kind,
+        namespace: workload.namespace,
+        name: workload.name,
+        replicas: workload.replicas,
+        readyReplicas: workload.readyReplicas
+      },
+      container: {
+        name: container.name,
+        currentUsage: container.currentUsage,
+        pods: container.pods
+      },
+      sampledPodCount: container.pods.filter((pod) => pod.cpuNanoCores !== null || pod.memoryBytes !== null).length,
+      summary: summarizeK8sHistory(history),
+      history
+    };
+  });
+  return {
+    window: options.window,
+    collectedAt: resources.collectedAt,
+    metricsFreshAt: resources.metricsFreshAt,
+    metricsStale: resources.metricsStale,
+    filters: {
+      namespace: options.namespace,
+      workload: options.workload,
+      container: options.container
+    },
+    entries
+  };
+}
+function formatDecimal(value) {
+  if (value >= 100) return value.toFixed(0);
+  if (value >= 10) return value.toFixed(1).replace(/\.0$/, "");
+  return value.toFixed(2).replace(/\.0+$/, "").replace(/(\.\d)0$/, "$1");
+}
+function formatK8sCpu(value) {
+  if (value === null) return "-";
+  const milliCores = value / 1e6;
+  return `${formatDecimal(milliCores)}m`;
+}
+function formatK8sMemory(value) {
+  if (value === null) return "-";
+  const units = ["B", "Ki", "Mi", "Gi", "Ti"];
+  let amount = value;
+  let unitIndex = 0;
+  while (amount >= 1024 && unitIndex < units.length - 1) {
+    amount /= 1024;
+    unitIndex += 1;
+  }
+  return `${formatDecimal(amount)}${units[unitIndex]}`;
+}
+function getK8sUsageState(entry) {
+  const hasHistory = entry.history.envelope.length > 0;
+  const terminalPods = entry.container.pods.filter((pod) => pod.phase === "Succeeded" || pod.phase === "Failed").length;
+  const inactive = entry.sampledPodCount === 0 && (entry.workload.replicas === 0 || entry.container.pods.length > 0 && terminalPods === entry.container.pods.length || entry.workload.kind === "CronJob" && entry.container.pods.length === 0);
+  if (inactive) return "inactive";
+  if (entry.sampledPodCount === 0) return hasHistory ? entry.history.stale ? "stale" : "no current" : "no data";
+  if (!hasHistory) return "warming";
+  if (entry.history.stale) return "stale";
+  if (entry.history.incomplete) return "partial";
+  return "healthy";
+}
+function abbreviatedK8sKind(kind) {
+  switch (kind) {
+    case "Deployment":
+      return "deploy";
+    case "StatefulSet":
+      return "sts";
+    case "DaemonSet":
+      return "ds";
+    case "CronJob":
+      return "cron";
+    case "ReplicaSet":
+      return "rs";
+    case "Job":
+      return "job";
+    case "Pod":
+      return "pod";
+  }
+}
+function renderK8sUsageReport(report) {
+  const freshness = report.metricsFreshAt ?? "unavailable";
+  const lines = [
+    `Window: ${report.window}  Collector: ${report.metricsStale ? "stale" : "current"}  Fresh: ${freshness}`,
+    "PODS counts pods with current metrics."
+  ];
+  if (report.entries.length === 0) return `${lines.join("\n")}
+No managed-vCluster workload containers found.
+`;
+  const headers = ["WORKLOAD", "CONTAINER", "PODS", "CPU NOW", "CPU MAX", "MEM NOW", "MEM MAX", "STATE"];
+  const grouped = /* @__PURE__ */ new Map();
+  for (const entry of report.entries) {
+    const entries = grouped.get(entry.workload.namespace) ?? [];
+    entries.push(entry);
+    grouped.set(entry.workload.namespace, entries);
+  }
+  for (const [namespace, entries] of grouped) {
+    const rows = entries.map((entry) => {
+      const state = getK8sUsageState(entry);
+      return [
+        `${abbreviatedK8sKind(entry.workload.kind)}/${entry.workload.name}`,
+        entry.container.name,
+        String(entry.sampledPodCount),
+        formatK8sCpu(entry.container.currentUsage.cpuNanoCores),
+        formatK8sCpu(entry.summary.cpuMaxNanoCores),
+        formatK8sMemory(entry.container.currentUsage.memoryBytes),
+        formatK8sMemory(entry.summary.memoryMaxBytes),
+        state === "healthy" ? "-" : state
+      ];
+    });
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+    const separator = widths.map((width) => "-".repeat(width)).join("  ");
+    lines.push("", `Namespace: ${namespace}`, formatRow(headers), separator, ...rows.map(formatRow));
+  }
+  return `${lines.join("\n")}
+`;
+}
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
@@ -1187,6 +1410,17 @@ function summarizeEnvData(data) {
     ])
   );
 }
+function parseGetEnvsArgs(args) {
+  let showValues = false;
+  for (const arg of args) {
+    if (arg === "--show-values") {
+      showValues = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown get envs flag: ${arg}` : `Unexpected get envs value: ${arg}`);
+  }
+  return { showValues };
+}
 function renderEnvSummary(data) {
   const lines = [];
   for (const [name, env] of Object.entries(data)) {
@@ -1195,6 +1429,24 @@ function renderEnvSummary(data) {
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
 }
+function renderEnvValues(data) {
+  const lines = Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => `${name}  ${env.value === null ? "<missing>" : JSON.stringify(env.value)}  ${env.description}`);
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "No environment variables declared.\n";
+}
+function getProjectEnvValue(data, name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid environment variable name: ${name}`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(data, name)) {
+    throw new Error(`Environment variable ${name} is not declared for this project`);
+  }
+  const value = data[name]?.value;
+  if (value === null || value === void 0) {
+    throw new Error(`Environment variable ${name} does not have a value`);
+  }
+  return value;
+}
 function renderEnvSetResult(result) {
   const lines = [`Updated ${result.updated.length} environment variable${result.updated.length === 1 ? "" : "s"} for ${result.project}.`];
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
@@ -1474,6 +1726,11 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "k8s" && second === "usage") {
+    const report = await collectK8sUsage(client, parseK8sUsageArgs(args.slice(2)));
+    write(report, renderK8sUsageReport(report));
+    return;
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -1545,11 +1802,25 @@ Sessions: ${result.sessions.length}
     return;
   }
   if (first === "get" && second === "envs") {
-    if (args.length !== 3) throw new Error(`Unexpected get envs argument: ${args[3] ?? ""}`.trim());
     const projectRef = requireValue(args[2], "Missing project reference");
+    const options = parseGetEnvsArgs(args.slice(3));
     const project = await client.projects.describe(projectRef);
-    const envs = summarizeEnvData(await client.projects.env.get(project.id));
-    write({ project: project.path, envs }, renderEnvSummary(envs));
+    const envs = await client.projects.env.get(project.id);
+    if (options.showValues) {
+      write({ project: project.path, envs }, renderEnvValues(envs));
+    } else {
+      const summary = summarizeEnvData(envs);
+      write({ project: project.path, envs: summary }, renderEnvSummary(summary));
+    }
+    return;
+  }
+  if (first === "get" && second === "env") {
+    if (args.length > 4) throw new Error(`Unexpected get env argument: ${args[4]}`);
+    const projectRef = requireValue(args[2], "Missing project reference");
+    const name = requireValue(args[3], "Missing environment variable name");
+    const project = await client.projects.describe(projectRef);
+    const value = getProjectEnvValue(await client.projects.env.get(project.id), name);
+    write({ project: project.path, name, value }, value);
     return;
   }
   if (first === "set" && second === "envs") {
@@ -1722,6 +1993,12 @@ function resolveCommandExecution(options, rest) {
       text: PS_HELP_TEXT
     };
   }
+  if (command === "k8s" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: K8S_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1850,6 +2127,15 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
   }
+  if (command === "k8s") {
+    const subcommand = commandArgs[0];
+    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+    }
+    parseK8sUsageArgs(commandArgs.slice(1));
+    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1887,9 +2173,29 @@ function resolveCommandExecution(options, rest) {
       if (options.branch) {
         throw new Error("--branch/-b is not supported for project environment variables");
       }
+      parseGetEnvsArgs(commandArgs.slice(1));
+      return {
+        kind: "plugin",
+        pluginArgs: ["get", "envs", options.project, ...commandArgs.slice(1)]
+      };
+    }
+    if (target === "env") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `get env`");
+      }
+      if (options.branch) {
+        throw new Error("--branch/-b is not supported for project environment variables");
+      }
+      const name = requireValue(commandArgs[1], "Environment variable name is required for `get env`");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected get env argument: ${commandArgs[2]}`);
+      }
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid environment variable name: ${name}`);
+      }
       return {
         kind: "plugin",
-        pluginArgs: ["get", "envs", options.project]
+        pluginArgs: ["get", "env", options.project, name]
       };
     }
     throw new Error("Unknown get command");
@@ -2278,8 +2584,13 @@ async function main(argv = process.argv.slice(2)) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  collectK8sUsage,
+  formatK8sCpu,
+  formatK8sMemory,
   formatProcessAge,
   getCliHelpText,
+  getK8sUsageState,
+  getProjectEnvValue,
   getR5dctlVersion,
   main,
   parseAnswerFlags,
@@ -2287,7 +2598,9 @@ async function main(argv = process.argv.slice(2)) {
   parseConversationWorkDetailArgs,
   parseEnvFlags,
   parseEnvRequestResponseArgs,
+  parseGetEnvsArgs,
   parseGlobalArgs,
+  parseK8sUsageArgs,
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
@@ -2298,6 +2611,8 @@ async function main(argv = process.argv.slice(2)) {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderEnvValues,
+  renderK8sUsageReport,
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -69,6 +69,13 @@ const PS_HELP_TEXT = [
   "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
+const K8S_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+  "",
+  "Show current and rolling CPU and memory usage for managed-vCluster workload containers.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -98,8 +105,13 @@ const SHARED_HELP_ENTRIES = [
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
   {
     section: "envs",
-    usage: "-p <project> get envs",
-    description: "List declared envs and whether each has a value, without revealing values."
+    usage: "-p <project> get envs [--show-values]",
+    description: "List declared envs; use --show-values to reveal their values."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> get env <name>",
+    description: "Write one env value exactly to stdout for command substitution or piping."
   },
   {
     section: "envs",
@@ -164,6 +176,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "-s <session-id> answer-env-request [-e KEY=value] [--context <text>]",
     description: "Answer a pending environment variable request with values, context, or both."
   },
+  {
+    section: "kubernetes",
+    usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+    description: "Show current and rolling CPU and memory usage for managed-vCluster workload containers."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -202,6 +219,7 @@ const HELP_SECTION_ORDER = [
   "branches",
   "envs",
   "sessions",
+  "kubernetes",
   "processes",
   "shell",
   "agents",
@@ -214,6 +232,7 @@ const HELP_SECTION_TITLES = {
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  kubernetes: "Kubernetes",
   processes: "Processes",
   shell: "Shell",
   agents: "Agents",
@@ -878,6 +897,36 @@ function parseRecentSessionArgs(args) {
   if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error("--limit must be an integer between 1 and 200");
   return { limit };
 }
+function parseK8sUsageArgs(args) {
+  const parsed = { window: "24h" };
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const option = ["--namespace", "--workload", "--container", "--window"].find(
+      (candidate) => arg === candidate || arg.startsWith(`${candidate}=`)
+    );
+    if (!option) throw new Error(`Unknown k8s usage argument: ${arg}`);
+    if (seen.has(option)) throw new Error(`Use ${option} only once`);
+    seen.add(option);
+    const inlineValue = parseLongOptionWithEquals(arg, option);
+    const candidateValue = inlineValue ?? args[index + 1];
+    if (!candidateValue || candidateValue.startsWith("--")) throw new Error(`Missing value for ${option}`);
+    const value = candidateValue;
+    if (inlineValue === void 0) index += 1;
+    if (option === "--window") {
+      if (value !== "24h" && value !== "7d") throw new Error("--window must be 24h or 7d");
+      parsed.window = value;
+    } else if (option === "--namespace") {
+      parsed.namespace = value;
+    } else if (option === "--workload") {
+      parsed.workload = value;
+    } else {
+      parsed.container = value;
+    }
+  }
+  return parsed;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1039,6 +1088,171 @@ Error: ${result.error}` : "";
   return `Workspace sync ${result.outcome} on ${result.workerLabel}; HEAD ${head}; ${result.diffSizeBytes} bytes.${discarded}${error}
 `;
 }
+function summarizeK8sHistory(history) {
+  if (history.envelope.length === 0) {
+    return {
+      cpuMinNanoCores: null,
+      cpuMaxNanoCores: null,
+      memoryMinBytes: null,
+      memoryMaxBytes: null,
+      sampleCount: 0
+    };
+  }
+  return {
+    cpuMinNanoCores: Math.min(...history.envelope.map((point) => point.cpuMinNanoCores)),
+    cpuMaxNanoCores: Math.max(...history.envelope.map((point) => point.cpuMaxNanoCores)),
+    memoryMinBytes: Math.min(...history.envelope.map((point) => point.memoryMinBytes)),
+    memoryMaxBytes: Math.max(...history.envelope.map((point) => point.memoryMaxBytes)),
+    sampleCount: history.envelope.reduce((total, point) => total + point.sampleCount, 0)
+  };
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (nextIndex < items.length) {
+        const index = nextIndex++;
+        const item = items[index];
+        if (item !== void 0) results[index] = await fn(item);
+      }
+    })
+  );
+  return results;
+}
+async function collectK8sUsage(client, options) {
+  const resources = await client.k8s.resources();
+  const candidates = resources.workloads.flatMap((workload) => workload.containers.map((container) => ({ workload, container }))).filter(({ workload, container }) => {
+    const workloadMatches = !options.workload || options.workload === workload.name || options.workload === `${workload.namespace}/${workload.name}` || options.workload === workload.uid;
+    return (!options.namespace || options.namespace === workload.namespace) && workloadMatches && (!options.container || options.container === container.name);
+  }).sort(
+    (left, right) => left.workload.namespace.localeCompare(right.workload.namespace) || left.workload.name.localeCompare(right.workload.name) || left.container.name.localeCompare(right.container.name)
+  );
+  if (candidates.length === 0 && (options.namespace || options.workload || options.container)) {
+    throw new Error("No managed-vCluster workload containers matched the requested filters");
+  }
+  const entries = await mapWithConcurrency(candidates, 8, async ({ workload, container }) => {
+    const history = await client.k8s.resourceHistory({ workloadUid: workload.uid, containerName: container.name, window: options.window });
+    return {
+      workload: {
+        uid: workload.uid,
+        kind: workload.kind,
+        namespace: workload.namespace,
+        name: workload.name,
+        replicas: workload.replicas,
+        readyReplicas: workload.readyReplicas
+      },
+      container: {
+        name: container.name,
+        currentUsage: container.currentUsage,
+        pods: container.pods
+      },
+      sampledPodCount: container.pods.filter((pod) => pod.cpuNanoCores !== null || pod.memoryBytes !== null).length,
+      summary: summarizeK8sHistory(history),
+      history
+    };
+  });
+  return {
+    window: options.window,
+    collectedAt: resources.collectedAt,
+    metricsFreshAt: resources.metricsFreshAt,
+    metricsStale: resources.metricsStale,
+    filters: {
+      namespace: options.namespace,
+      workload: options.workload,
+      container: options.container
+    },
+    entries
+  };
+}
+function formatDecimal(value) {
+  if (value >= 100) return value.toFixed(0);
+  if (value >= 10) return value.toFixed(1).replace(/\.0$/, "");
+  return value.toFixed(2).replace(/\.0+$/, "").replace(/(\.\d)0$/, "$1");
+}
+function formatK8sCpu(value) {
+  if (value === null) return "-";
+  const milliCores = value / 1e6;
+  return `${formatDecimal(milliCores)}m`;
+}
+function formatK8sMemory(value) {
+  if (value === null) return "-";
+  const units = ["B", "Ki", "Mi", "Gi", "Ti"];
+  let amount = value;
+  let unitIndex = 0;
+  while (amount >= 1024 && unitIndex < units.length - 1) {
+    amount /= 1024;
+    unitIndex += 1;
+  }
+  return `${formatDecimal(amount)}${units[unitIndex]}`;
+}
+function getK8sUsageState(entry) {
+  const hasHistory = entry.history.envelope.length > 0;
+  const terminalPods = entry.container.pods.filter((pod) => pod.phase === "Succeeded" || pod.phase === "Failed").length;
+  const inactive = entry.sampledPodCount === 0 && (entry.workload.replicas === 0 || entry.container.pods.length > 0 && terminalPods === entry.container.pods.length || entry.workload.kind === "CronJob" && entry.container.pods.length === 0);
+  if (inactive) return "inactive";
+  if (entry.sampledPodCount === 0) return hasHistory ? entry.history.stale ? "stale" : "no current" : "no data";
+  if (!hasHistory) return "warming";
+  if (entry.history.stale) return "stale";
+  if (entry.history.incomplete) return "partial";
+  return "healthy";
+}
+function abbreviatedK8sKind(kind) {
+  switch (kind) {
+    case "Deployment":
+      return "deploy";
+    case "StatefulSet":
+      return "sts";
+    case "DaemonSet":
+      return "ds";
+    case "CronJob":
+      return "cron";
+    case "ReplicaSet":
+      return "rs";
+    case "Job":
+      return "job";
+    case "Pod":
+      return "pod";
+  }
+}
+function renderK8sUsageReport(report) {
+  const freshness = report.metricsFreshAt ?? "unavailable";
+  const lines = [
+    `Window: ${report.window}  Collector: ${report.metricsStale ? "stale" : "current"}  Fresh: ${freshness}`,
+    "PODS counts pods with current metrics."
+  ];
+  if (report.entries.length === 0) return `${lines.join("\n")}
+No managed-vCluster workload containers found.
+`;
+  const headers = ["WORKLOAD", "CONTAINER", "PODS", "CPU NOW", "CPU MAX", "MEM NOW", "MEM MAX", "STATE"];
+  const grouped = /* @__PURE__ */ new Map();
+  for (const entry of report.entries) {
+    const entries = grouped.get(entry.workload.namespace) ?? [];
+    entries.push(entry);
+    grouped.set(entry.workload.namespace, entries);
+  }
+  for (const [namespace, entries] of grouped) {
+    const rows = entries.map((entry) => {
+      const state = getK8sUsageState(entry);
+      return [
+        `${abbreviatedK8sKind(entry.workload.kind)}/${entry.workload.name}`,
+        entry.container.name,
+        String(entry.sampledPodCount),
+        formatK8sCpu(entry.container.currentUsage.cpuNanoCores),
+        formatK8sCpu(entry.summary.cpuMaxNanoCores),
+        formatK8sMemory(entry.container.currentUsage.memoryBytes),
+        formatK8sMemory(entry.summary.memoryMaxBytes),
+        state === "healthy" ? "-" : state
+      ];
+    });
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+    const separator = widths.map((width) => "-".repeat(width)).join("  ");
+    lines.push("", `Namespace: ${namespace}`, formatRow(headers), separator, ...rows.map(formatRow));
+  }
+  return `${lines.join("\n")}
+`;
+}
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
@@ -1130,6 +1344,17 @@ function summarizeEnvData(data) {
     ])
   );
 }
+function parseGetEnvsArgs(args) {
+  let showValues = false;
+  for (const arg of args) {
+    if (arg === "--show-values") {
+      showValues = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown get envs flag: ${arg}` : `Unexpected get envs value: ${arg}`);
+  }
+  return { showValues };
+}
 function renderEnvSummary(data) {
   const lines = [];
   for (const [name, env] of Object.entries(data)) {
@@ -1138,6 +1363,24 @@ function renderEnvSummary(data) {
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
 }
+function renderEnvValues(data) {
+  const lines = Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => `${name}  ${env.value === null ? "<missing>" : JSON.stringify(env.value)}  ${env.description}`);
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "No environment variables declared.\n";
+}
+function getProjectEnvValue(data, name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid environment variable name: ${name}`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(data, name)) {
+    throw new Error(`Environment variable ${name} is not declared for this project`);
+  }
+  const value = data[name]?.value;
+  if (value === null || value === void 0) {
+    throw new Error(`Environment variable ${name} does not have a value`);
+  }
+  return value;
+}
 function renderEnvSetResult(result) {
   const lines = [`Updated ${result.updated.length} environment variable${result.updated.length === 1 ? "" : "s"} for ${result.project}.`];
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
@@ -1417,6 +1660,11 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "k8s" && second === "usage") {
+    const report = await collectK8sUsage(client, parseK8sUsageArgs(args.slice(2)));
+    write(report, renderK8sUsageReport(report));
+    return;
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -1488,11 +1736,25 @@ Sessions: ${result.sessions.length}
     return;
   }
   if (first === "get" && second === "envs") {
-    if (args.length !== 3) throw new Error(`Unexpected get envs argument: ${args[3] ?? ""}`.trim());
     const projectRef = requireValue(args[2], "Missing project reference");
+    const options = parseGetEnvsArgs(args.slice(3));
     const project = await client.projects.describe(projectRef);
-    const envs = summarizeEnvData(await client.projects.env.get(project.id));
-    write({ project: project.path, envs }, renderEnvSummary(envs));
+    const envs = await client.projects.env.get(project.id);
+    if (options.showValues) {
+      write({ project: project.path, envs }, renderEnvValues(envs));
+    } else {
+      const summary = summarizeEnvData(envs);
+      write({ project: project.path, envs: summary }, renderEnvSummary(summary));
+    }
+    return;
+  }
+  if (first === "get" && second === "env") {
+    if (args.length > 4) throw new Error(`Unexpected get env argument: ${args[4]}`);
+    const projectRef = requireValue(args[2], "Missing project reference");
+    const name = requireValue(args[3], "Missing environment variable name");
+    const project = await client.projects.describe(projectRef);
+    const value = getProjectEnvValue(await client.projects.env.get(project.id), name);
+    write({ project: project.path, name, value }, value);
     return;
   }
   if (first === "set" && second === "envs") {
@@ -1665,6 +1927,12 @@ function resolveCommandExecution(options, rest) {
       text: PS_HELP_TEXT
     };
   }
+  if (command === "k8s" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: K8S_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1793,6 +2061,15 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
   }
+  if (command === "k8s") {
+    const subcommand = commandArgs[0];
+    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+    }
+    parseK8sUsageArgs(commandArgs.slice(1));
+    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1830,9 +2107,29 @@ function resolveCommandExecution(options, rest) {
       if (options.branch) {
         throw new Error("--branch/-b is not supported for project environment variables");
       }
+      parseGetEnvsArgs(commandArgs.slice(1));
+      return {
+        kind: "plugin",
+        pluginArgs: ["get", "envs", options.project, ...commandArgs.slice(1)]
+      };
+    }
+    if (target === "env") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `get env`");
+      }
+      if (options.branch) {
+        throw new Error("--branch/-b is not supported for project environment variables");
+      }
+      const name = requireValue(commandArgs[1], "Environment variable name is required for `get env`");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected get env argument: ${commandArgs[2]}`);
+      }
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid environment variable name: ${name}`);
+      }
       return {
         kind: "plugin",
-        pluginArgs: ["get", "envs", options.project]
+        pluginArgs: ["get", "env", options.project, name]
       };
     }
     throw new Error("Unknown get command");
@@ -2220,8 +2517,13 @@ async function main(argv = process.argv.slice(2)) {
   }
 }
 export {
+  collectK8sUsage,
+  formatK8sCpu,
+  formatK8sMemory,
   formatProcessAge,
   getCliHelpText,
+  getK8sUsageState,
+  getProjectEnvValue,
   getR5dctlVersion,
   main,
   parseAnswerFlags,
@@ -2229,7 +2531,9 @@ export {
   parseConversationWorkDetailArgs,
   parseEnvFlags,
   parseEnvRequestResponseArgs,
+  parseGetEnvsArgs,
   parseGlobalArgs,
+  parseK8sUsageArgs,
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
@@ -2240,6 +2544,8 @@ export {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderEnvValues,
+  renderK8sUsageReport,
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessRun, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { R5dctlClient, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessRun, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -65,8 +65,50 @@ export declare function parseShellArgs(args: string[]): {
 };
 export declare function parsePsListArgs(args: string[]): R5dctlProcessListInput;
 export declare function parsePsHistoryArgs(args: string[]): R5dctlProcessListInput;
+export type K8sUsageOptions = {
+    namespace?: string;
+    workload?: string;
+    container?: string;
+    window: "24h" | "7d";
+};
+export declare function parseK8sUsageArgs(args: string[]): K8sUsageOptions;
 export declare function renderWorkspaceStatus(status: R5dctlWorkspaceStatus): string;
 export declare function renderWorkspaceSync(result: R5dctlWorkspaceSyncResult): string;
+export type K8sUsageSummary = {
+    cpuMinNanoCores: number | null;
+    cpuMaxNanoCores: number | null;
+    memoryMinBytes: number | null;
+    memoryMaxBytes: number | null;
+    sampleCount: number;
+};
+export type K8sUsageReport = {
+    window: "24h" | "7d";
+    collectedAt: string;
+    metricsFreshAt: string | null;
+    metricsStale: boolean;
+    filters: Omit<K8sUsageOptions, "window">;
+    entries: Array<{
+        workload: Pick<R5dctlK8sWorkload, "uid" | "kind" | "namespace" | "name" | "replicas" | "readyReplicas">;
+        container: {
+            name: string;
+            currentUsage: R5dctlK8sUsage;
+            pods: Array<R5dctlK8sUsage & {
+                podUid: string;
+                podName: string;
+                phase: string | null;
+            }>;
+        };
+        sampledPodCount: number;
+        summary: K8sUsageSummary;
+        history: R5dctlK8sResourceHistory;
+    }>;
+};
+export declare function collectK8sUsage(client: Pick<R5dctlClient, "k8s">, options: K8sUsageOptions): Promise<K8sUsageReport>;
+export declare function formatK8sCpu(value: number | null): string;
+export declare function formatK8sMemory(value: number | null): string;
+export type K8sUsageState = "healthy" | "partial" | "stale" | "inactive" | "warming" | "no data" | "no current";
+export declare function getK8sUsageState(entry: K8sUsageReport["entries"][number]): K8sUsageState;
+export declare function renderK8sUsageReport(report: K8sUsageReport): string;
 export declare function formatProcessAge(startedAt: string, nowMs?: number): string;
 export declare function renderProcessList(processes: R5dctlProcessRun[], nowMs?: number): string;
 export declare function renderProcessHistory(processes: R5dctlProcessRun[], nowMs?: number): string;
@@ -76,6 +118,11 @@ export type EnvSummaryData = Record<string, {
     hasValue: boolean;
 }>;
 export declare function summarizeEnvData(data: R5dctlEnvData): EnvSummaryData;
+export declare function parseGetEnvsArgs(args: string[]): {
+    showValues: boolean;
+};
+export declare function renderEnvValues(data: R5dctlEnvData): string;
+export declare function getProjectEnvValue(data: R5dctlEnvData, name: string): string;
 export declare function parseConversationRenderArgs(args: string[]): ConversationRenderOptions;
 export declare function renderConversationResponse(read: R5dctlConversationResponse): string;
 export declare function parseConversationWorkDetailArgs(args: string[]): R5dctlConversationWorkDetail;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,7 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.49",
+    "@ricsam/r5d-api": "^0.0.51",
     "dotenv": "^17",
     "ws": "^8.18.3"
   },