dataiku-sdk 3.4.0 → 3.5.0

package/dist/src/cli/commands/saved-model.js

@@ -1,23 +1,24 @@
+import { unexpectedResponseError, } from "../../errors.js";
 import { writeResponseToFile, } from "../../utils/response-file.js";
 import { json, jsonInput, parseBooleanOption, 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";
 /**
  * Mutating actions accept --plan (buildMutationPlan in contract.ts owns the
  * --plan path centrally); the handlers below keep --dry-run support with a
  * zero-request planned payload, mirroring set-active/delete.
  */
-export const savedModelCommands = {
+export const savedModelCommands = withUsage("saved-model", {
     list: {
         handler: (c, _a, f) => c.savedModels.list(f["project-key"]),
-        usage: "dss saved-model list [--project-key KEY]",
         description: "List saved models in a project.",
         examples: ["dss saved-model list --project-key PROJECT",],
     },
     "create-external": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model create-external <name> --type MLFLOW_PYFUNC|PROXY_MODEL [--prediction-type TYPE] [--configuration JSON] [--data JSON] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "create-external");
             requireArgs(a, 1, usage);
             const savedModelType = f["type"]?.trim();
             if (savedModelType !== "MLFLOW_PYFUNC" && savedModelType !== "PROXY_MODEL") {
@@ -66,7 +67,6 @@ export const savedModelCommands = {
                     : {}),
             }, projectKey);
         },
-        usage: "dss saved-model create-external <name> --type MLFLOW_PYFUNC|PROXY_MODEL [--prediction-type TYPE] [--configuration JSON] [--data JSON] [--dry-run] [--project-key KEY]",
         description: "Create a saved model for MLflow or external (proxy) models. --type selects savedModelType; --prediction-type is BINARY_CLASSIFICATION, MULTICLASS, or REGRESSION; --configuration (JSON via --data/--data-file/--stdin) is the PROXY_MODEL protocol configuration forwarded as proxyModelConfiguration.",
         examples: [
             "dss saved-model create-external 'MLflow Demo' --type MLFLOW_PYFUNC --prediction-type BINARY_CLASSIFICATION",
@@ -75,16 +75,15 @@ export const savedModelCommands = {
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss saved-model get <modelId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("saved-model", "get"));
             return c.savedModels.get(a[0], f["project-key"]);
         },
-        usage: "dss saved-model get <modelId> [--project-key KEY]",
         description: "Get a saved model.",
         examples: ["dss saved-model get MODEL_ID --project-key PROJECT",],
     },
     "update-settings": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model update-settings <modelId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "update-settings");
             requireArgs(a, 1, usage);
             const settings = requiredJsonInput(f, "Saved-model settings JSON is required via --data, --data-file, or --stdin (GET-then-PUT the full settings document).");
             const projectKey = f["project-key"];
@@ -103,7 +102,6 @@ export const savedModelCommands = {
                 resource: "saved-model",
             }));
         },
-        usage: "dss saved-model update-settings <modelId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: "Save the settings of a saved model. The payload must be the complete settings document as returned by `saved-model get` (GET-then-PUT workflow, per the official client).",
         examples: [
             "dss saved-model get MODEL_ID --project-key P | jq . > settings.json && dss saved-model update-settings MODEL_ID --data-file settings.json --project-key P",
@@ -111,19 +109,17 @@ export const savedModelCommands = {
     },
     "list-versions": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss saved-model list-versions <modelId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("saved-model", "list-versions"));
             return c.savedModels.listVersions(a[0], f["project-key"]);
         },
-        usage: "dss saved-model list-versions <modelId> [--project-key KEY]",
         description: "List versions of a saved model.",
         examples: ["dss saved-model list-versions MODEL_ID --project-key PROJECT",],
     },
     "version-details": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss saved-model version-details <modelId> <versionId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("saved-model", "version-details"));
             return c.savedModels.versionDetails(a[0], a[1], f["project-key"]);
         },
-        usage: "dss saved-model version-details <modelId> <versionId> [--project-key KEY]",
         description: "Get details for one saved-model version.",
         examples: [
             "dss saved-model version-details MODEL_ID VERSION_ID --project-key PROJECT",
@@ -131,10 +127,9 @@ export const savedModelCommands = {
     },
     "version-snippet": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss saved-model version-snippet <modelId> <versionId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("saved-model", "version-snippet"));
             return c.savedModels.versionSnippet(a[0], a[1], f["project-key"]);
         },
-        usage: "dss saved-model version-snippet <modelId> <versionId> [--project-key KEY]",
         description: "Get the snippet (short summary) for one saved-model version.",
         examples: [
             "dss saved-model version-snippet MODEL_ID VERSION_ID --project-key PROJECT",
@@ -142,7 +137,7 @@ export const savedModelCommands = {
     },
     "set-active": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss saved-model set-active <modelId> <versionId> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("saved-model", "set-active"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
                 return {
@@ -157,7 +152,6 @@ export const savedModelCommands = {
             }
             return c.savedModels.setActiveVersion(a[0], a[1], projectKey);
         },
-        usage: "dss saved-model set-active <modelId> <versionId> [--dry-run] [--project-key KEY]",
         description: "Set the active version of a saved model.",
         examples: [
             "dss saved-model set-active MODEL_ID VERSION_ID --project-key PROJECT",
@@ -166,7 +160,7 @@ export const savedModelCommands = {
     },
     "delete-versions": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model delete-versions <modelId> <versionsCSV> [--remove-intermediate true|false] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "delete-versions");
             requireArgs(a, 2, usage);
             const versions = a[1].split(",").map((v) => v.trim()).filter((v) => v.length > 0);
             if (versions.length === 0) {
@@ -188,7 +182,6 @@ export const savedModelCommands = {
             await c.savedModels.deleteVersions(versions, { removeIntermediate, }, a[0], projectKey);
             return { deletedVersions: versions, resource: "saved-model", id: a[0], };
         },
-        usage: "dss saved-model delete-versions <modelId> <versionsCSV> [--remove-intermediate true|false] [--dry-run] [--project-key KEY]",
         description: "Delete one or more versions of a saved model (comma-separated version ids). Destructive. Implemented as POST .../actions/delete-versions per the official Python client (the REST reference's GET entry is a doc bug); the transport never retries this request.",
         examples: [
             "dss saved-model delete-versions MODEL_ID VERSION_A,VERSION_B --project-key PROJECT",
@@ -197,7 +190,7 @@ export const savedModelCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss saved-model delete <modelId> [--if-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("saved-model", "delete"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.savedModels.get(a[0], projectKey));
@@ -210,7 +203,6 @@ export const savedModelCommands = {
             await c.savedModels.delete(a[0], projectKey);
             return { deleted: a[0], resource: "saved-model", };
         },
-        usage: "dss saved-model delete <modelId> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a saved model.",
         examples: [
             "dss saved-model delete MODEL_ID --if-exists --project-key PROJECT",
@@ -219,7 +211,7 @@ export const savedModelCommands = {
     },
     "import-mlflow-version": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model import-mlflow-version <modelId> <versionId> --archive PATH [--code-env NAME] [--container-exec-config NAME] [--set-active true|false] [--binary-classification-threshold N] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "import-mlflow-version");
             requireArgs(a, 2, usage);
             const archive = f["archive"];
             if (!archive)
@@ -239,7 +231,6 @@ export const savedModelCommands = {
             }
             return c.savedModels.importMlflowVersion(archive, a[1], options, a[0], projectKey);
         },
-        usage: "dss saved-model import-mlflow-version <modelId> <versionId> --archive PATH [--code-env NAME] [--container-exec-config NAME] [--set-active true|false] [--binary-classification-threshold N] [--dry-run] [--project-key KEY]",
         description: "Import a new MLflow version from a local zip archive of the MLflow model folder (multipart upload). The saved model must be of type MLFLOW_PYFUNC.",
         examples: [
             "dss saved-model import-mlflow-version MODEL_ID v1 --archive ./mlflow-model.zip --project-key PROJECT",
@@ -248,7 +239,7 @@ export const savedModelCommands = {
     },
     "import-mlflow-version-from-folder": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model import-mlflow-version-from-folder <modelId> <versionId> --folder PROJECT.FOLDER_ID --path PATH [--code-env NAME] [--container-exec-config NAME] [--set-active true|false] [--binary-classification-threshold N] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "import-mlflow-version-from-folder");
             requireArgs(a, 2, usage);
             const folder = f["folder"];
             if (!folder) {
@@ -272,7 +263,6 @@ export const savedModelCommands = {
             }
             return c.savedModels.importMlflowVersionFromFolder(folder, path, a[1], options, a[0], projectKey);
         },
-        usage: "dss saved-model import-mlflow-version-from-folder <modelId> <versionId> --folder PROJECT.FOLDER_ID --path PATH [--code-env NAME] [--container-exec-config NAME] [--set-active true|false] [--binary-classification-threshold N] [--dry-run] [--project-key KEY]",
         description: "Import a new MLflow version from an MLflow model folder stored in a managed folder (folderRef PROJECT_KEY.FOLDER_ID). Sends the backend-mandated multipart request with a zero-byte file part, matching the official Python client.",
         examples: [
             "dss saved-model import-mlflow-version-from-folder MODEL_ID v1 --folder PROJ.z7pSyYzE --path /artifacts/model --project-key PROJ",
@@ -280,10 +270,9 @@ export const savedModelCommands = {
     },
     "external-metadata-get": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss saved-model external-metadata-get <modelId> <versionId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("saved-model", "external-metadata-get"));
             return c.savedModels.externalMetadataGet(a[0], a[1], f["project-key"]);
         },
-        usage: "dss saved-model external-metadata-get <modelId> <versionId> [--project-key KEY]",
         description: "Get the external-ml metadata of a saved-model version (MLflow or proxy).",
         examples: [
             "dss saved-model external-metadata-get MODEL_ID VERSION_ID --project-key PROJECT",
@@ -291,7 +280,7 @@ export const savedModelCommands = {
     },
     "external-metadata-put": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model external-metadata-put <modelId> <versionId> (--data JSON|--data-file PATH|--stdin) [--container-exec-config NAME] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "external-metadata-put");
             requireArgs(a, 2, usage);
             const metadata = requiredJsonInput(f, "Metadata JSON is required via --data, --data-file, or --stdin (GET-then-PUT the full external-ml metadata document).");
             const projectKey = f["project-key"];
@@ -312,7 +301,6 @@ export const savedModelCommands = {
             }
             return c.savedModels.externalMetadataPut(a[0], a[1], metadata, containerExecConfigName === undefined ? undefined : { containerExecConfigName, }, projectKey).then(() => ({ updated: a[0], versionId: a[1], resource: "saved-model", }));
         },
-        usage: "dss saved-model external-metadata-put <modelId> <versionId> (--data JSON|--data-file PATH|--stdin) [--container-exec-config NAME] [--dry-run] [--project-key KEY]",
         description: "Save the external-ml metadata of a saved-model version. The payload must be the full metadata document as returned by external-metadata-get (GET-then-PUT). DSS requires the containerExecConfigName query parameter; it defaults to NONE for an external API caller (LOCAL-CONFIG resolution) when --container-exec-config is omitted.",
         examples: [
             "dss saved-model external-metadata-put MODEL_ID VERSION_ID --data-file metadata.json --project-key PROJECT",
@@ -320,7 +308,7 @@ export const savedModelCommands = {
     },
     "evaluate-version": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model evaluate-version <modelId> <versionId> --dataset REF [--container-exec-config NAME] [--sampling JSON] [--use-optimal-threshold true|false] [--skip-expensive-reports true|false] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "evaluate-version");
             requireArgs(a, 2, usage);
             const dataset = f["dataset"];
             if (!dataset)
@@ -367,7 +355,6 @@ export const savedModelCommands = {
             await c.savedModels.evaluateVersion(body, options, a[0], a[1], projectKey);
             return { evaluated: a[0], versionId: a[1], resource: "saved-model", };
         },
-        usage: "dss saved-model evaluate-version <modelId> <versionId> --dataset REF [--container-exec-config NAME] [--sampling JSON] [--use-optimal-threshold true|false] [--skip-expensive-reports true|false] [--dry-run] [--project-key KEY]",
         description: 'Evaluate an external/MLflow model version on a dataset. external-metadata-put must have been called first. --sampling is an optional JSON sampling parameter (e.g. {"samplingMethod":"HEAD_SEQUENTIAL","maxRecords":100}).',
         examples: [
             "dss saved-model evaluate-version MODEL_ID VERSION_ID --dataset PROJECT.my-dataset --project-key PROJECT",
@@ -376,7 +363,7 @@ export const savedModelCommands = {
     },
     "download-scoring-jar": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model download-scoring-jar <modelId> <versionId> --output PATH [--full-class-name NAME] [--include-libs true|false] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "download-scoring-jar");
             requireArgs(a, 2, usage);
             const out = f["output"];
             if (!out)
@@ -390,12 +377,11 @@ export const savedModelCommands = {
             };
             const res = await c.savedModels.downloadScoringJar(jarOptions, a[0], a[1], f["project-key"]);
             if (!res.body) {
-                throw new Error("savedModels.downloadScoringJar response did not include a body");
+                throw unexpectedResponseError("savedModels.downloadScoringJar response did not include a body");
             }
             const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
-        usage: "dss saved-model download-scoring-jar <modelId> <versionId> --output PATH [--full-class-name NAME] [--include-libs true|false] [--project-key KEY]",
         description: "Download the optimized scoring JAR of a version (license-gated server side). --full-class-name forwards the documented fullClassName query parameter; --include-libs toggles including scoring libraries.",
         examples: [
             "dss saved-model download-scoring-jar MODEL_ID VERSION_ID --output ./scoring.jar --project-key PROJECT",
@@ -404,18 +390,17 @@ export const savedModelCommands = {
     },
     "download-scoring-pmml": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss saved-model download-scoring-pmml <modelId> <versionId> --output PATH [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("saved-model", "download-scoring-pmml"));
             const out = f["output"];
             if (!out)
                 throw new UsageError("--output PATH is required.", "missing_required_flag");
             const res = await c.savedModels.downloadScoringPmml(a[0], a[1], f["project-key"]);
             if (!res.body) {
-                throw new Error("savedModels.downloadScoringPmml response did not include a body");
+                throw unexpectedResponseError("savedModels.downloadScoringPmml response did not include a body");
             }
             const bytes = await writeResponseToFile(out, res);
             return { path: out, bytes, };
         },
-        usage: "dss saved-model download-scoring-pmml <modelId> <versionId> --output PATH [--project-key KEY]",
         description: "Download the PMML scoring file of a version (license-gated server side).",
         examples: [
             "dss saved-model download-scoring-pmml MODEL_ID VERSION_ID --output ./model.pmml --project-key PROJECT",
@@ -423,7 +408,7 @@ export const savedModelCommands = {
     },
     "set-user-meta": {
         handler: async (c, a, f) => {
-            const usage = "dss saved-model set-user-meta <modelId> <versionId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("saved-model", "set-user-meta");
             requireArgs(a, 2, usage);
             const userMeta = requiredJsonInput(f, "User-meta JSON is required via --data, --data-file, or --stdin.");
             const projectKey = f["project-key"];
@@ -444,13 +429,12 @@ export const savedModelCommands = {
                 resource: "saved-model",
             }));
         },
-        usage: "dss saved-model set-user-meta <modelId> <versionId> (--data JSON|--data-file PATH|--stdin) [--dry-run] [--project-key KEY]",
         description: 'Update the user metadata of a model version. Send only the "userMeta" field of a previously-retrieved version-details object.',
         examples: [
             'dss saved-model set-user-meta MODEL_ID VERSION_ID --data \'{"name":"Churn model","description":"v2"}\' --project-key PROJECT',
         ],
     },
-};
+});
 function mlflowImportOptions(f) {
     const codeEnvName = f["code-env"];
     const containerExecConfigName = f["container-exec-config"];

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

@@ -1,26 +1,25 @@
 import { jsonInput, num, parseBooleanOption, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { encodedProjectEndpoint, readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const scenarioCommands = {
+export const scenarioCommands = withUsage("scenario", {
     list: {
         handler: (c, _a, f) => c.scenarios.list(f["project-key"]),
-        usage: "dss scenario list [--project-key KEY]",
         description: "List all scenarios in a project.",
         examples: ["dss scenario list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss scenario get <id>");
+            requireArgs(a, 1, commandUsage("scenario", "get"));
             return c.scenarios.get(a[0], { projectKey: f["project-key"], });
         },
-        usage: "dss scenario get <id> [--project-key KEY]",
         description: "Get raw scenario definition. For step-based scenario edits, patch params.steps; rawParams.params is DSS echo data.",
         examples: ["dss scenario get my_scenario",],
     },
     run: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario run <id>");
+            requireArgs(a, 1, commandUsage("scenario", "run"));
             const pk = f["project-key"];
             const options = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
@@ -42,13 +41,12 @@ export const scenarioCommands = {
             }
             return c.scenarios.run(a[0], pk);
         },
-        usage: "dss scenario run <id> [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
         description: "Trigger a scenario run, optionally waiting for completion.",
         examples: ["dss scenario run my_scenario", "dss scenario run my_scenario --wait",],
     },
     "run-and-wait": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario run-and-wait <id>");
+            requireArgs(a, 1, commandUsage("scenario", "run-and-wait"));
             const pk = f["project-key"];
             const options = {
                 pollIntervalMs: num(f["poll-interval"], "--poll-interval"),
@@ -67,7 +65,6 @@ export const scenarioCommands = {
             }
             return c.scenarios.runAndWait(a[0], { ...options, projectKey: pk, });
         },
-        usage: "dss scenario run-and-wait <id> [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
         description: "Run a scenario and wait for completion.",
         examples: [
             "dss scenario run-and-wait my_scenario",
@@ -76,16 +73,15 @@ export const scenarioCommands = {
     },
     status: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss scenario status <id>");
+            requireArgs(a, 1, commandUsage("scenario", "status"));
             return c.scenarios.status(a[0], f["project-key"]);
         },
-        usage: "dss scenario status <id> [--project-key KEY]",
         description: "Get the current run status of a scenario.",
         examples: ["dss scenario status my_scenario",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario delete <id>");
+            requireArgs(a, 1, commandUsage("scenario", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.scenarios.get(a[0], { projectKey: pk, }));
@@ -98,13 +94,12 @@ export const scenarioCommands = {
             await c.scenarios.delete(a[0], pk);
             return { deleted: a[0], resource: "scenario", };
         },
-        usage: "dss scenario delete <id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a scenario.",
         examples: ["dss scenario delete my_scenario", "dss scenario delete my_scenario --if-exists",],
     },
     create: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss scenario create <id> <name>");
+            requireArgs(a, 2, commandUsage("scenario", "create"));
             const pk = f["project-key"];
             const payload = {
                 scenarioId: a[0],
@@ -135,7 +130,6 @@ export const scenarioCommands = {
             });
             return { created: a[0], name: a[1], resource: "scenario", };
         },
-        usage: "dss scenario create <id> <name> [--type step_based|custom_python] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a new scenario.",
         examples: [
             'dss scenario create my_scenario "My Scenario"',
@@ -144,10 +138,10 @@ export const scenarioCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("scenario", "update"));
             const data = jsonInput(f);
             if (data === undefined) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("scenario", "update")}`);
             }
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -181,7 +175,6 @@ export const scenarioCommands = {
                 unchangedPaths: result.unchangedPaths,
             };
         },
-        usage: "dss scenario update <id> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Update scenario settings via JSON merge; edit step-based scenario steps at params.steps, not rawParams.params.steps.",
         examples: [
             'dss scenario update my_scenario --data \'{"params":{"steps":[]}}\' --dry-run',
@@ -190,7 +183,7 @@ export const scenarioCommands = {
     },
     abort: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario abort <id>");
+            requireArgs(a, 1, commandUsage("scenario", "abort"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
                 return {
@@ -205,36 +198,33 @@ export const scenarioCommands = {
             await c.scenarios.abort(a[0], pk);
             return { aborted: a[0], resource: "scenario", };
         },
-        usage: "dss scenario abort <id> [--dry-run] [--project-key KEY]",
         description: "Abort a running scenario. Returns when DSS accepts the abort; the scenario may take time to stop.",
         examples: ["dss scenario abort my_scenario",],
     },
     "last-runs": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss scenario last-runs <id>");
+            requireArgs(a, 1, commandUsage("scenario", "last-runs"));
             return c.scenarios.getLastRuns(a[0], {
                 limit: num(f["limit"], "--limit"),
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss scenario last-runs <id> [--limit N] [--project-key KEY]",
         description: "List the most recent runs of a scenario (run id, start/end, outcome).",
         examples: ["dss scenario last-runs my_scenario --limit 10",],
     },
     "get-run": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss scenario get-run <id> <runId>");
+            requireArgs(a, 2, commandUsage("scenario", "get-run"));
             return c.scenarios.getRunDetails(a[0], a[1], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss scenario get-run <id> <runId> [--project-key KEY]",
         description: "Get the details of a specific scenario run, including per-step outcomes.",
         examples: ["dss scenario get-run my_scenario 2024-09-01-01-02-03-123",],
     },
     log: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss scenario log <id> <runId>");
+            requireArgs(a, 2, commandUsage("scenario", "log"));
             const result = await c.scenarios.getRunLog(a[0], a[1], {
                 stepId: f["step-id"],
                 maxLogBytes: num(f["max-log-bytes"], "--max-log-bytes"),
@@ -252,7 +242,6 @@ export const scenarioCommands = {
             }
             return result.text;
         },
-        usage: "dss scenario log <id> <runId> [--step-id STEP_ID] [--max-log-bytes N] [--output PATH] [--project-key KEY]",
         description: "Get the log of a scenario run (or one step via --step-id). Byte-bounded at --max-log-bytes (default 1 MiB); --output PATH writes it to a file (stdout returns the path).",
         examples: [
             "dss scenario log my_scenario 2024-09-01-01-02-03-123",
@@ -261,19 +250,18 @@ export const scenarioCommands = {
     },
     "payload-get": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss scenario payload-get <id>");
+            requireArgs(a, 1, commandUsage("scenario", "payload-get"));
             return c.scenarios.getPayload(a[0], { projectKey: f["project-key"], });
         },
-        usage: "dss scenario payload-get <id> [--project-key KEY]",
         description: "Get the payload of a custom scenario (e.g. its Python script).",
         examples: ["dss scenario payload-get my_custom_scenario",],
     },
     "payload-set": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss scenario payload-set <id> (--data '{...}' | --data-file PATH | --stdin)");
+            requireArgs(a, 1, commandUsage("scenario", "payload-set"));
             const payload = jsonInput(f);
             if (payload === undefined) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario payload-set <id> (--data '{...}' | --data-file PATH | --stdin)");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("scenario", "payload-set")}`);
             }
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -290,7 +278,6 @@ export const scenarioCommands = {
             await c.scenarios.setPayload(a[0], payload, { projectKey: pk, });
             return { updated: a[0], resource: "scenario", part: "payload", };
         },
-        usage: "dss scenario payload-set <id> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Update the payload of a custom scenario (e.g. replace its Python script).",
         examples: [
             'dss scenario payload-set my_custom_scenario --data \'{"script":"print(1)"}\' --dry-run',
@@ -299,10 +286,10 @@ export const scenarioCommands = {
     },
     "active-set": {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss scenario active-set <id> <true|false>");
+            requireArgs(a, 2, commandUsage("scenario", "active-set"));
             const active = parseBooleanOption(a[1], "active");
             if (active === undefined) {
-                throw new UsageError("active must be 'true' or 'false'. Usage: dss scenario active-set <id> <true|false>");
+                throw new UsageError(`active must be 'true' or 'false'. Usage: ${commandUsage("scenario", "active-set")}`);
             }
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -318,11 +305,10 @@ export const scenarioCommands = {
             }
             return c.scenarios.setActive(a[0], active, { projectKey: pk, });
         },
-        usage: "dss scenario active-set <id> <true|false> [--dry-run] [--project-key KEY]",
         description: "Activate or deactivate a scenario (light update; deactivated scenarios ignore triggers).",
         examples: [
             "dss scenario active-set my_scenario false",
             "dss scenario active-set my_scenario true --dry-run",
         ],
     },
-};
+});

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

@@ -4,8 +4,9 @@ import { dirname, resolve, } from "node:path";
 import { writeResponseToFile, } from "../../utils/response-file.js";
 import { readStdinText, stripUtf8Bom, } from "../coerce.js";
 import { enqueueCliWarning, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { UsageError, } from "../usage.js";
-const SQL_QUERY_USAGE = "dss sql query (SQL | --sql QUERY | --sql-file PATH | --sql - | --stdin) (--connection CONN | --dataset FULL_NAME) [--database DB] [--output PATH|--output-file PATH] [--preview N] [--start-retries N] [--request-timeout MS] [--project-key KEY]";
+const SQL_QUERY_USAGE = commandUsage("sql", "query");
 const DEFAULT_SQL_PREVIEW_ROWS = 5;
 /**
  * Parse `--preview N` into a non-negative row count. Rejects non-integers,
@@ -86,7 +87,7 @@ export function resolveSqlQueryInvocation(args, flags, projectKeyOverride) {
         type: "sql",
     };
 }
-export const sqlCommands = {
+export const sqlCommands = withUsage("sql", {
     query: {
         handler: async (c, a, f) => {
             const outputFile = f["output"]
@@ -133,7 +134,6 @@ export const sqlCommands = {
                 written: outputPath,
             };
         },
-        usage: SQL_QUERY_USAGE,
         description: "Run potentially mutating SQL against a DSS connection or dataset. Use --preview N for bounded stdout or --output PATH for full rows. --start-retries may execute SQL more than once; use it only when repetition is safe.",
         examples: [
             "dss sql query 'SELECT * FROM orders LIMIT 10' --connection my_pg",
@@ -144,4 +144,4 @@ export const sqlCommands = {
             "dss sql query 'SELECT 1' --connection my_pg --start-retries 4",
         ],
     },
-};
+});