dataiku-sdk 3.4.0 → 3.6.0

package/dist/src/cli/commands/folder.js

@@ -2,14 +2,14 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { addTransientTargetContext, encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 async function resolveFolderId(client, nameOrId, flags) {
     return client.folders.resolveId(nameOrId, flags["project-key"]);
 }
-export const folderCommands = {
+export const folderCommands = withUsage("folder", {
     list: {
         handler: (c, _a, f) => c.folders.list(f["project-key"]),
-        usage: "dss folder list [--project-key KEY]",
         description: "List managed folders in a project.",
         examples: ["dss folder list",],
     },
@@ -20,7 +20,7 @@ export const folderCommands = {
             const connection = f["connection"];
             const pk = f["project-key"];
             if (!name) {
-                throw new UsageError("--name is required. Usage: dss folder create --name NAME [--type TYPE] [--connection CONN] [--path PATH]");
+                throw new UsageError(`--name is required. Usage: ${commandUsage("folder", "create")}`);
             }
             const payload = {
                 name,
@@ -49,7 +49,6 @@ export const folderCommands = {
             const created = await c.folders.create(payload);
             return { created: created.id ?? name, resource: "folder", ...created, };
         },
-        usage: "dss folder create --name NAME [--type TYPE] [--connection CONN] [--path PATH] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a managed folder; when omitted, the connection is selected from writable managed-folder storage and DSS infers the folder type.",
         examples: [
             "dss folder create --name exports",
@@ -59,19 +58,18 @@ export const folderCommands = {
     },
     get: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss folder get <name-or-id>");
+            requireArgs(a, 1, commandUsage("folder", "get"));
             return c.folders.get(await resolveFolderId(c, a[0], f), f["project-key"]);
         },
-        usage: "dss folder get <name-or-id> [--project-key KEY]",
         description: "Get managed folder settings.",
         examples: ["dss folder get my_folder",],
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss folder update <name-or-id> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("folder", "update"));
             const data = jsonInput(f);
             if (!data) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss folder update <name-or-id> [--data '{...}' | --data-file PATH | --stdin]");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("folder", "update")}`);
             }
             const pk = f["project-key"];
             const folderId = await resolveFolderId(c, a[0], f);
@@ -91,7 +89,6 @@ export const folderCommands = {
             await c.folders.update(folderId, data, pk);
             return { updated: folderId, resource: "folder", };
         },
-        usage: "dss folder update <name-or-id> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Update managed folder settings by deep-merging a JSON patch.",
         examples: [
             'dss folder update exports --data \'{"tags":["agent"]}\' --dry-run',
@@ -100,7 +97,7 @@ export const folderCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss folder delete <name-or-id>");
+            requireArgs(a, 1, commandUsage("folder", "delete"));
             const pk = f["project-key"];
             const folderId = await resolveFolderId(c, a[0], f);
             if (executionMode(f).dryRun || f["if-exists"] === true) {
@@ -121,13 +118,12 @@ export const folderCommands = {
             await c.folders.delete(folderId, pk);
             return { deleted: folderId, resource: "folder", };
         },
-        usage: "dss folder delete <name-or-id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a managed folder.",
         examples: ["dss folder delete exports --if-exists",],
     },
     contents: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss folder contents <name-or-id>");
+            requireArgs(a, 1, commandUsage("folder", "contents"));
             const startedAt = Date.now();
             let folderId = a[0];
             try {
@@ -140,7 +136,6 @@ export const folderCommands = {
                 addTransientTargetContext(error, `folder:${folderId}`, Date.now() - startedAt);
             }
         },
-        usage: "dss folder contents <name-or-id> [--retries N] [--request-timeout MS] [--project-key KEY]",
         description: "List files in a managed folder.",
         examples: [
             "dss folder contents my_folder",
@@ -149,14 +144,13 @@ export const folderCommands = {
     },
     download: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss folder download <name-or-id> <remote-path> [local-path]");
+            requireArgs(a, 2, commandUsage("folder", "download"));
             const localPath = a[2] ?? f["output"];
             return c.folders.download(await resolveFolderId(c, a[0], f), a[1], {
                 localPath,
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss folder download <name-or-id> <remote-path> [local-path] [--output PATH] [--project-key KEY]",
         description: "Download a file from a managed folder.",
         examples: [
             "dss folder download my_folder /data/report.csv",
@@ -165,7 +159,7 @@ export const folderCommands = {
     },
     upload: {
         handler: async (c, a, f) => {
-            requireArgs(a, 3, "dss folder upload <name-or-id> <path> <localPath>");
+            requireArgs(a, 3, commandUsage("folder", "upload"));
             const pk = f["project-key"];
             const folderId = await resolveFolderId(c, a[0], f);
             if (executionMode(f).dryRun) {
@@ -184,21 +178,19 @@ export const folderCommands = {
             await c.folders.upload(folderId, a[1], a[2], pk);
             return { uploaded: a[1], folder: a[0], localPath: a[2], resource: "folder", };
         },
-        usage: "dss folder upload <name-or-id> <path> <localPath> [--dry-run] [--project-key KEY]",
         description: "Upload a local file to a managed folder.",
         examples: ["dss folder upload my_folder /data/report.csv ./report.csv --dry-run",],
     },
     "delete-file": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss folder delete-file <name-or-id> <path>");
+            requireArgs(a, 2, commandUsage("folder", "delete-file"));
             if (executionMode(f).dryRun) {
                 return { dryRun: true, action: "delete-file", resource: "folder", folder: a[0], path: a[1], };
             }
             await c.folders.deleteFile(await resolveFolderId(c, a[0], f), a[1], f["project-key"]);
             return { deleted: a[1], folder: a[0], resource: "folder", };
         },
-        usage: "dss folder delete-file <name-or-id> <path> [--dry-run] [--project-key KEY]",
         description: "Delete a file from a managed folder.",
         examples: ["dss folder delete-file my_folder /data/report.csv",],
     },
-};
+});

package/dist/src/cli/commands/future.js

@@ -1,41 +1,39 @@
 import { num, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { planResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const futureCommands = {
+export const futureCommands = withUsage("future", {
     get: {
         handler: (c, a) => {
-            requireArgs(a, 1, "dss future get <id>");
+            requireArgs(a, 1, commandUsage("future", "get"));
             return c.futures.get(a[0]);
         },
-        usage: "dss future get <id>",
         description: "Get a DSS future state and retrieve the result if ready.",
         examples: ["dss future get FUTURE_ID",],
     },
     peek: {
         handler: (c, a) => {
-            requireArgs(a, 1, "dss future peek <id>");
+            requireArgs(a, 1, commandUsage("future", "peek"));
             return c.futures.peek(a[0]);
         },
-        usage: "dss future peek <id>",
         description: "Peek at a DSS future state without consuming its result.",
         examples: ["dss future peek FUTURE_ID",],
     },
     wait: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss future wait <id>");
+            requireArgs(a, 1, commandUsage("future", "wait"));
             return c.futures.wait(a[0], {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
                 timeoutMs: num(f["timeout"], "--timeout"),
             });
         },
-        usage: "dss future wait <id> [--timeout MS] [--poll-interval MS]",
         description: "Wait for a DSS future to finish.",
         examples: ["dss future wait FUTURE_ID --timeout 60000",],
     },
     abort: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss future abort <id>");
+            requireArgs(a, 1, commandUsage("future", "abort"));
             const id = a[0];
             if (executionMode(f).dryRun) {
                 return planResult("future", "abort", {
@@ -51,8 +49,7 @@ export const futureCommands = {
             await c.futures.abort(id);
             return { aborted: id, resource: "future", };
         },
-        usage: "dss future abort <id> [--dry-run]",
         description: "Abort a DSS future.",
         examples: ["dss future abort FUTURE_ID --dry-run",],
     },
-};
+});

package/dist/src/cli/commands/group.js

@@ -1,6 +1,7 @@
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 /** Group identifiers must be non-empty before any request or dry-run preview. */
 function requireGroupName(value, usage) {
@@ -10,26 +11,24 @@ function requireGroupName(value, usage) {
     }
     return trimmed;
 }
-export const groupCommands = {
+export const groupCommands = withUsage("group", {
     list: {
         handler: (c) => c.groups.list(),
-        usage: "dss group list",
         description: "List DSS groups (admin).",
         examples: ["dss group list",],
     },
     get: {
         handler: (c, a) => {
-            const usage = "dss group get <name>";
+            const usage = commandUsage("group", "get");
             requireArgs(a, 1, usage);
             return c.groups.get(requireGroupName(a[0], usage));
         },
-        usage: "dss group get <name>",
         description: "Get a DSS group (admin).",
         examples: ["dss group get administrators",],
     },
     create: {
         handler: async (c, _a, f) => {
-            const usage = "dss group create (--data JSON|--data-file PATH|--stdin)";
+            const usage = commandUsage("group", "create");
             const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (group definition). Usage: ${usage}`);
             if (executionMode(f).dryRun) {
                 return {
@@ -44,7 +43,6 @@ export const groupCommands = {
             }
             return c.groups.create(body);
         },
-        usage: "dss group create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: 'Create a DSS group (admin). Body follows the DSS Group schema, e.g. {"name":"analysts","admin":false,"description":"..."}.',
         examples: [
             `dss group create --data '{"name":"analysts","admin":false,"description":"Business analysts"}'`,
@@ -52,7 +50,7 @@ export const groupCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            const usage = "dss group update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+            const usage = commandUsage("group", "update");
             requireArgs(a, 1, usage);
             const name = requireGroupName(a[0], usage);
             const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (group definition). Usage: ${usage}`);
@@ -71,7 +69,6 @@ export const groupCommands = {
             await c.groups.update(name, body);
             return { updated: name, };
         },
-        usage: "dss group update <name> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: "Update a DSS group (admin). The body MUST be the Group object obtained from `dss group get` (PUT semantics); pass undocumented attributes through unchanged. Use --dry-run to preview the merged result without writing.",
         examples: [
             `dss group update analysts --data '{"name":"ANALYSTS","admin":false,"description":"Business analysts"}'`,
@@ -79,7 +76,7 @@ export const groupCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            const usage = "dss group delete <name> [--if-exists] [--dry-run]";
+            const usage = commandUsage("group", "delete");
             requireArgs(a, 1, usage);
             const name = requireGroupName(a[0], usage);
             if (executionMode(f).dryRun) {
@@ -102,8 +99,7 @@ export const groupCommands = {
             }
             return c.groups.delete(name);
         },
-        usage: "dss group delete <name> [--if-exists] [--dry-run]",
         description: "Delete a DSS group (admin). Destructive and irreversible.",
         examples: ["dss group delete analysts", "dss group delete analysts --if-exists",],
     },
-};
+});

package/dist/src/cli/commands/insight.js

@@ -2,20 +2,19 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { json, jsonInput, parseBooleanOption, textInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const insightCommands = {
+export const insightCommands = withUsage("insight", {
     list: {
         handler: (c, _a, f) => c.insights.list(f["project-key"]),
-        usage: "dss insight list [--project-key KEY]",
         description: "List project insights.",
         examples: ["dss insight list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss insight get <id>");
+            requireArgs(a, 1, commandUsage("insight", "get"));
             return c.insights.get(a[0], f["project-key"]);
         },
-        usage: "dss insight get <id> [--project-key KEY]",
         description: "Get insight definition.",
         examples: ["dss insight get INSIGHT_ID",],
     },
@@ -29,7 +28,7 @@ export const insightCommands = {
             const contentType = f["content-type"];
             const payload = textInput(f);
             if (!data && (!name || !type)) {
-                throw new UsageError("--data or both --name and --type are required. Usage: dss insight create --name NAME --type TYPE");
+                throw new UsageError(`--data or both --name and --type are required. Usage: ${commandUsage("insight", "create")}`);
             }
             const prototype = { ...data, };
             if (name !== undefined)
@@ -76,7 +75,6 @@ export const insightCommands = {
             });
             return { created: created.id, resource: "insight", ...created, };
         },
-        usage: "dss insight create (--data JSON|--data-file PATH|--stdin | --name NAME --type TYPE [--params JSON] [--listed true|false]) [--content TEXT|--file PATH --content-type MIME] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create an insight from a raw prototype or minimal name/type fields.",
         examples: [
             "dss insight create --name 'Agent chart' --type chart --params '{\"dataset\":\"orders\"}' --dry-run",
@@ -85,7 +83,7 @@ export const insightCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss insight update <id> (--name NAME|--listed true|false|--params JSON|--content TEXT|--file PATH|--content-type MIME|--data JSON|--data-file PATH|--stdin)");
+            requireArgs(a, 1, commandUsage("insight", "update"));
             const data = jsonInput(f);
             const name = f["name"];
             const params = json(f["params"]);
@@ -131,13 +129,12 @@ export const insightCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss insight update <id> (--name NAME|--listed true|false|--params JSON|--content TEXT|--file PATH|--content-type MIME|--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Update an insight using GET-before-POST merge semantics.",
         examples: ["dss insight update INSIGHT_ID --name 'Updated' --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss insight delete <id>");
+            requireArgs(a, 1, commandUsage("insight", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.insights.get(a[0], pk));
@@ -150,8 +147,7 @@ export const insightCommands = {
             await c.insights.delete(a[0], pk);
             return { deleted: a[0], resource: "insight", };
         },
-        usage: "dss insight delete <id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete an insight.",
         examples: ["dss insight delete INSIGHT_ID --dry-run",],
     },
-};
+});

package/dist/src/cli/commands/job.js

@@ -1,8 +1,10 @@
 import { mkdir, writeFile, } from "node:fs/promises";
 import { dirname, resolve, } from "node:path";
-import { jobBuildTargetTypeFromFlags, jobLogFilterFromFlag, maxLogLinesFromFlags, num, plainRecord, } from "../coerce.js";
+import { asRecord, } from "../../utils/records.js";
+import { jobBuildTargetTypeFromFlags, jobLogFilterFromFlag, maxLogLinesFromFlags, num, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 // ---------------------------------------------------------------------------
 // Utility helpers
@@ -10,7 +12,7 @@ import { requireArgs, UsageError, } from "../usage.js";
 function nestedValue(value, path) {
     let current = value;
     for (const key of path) {
-        const record = plainRecord(current);
+        const record = asRecord(current);
         if (!record)
             return undefined;
         current = record[key];
@@ -94,7 +96,7 @@ function collectWarningCounts(value, inActivity, counts) {
             collectWarningCounts(item, inActivity, counts);
         return;
     }
-    const record = plainRecord(value);
+    const record = asRecord(value);
     if (!record)
         return;
     for (const [key, item,] of Object.entries(record)) {
@@ -190,34 +192,31 @@ async function jobInspectionSummary(client, jobId, flags) {
         },
     };
 }
-export const jobCommands = {
+export const jobCommands = withUsage("job", {
     list: {
         handler: async (c, _a, f) => filteredJobList(await c.jobs.list(f["project-key"]), f),
-        usage: "dss job list [--state STATE] [--contains TEXT] [--output ID] [--latest] [--limit N] [--project-key KEY]",
         description: "List recent jobs, optionally filtered for automation.",
         examples: ["dss job list --state DONE --latest", "dss job list --contains WLM225S --limit 10",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss job get <id>");
+            requireArgs(a, 1, commandUsage("job", "get"));
             return c.jobs.get(a[0], f["project-key"]);
         },
-        usage: "dss job get <id> [--project-key KEY]",
         description: "Get job details.",
         examples: ["dss job get JOB_ID",],
     },
     summary: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss job summary <id>");
+            requireArgs(a, 1, commandUsage("job", "summary"));
             return jobInspectionSummary(c, a[0], f);
         },
-        usage: "dss job summary <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--max-lines N|--max-log-lines N] [--project-key KEY]",
         description: "Summarize job state, outputs, warnings, progress, and useful terminal log lines.",
         examples: ["dss job summary JOB_ID --max-log-lines 200",],
     },
     log: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job log <id>");
+            requireArgs(a, 1, commandUsage("job", "log"));
             const logFilter = f["errors-only"] === true
                 ? "errors"
                 : jobLogFilterFromFlag(f["log-filter"]);
@@ -237,7 +236,6 @@ export const jobCommands = {
             await writeFile(outputPath, log.endsWith("\n") ? log : `${log}\n`, "utf-8");
             return outputPath;
         },
-        usage: "dss job log <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--log-filter stdout|stderr|user|errors] [--errors-only] [--max-lines N|--max-log-lines N] [--output PATH] [--project-key KEY]",
         description: "Get public API job log output. Use --errors-only (or --log-filter errors) to surface just error/traceback lines, and --output PATH to write the log to a file (stdout returns the path). --log-id is accepted for UI parity but DSS API-key auth cannot select browser-only cat-activity-log files.",
         examples: [
             "dss job log JOB_ID",
@@ -246,7 +244,7 @@ export const jobCommands = {
     },
     "log-url": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss job log-url <url>");
+            requireArgs(a, 1, commandUsage("job", "log-url"));
             let parsed;
             try {
                 parsed = new URL(a[0], "http://dss.local");
@@ -262,7 +260,6 @@ export const jobCommands = {
             }
             return c.jobs.logFromUrl(a[0], { maxLogLines: maxLogLinesFromFlags(f), });
         },
-        usage: "dss job log-url <url> [--max-lines N|--max-log-lines N]",
         description: "Fetch a DSS cat-activity-log URL pasted from the UI.",
         examples: [
             'dss job log-url "https://dss/dip/api/flow/jobs/cat-activity-log?projectKey=TEST&jobId=JOB&activityId=A&logId=L"',
@@ -270,7 +267,7 @@ export const jobCommands = {
     },
     build: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job build <target>");
+            requireArgs(a, 1, commandUsage("job", "build"));
             const pk = f["project-key"];
             const options = {
                 buildMode: f["build-mode"],
@@ -295,7 +292,6 @@ export const jobCommands = {
             }
             return c.jobs.build(a[0], { ...options, projectKey: pk, });
         },
-        usage: "dss job build <target> [--target-type dataset|managed-folder] [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--wait] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
         description: "Start a dataset or managed-folder build, optionally waiting for completion.",
         examples: [
             "dss job build orders",
@@ -305,7 +301,7 @@ export const jobCommands = {
     },
     "build-and-wait": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job build-and-wait <target>");
+            requireArgs(a, 1, commandUsage("job", "build-and-wait"));
             const pk = f["project-key"];
             const options = {
                 buildMode: f["build-mode"],
@@ -331,7 +327,6 @@ export const jobCommands = {
             }
             return c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
         },
-        usage: "dss job build-and-wait <target> [--target-type dataset|managed-folder] [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
         description: "Build a dataset or managed folder and wait for completion.",
         examples: [
             "dss job build-and-wait orders",
@@ -342,7 +337,7 @@ export const jobCommands = {
     },
     wait: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss job wait <id>");
+            requireArgs(a, 1, commandUsage("job", "wait"));
             return c.jobs.wait(a[0], {
                 includeLogs: f["include-logs"] === true,
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
@@ -353,7 +348,6 @@ export const jobCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss job wait <id> [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--project-key KEY]",
         description: "Wait for an existing job to complete.",
         examples: [
             "dss job wait JOB_ID",
@@ -362,7 +356,7 @@ export const jobCommands = {
     },
     monitor: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job monitor <id...>");
+            requireArgs(a, 1, commandUsage("job", "monitor"));
             const options = {
                 includeLogs: f["include-logs"] === true,
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
@@ -375,13 +369,12 @@ export const jobCommands = {
             const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
             return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
-        usage: "dss job monitor <id...> [--summary] [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
         description: "Monitor one or more existing jobs and summarize progress counters from logs.",
         examples: ["dss job monitor JOB_ID --summary", "dss job monitor JOB1 JOB2 --until all-done",],
     },
     watch: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job watch <id...>");
+            requireArgs(a, 1, commandUsage("job", "watch"));
             const options = {
                 includeLogs: f["include-logs"] === true,
                 logFilter: jobLogFilterFromFlag(f["log-filter"]),
@@ -394,13 +387,12 @@ export const jobCommands = {
             const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
             return aggregateJobWaitResults(jobs, String(f["until"] ?? "all-done"));
         },
-        usage: "dss job watch <id...> [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
         description: "Watch one or more existing jobs with progress extraction enabled.",
         examples: ["dss job watch JOB_ID", "dss job watch JOB1 JOB2 --until all-done",],
     },
     abort: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss job abort <id>");
+            requireArgs(a, 1, commandUsage("job", "abort"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
                 return {
@@ -415,8 +407,7 @@ export const jobCommands = {
             await c.jobs.abort(a[0], pk);
             return { aborted: a[0], resource: "job", };
         },
-        usage: "dss job abort <id> [--dry-run] [--project-key KEY]",
         description: "Abort a running job.",
         examples: ["dss job abort JOB_ID", "dss job abort JOB_ID --dry-run",],
     },
-};
+});

package/dist/src/cli/commands/knowledge-bank.js

@@ -1,10 +1,11 @@
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { planResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const KB_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
-const KB_SEARCH_USAGE = "dss knowledge-bank search <knowledgeBankId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
-const KB_CLEAR_USAGE = "dss knowledge-bank clear <knowledgeBankId> [--dry-run] [--project-key KEY]";
+const KB_SEARCH_USAGE = commandUsage("knowledge-bank", "search");
+const KB_CLEAR_USAGE = commandUsage("knowledge-bank", "clear");
 /**
  * Validate a search body before any execution mode: the same check runs for
  * live, --plan, and --dry-run so planning can never succeed for a body the
@@ -24,7 +25,7 @@ function requireNonEmptyPositional(value, usage) {
     }
     return value;
 }
-export const knowledgeBankCommands = {
+export const knowledgeBankCommands = withUsage("knowledge-bank", {
     search: {
         handler: async (c, a, f) => {
             const knowledgeBankId = requireNonEmptyPositional(a[0], KB_SEARCH_USAGE);
@@ -44,7 +45,6 @@ export const knowledgeBankCommands = {
             }
             return c.knowledgeBanks.search(knowledgeBankId, body, projectKey);
         },
-        usage: KB_SEARCH_USAGE,
         description: "Search a knowledge bank for documents matching a query. Runs retrieval against the backing vector store. Body: { query, params?: { maxDocuments, searchType, similarityThreshold, mmrK, mmrDiversity, useAdvancedReranking, rrfRankConstant, rrfRankWindowSize } }.",
         examples: [
             'dss knowledge-bank search my-kb --data \'{"query":"Hello, world!"}\'',
@@ -70,11 +70,10 @@ export const knowledgeBankCommands = {
             await c.knowledgeBanks.clear(knowledgeBankId, projectKey);
             return { cleared: knowledgeBankId, resource: "knowledge-bank", };
         },
-        usage: KB_CLEAR_USAGE,
         description: "DESTRUCTIVE: clear all data from a knowledge bank. The stored content is removed and cannot be recovered from this command.",
         examples: [
             "dss knowledge-bank clear my-kb --dry-run",
             "dss knowledge-bank clear my-kb",
         ],
     },
-};
+});

package/dist/src/cli/commands/llm.js

@@ -1,11 +1,11 @@
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { planResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
 const LLM_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
-const LLM_LIST_USAGE = "dss llm list [--purpose GENERIC_COMPLETION|TEXT_EMBEDDING_EXTRACTION|IMAGE_GENERATION|NAME] [--project-key KEY]";
-const LLM_COMPLETIONS_USAGE = "dss llm completions (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
-const LLM_EMBEDDINGS_USAGE = "dss llm embeddings (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+const LLM_COMPLETIONS_USAGE = commandUsage("llm", "completions");
+const LLM_EMBEDDINGS_USAGE = commandUsage("llm", "embeddings");
 /**
  * Validate a completions/embeddings payload before any execution mode: the
  * same check runs for live, --plan, and --dry-run so planning can never
@@ -23,7 +23,7 @@ function requireLlmInferenceBody(flags, usage) {
     }
     return body;
 }
-export const llmCommands = {
+export const llmCommands = withUsage("llm", {
     list: {
         handler: (c, _a, f) => {
             const purpose = f["purpose"];
@@ -32,7 +32,6 @@ export const llmCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: LLM_LIST_USAGE,
         description: "List LLMs available in a project (includes Retrieval-Augmented Generation ones). Does not invoke any LLM.",
         examples: ["dss llm list", "dss llm list --purpose TEXT_EMBEDDING_EXTRACTION",],
     },
@@ -56,7 +55,6 @@ export const llmCommands = {
             }
             return c.llms.completions(body, projectKey);
         },
-        usage: LLM_COMPLETIONS_USAGE,
         description: "Perform completions on an LLM. COST-BEARING: invokes the LLM provider and may incur charges. Body: { llmId, queries: [{ messages: [...] }], settings?: {...} }.",
         examples: [
             'dss llm completions --data \'{"llmId":"openai:openai1:gpt-4","queries":[{"messages":[{"role":"user","content":"Hello"}]}]}\'',
@@ -83,11 +81,10 @@ export const llmCommands = {
             }
             return c.llms.embeddings(body, projectKey);
         },
-        usage: LLM_EMBEDDINGS_USAGE,
         description: 'Perform embeddings on an LLM. COST-BEARING: invokes the LLM provider and may incur charges. Body: { llmId, queries: [{ text: "..." }] }.',
         examples: [
             'dss llm embeddings --data \'{"llmId":"openai:openai1:ada002-text-embedding","queries":[{"text":"Who wrote Beethoven 9th?"}]}\'',
             'dss llm embeddings --data \'{"llmId":"x","queries":[{"text":"y"}]}\' --dry-run',
         ],
     },
-};
+});