@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/cli/admin/ai-quotas.ts

@@ -0,0 +1,161 @@
+import { AiModelPricingSchema, type AiModelPricing } from "../../shared/ai-costs";
+import {
+  AiQuotaConfigSchema,
+  AiQuotaReportQuerySchema,
+  AiQuotaIdentitySchema,
+  AiQuotaResetSchema,
+  type AiQuotaConfig,
+  type AiQuotaIdentity,
+} from "../../shared/ai-quotas";
+import { cliText, command, confirmFlag, flag, printRows, printStructured, type CloudCliContext } from "../index";
+import { apiGet, apiJson, queryString, readJsonInput } from "./shared";
+
+const path = "/api/admin/core/ai-quotas";
+const identity = {
+  type: flag.enum(["user", "service_account"] as const, { default: "user", description: "Identity type" }),
+  id: flag.string({ required: true, description: "Identity UUID from users" }),
+};
+const print = (ctx: CloudCliContext, value: unknown) => {
+  if (!printStructured(ctx, value)) ctx.print(JSON.stringify(value, null, 2));
+};
+const confirm = (ctx: CloudCliContext, yes: boolean) => {
+  if (!yes) throw new Error(cliText(ctx, { en: "Quota changes require --yes.", de: "Kontingentänderungen erfordern --yes." }));
+};
+
+export const aiQuotaCommands = [
+  command("ai models pricing get", {
+    summary: "List configured model input/output reference prices per million tokens",
+    async run({ ctx }) {
+      print(ctx, await apiGet(ctx, `${path}/models`));
+    },
+  }),
+  command("ai models pricing set", {
+    summary: "Set one model's reference prices; JSON null removes prices and makes it unlimited",
+    flags: {
+      id: flag.string({ required: true, description: "Model profile ID" }),
+      pricing: flag.input({
+        required: true,
+        description: "{inputPerMillion,outputPerMillion} or null: --pricing, --pricing-file or --stdin",
+      }),
+      yes: confirmFlag("Confirm model price change"),
+    },
+    async run({ ctx, flags }) {
+      confirm(ctx, flags.yes);
+      const pricing = AiModelPricingSchema.nullable().parse(await readJsonInput<unknown>(flags.pricing, "model pricing"));
+      const current = await apiGet<{ models: { id: string; pricing?: AiModelPricing }[] }>(ctx, `${path}/models`);
+      const model = current.models.find((model) => model.id === flags.id);
+      if (!model) throw new Error("Model not found.");
+      print(
+        ctx,
+        await apiJson(ctx, "PUT", `${path}/models/${encodeURIComponent(flags.id!)}/pricing`, { pricing, expected: model.pricing ?? null }),
+      );
+    },
+  }),
+  command("ai quotas background status", {
+    summary: "Show rolling 24-hour background costs and emergency-stop state",
+    async run({ ctx }) {
+      print(ctx, await apiGet(ctx, `${path}/background`));
+    },
+  }),
+  command("ai quotas background release", {
+    summary: "Release the background emergency stop after reviewing costs",
+    flags: { yes: confirmFlag("Confirm release of the background AI emergency stop") },
+    async run({ ctx, flags }) {
+      confirm(ctx, flags.yes);
+      print(ctx, await apiJson(ctx, "POST", `${path}/background/release`, {}));
+    },
+  }),
+  command("ai quotas config get", {
+    summary: "Export Assistant limits, rules and revision (platform admin)",
+    async run({ ctx }) {
+      print(ctx, await apiGet<AiQuotaConfig>(ctx, path));
+    },
+  }),
+  command("ai quotas config set", {
+    summary: "Replace Assistant quota configuration using its current revision",
+    flags: {
+      config: flag.input({ required: true, description: "Complete configuration JSON: --config, --config-file or --stdin" }),
+      yes: confirmFlag("Confirm replacement of Assistant quota configuration"),
+    },
+    async run({ ctx, flags }) {
+      confirm(ctx, flags.yes);
+      const config = AiQuotaConfigSchema.parse(await readJsonInput<unknown>(flags.config, "quota configuration"));
+      print(ctx, await apiJson<AiQuotaConfig>(ctx, "PUT", path, config));
+    },
+  }),
+  command("ai quotas models", {
+    summary: "List configured model profiles; only priced chat models support cost rules",
+    async run({ ctx }) {
+      const result = await apiGet<{ models: { id: string; label: string; pricing?: AiModelPricing }[] }>(ctx, `${path}/models`);
+      printRows(
+        ctx,
+        result,
+        result.models.map((model) => ({ ...model, pricing: model.pricing ? JSON.stringify(model.pricing) : "unpriced" })),
+        [{ key: "id" }, { key: "label" }, { key: "pricing" }],
+      );
+    },
+  }),
+  command("ai quotas report", {
+    summary: "Report chat costs and current allowances with the same filters as the admin page",
+    flags: {
+      range: flag.enum(["24h", "7d", "30d", "90d"] as const, { default: "30d" }),
+      until: flag.string({ description: "ISO period end; reuse query.until for consistent pagination" }),
+      search: flag.string({ description: "Search identity labels" }),
+      model: flag.string({ description: "Model profile ID" }),
+      status: flag.enum(["all", "available", "exhausted", "unknown", "unlimited", "disabled"] as const, { default: "all" }),
+      sort: flag.enum(["label", "cost", "lastUsed"] as const, { default: "lastUsed" }),
+      direction: flag.enum(["asc", "desc"] as const, { default: "desc" }),
+      page: flag.int({ min: 1, max: 1_000_000, default: 1 }),
+      identity: flag.string({ description: "Optional selected identity UUID" }),
+      identityType: flag.enum(["user", "service_account"] as const, { default: "user" }),
+    },
+    async run({ ctx, flags }) {
+      const query = AiQuotaReportQuerySchema.parse(flags);
+      print(ctx, await apiGet(ctx, `${path}/report${queryString(query)}`));
+    },
+  }),
+  command("ai quotas users", {
+    summary: "List chat users; search also finds identities without prior usage",
+    flags: {
+      search: flag.string({ description: "Search identity labels" }),
+      page: flag.int({ min: 1, default: 1 }),
+    },
+    async run({ ctx, flags }) {
+      const result = await apiGet<{ items: AiQuotaIdentity[]; total: number; page: number; perPage: number }>(
+        ctx,
+        `${path}/users${queryString(flags)}`,
+      );
+      printRows(ctx, result, result.items, [{ key: "id" }, { key: "type" }, { key: "label" }, { key: "lastUsed" }]);
+      if (ctx.options.output === "text")
+        ctx.print(
+          cliText(ctx, {
+            en: `Page ${result.page}; ${result.total} identities.`,
+            de: `Seite ${result.page}; ${result.total} Identitäten.`,
+          }),
+        );
+    },
+  }),
+  command("ai quotas balance", {
+    summary: "Show one identity's effective limits, usage and reset times",
+    flags: identity,
+    async run({ ctx, flags }) {
+      const subject = AiQuotaIdentitySchema.parse(flags);
+      print(ctx, await apiGet(ctx, `${path}/balance${queryString(subject)}`));
+    },
+  }),
+  command("ai quotas reset", {
+    summary: "Reset one identity and quota scope; reuse request ID when retrying",
+    flags: {
+      ...identity,
+      scope: flag.string({ required: true, description: "Model profile ID or * (quote the wildcard)" }),
+      requestId: flag.string({ required: true, description: "UUID for this reset; reuse for retries, use a new UUID for a new reset" }),
+      yes: confirmFlag("Confirm reset of this identity and quota scope"),
+    },
+    async run({ ctx, flags }) {
+      confirm(ctx, flags.yes);
+      const { yes: _yes, ...input } = flags;
+      const reset = AiQuotaResetSchema.parse(input);
+      print(ctx, await apiJson(ctx, "POST", `${path}/reset`, reset));
+    },
+  }),
+];

package/src/cli/admin/ai-skills.ts

@@ -0,0 +1,64 @@
+import type { AiSkillAdminListItem } from "../../ai/skills";
+import { arg, command, confirmFlag, flag, printRows, printStructured } from "../index";
+import { apiGet, apiJson, queryString } from "./shared";
+
+export const aiSkillCommands = [
+  command("ai skills list", {
+    summary: "List all Skills with template origin, version, status, and revision (platform admin)",
+    flags: {
+      search: flag.string(),
+      page: flag.int({ min: 1, default: 1 }),
+      perPage: flag.int({ name: "per-page", min: 1, max: 500, default: 100 }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await apiGet<{ items: AiSkillAdminListItem[]; total: number; page: number; perPage: number }>(
+        ctx,
+        `/api/admin/core/ai-skills${queryString(flags)}`,
+      );
+      printRows(ctx, result, result.items, [
+        { key: "shortId" },
+        { key: "name" },
+        { key: "revision" },
+        { key: "templateId" },
+        { key: "templateVersion" },
+        { key: "currentTemplateVersion" },
+        { key: "templateStatus" },
+      ]);
+    },
+  }),
+  command("ai skills templates", {
+    summary: "List current trusted Skill template IDs and versions",
+    run: async ({ ctx }) => {
+      const result = await apiGet<{ templates: { templateId: string; name: string; version: number }[] }>(
+        ctx,
+        "/api/admin/core/ai-skills/templates",
+      );
+      printRows(ctx, result, result.templates, [{ key: "templateId" }, { key: "name" }, { key: "version" }]);
+    },
+  }),
+  ...(["associate", "reset"] as const).map((mode) =>
+    command(`ai skills ${mode}`, {
+      summary:
+        mode === "associate"
+          ? "Associate an existing Skill with a template, preserving all content"
+          : "Replace all linked Skill content and references with the current template",
+      args: { skillId: arg.required() },
+      flags: {
+        templateId: flag.string({ name: "template", required: true }),
+        templateVersion: flag.int({ name: "template-version", required: true, min: 1 }),
+        expectedRevision: flag.int({ name: "revision", required: true, min: 1 }),
+        yes: confirmFlag("Confirm the exact Skill and template; export customized content before resetting"),
+      },
+      run: async ({ ctx, args, flags }) => {
+        if (!flags.yes) throw new Error("Review the Skill and template first, then confirm with --yes.");
+        const { yes: _yes, ...input } = flags;
+        const result = await apiJson(ctx, "POST", `/api/admin/core/ai-skills/${encodeURIComponent(args.skillId)}/template`, {
+          ...input,
+          mode,
+          confirmed: true,
+        });
+        if (!printStructured(ctx, result)) ctx.print("Skill template updated.");
+      },
+    }),
+  ),
+];

package/src/cli/admin/ai-usage.ts

@@ -1,25 +1,29 @@
+import type { AiUsageReport, AiUsageRun } from "../../ai/usage";
+import { AI_USAGE_RANGES, AI_USAGE_REASONS } from "../../shared/ai-usage";
 import { arg, command, flag } from "../index";
 import { apiGet, printJsonOrTable } from "./shared";
-import { AI_USAGE_RANGES, AI_USAGE_REASONS } from "../../shared/ai-usage";
-import type { AiUsageReport, AiUsageRun } from "../../ai/usage";
+
 const filters = {
   range: flag.enum(AI_USAGE_RANGES, { default: "30d", description: "Response/run period" }),
   until: flag.string({ description: "Fixed ISO end time; reuse report.query.until across pages" }),
   userId: flag.string({ name: "user", description: "User UUID or unassigned" }),
   modelProfileId: flag.string({ name: "model", description: "Model profile ID" }),
   providerModel: flag.string({ name: "provider-model", description: "Actual provider model" }),
+  workflowId: flag.string({ name: "workflow", description: "Workflow definition UUID" }),
+  workflowRunId: flag.string({ name: "workflow-run", description: "Workflow run UUID" }),
   appId: flag.string({ name: "app", description: "Source application ID" }),
-  kind: flag.enum(["chat", "background", "tool"] as const, { description: "Run kind (runs only)" }),
+  kind: flag.enum(["chat", "background"] as const, { description: "Run kind (runs only)" }),
   status: flag.string({ description: "Run status, e.g. failed (runs only)" }),
-  task: flag.string({ description: "Exact task or tool name (runs only)" }),
+  task: flag.string({ description: "Exact background task name (runs only)" }),
   errorCode: flag.string({ name: "error-code", description: "Stored error code (runs only)" }),
   search: flag.string({ description: "Search task and error text (runs/facets only)" }),
   rating: flag.enum(["up", "down"] as const, { description: "Rating (feedback only)" }),
   reason: flag.enum(AI_USAGE_REASONS, { description: "Feedback reason (feedback only)" }),
-  sort: flag.enum(["runs", "tokens", "credits", "errors", "negative", "negativeRate"] as const, {
+  sort: flag.enum(["runs", "tokens", "cost", "errors", "negative", "negativeRate"] as const, {
     default: "runs",
     description: "Comparison sort order",
   }),
+  direction: flag.enum(["asc", "desc"] as const, { default: "desc", description: "Comparison sort direction" }),
   page: flag.int({ default: 1, min: 1 }),
   perPage: flag.int({ name: "per-page", default: 50, min: 1, max: 100 }),
 };
@@ -30,7 +34,7 @@ const params = (values: Record<string, string | number | undefined>) => {
   return q;
 };
 export const aiUsageCommands = [
-  ...(["report", "users", "models", "tasks", "apps", "launches", "capabilities", "feedback", "runs"] as const).map((section) =>
+  ...(["report", "users", "models", "tasks", "apps", "workflows", "launches", "feedback", "runs"] as const).map((section) =>
     command(`ai usage ${section}`, {
       summary:
         section === "report"
@@ -44,25 +48,39 @@ export const aiUsageCommands = [
           return printJsonOrTable(
             ctx,
             report,
-            [report.overview],
-            [{ key: "runs" }, { key: "tokens" }, { key: "credits" }, { key: "failed" }, { key: "positive" }, { key: "negative" }],
+            [{ ...report.overview, unit: report.unit }],
+            [
+              { key: "runs" },
+              { key: "tokens" },
+              { key: "cost" },
+              { key: "unit" },
+              { key: "failed" },
+              { key: "positive" },
+              { key: "negative" },
+            ],
           );
         const page = report[section];
         if (ctx.options.output === "jsonl") {
-          for (const item of page.items) ctx.jsonLine(item);
+          for (const item of page.items) ctx.jsonLine({ ...item, unit: report.unit });
           return;
         }
-        if (ctx.options.output === "json") return ctx.json({ ...page, query: report.query, since: report.since, until: report.until });
+        if (ctx.options.output === "json")
+          return ctx.json({ ...page, query: report.query, since: report.since, until: report.until, unit: report.unit });
         if (section === "runs")
-          ctx.table(report.runs.items, [
-            { key: "id" },
-            { key: "kind" },
-            { key: "task" },
-            { key: "status" },
-            { key: "userLabel" },
-            { key: "modelProfileId" },
-            { key: "error" },
-          ]);
+          ctx.table(
+            report.runs.items.map((row) => ({ ...row, unit: report.unit })),
+            [
+              { key: "id" },
+              { key: "kind" },
+              { key: "task" },
+              { key: "status" },
+              { key: "userLabel" },
+              { key: "modelProfileId" },
+              { key: "cost" },
+              { key: "unit" },
+              { key: "error" },
+            ],
+          );
         else if (section === "feedback")
           ctx.table(report.feedback.items, [
             { key: "id" },
@@ -73,17 +91,22 @@ export const aiUsageCommands = [
           ]);
         else if (section === "launches") ctx.table(report.launches.items, [{ key: "appId" }, { key: "chats" }, { key: "users" }]);
         else
-          ctx.table(report[section].items, [
-            { key: "id" },
-            { key: "label" },
-            { key: "providerModel" },
-            { key: "runs" },
-            { key: "tokens" },
-            { key: "failed" },
-            { key: "positive" },
-            { key: "negative" },
-            { key: "rated" },
-          ]);
+          ctx.table(
+            report[section].items.map((row) => ({ ...row, unit: report.unit })),
+            [
+              { key: "id" },
+              { key: "label" },
+              { key: "providerModel" },
+              { key: "runs" },
+              { key: "tokens" },
+              { key: "cost" },
+              { key: "unit" },
+              { key: "failed" },
+              { key: "positive" },
+              { key: "negative" },
+              { key: "rated" },
+            ],
+          );
         ctx.print(`Page ${page.page}; ${page.total} total. Snapshot until ${report.until}`);
       },
     }),

package/src/cli/admin/app-credentials.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { arg, cliText, command, confirmFlag, flag, printStructured } from "../index";
+import { apiGet, apiJson } from "./shared";
+
+const root = "/api/admin/identity/workloads";
+const path = (appId: string) => `${root}/${encodeURIComponent(appId)}/credentials`;
+const metadata = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: z.string(),
+  tokenPrefix: z.string(),
+  expiresAt: z.string().nullable(),
+});
+
+export const appCredentialCommands = [
+  command("app-credentials apps", {
+    summary: "List registered applications for workload credentials",
+    async run({ ctx }) {
+      const apps = z.array(z.object({ id: z.string(), name: z.string() })).parse(await apiGet(ctx, root));
+      if (!printStructured(ctx, apps))
+        ctx.table(apps, [
+          { key: "id", label: "App" },
+          { key: "name", label: "Name" },
+        ]);
+    },
+  }),
+  command("app-credentials list", {
+    summary: "List one app's credential metadata without secrets",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: { page: flag.int({ min: 1, default: 1 }), perPage: flag.int({ min: 1, max: 500, default: 20 }) },
+    async run({ ctx, args, flags }) {
+      const listing = z
+        .object({ items: z.array(metadata), page: z.number(), perPage: z.number(), total: z.number(), hasNext: z.boolean() })
+        .parse(await apiGet(ctx, `${path(args.app)}?page=${flags.page}&perPage=${flags.perPage}`));
+      if (!printStructured(ctx, listing))
+        ctx.table(listing.items, [
+          { key: "id", label: "ID" },
+          { key: "name", label: "Name" },
+          { key: "status", label: "Status" },
+          { key: "expiresAt", label: "Expires" },
+        ]);
+    },
+  }),
+  command("app-credentials create", {
+    summary: "Create an app credential; returns the token once (store stdout securely)",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: {
+      name: flag.string({ required: true }),
+      expiresAt: flag.string({ description: "Optional future ISO 8601 expiry" }),
+      yes: confirmFlag("Create this app credential"),
+    },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes)
+        throw new Error(cliText(ctx, { en: "Creating an app credential requires --yes.", de: "App-Zugang erstellen erfordert --yes." }));
+      const result = z
+        .object({ credential: metadata, token: z.string() })
+        .parse(
+          await apiJson(ctx, "POST", path(args.app), {
+            name: flags.name,
+            scopes: ["identity:invoke"],
+            ...(flags.expiresAt ? { expiresAt: flags.expiresAt } : {}),
+          }),
+        );
+      if (!printStructured(ctx, result)) ctx.print(result.token);
+    },
+  }),
+  command("app-credentials revoke", {
+    summary: "Revoke one exact app credential; its background calls will stop",
+    args: { app: arg.required({ valueLabel: "app" }), credential: arg.required({ valueLabel: "credential" }) },
+    flags: { yes: confirmFlag("Revoke this app credential") },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes)
+        throw new Error(cliText(ctx, { en: "Revoking an app credential requires --yes.", de: "App-Zugang widerrufen erfordert --yes." }));
+      const credentialId = z.uuid().parse(args.credential);
+      const result = await apiJson(ctx, "DELETE", `${path(args.app)}/${credentialId}`);
+      if (!printStructured(ctx, result)) ctx.print(cliText(ctx, { en: "Credential revoked.", de: "Zugang widerrufen." }));
+    },
+  }),
+];

package/src/cli/admin/data.ts

@@ -18,11 +18,18 @@ export type PostgresDiagnostics = {
   totalBytes: number;
   installedExtensions: number;
   availableExtensions: number;
+  runtime: {
+    deadlocks: number;
+    oldestTransactionSeconds: number;
+    oldestQuerySeconds: number;
+  };
   tableRows: {
     schema: string;
     name: string;
     estimatedRows: number;
     deadRows: number;
+    seqScans: number;
+    indexScans: number;
     totalBytes: number;
     tableBytes: number;
     indexBytes: number;
@@ -117,6 +124,9 @@ export const dataCommands = [
           tables: data.tables,
           storage: formatBytes(data.totalBytes),
           extensions: `${data.installedExtensions}/${data.availableExtensions}`,
+          deadlocks: data.available ? data.runtime.deadlocks : "-",
+          oldestTransaction: data.available ? formatSeconds(data.runtime.oldestTransactionSeconds) : "-",
+          oldestQuery: data.available ? formatSeconds(data.runtime.oldestQuerySeconds) : "-",
           warnings: data.warnings.length,
           error: data.error ?? "",
         },
@@ -127,6 +137,9 @@ export const dataCommands = [
         { key: "tables" },
         { key: "storage" },
         { key: "extensions" },
+        { key: "deadlocks", label: "Deadlocks since reset" },
+        { key: "oldestTransaction", label: "Oldest transaction" },
+        { key: "oldestQuery", label: "Oldest active query" },
         { key: "warnings" },
         { key: "error" },
       ]);
@@ -161,6 +174,8 @@ export const dataCommands = [
         heap: formatBytes(table.tableBytes),
         indexes: formatBytes(table.indexBytes),
         deadRows: table.deadRows,
+        seqScans: table.seqScans,
+        indexScans: table.indexScans,
         warnings: table.warnings.join(", "),
       }));
       printJsonOrTable(ctx, { ...data, tableRows: tables }, rows, [
@@ -170,6 +185,8 @@ export const dataCommands = [
         { key: "heap" },
         { key: "indexes" },
         { key: "deadRows" },
+        { key: "seqScans", label: "Seq scans since reset" },
+        { key: "indexScans", label: "Index scans since reset" },
         { key: "warnings" },
       ]);
     },

package/src/cli/admin/index.ts

@@ -1,3 +1,4 @@
+import { appCredentialCommands } from "./app-credentials";
 /**
  * `cld admin` — Cloud administration surfaces.
  *
@@ -9,6 +10,8 @@ import { defineCliCommands } from "../commands";
 import { accountAdministrationCommands } from "./account-administration";
 import { accountCategoryCommands } from "./account-categories";
 import { appSignInCommands } from "./app-sign-in";
+import { aiSkillCommands } from "./ai-skills";
+import { aiQuotaCommands } from "./ai-quotas";
 import { aiUsageCommands } from "./ai-usage";
 import { dataCommands } from "./data";
 import { documentationCommands } from "./documentation";
@@ -30,19 +33,25 @@ export default defineCliCommands({
   name: "admin",
   summary: "Inspect and operate Cloud administration surfaces.",
   groupSummaries: {
+    "app-credentials": "Manage per-application credentials for background work.",
     "app-sign-in config": "Manage the trusted app website and pairing policy.",
     "accounts config": "Manage account types and sign-in visibility.",
     "accounts administration": "Manage account requests and account/group follow-up notices.",
+    "ai quotas": "Manage direct Assistant chat limits and consumption.",
+    "ai quotas config": "Export and replace quota policies with revision checks.",
     legal: "Manage Terms, Privacy, and Imprint.",
     linux: "Prepare Linux identities.",
     "linux config": "Manage Linux identity defaults and allocation range.",
   },
   commands: [
+    ...appCredentialCommands,
     ...documentationCommands,
     ...appSignInCommands,
     ...accountCategoryCommands,
     ...accountAdministrationCommands,
     ...aiUsageCommands,
+    ...aiQuotaCommands,
+    ...aiSkillCommands,
     ...instanceCommands,
     ...gatewayCommands,
     ...logCommands,

package/src/cli/capabilities.ts

@@ -1,3 +1,5 @@
+import { saveCapabilityStream } from "./capability-streams";
+import { CapabilityStreamSchema } from "../contracts/capabilities";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import {
@@ -118,6 +120,33 @@ export default defineCliCommands({
   name: "capabilities",
   summary: "Discover and invoke versioned Cloud app capabilities.",
   commands: [
+    ...(["read", "write", "status", "abort"] as const).map(verb => command(`stream-${verb}`, {
+      summary: `${verb} an authenticated binary capability stream`,
+      flags: {
+        input: flag.input({ required: true, description: "Stream descriptor JSON; use --input-file or --stdin" }),
+        ...(verb === "read" ? { out: flag.string({ required: true, description: "New output file; never overwritten" }) } : {}),
+        ...(verb === "write" ? { file: flag.string({ required: true, description: "Local binary file to upload" }) } : {}),
+      },
+      run: async ({ctx, flags}) => {
+        const stream = CapabilityStreamSchema.parse(await parseInput(flags.input));
+        if ((verb === "read") !== (stream.direction === "read")) throw new Error("Wrong stream direction.");
+        const body = verb === "write" ? Bun.file(String(flags.file)) : undefined;
+        if (body && (!(await body.exists()) || body.size !== stream.size)) throw new Error("Input file must match the authorized byte size.");
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        process.once("SIGINT", abort); process.once("SIGTERM", abort);
+        try {
+          const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(300_000)]);
+          const response = await ctx.fetch(`/api/capabilities/v1/streams/${verb}`, {
+            method: "POST", headers: {"x-cloud-stream-id": stream.id, "content-type": "application/octet-stream"},
+            body, signal, redirect: "error",
+          });
+          printGenericResult(ctx, verb === "read"
+            ? await saveCapabilityStream(response, stream, String(flags.out), signal)
+            : await readCapabilityJson(response, CAPABILITY_MAX_RESULT_BYTES));
+        } finally { process.off("SIGINT", abort); process.off("SIGTERM", abort); }
+      },
+    })),
     command("catalog", {
       summary: "List live capability manifests",
       flags: {

package/src/cli/capability-streams.ts

@@ -0,0 +1,25 @@
+import { createWriteStream } from "node:fs";
+import { link, mkdtemp, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { exactStream } from "../capabilities/stream-body";
+import type { CapabilityStream } from "../contracts/capabilities";
+
+/** Publish only a complete download; never overwrite an existing local file. */
+export async function saveCapabilityStream(response: Response, stream: CapabilityStream, output: string, signal: AbortSignal) {
+  if (!response.ok || !response.body) {
+    await response.body?.cancel();
+    throw new Error(`Stream read failed (HTTP ${response.status}).`);
+  }
+  const path = resolve(output);
+  const temporary = await mkdtemp(join(dirname(path), ".cloud-stream-"));
+  try {
+    const part = join(temporary, "content");
+    await pipeline(exactStream(response.body, stream.size), createWriteStream(part, { flags: "wx", mode: 0o600 }), { signal });
+    signal.throwIfAborted();
+    await link(part, path);
+    return { path, bytes: stream.size };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/src/cli/index.ts

@@ -32,7 +32,7 @@ export type CloudCliContext = {
   setDefault: (key: string, value: string | undefined) => Promise<void>;
   createApiClient: <TApi extends Hono<any, any, any>>(basePath: string) => CloudApiClient<TApi>;
   fetch: (path: string, init?: RequestInit) => Promise<Response>;
-  readJson: <T>(response: Response) => Promise<T>;
+  readJson: <T>(response: Pick<Response, "json" | "text" | "ok" | "status" | "statusText">) => Promise<T>;
   print: (value?: string) => void;
   /** Write a stdout chunk without adding a newline. */
   /** Resolves once the value is flushed; await it when writing large output. */
@@ -51,7 +51,8 @@ export type CloudCliModule = {
   booleanFlags?: readonly string[];
   requiresCloud?: boolean;
   requiresCloudFor?: (args: string[], flags: CloudCliFlags) => boolean;
-  help?: () => string;
+  /** Render module help in the request locale; command syntax stays unchanged. */
+  help?: (locale?: string) => string;
   run: (context: CloudCliContext) => Promise<number | void> | number | void;
 };