@2kw/ai 6.2.2 → 6.3.0-dev.106

package/dist/commands/datasets.js

@@ -3,6 +3,7 @@ import { getClient, runAction } from "../lib/client.js";
 import { resolveLatestVersionId } from "../lib/datasets.js";
 import { formatPage, formatDetail, formatList, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { makeDatasetVersionsCommand } from "./dataset-versions.js";
 export function makeDatasetsCommand() {
     const cmd = new Command("datasets").description("Manage datasets");
@@ -77,24 +78,25 @@ export function makeDatasetsCommand() {
         .option("--metadata <json>", "Metadata (JSON)")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
+            const changes = {
+                name: opts.name,
+                description: opts.description,
+                type: opts.type,
+                inputSchema: opts.inputSchema ? JSON.parse(opts.inputSchema) : undefined,
+                expectedOutputSchema: opts.expectedOutputSchema ? JSON.parse(opts.expectedOutputSchema) : undefined,
+                metadata: opts.metadata ? JSON.parse(opts.metadata) : undefined,
+            };
             const client = getClient(command);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.type !== undefined)
-                body.type = opts.type;
-            if (opts.inputSchema)
-                body.inputSchema = JSON.parse(opts.inputSchema);
-            if (opts.expectedOutputSchema)
-                body.expectedOutputSchema = JSON.parse(opts.expectedOutputSchema);
-            if (opts.metadata)
-                body.metadata = JSON.parse(opts.metadata);
+            // PUT /v1/datasets/{id} replaces the whole dataset, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/datasets/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Dataset ${id} could not be read.`);
             const { data } = await client.PUT("/v1/datasets/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });

package/dist/commands/experiments.js

@@ -5,6 +5,7 @@ import Table from "cli-table3";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail, formatList, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { isJsonOutput } from "../lib/config.js";
 const TERMINAL_STATUSES = new Set(["COMPLETED", "FAILED"]);
 /** Summarize a single cell of the comparison matrix (a variant's result for one item). */
@@ -92,21 +93,24 @@ export function makeExperimentsCommand() {
         .option("--metadata <json>", "Metadata (JSON)")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
+            const changes = {
+                name: opts.name,
+                description: opts.description,
+                type: opts.type,
+                datasetVersionId: opts.datasetVersion,
+                metadata: opts.metadata ? JSON.parse(opts.metadata) : undefined,
+            };
             const client = getClient(command);
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.type !== undefined)
-                body.type = opts.type;
-            if (opts.datasetVersion !== undefined)
-                body.datasetVersionId = opts.datasetVersion;
-            if (opts.metadata)
-                body.metadata = JSON.parse(opts.metadata);
+            // PUT /v1/experiments/{id} replaces the whole experiment, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/experiments/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Experiment ${id} could not be read.`);
             const { data } = await client.PUT("/v1/experiments/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });
@@ -131,7 +135,7 @@ export function makeExperimentsCommand() {
         .description("Add a variant to an experiment")
         .requiredOption("--experiment <id>", "Experiment ID")
         .requiredOption("-n, --name <name>", "Variant name")
-        .requiredOption("--task-type <type>", "Task type")
+        .requiredOption("--task-type <type>", "Task type: extraction or agent")
         .requiredOption("--config <json>", "Variant configuration (JSON)")
         .option("-d, --description <text>", "Variant description")
         .option("--sort-order <n>", "Sort order", parseInt)
@@ -179,27 +183,33 @@ export function makeExperimentsCommand() {
         .argument("<variantId>", "Variant ID")
         .requiredOption("--experiment <id>", "Experiment ID")
         .option("-n, --name <name>", "Variant name")
-        .option("--task-type <type>", "Task type")
+        .option("--task-type <type>", "Task type; must equal the variant's current one (it cannot change)")
         .option("--config <json>", "Variant configuration (JSON)")
         .option("-d, --description <text>", "Variant description")
         .option("--sort-order <n>", "Sort order", parseInt)
         .action(async (variantId, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
+            const changes = {
+                name: opts.name,
+                taskType: opts.taskType,
+                configuration: opts.config ? JSON.parse(opts.config) : undefined,
+                description: opts.description,
+                sortOrder: opts.sortOrder,
+            };
             const client = getClient(command);
-            const body = {};
-            if (opts.name !== undefined)
-                body.name = opts.name;
-            if (opts.taskType !== undefined)
-                body.taskType = opts.taskType;
-            if (opts.config)
-                body.configuration = JSON.parse(opts.config);
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.sortOrder !== undefined)
-                body.sortOrder = opts.sortOrder;
+            // The variant PUT writes name, description and configuration as sent, so an omitted one would
+            // be cleared. There is no single-variant GET: read it from the list. The read's version goes
+            // back with the body, so a change made since is refused with 409.
+            const { data: variants } = await client.GET("/v1/experiments/{id}/variants", {
+                params: { path: { id: opts.experiment } },
+            });
+            const current = variants?.find((v) => v.id === variantId);
+            if (!current)
+                throw new Error(`Variant ${variantId} is not a variant of experiment ${opts.experiment}.`);
             const { data } = await client.PUT("/v1/experiments/{id}/variants/{variantId}", {
                 params: { path: { id: opts.experiment, variantId } },
-                body: body,
+                body: overlay(current, changes),
             });
             formatDetail(data, command);
         });

package/dist/commands/files.js

@@ -8,40 +8,22 @@ import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/out
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload a single file with purpose=agent_input|knowledge. Bypasses the typed
- * client the same way convert.ts and transcribe.ts do: the generated types
- * describe the multipart body as an opaque `file: string`, which is not
- * something FormData can produce a match for.
+ * Upload a single file with purpose=agent_input|knowledge. The generated type
+ * describes the "file" part as a binary string, which FormData cannot match,
+ * so the placeholder body satisfies the type and bodySerializer sends the
+ * real part.
  */
 async function uploadFile(command, filePath, purpose) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const { blob, filename } = fileToBlob(filePath);
     const formData = new FormData();
     formData.append("file", blob, filename);
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/files?purpose=${encodeURIComponent(purpose)}`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/files", {
+        params: { query: { purpose } },
+        body: { file: "" },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data;
 }
 /** Stream a file's bytes from /v1/files/{fileId}/content via a raw fetch. */
 async function downloadFile(command, fileId) {

package/dist/commands/installations.js

@@ -73,7 +73,7 @@ export function makeInstallationsCommand() {
                 body.status = opts.status;
             const { data } = await client.PUT("/v1/installations/{id}", {
                 params: { path: { id } },
-                body: body,
+                body,
             });
             formatDetail(data, command);
         });

package/dist/commands/knowledge-documents.js

@@ -1,49 +1,29 @@
 import { Command } from "commander";
 import chalk from "chalk";
-import { getClient, resolveAuthHeader, runAction } from "../lib/client.js";
-import { resolveConfig, isJsonOutput } from "../lib/config.js";
-import { BackboneApiError } from "../lib/errors.js";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
 import { formatPage, formatDetail, formatSuccess, withSpinner } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 import { fileToBlob } from "../lib/multipart.js";
 /**
- * Upload one or more local files to a knowledge base. Bypasses the typed
- * client the same way convert.ts's multipartConvert does: springdoc mis-shapes
- * this endpoint's `files` parameter as a query array of binary strings, but the
- * controller (`KnowledgeDocumentController.upload`) actually reads it off a
- * multipart/form-data body with repeated "files" parts.
+ * Upload one or more local files to a knowledge base as repeated "files"
+ * parts of a multipart/form-data body. The generated type describes each part
+ * as a binary string, which FormData cannot match, so the placeholder body
+ * satisfies the type and bodySerializer sends the real parts.
  */
 async function uploadDocuments(command, knowledgeBaseId, paths) {
-    const config = resolveConfig(command);
-    const authHeader = await resolveAuthHeader(config);
     const formData = new FormData();
     for (const p of paths) {
         const { blob, filename } = fileToBlob(p);
         formData.append("files", blob, filename);
     }
-    const baseUrl = config.baseUrl.replace(/\/+$/, "");
-    const url = `${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { Authorization: authHeader },
-        body: formData,
+    const client = getClient(command);
+    const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+        params: { path: { knowledgeBaseId } },
+        body: { files: [] },
+        bodySerializer: () => formData,
     });
-    if (!res.ok) {
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            body = {
-                error: res.statusText,
-                message: `HTTP ${res.status}: ${res.statusText}`,
-                status: res.status,
-                timestamp: new Date().toISOString(),
-            };
-        }
-        throw new BackboneApiError(body);
-    }
-    return (await res.json());
+    return data ?? [];
 }
 function printUploadResults(results, command) {
     if (isJsonOutput(command)) {
@@ -119,6 +99,18 @@ export function makeKnowledgeDocumentsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("retry")
+        .description("Re-ingest a document whose newest revision failed, from its stored file")
+        .argument("<documentId>", "Document ID")
+        .requiredOption("--kb <id>", "Knowledge base ID")
+        .action(async (documentId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents/{documentId}/retry", { params: { path: { knowledgeBaseId: opts.kb, documentId } } });
+            formatDetail(data, command);
+        });
+    });
     cmd
         .command("delete")
         .description("Delete a document and take every revision out of retrieval")

package/dist/commands/memory.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export declare function ifMatchHeader(version: string): string;
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export declare function makeMemoryCommand(): Command;
+//# sourceMappingURL=memory.d.ts.map

package/dist/commands/memory.js

@@ -0,0 +1,132 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { CliUsageError } from "../lib/errors.js";
+import { formatDetail, formatList, formatSuccess } from "../lib/output.js";
+/** The If-Match value for a version a GET returned: the quoted ETag the API expects. */
+export function ifMatchHeader(version) {
+    if (!/^\d{1,18}$/.test(version)) {
+        throw new CliUsageError(`--if-match takes the file's version, a whole number: ${version}`);
+    }
+    return `"${version}"`;
+}
+function requireYes(opts, what) {
+    if (!opts.yes) {
+        throw new CliUsageError(`${what} cannot be undone. Pass --yes to confirm.`);
+    }
+}
+/**
+ * Agent memory (agent memory spec §7.1, §7.4). `ls`, `cat`, `put`, `rm` and `forget` act on
+ * the caller's own memory; `members` and `erase` are for ADMIN and OWNER and never show
+ * paths or content. Content is lossless: `cat` prints it raw, `put` sends the file as is.
+ */
+export function makeMemoryCommand() {
+    const cmd = new Command("memory").description("Your agent memory files; member totals and erasure for admins");
+    cmd
+        .command("ls")
+        .description("List your memory files")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/files");
+            formatList(data, command, [
+                "path",
+                "sizeBytes",
+                "version",
+                "updatedAt",
+                "lastWrittenByAgentId",
+            ]);
+        });
+    });
+    cmd
+        .command("cat <path>")
+        .description("Print one of your memory files, raw (--json for the file object)")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/me/file", {
+                params: { query: { path } },
+            });
+            if (isJsonOutput(command)) {
+                formatDetail(data, command);
+            }
+            else {
+                process.stdout.write(data.content);
+            }
+        });
+    });
+    cmd
+        .command("put <path>")
+        .description("Create or replace one of your memory files from a local UTF-8 file")
+        .requiredOption("--file <file>", "Local file whose content is stored")
+        .option("--if-match <version>", "Only replace the file if it still has this version")
+        .action(async (path, opts, command) => {
+        await runAction(command, async () => {
+            // An empty --if-match (e.g. an unset shell variable) must be refused, never dropped
+            // into an unconditional overwrite.
+            const headers = opts.ifMatch !== undefined ? { "If-Match": ifMatchHeader(opts.ifMatch) } : undefined;
+            const content = readFileSync(opts.file, "utf8");
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/memories/me/file", {
+                params: { query: { path } },
+                body: { content },
+                headers,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("rm <path>")
+        .description("Delete one of your memory files, or a directory with everything below it")
+        .action(async (path, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+            formatSuccess(`Deleted ${path}`, command);
+        });
+    });
+    cmd
+        .command("forget")
+        .description("Delete your whole memory (cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Forgetting your whole memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/me");
+            formatSuccess("Forgot your whole memory", command);
+        });
+    });
+    cmd
+        .command("members")
+        .description("Memory totals per member, without paths or content (ADMIN+)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/memories/users");
+            formatList(data, command, [
+                "userId",
+                "fileCount",
+                "totalBytes",
+                "lastUpdatedAt",
+            ]);
+        });
+    });
+    cmd
+        .command("erase <userId>")
+        .description("Erase a member's whole memory (ADMIN+, cannot be undone)")
+        .option("--yes", "Confirm")
+        .action(async (userId, opts, command) => {
+        await runAction(command, async () => {
+            requireYes(opts, "Erasing a member's memory");
+            const client = getClient(command);
+            await client.DELETE("/v1/memories/users/{userId}", {
+                params: { path: { userId } },
+            });
+            formatSuccess(`Erased the memory of ${userId}`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=memory.js.map

package/dist/commands/prompts.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
 import { formatPage, formatDetail, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 import { makePromptVersionsCommand } from "./prompt-versions.js";
 import { makePromptLabelsCommand } from "./prompt-labels.js";
 export function makePromptsCommand() {
@@ -59,17 +60,17 @@ export function makePromptsCommand() {
         .option("--type <type>", "New type")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            assertNameNotBlank(opts.name);
             const client = getClient(command);
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
-            if (opts.type !== undefined)
-                body.type = opts.type;
+            // PUT /v1/prompts/{id} replaces the whole prompt, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/prompts/{id}", {
+                params: { path: { id } },
+            });
+            if (!current)
+                throw new Error(`Prompt ${id} could not be read.`);
             const { data } = await client.PUT("/v1/prompts/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: overlay(current, { name: opts.name, description: opts.description, type: opts.type }),
             });
             formatDetail(data, command);
         });

package/dist/commands/relays.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeRelaysCommand(): Command;
+//# sourceMappingURL=relays.d.ts.map

package/dist/commands/relays.js

@@ -0,0 +1,135 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { formatDetail, formatPage, formatSuccess } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+/**
+ * Prints an enrolment response in text mode. The relay record comes first when the response
+ * carries one: `create` is the only place the new relay's id is ever shown, and every other
+ * subcommand takes that id as its argument.
+ */
+function printEnrolment(data, command) {
+    if (isJsonOutput(command)) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (data.relay) {
+        formatDetail(data.relay, command);
+        console.log("");
+    }
+    console.log(data.enrolmentExpiresAt
+        ? `Enrolment token (shown once, valid until ${data.enrolmentExpiresAt}):`
+        : "Enrolment token (shown once):");
+    console.log(`  ${data.enrolmentToken ?? ""}`);
+    console.log("");
+    console.log("Run the relay inside your network:");
+    console.log(data.dockerRun ?? "");
+}
+export function makeRelaysCommand() {
+    const cmd = new Command("relays").description("Manage MCP relays that reach MCP servers on private networks");
+    const list = new Command("list").description("List MCP relays");
+    addPaginationOptions(list);
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/mcp-relays", {
+                params: { query: { ...paginationParams(opts) } },
+            });
+            formatPage(data, command, [
+                "id",
+                "name",
+                "status",
+                "online",
+                "relayVersion",
+                "inventoryReportedAt",
+            ]);
+        });
+    });
+    cmd.addCommand(list);
+    cmd
+        .command("get")
+        .description("Show a relay with its inventory")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/mcp-relays/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create a relay; prints a single-use enrolment token and a docker run snippet")
+        .requiredOption("--name <name>", 'Display name, e.g. "Office Berlin"')
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/mcp-relays", {
+                body: { name: opts.name },
+            });
+            printEnrolment(data ?? {}, command);
+        });
+    });
+    cmd
+        .command("rename")
+        .description("Rename a relay")
+        .argument("<id>", "Relay ID")
+        .requiredOption("--name <name>", "New name")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.PATCH("/v1/mcp-relays/{id}", {
+                params: { path: { id } },
+                body: { name: opts.name },
+            });
+            formatDetail(data, command);
+        });
+    });
+    for (const [name, disabled, description] of [
+        ["disable", true, "Disable a relay: it gets no new work and its enrolment token is voided"],
+        ["enable", false, "Enable a disabled relay"],
+    ]) {
+        cmd
+            .command(name)
+            .description(description)
+            .argument("<id>", "Relay ID")
+            .action(async (id, _opts, command) => {
+            await runAction(command, async () => {
+                const client = getClient(command);
+                const { data } = await client.PATCH("/v1/mcp-relays/{id}", {
+                    params: { path: { id } },
+                    body: { disabled },
+                });
+                formatDetail(data, command);
+            });
+        });
+    }
+    cmd
+        .command("re-enrol")
+        .description("Issue a new enrolment token; redeeming it replaces the relay's key")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/mcp-relays/{id}/enrolment-token", {
+                params: { path: { id } },
+            });
+            printEnrolment(data ?? {}, command);
+        });
+    });
+    cmd
+        .command("delete")
+        .description("Revoke a relay for good")
+        .argument("<id>", "Relay ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/mcp-relays/{id}", { params: { path: { id } } });
+            formatSuccess(`Relay ${id} revoked.`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=relays.js.map

package/dist/commands/schemas.js

@@ -58,15 +58,24 @@ export function makeSchemasCommand() {
         .option("-d, --description <text>", "New description")
         .action(async (id, opts, command) => {
         await runAction(command, async () => {
+            let name = opts.name;
+            let description = opts.description;
+            if (name !== undefined && !name.trim())
+                throw new Error("--name must not be empty.");
             const client = getClient(command);
-            const body = {};
-            if (opts.name)
-                body.name = opts.name;
-            if (opts.description !== undefined)
-                body.description = opts.description;
+            // PUT /v1/schemas/{id} replaces the whole schema, so an omitted field would be stored as null.
+            if (name === undefined || description === undefined) {
+                const { data: current } = await client.GET("/v1/schemas/{id}", {
+                    params: { path: { id } },
+                });
+                if (!current)
+                    throw new Error(`Schema ${id} could not be read.`);
+                name ??= current.name;
+                description ??= current.description;
+            }
             const { data } = await client.PUT("/v1/schemas/{id}", {
                 params: { path: { id } },
-                body: body,
+                body: { name, description },
             });
             formatDetail(data, command);
         });