dataiku-sdk 3.3.0 → 3.5.0

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

@@ -1,6 +1,7 @@
 import { requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, planResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
 const STATISTICS_PLAN_EXIT_CODES = { usage: 1, error: 2, transient: 3, };
 const STATISTICS_FUTURE_PLAN_EXIT_CODES = {
@@ -28,28 +29,26 @@ function statisticsPlan(action, options) {
         plannedAndDryRun: true,
     });
 }
-export const statisticsCommands = {
+export const statisticsCommands = withUsage("statistics", {
     "list-worksheets": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss statistics list-worksheets <dataset> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("statistics", "list-worksheets"));
             return c.statistics.listWorksheets(a[0], f["project-key"]);
         },
-        usage: "dss statistics list-worksheets <dataset> [--project-key KEY]",
         description: "List EDA statistics worksheets for a dataset.",
         examples: ["dss statistics list-worksheets customers",],
     },
     "get-worksheet": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "get-worksheet"));
             return c.statistics.getWorksheet(a[0], a[1], f["project-key"]);
         },
-        usage: "dss statistics get-worksheet <dataset> <worksheetId> [--project-key KEY]",
         description: "Get one statistics worksheet definition.",
         examples: ["dss statistics get-worksheet customers ws_1",],
     },
     "create-worksheet": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("statistics", "create-worksheet"));
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -62,7 +61,6 @@ export const statisticsCommands = {
             }
             return c.statistics.createWorksheet(a[0], body, projectKey);
         },
-        usage: "dss statistics create-worksheet <dataset> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Create a statistics worksheet from a JSON definition.",
         examples: [
             'dss statistics create-worksheet customers --data \'{"name":"Customer stats","dataSpec":{"inputDatasetSmartName":"customers","datasetSelection":{"partitionSelectionMethod":"ALL","maxRecords":30000,"samplingMethod":"FULL"}}}\'',
@@ -70,7 +68,7 @@ export const statisticsCommands = {
     },
     "update-worksheet": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "update-worksheet"));
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (worksheet definition).");
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -83,13 +81,12 @@ export const statisticsCommands = {
             }
             return c.statistics.updateWorksheet(a[0], a[1], body, projectKey);
         },
-        usage: "dss statistics update-worksheet <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Replace a statistics worksheet definition.",
         examples: ["dss statistics update-worksheet customers ws_1 --data-file ws.json",],
     },
     "delete-worksheet": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss statistics delete-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "delete-worksheet"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
                 return statisticsPlan("delete-worksheet", {
@@ -101,13 +98,12 @@ export const statisticsCommands = {
             await c.statistics.deleteWorksheet(a[0], a[1], projectKey);
             return { deleted: a[1], };
         },
-        usage: "dss statistics delete-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]",
         description: "Delete a statistics worksheet.",
         examples: ["dss statistics delete-worksheet customers ws_1",],
     },
     "run-worksheet": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss statistics run-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "run-worksheet"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
                 return statisticsPlan("run-worksheet", {
@@ -119,13 +115,12 @@ export const statisticsCommands = {
             }
             return c.statistics.runWorksheet(a[0], a[1], projectKey);
         },
-        usage: "dss statistics run-worksheet <dataset> <worksheetId> [--dry-run] [--project-key KEY]",
         description: "Run a statistics worksheet and return the DSS future response.",
         examples: ["dss statistics run-worksheet customers ws_1",],
     },
     "run-card": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "run-card"));
             const card = requiredJsonInput(f, "--data, --data-file, or --stdin is required (card settings).");
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -139,13 +134,12 @@ export const statisticsCommands = {
             }
             return c.statistics.runCard(a[0], a[1], card, projectKey);
         },
-        usage: "dss statistics run-card <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Run a single card in a worksheet context.",
         examples: ["dss statistics run-card customers ws_1 --data-file card.json",],
     },
     "run-computation": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("statistics", "run-computation"));
             const computation = requiredJsonInput(f, "--data, --data-file, or --stdin is required (computation settings).");
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -159,8 +153,7 @@ export const statisticsCommands = {
             }
             return c.statistics.runComputation(a[0], a[1], computation, projectKey);
         },
-        usage: "dss statistics run-computation <dataset> <worksheetId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Run a single computation in a worksheet context.",
         examples: ["dss statistics run-computation customers ws_1 --data-file comp.json",],
     },
-};
+});

package/dist/src/cli/commands/streaming-endpoint.js

@@ -1,50 +1,46 @@
 import { jsonInput, requiredJsonInput, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const streamingEndpointCommands = {
+export const streamingEndpointCommands = withUsage("streaming-endpoint", {
     list: {
         handler: (c, _a, f) => c.streamingEndpoints.list(f["project-key"]),
-        usage: "dss streaming-endpoint list [--project-key KEY]",
         description: "List streaming endpoints in a project.",
         examples: ["dss streaming-endpoint list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss streaming-endpoint get <id> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("streaming-endpoint", "get"));
             return c.streamingEndpoints.getSettings(a[0], f["project-key"]);
         },
-        usage: "dss streaming-endpoint get <id> [--project-key KEY]",
         description: "Get a streaming endpoint's settings.",
         examples: ["dss streaming-endpoint get my-stream",],
     },
     create: {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("streaming-endpoint", "create"));
             const body = jsonInput(f) ?? {};
             return c.streamingEndpoints.create(a[0], a[1], body, f["project-key"]);
         },
-        usage: "dss streaming-endpoint create <id> <type> [--data JSON|--data-file PATH|--stdin] [--project-key KEY]",
         description: "Create a streaming endpoint of the given type.",
         examples: ["dss streaming-endpoint create my-stream kafka",],
     },
     "update-settings": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("streaming-endpoint", "update-settings"));
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (endpoint settings).");
             await c.streamingEndpoints.updateSettings(a[0], body, f["project-key"]);
             return { updated: a[0], };
         },
-        usage: "dss streaming-endpoint update-settings <id> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
         description: "Replace a streaming endpoint's settings.",
         examples: ["dss streaming-endpoint update-settings my-stream --data-file settings.json",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss streaming-endpoint delete <id> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("streaming-endpoint", "delete"));
             await c.streamingEndpoints.delete(a[0], f["project-key"]);
             return { deleted: a[0], };
         },
-        usage: "dss streaming-endpoint delete <id> [--project-key KEY]",
         description: "Delete a streaming endpoint.",
         examples: ["dss streaming-endpoint delete my-stream",],
     },
-};
+});

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

@@ -2,6 +2,7 @@ import { normalizeSecretKey, sanitizeSecrets, } from "../../utils/secret-sanitiz
 import { requiredJsonInput, splitCsvFlag, } 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";
 /** Credential-bearing user keys, matched after stripping -/_ and lowercasing. */
 const SENSITIVE_USER_NORMALIZED_KEYS = {
@@ -77,26 +78,24 @@ function requireLogin(value, usage) {
     }
     return trimmed;
 }
-export const userCommands = {
+export const userCommands = withUsage("user", {
     list: {
         handler: (c, _a, f) => c.users.list(f["connected"] === true ? { connected: true, } : undefined),
-        usage: "dss user list [--connected]",
         description: "List DSS users (admin). --connected reports currently connected users via WebSockets, which may under-report when WebSockets are disabled.",
         examples: ["dss user list", "dss user list --connected",],
     },
     get: {
         handler: (c, a) => {
-            const usage = "dss user get <login>";
+            const usage = commandUsage("user", "get");
             requireArgs(a, 1, usage);
             return c.users.get(requireLogin(a[0], usage));
         },
-        usage: "dss user get <login>",
         description: "Get a DSS user (admin).",
         examples: ["dss user get admin",],
     },
     create: {
         handler: async (c, _a, f) => {
-            const usage = "dss user create (--data JSON|--data-file PATH|--stdin)";
+            const usage = commandUsage("user", "create");
             const body = requiredUserJson(f, usage);
             if (executionMode(f).dryRun) {
                 return {
@@ -112,7 +111,6 @@ export const userCommands = {
             const result = await c.users.create(body);
             return sanitizeUserSecrets(result, userSecretsFromBody(body));
         },
-        usage: "dss user create (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: 'Create a DSS user (admin). The JSON body follows the DSS User schema, e.g. {"login":"UserA","sourceType":"LOCAL","displayName":"User A","groups":[],"userProfile":"DATA_ANALYST","password":"..."}. Secrets are never echoed in output.',
         examples: [
             `dss user create --data '{"login":"UserA","sourceType":"LOCAL","displayName":"User A","groups":[],"userProfile":"DATA_ANALYST","password":"s3cret"}'`,
@@ -120,7 +118,7 @@ export const userCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            const usage = "dss user update <login> (--data JSON|--data-file PATH|--stdin) [--dry-run]";
+            const usage = commandUsage("user", "update");
             requireArgs(a, 1, usage);
             const login = requireLogin(a[0], usage);
             const body = requiredUserJson(f, usage);
@@ -139,7 +137,6 @@ export const userCommands = {
             const result = await c.users.update(login, body);
             return sanitizeUserSecrets(result, userSecretsFromBody(body));
         },
-        usage: "dss user update <login> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: "Update a DSS user (admin). The body MUST be the User object obtained from `dss user get` (PUT semantics); pass undocumented attributes through unchanged. Use --dry-run to preview the merged result without writing.",
         examples: [
             `dss user update UserA --data '{"login":"UserA","displayName":"User A2","groups":["administrators"],"codeAllowed":true}'`,
@@ -147,7 +144,7 @@ export const userCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            const usage = "dss user delete <login> [--if-exists] [--dry-run]";
+            const usage = commandUsage("user", "delete");
             requireArgs(a, 1, usage);
             const login = requireLogin(a[0], usage);
             if (executionMode(f).dryRun) {
@@ -170,13 +167,12 @@ export const userCommands = {
             }
             return c.users.delete(login);
         },
-        usage: "dss user delete <login> [--if-exists] [--dry-run]",
         description: "Delete a DSS user (admin). Destructive and irreversible.",
         examples: ["dss user delete UserA", "dss user delete UserA --if-exists",],
     },
     resync: {
         handler: async (c, a, f) => {
-            const usage = "dss user resync <login>";
+            const usage = commandUsage("user", "resync");
             requireArgs(a, 1, usage);
             const login = requireLogin(a[0], usage);
             if (executionMode(f).dryRun) {
@@ -191,7 +187,6 @@ export const userCommands = {
             }
             return c.users.resync(login);
         },
-        usage: "dss user resync <login> [--dry-run]",
         description: "Resync one DSS user (admin). Returns a DSS future; poll with `dss future wait <jobId>` when hasResult is false.",
         examples: ["dss user resync UserA",],
     },
@@ -199,7 +194,7 @@ export const userCommands = {
         handler: async (c, _a, f) => {
             const logins = splitCsvFlag(f["logins"]);
             if (logins.length === 0) {
-                throw new UsageError("--logins is required. Usage: dss user resync-multi --logins user1,user2", "missing_required_flag");
+                throw new UsageError(`--logins is required. Usage: ${commandUsage("user", "resync-multi")}`, "missing_required_flag");
             }
             if (executionMode(f).dryRun) {
                 return {
@@ -214,7 +209,6 @@ export const userCommands = {
             }
             return c.users.resyncMulti(logins);
         },
-        usage: "dss user resync-multi --logins CSV [--dry-run]",
         description: "Resync multiple DSS users (admin). Returns a DSS future.",
         examples: ["dss user resync-multi --logins user1,user2,user3",],
     },
@@ -232,7 +226,6 @@ export const userCommands = {
             }
             return c.users.externalUsers();
         },
-        usage: "dss user external-users [--dry-run]",
         description: "Fetch externally sourced users and their provisioning status (admin). Returns a DSS future whose result is the external user list when hasResult is true.",
         examples: ["dss user external-users",],
     },
@@ -250,13 +243,12 @@ export const userCommands = {
             }
             return c.users.externalGroups();
         },
-        usage: "dss user external-groups [--dry-run]",
         description: "Fetch externally sourced groups (admin). Returns a DSS future whose result is the external group name list when hasResult is true.",
         examples: ["dss user external-groups",],
     },
     provision: {
         handler: async (c, _a, f) => {
-            const usage = "dss user provision (--data JSON|--data-file PATH|--stdin)";
+            const usage = commandUsage("user", "provision");
             const body = requiredJsonInput(f, `--data, --data-file, or --stdin is required (provisioning request). Usage: ${usage}`);
             if (executionMode(f).dryRun) {
                 return {
@@ -271,7 +263,6 @@ export const userCommands = {
             }
             return c.users.provision(body);
         },
-        usage: "dss user provision (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: "Provision users from an external source (admin). Body is the documented {userSourceType, users[]} request; returns a DSS future with a provisioning summary.",
         examples: [
             `dss user provision --data '{"userSourceType":"AZURE_AD","users":[{"login":"bob","displayName":"Bob","sourceGroupNames":["externalGroupA"],"dkuGroupNames":["dssGroupA"]}]}'`,
@@ -279,18 +270,16 @@ export const userCommands = {
     },
     activity: {
         handler: (c) => c.users.activityAll(),
-        usage: "dss user activity",
         description: "Get last activity timestamps for all DSS users (admin).",
         examples: ["dss user activity",],
     },
     "activity-get": {
         handler: (c, a) => {
-            const usage = "dss user activity-get <login>";
+            const usage = commandUsage("user", "activity-get");
             requireArgs(a, 1, usage);
             return c.users.activity(requireLogin(a[0], usage));
         },
-        usage: "dss user activity-get <login>",
         description: "Get last activity timestamps for one DSS user (admin).",
         examples: ["dss user activity-get UserA",],
     },
-};
+});

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

@@ -1,10 +1,10 @@
 import { json, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { withUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
-export const variableCommands = {
+export const variableCommands = withUsage("variable", {
     get: {
         handler: (c, _a, f) => c.variables.get(f["project-key"]),
-        usage: "dss variable get [--project-key KEY]",
         description: "Get project variables (standard and local).",
         examples: ["dss variable get", "dss variable get --project-key MYPROJ",],
     },
@@ -40,11 +40,10 @@ export const variableCommands = {
                 projectKey: pk,
             });
         },
-        usage: `dss variable set (--standard '{"k":"v"}'|--local '{"k":"v"}') [--replace] [--dry-run] [--project-key KEY]`,
         description: "Set project variables via JSON merge (or full replace with --replace).",
         examples: [
             'dss variable set --standard \'{"env":"staging"}\' --dry-run',
             "dss variable set --local '{\"debug\":true}' --replace",
         ],
     },
-};
+});

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

@@ -1,32 +1,31 @@
 import { ClientValidationError, } from "../../errors.js";
 import { deepMerge, } from "../../utils/deep-merge.js";
-import { stableHash, } from "../../utils/stable-hash.js";
+import { SHA256_HEX_PATTERN, stableHash, } from "../../utils/stable-hash.js";
 import { num, requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-const UPDATE_SETTINGS_USAGE = "dss webapp update-settings <webappId> (--data JSON|--data-file PATH|--stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]";
-const RESTART_USAGE = "dss webapp restart-backend <webappId> [--wait] [--timeout MS] [--poll-interval MS] [--project-key KEY]";
+const UPDATE_SETTINGS_USAGE = commandUsage("webapp", "update-settings");
+const RESTART_USAGE = commandUsage("webapp", "restart-backend");
 function validateExpectHash(value) {
     if (value === undefined || value === false)
         return undefined;
-    if (typeof value !== "string" || !/^[0-9a-fA-F]{64}$/.test(value)) {
+    if (typeof value !== "string" || !SHA256_HEX_PATTERN.test(value)) {
         throw new ClientValidationError("Expected webapp hash must be a 64-character SHA-256 hex digest.", "validation_failed", "Run this update with --dry-run and capture currentHash before retrying.");
     }
     return value;
 }
-export const webappCommands = {
+export const webappCommands = withUsage("webapp", {
     list: {
         handler: (c, _a, f) => c.webapps.list(f["project-key"]),
-        usage: "dss webapp list [--project-key KEY]",
         description: "List webapps in a project.",
         examples: ["dss webapp list",],
     },
     "get-settings": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss webapp get-settings <webappId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("webapp", "get-settings"));
             return c.webapps.getSettings(a[0], f["project-key"]);
         },
-        usage: "dss webapp get-settings <webappId> [--project-key KEY]",
         description: "Get a webapp's settings.",
         examples: ["dss webapp get-settings WEBAPP_ID",],
     },
@@ -35,7 +34,6 @@ export const webappCommands = {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (webapp definition).");
             return c.webapps.create(body, f["project-key"]);
         },
-        usage: "dss webapp create (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
         description: "Create a webapp from a JSON definition.",
         examples: ["dss webapp create --data-file webapp.json",],
     },
@@ -73,7 +71,6 @@ export const webappCommands = {
             const updated = await c.webapps.updateSettings(a[0], body, projectKey, { expectHash, });
             return { updated: a[0], ...updated, };
         },
-        usage: UPDATE_SETTINGS_USAGE,
         description: "Merge supplied fields into a webapp's settings (GET-merge-PUT) and PUT the full object, so fields outside the patch are never dropped. --expect-hash refuses the write when the object changed since it was fetched; --dry-run reports current, next, and both hashes without writing.",
         examples: [
             "dss webapp update-settings WEBAPP_ID --data-file webapp.json",
@@ -82,11 +79,10 @@ export const webappCommands = {
     },
     "stop-backend": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss webapp stop-backend <webappId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("webapp", "stop-backend"));
             await c.webapps.stopBackend(a[0], f["project-key"]);
             return { stopped: true, };
         },
-        usage: "dss webapp stop-backend <webappId> [--project-key KEY]",
         description: "Stop a webapp's backend.",
         examples: ["dss webapp stop-backend WEBAPP_ID",],
     },
@@ -103,7 +99,6 @@ export const webappCommands = {
             const future = await c.webapps.startOrRestartBackend(a[0], projectKey);
             return { restarted: true, future, };
         },
-        usage: RESTART_USAGE,
         description: "Start or restart a webapp's backend. The documented endpoint returns a restart future; --wait settles it and returns the FutureWaitResult.",
         examples: [
             "dss webapp restart-backend WEBAPP_ID",
@@ -112,11 +107,10 @@ export const webappCommands = {
     },
     "backend-state": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss webapp backend-state <webappId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("webapp", "backend-state"));
             return c.webapps.getBackendState(a[0], f["project-key"]);
         },
-        usage: "dss webapp backend-state <webappId> [--project-key KEY]",
         description: "Get a webapp backend's runtime state.",
         examples: ["dss webapp backend-state WEBAPP_ID",],
     },
-};
+});

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

@@ -2,34 +2,33 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { jsonInput, 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 wikiCommands = {
+export const wikiCommands = withUsage("wiki", {
     settings: {
         handler: (c, _a, f) => c.wiki.settings(f["project-key"]),
-        usage: "dss wiki settings [--project-key KEY]",
         description: "Get project wiki settings and taxonomy.",
         examples: ["dss wiki settings",],
     },
     list: {
         handler: (c, _a, f) => c.wiki.list(f["project-key"]),
-        usage: "dss wiki list [--project-key KEY]",
         description: "List wiki articles by walking the taxonomy.",
         examples: ["dss wiki list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss wiki get <id-or-name>");
+            requireArgs(a, 1, commandUsage("wiki", "get"));
             return c.wiki.get(a[0], f["project-key"]);
         },
-        usage: "dss wiki get <id-or-name> [--project-key KEY]",
         description: "Get a wiki article including markdown body.",
         examples: ["dss wiki get ARTICLE_ID",],
     },
     create: {
         handler: async (c, _a, f) => {
             const name = f["name"];
-            if (!name)
-                throw new UsageError("--name is required. Usage: dss wiki create --name NAME");
+            if (!name) {
+                throw new UsageError(`--name is required. Usage: ${commandUsage("wiki", "create")}`);
+            }
             const content = textInput(f);
             const pk = f["project-key"];
             if (f["if-not-exists"] === true || executionMode(f).dryRun) {
@@ -60,7 +59,6 @@ export const wikiCommands = {
             });
             return { created: created.article.id, resource: "wiki", ...created, };
         },
-        usage: "dss wiki create --name NAME [--parent ID] [--content TEXT|--file PATH] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a wiki article, optionally with markdown content.",
         examples: [
             "dss wiki create --name 'Agent notes' --content '# Notes'",
@@ -69,7 +67,7 @@ export const wikiCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss wiki update <id-or-name> [--name NAME] [--content TEXT|--file PATH|--data JSON]");
+            requireArgs(a, 1, commandUsage("wiki", "update"));
             const data = jsonInput(f);
             const content = textInput(f);
             const name = f["name"];
@@ -98,13 +96,12 @@ export const wikiCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss wiki update <id-or-name> (--name NAME | --content TEXT|--file PATH|--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Update wiki article metadata/body via merge.",
         examples: ["dss wiki update ARTICLE_ID --content '# Updated' --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss wiki delete <id-or-name>");
+            requireArgs(a, 1, commandUsage("wiki", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.wiki.get(a[0], pk));
@@ -117,8 +114,7 @@ export const wikiCommands = {
             await c.wiki.delete(a[0], pk);
             return { deleted: a[0], resource: "wiki", };
         },
-        usage: "dss wiki delete <id-or-name> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a wiki article.",
         examples: ["dss wiki delete ARTICLE_ID --dry-run",],
     },
-};
+});

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

@@ -1,18 +1,17 @@
 import { requiredJsonInput, } from "../coerce.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const workspaceCommands = {
+export const workspaceCommands = withUsage("workspace", {
     list: {
         handler: (c) => c.workspaces.list(),
-        usage: "dss workspace list",
         description: "List collaboration workspaces on the instance.",
         examples: ["dss workspace list",],
     },
     get: {
         handler: (c, a) => {
-            requireArgs(a, 1, "dss workspace get <workspaceKey>");
+            requireArgs(a, 1, commandUsage("workspace", "get"));
             return c.workspaces.get(a[0]);
         },
-        usage: "dss workspace get <workspaceKey>",
         description: "Get a workspace's settings.",
         examples: ["dss workspace get MY_WS",],
     },
@@ -21,48 +20,43 @@ export const workspaceCommands = {
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace definition).");
             return c.workspaces.create(body);
         },
-        usage: "dss workspace create (--data JSON|--data-file PATH|--stdin)",
         description: "Create a collaboration workspace.",
         examples: ["dss workspace create --data-file ws.json",],
     },
     "update-settings": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+            requireArgs(a, 1, commandUsage("workspace", "update-settings"));
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (workspace settings).");
             await c.workspaces.updateSettings(a[0], body);
             return { updated: a[0], };
         },
-        usage: "dss workspace update-settings <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
         description: "Replace a workspace's settings (admin).",
         examples: ["dss workspace update-settings MY_WS --data-file ws.json",],
     },
     delete: {
         handler: async (c, a) => {
-            requireArgs(a, 1, "dss workspace delete <workspaceKey>");
+            requireArgs(a, 1, commandUsage("workspace", "delete"));
             await c.workspaces.delete(a[0]);
             return { deleted: a[0], };
         },
-        usage: "dss workspace delete <workspaceKey>",
         description: "Delete a workspace (admin).",
         examples: ["dss workspace delete MY_WS",],
     },
     "list-objects": {
         handler: (c, a) => {
-            requireArgs(a, 1, "dss workspace list-objects <workspaceKey>");
+            requireArgs(a, 1, commandUsage("workspace", "list-objects"));
             return c.workspaces.listObjects(a[0]);
         },
-        usage: "dss workspace list-objects <workspaceKey>",
         description: "List objects shared in a workspace.",
         examples: ["dss workspace list-objects MY_WS",],
     },
     "add-object": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)");
+            requireArgs(a, 1, commandUsage("workspace", "add-object"));
             const object = requiredJsonInput(f, "--data, --data-file, or --stdin is required (object definition).");
             return c.workspaces.addObject(a[0], object);
         },
-        usage: "dss workspace add-object <workspaceKey> (--data JSON|--data-file PATH|--stdin)",
         description: "Add an object (link or DSS object) to a workspace.",
         examples: ["dss workspace add-object MY_WS --data-file object.json",],
     },
-};
+});