dataiku-sdk 3.3.0 → 3.5.0

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

@@ -1,9 +1,8 @@
-import { macroResultMaxBytes, } from "../../resources/macros.js";
 import { jsonInput, 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";
-const MACRO_RUN_USAGE = "dss macro run <macro_id> [--wait] [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]";
 /**
  * Flags accepted by run/run-and-wait; validated identically for live, dry-run,
  * and --plan so a plan that would fail cannot be "fixed" by dropping flags.
@@ -66,28 +65,26 @@ function requireNotBlankId(value, usage) {
         throw new UsageError(`Macro/run id must be non-empty. Usage: ${usage}`);
     }
 }
-export const macroCommands = {
+export const macroCommands = withUsage("macro", {
     list: {
         handler: (c, _a, f) => c.macros.list(f["project-key"]),
-        usage: "dss macro list [--project-key KEY]",
         description: "List the macros (runnables) available in a project.",
         examples: ["dss macro list",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss macro get <macro_id>");
+            requireArgs(a, 1, commandUsage("macro", "get"));
             requireNotBlankId(a[0], "dss macro get <macro_id>");
             return c.macros.definition(a[0], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss macro get <macro_id> [--project-key KEY]",
         description: "Get a macro's definition: parameters, result type, owning plugin, labels.",
         examples: ["dss macro get compute_orders",],
     },
     run: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss macro run <macro_id>");
+            requireArgs(a, 1, commandUsage("macro", "run"));
             const pk = f["project-key"];
             const waitOptions = macroWaitOptionsFromFlags(f);
             const runParams = macroRunParamsFromFlags(f);
@@ -117,7 +114,6 @@ export const macroCommands = {
             }
             return c.macros.run(a[0], { ...runParams, projectKey: pk, });
         },
-        usage: MACRO_RUN_USAGE,
         description: "Start a macro run. Macros execute arbitrary plugin code and are classified destructive. --wait polls to completion and exits 4 on failure; without it only the runId is returned. --data JSON may carry { params: {...}, adminParams: {...} } for parameterized macros.",
         examples: [
             "dss macro run compute_orders",
@@ -128,7 +124,7 @@ export const macroCommands = {
     },
     "run-and-wait": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss macro run-and-wait <macro_id>");
+            requireArgs(a, 1, commandUsage("macro", "run-and-wait"));
             const pk = f["project-key"];
             const waitOptions = macroWaitOptionsFromFlags(f);
             const runParams = macroRunParamsFromFlags(f);
@@ -155,7 +151,6 @@ export const macroCommands = {
                 projectKey: pk,
             });
         },
-        usage: "dss macro run-and-wait <macro_id> [--timeout MS (default 120000)] [--poll-interval MS] [--data JSON] [--dry-run] [--project-key KEY]",
         description: "Run a macro and poll its state until it finishes. Exits 4 on failure; returns { success: false, timedOut: true } on timeout.",
         examples: [
             "dss macro run-and-wait compute_orders",
@@ -164,7 +159,7 @@ export const macroCommands = {
     },
     abort: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss macro abort <macro_id> <run_id>");
+            requireArgs(a, 2, commandUsage("macro", "abort"));
             requireNotBlankId(a[0], "dss macro abort <macro_id> <run_id>");
             requireNotBlankId(a[1], "dss macro abort <macro_id> <run_id>");
             const pk = f["project-key"];
@@ -182,26 +177,24 @@ export const macroCommands = {
             await c.macros.abort(a[0], a[1], pk);
             return { aborted: a[1], runId: a[1], resource: "macro", };
         },
-        usage: "dss macro abort <macro_id> <run_id> [--dry-run] [--project-key KEY]",
         description: "Request abort of a running macro run.",
         examples: ["dss macro abort compute_orders run_42",],
     },
     state: {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss macro state <macro_id> <run_id>");
+            requireArgs(a, 2, commandUsage("macro", "state"));
             requireNotBlankId(a[0], "dss macro state <macro_id> <run_id>");
             requireNotBlankId(a[1], "dss macro state <macro_id> <run_id>");
             return c.macros.state(a[0], a[1], {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss macro state <macro_id> <run_id> [--project-key KEY]",
         description: "Get the poll state of a macro run: running flag, progress stack, failure details.",
         examples: ["dss macro state compute_orders run_42",],
     },
     result: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss macro result <macro_id> <run_id>");
+            requireArgs(a, 2, commandUsage("macro", "result"));
             requireNotBlankId(a[0], "dss macro result <macro_id> <run_id>");
             requireNotBlankId(a[1], "dss macro result <macro_id> <run_id>");
             const pk = f["project-key"];
@@ -211,11 +204,11 @@ export const macroCommands = {
             }
             return c.macros.result(a[0], a[1], {
                 projectKey: pk,
-                maxBytes: macroResultMaxBytes(maxBytes),
+                maxBytes: require("../../resources/macros.js")
+                    .macroResultMaxBytes(maxBytes),
             });
         },
-        usage: "dss macro result <macro_id> <run_id> [--max-bytes N (default 8388608)] [--project-key KEY]",
         description: "Download a macro run's result. Text/HTML bodies print as a JSON string (stdout stays one JSON document, embedded newlines escaped); JSON bodies print as the parsed object.",
         examples: ["dss macro result compute_orders run_42", "dss macro result m r --max-bytes 1024",],
     },
-};
+});

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

@@ -1,6 +1,7 @@
 import { jsonInput, requiredJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { isNotFoundError, planResult, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
 const MEANING_PLAN_FAILURE_CODES = { usage: 1, error: 2, transient: 3, };
 function meaningEndpoint(meaningId) {
@@ -20,25 +21,23 @@ function meaningCreatePayload(id, label, type, body) {
         detectable: body.detectable ?? false,
     };
 }
-export const meaningCommands = {
+export const meaningCommands = withUsage("meaning", {
     list: {
         handler: (c) => c.meanings.list(),
-        usage: "dss meaning list",
         description: "List user-defined meanings (column semantic types) on the instance.",
         examples: ["dss meaning list",],
     },
     get: {
         handler: (c, a) => {
-            requireArgs(a, 1, "dss meaning get <meaningId>");
+            requireArgs(a, 1, commandUsage("meaning", "get"));
             return c.meanings.get(a[0]);
         },
-        usage: "dss meaning get <meaningId>",
         description: "Get a user-defined meaning definition.",
         examples: ["dss meaning get customer_type",],
     },
     create: {
         handler: async (c, a, f) => {
-            requireArgs(a, 3, "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin] [--dry-run]");
+            requireArgs(a, 3, commandUsage("meaning", "create"));
             const body = jsonInput(f) ?? {};
             const payload = meaningCreatePayload(a[0], a[1], a[2], body);
             if (executionMode(f).dryRun) {
@@ -55,13 +54,12 @@ export const meaningCommands = {
             }
             return c.meanings.create(a[0], a[1], a[2], body);
         },
-        usage: "dss meaning create <id> <label> <type> [--data JSON|--data-file PATH|--stdin] [--dry-run]",
         description: "Create a user-defined meaning (type e.g. VALUES_LIST, VALUES_MAPPING, PATTERN).",
         examples: ["dss meaning create vip VIP VALUES_LIST --dry-run",],
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin) [--dry-run]");
+            requireArgs(a, 1, commandUsage("meaning", "update"));
             const body = requiredJsonInput(f, "--data, --data-file, or --stdin is required (meaning definition).");
             if (executionMode(f).dryRun) {
                 return planResult("meaning", "update", {
@@ -77,13 +75,12 @@ export const meaningCommands = {
             }
             return c.meanings.update(a[0], body);
         },
-        usage: "dss meaning update <meaningId> (--data JSON|--data-file PATH|--stdin) [--dry-run]",
         description: "Replace a user-defined meaning definition.",
         examples: ["dss meaning update vip --data-file meaning.json --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss meaning delete <meaningId>");
+            requireArgs(a, 1, commandUsage("meaning", "delete"));
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await c.meanings.get(a[0]).catch((error) => {
                     if (isNotFoundError(error)
@@ -109,8 +106,7 @@ export const meaningCommands = {
             await c.meanings.delete(a[0]);
             return { deleted: a[0], resource: "meaning", };
         },
-        usage: "dss meaning delete <meaningId> [--if-exists] [--dry-run]",
         description: "Delete a user-defined meaning definition.",
         examples: ["dss meaning delete vip --dry-run",],
     },
-};
+});

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

@@ -1,39 +1,36 @@
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const metricsCommands = {
+export const metricsCommands = withUsage("metrics", {
     "dataset-get": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss metrics dataset-get <dataset> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("metrics", "dataset-get"));
             return c.metrics.getDatasetMetrics(a[0], f["project-key"]);
         },
-        usage: "dss metrics dataset-get <dataset> [--project-key KEY]",
         description: "Get the last computed metric values for a dataset.",
         examples: ["dss metrics dataset-get customers",],
     },
     "dataset-compute": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss metrics dataset-compute <dataset> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("metrics", "dataset-compute"));
             return c.metrics.computeDatasetMetrics(a[0], f["project-key"]);
         },
-        usage: "dss metrics dataset-compute <dataset> [--project-key KEY]",
         description: "Compute the DSS-configured metrics for a dataset.",
         examples: ["dss metrics dataset-compute customers",],
     },
     "dataset-history": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("metrics", "dataset-history"));
             return c.metrics.getDatasetMetricHistory(a[0], a[1], f["project-key"]);
         },
-        usage: "dss metrics dataset-history <dataset> <metricId> [--project-key KEY]",
         description: "Get the history of one dataset metric.",
         examples: ["dss metrics dataset-history customers records:COUNT_RECORDS",],
     },
     "folder-get": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss metrics folder-get <folderId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("metrics", "folder-get"));
             return c.metrics.getFolderMetrics(a[0], f["project-key"]);
         },
-        usage: "dss metrics folder-get <folderId> [--project-key KEY]",
         description: "Get the last computed metric values for a managed folder.",
         examples: ["dss metrics folder-get aBcDeFgH",],
     },
-};
+});

package/dist/src/cli/commands/ml-task.js

@@ -1,5 +1,6 @@
 import { num, requiredJsonInput, requiredStringFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 function optionalStringFlag(flags, name) {
     const value = flags[name];
@@ -16,10 +17,10 @@ function taskType(flags, usage) {
         return normalized;
     throw new UsageError("--task-type must be PREDICTION or CLUSTERING.", "invalid_enum");
 }
-export const mlTaskCommands = {
+export const mlTaskCommands = withUsage("ml-task", {
     create: {
         handler: async (c, a, f) => {
-            const usage = "dss ml-task create <analysisId> --task-type PREDICTION|CLUSTERING [--target COLUMN] [--prediction-type TYPE] [--backend-type TYPE] [--guess-policy POLICY] [--project-key KEY]";
+            const usage = commandUsage("ml-task", "create");
             requireArgs(a, 1, usage);
             const projectKey = f["project-key"];
             const normalizedTaskType = taskType(f, usage);
@@ -39,7 +40,6 @@ export const mlTaskCommands = {
             const created = await c.mlTasks.create(options);
             return { created: created.mlTaskId, resource: "ml-task", analysisId: a[0], ...created, };
         },
-        usage: "dss ml-task create <analysisId> --task-type PREDICTION|CLUSTERING [--target COLUMN] [--prediction-type TYPE] [--backend-type TYPE] [--guess-policy POLICY] [--project-key KEY]",
         description: "Create a prediction or clustering task in an analysis.",
         examples: [
             "dss ml-task create ANALYSIS_ID --task-type prediction --target churn --project-key PROJECT",
@@ -47,31 +47,28 @@ export const mlTaskCommands = {
     },
     status: {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss ml-task status <analysisId> <mlTaskId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("ml-task", "status"));
             return c.mlTasks.status(a[0], a[1], f["project-key"]);
         },
-        usage: "dss ml-task status <analysisId> <mlTaskId> [--project-key KEY]",
         description: "Get a Visual ML task's current status.",
         examples: ["dss ml-task status ANALYSIS_ID TASK_ID --project-key PROJECT",],
     },
     "get-settings": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss ml-task get-settings <analysisId> <mlTaskId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("ml-task", "get-settings"));
             return c.mlTasks.getSettings(a[0], a[1], f["project-key"]);
         },
-        usage: "dss ml-task get-settings <analysisId> <mlTaskId> [--project-key KEY]",
         description: "Get a Visual ML task's settings.",
         examples: ["dss ml-task get-settings ANALYSIS_ID TASK_ID --project-key PROJECT",],
     },
     "set-settings": {
         handler: (c, a, f) => {
-            const usage = "dss ml-task set-settings <analysisId> <mlTaskId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]";
+            const usage = commandUsage("ml-task", "set-settings");
             requireArgs(a, 2, usage);
             const settings = requiredJsonInput(f, "--data, --data-file, or --stdin is required (ML task settings).");
             const projectKey = f["project-key"];
             return c.mlTasks.saveSettings(a[0], a[1], settings, projectKey);
         },
-        usage: "dss ml-task set-settings <analysisId> <mlTaskId> (--data JSON|--data-file PATH|--stdin) [--project-key KEY]",
         description: "Replace a Visual ML task's settings from JSON input.",
         examples: [
             "dss ml-task set-settings ANALYSIS_ID TASK_ID --data-file settings.json --project-key PROJECT",
@@ -79,7 +76,7 @@ export const mlTaskCommands = {
     },
     train: {
         handler: async (c, a, f) => {
-            const usage = "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("ml-task", "train");
             requireArgs(a, 2, usage);
             const options = {
                 analysisId: a[0],
@@ -100,7 +97,6 @@ export const mlTaskCommands = {
             }
             return c.mlTasks.train(options);
         },
-        usage: "dss ml-task train <analysisId> <mlTaskId> [--session-name NAME] [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
         description: "Start ML task training, optionally waiting for trained model IDs. --timeout bounds only the wait phase after DSS accepts training; an invalid timeout fails before any request.",
         examples: [
             "dss ml-task train ANALYSIS_ID TASK_ID --session-name baseline --wait --timeout 60000 --project-key PROJECT",
@@ -109,19 +105,17 @@ export const mlTaskCommands = {
     },
     "list-models": {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss ml-task list-models <analysisId> <mlTaskId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("ml-task", "list-models"));
             return c.mlTasks.listTrainedModels(a[0], a[1], f["project-key"]);
         },
-        usage: "dss ml-task list-models <analysisId> <mlTaskId> [--project-key KEY]",
         description: "List trained models for a Visual ML task.",
         examples: ["dss ml-task list-models ANALYSIS_ID TASK_ID --project-key PROJECT",],
     },
     "model-details": {
         handler: (c, a, f) => {
-            requireArgs(a, 3, "dss ml-task model-details <analysisId> <mlTaskId> <modelId> [--project-key KEY]");
+            requireArgs(a, 3, commandUsage("ml-task", "model-details"));
             return c.mlTasks.trainedModelDetails(a[0], a[1], a[2], f["project-key"]);
         },
-        usage: "dss ml-task model-details <analysisId> <mlTaskId> <modelId> [--project-key KEY]",
         description: "Get details for one trained model.",
         examples: [
             "dss ml-task model-details ANALYSIS_ID TASK_ID MODEL_ID --project-key PROJECT",
@@ -129,7 +123,7 @@ export const mlTaskCommands = {
     },
     deploy: {
         handler: async (c, a, f) => {
-            const usage = "dss ml-task deploy <analysisId> <mlTaskId> <modelId> --model-name NAME --train-dataset DATASET [--test-dataset DATASET] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("ml-task", "deploy");
             requireArgs(a, 3, usage);
             const options = {
                 analysisId: a[0],
@@ -150,7 +144,6 @@ export const mlTaskCommands = {
             }
             return c.mlTasks.deployToFlow(options);
         },
-        usage: "dss ml-task deploy <analysisId> <mlTaskId> <modelId> --model-name NAME --train-dataset DATASET [--test-dataset DATASET] [--dry-run] [--project-key KEY]",
         description: "Deploy a trained model to the Flow as a saved model.",
         examples: [
             "dss ml-task deploy ANALYSIS_ID TASK_ID MODEL_ID --model-name churn-model --train-dataset train --test-dataset test --project-key PROJECT",
@@ -159,7 +152,7 @@ export const mlTaskCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss ml-task delete <analysisId> <mlTaskId> [--dry-run] [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("ml-task", "delete"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun) {
                 return {
@@ -174,11 +167,10 @@ export const mlTaskCommands = {
             await c.mlTasks.delete(a[0], a[1], projectKey);
             return { deleted: a[1], resource: "ml-task", analysisId: a[0], };
         },
-        usage: "dss ml-task delete <analysisId> <mlTaskId> [--dry-run] [--project-key KEY]",
         description: "Delete a Visual ML task.",
         examples: [
             "dss ml-task delete ANALYSIS_ID TASK_ID --project-key PROJECT",
             "dss ml-task delete ANALYSIS_ID TASK_ID --dry-run --project-key PROJECT",
         ],
     },
-};
+});

package/dist/src/cli/commands/model-evaluation-store.js

@@ -1,26 +1,25 @@
 import { requiredStringFlag, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, } from "../usage.js";
-export const modelEvaluationStoreCommands = {
+export const modelEvaluationStoreCommands = withUsage("model-evaluation-store", {
     list: {
         handler: (c, _a, f) => c.modelEvaluationStores.list(f["project-key"]),
-        usage: "dss model-evaluation-store list [--project-key KEY]",
         description: "List model evaluation stores in a project.",
         examples: ["dss model-evaluation-store list --project-key PROJECT",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss model-evaluation-store get <storeId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("model-evaluation-store", "get"));
             return c.modelEvaluationStores.get(a[0], f["project-key"]);
         },
-        usage: "dss model-evaluation-store get <storeId> [--project-key KEY]",
         description: "Get a model evaluation store.",
         examples: ["dss model-evaluation-store get STORE_ID --project-key PROJECT",],
     },
     create: {
         handler: async (c, _a, f) => {
-            const usage = "dss model-evaluation-store create --name NAME [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("model-evaluation-store", "create");
             const name = requiredStringFlag(f, "name", usage);
             const projectKey = f["project-key"];
             const options = { name, projectKey, };
@@ -35,7 +34,6 @@ export const modelEvaluationStoreCommands = {
             const created = await c.modelEvaluationStores.create(options);
             return { created: created.id, resource: "model-evaluation-store", ...created, };
         },
-        usage: "dss model-evaluation-store create --name NAME [--dry-run] [--project-key KEY]",
         description: "Create an empty model evaluation store.",
         examples: [
             "dss model-evaluation-store create --name production-evaluations --project-key PROJECT",
@@ -44,10 +42,9 @@ export const modelEvaluationStoreCommands = {
     },
     "list-evaluations": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss model-evaluation-store list-evaluations <storeId> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("model-evaluation-store", "list-evaluations"));
             return c.modelEvaluationStores.listEvaluations(a[0], f["project-key"]);
         },
-        usage: "dss model-evaluation-store list-evaluations <storeId> [--project-key KEY]",
         description: "List evaluations in a model evaluation store.",
         examples: [
             "dss model-evaluation-store list-evaluations STORE_ID --project-key PROJECT",
@@ -55,7 +52,7 @@ export const modelEvaluationStoreCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss model-evaluation-store delete <storeId> [--if-exists] [--dry-run] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("model-evaluation-store", "delete"));
             const projectKey = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.modelEvaluationStores.get(a[0], projectKey));
@@ -74,11 +71,10 @@ export const modelEvaluationStoreCommands = {
             await c.modelEvaluationStores.delete(a[0], projectKey);
             return { deleted: a[0], resource: "model-evaluation-store", };
         },
-        usage: "dss model-evaluation-store delete <storeId> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a model evaluation store.",
         examples: [
             "dss model-evaluation-store delete STORE_ID --if-exists --project-key PROJECT",
             "dss model-evaluation-store delete STORE_ID --dry-run --project-key PROJECT",
         ],
     },
-};
+});

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

@@ -1,13 +1,13 @@
 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, requireNoArgs, UsageError, } from "../usage.js";
-export const notebookCommands = {
+export const notebookCommands = withUsage("notebook", {
     "list-jupyter": {
         handler: (c, _a, f) => c.notebooks.listJupyter(f["project-key"], {
             active: parseBooleanOption(f["active"], "--active"),
         }),
-        usage: "dss notebook list-jupyter [--active true|false] [--project-key KEY]",
         description: "List Jupyter notebooks. Pass --active to use the official ?active= filter: true lists currently running notebooks, false lists non-running ones.",
         examples: [
             "dss notebook list-jupyter",
@@ -16,16 +16,15 @@ export const notebookCommands = {
     },
     "get-jupyter": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss notebook get-jupyter <name>");
+            requireArgs(a, 1, commandUsage("notebook", "get-jupyter"));
             return c.notebooks.getJupyter(a[0], f["project-key"]);
         },
-        usage: "dss notebook get-jupyter <name> [--project-key KEY]",
         description: "Get a Jupyter notebook.",
         examples: ["dss notebook get-jupyter my_notebook",],
     },
     "delete-jupyter": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook delete-jupyter <name>");
+            requireArgs(a, 1, commandUsage("notebook", "delete-jupyter"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.notebooks.getJupyter(a[0], pk));
@@ -38,13 +37,12 @@ export const notebookCommands = {
             await c.notebooks.deleteJupyter(a[0], pk);
             return { deleted: a[0], resource: "jupyter-notebook", };
         },
-        usage: "dss notebook delete-jupyter <name> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a Jupyter notebook.",
         examples: ["dss notebook delete-jupyter my_notebook --dry-run",],
     },
     "clear-jupyter-outputs": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook clear-jupyter-outputs <name>");
+            requireArgs(a, 1, commandUsage("notebook", "clear-jupyter-outputs"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
                 // The real mutation is a single server-side DELETE of the
@@ -65,16 +63,14 @@ export const notebookCommands = {
             await c.notebooks.clearJupyterOutputs(a[0], pk);
             return { cleared: a[0], resource: "jupyter-notebook", };
         },
-        usage: "dss notebook clear-jupyter-outputs <name> [--dry-run] [--project-key KEY]",
         description: "Clear all cell outputs from a Jupyter notebook.",
         examples: ["dss notebook clear-jupyter-outputs my_notebook --dry-run",],
     },
     "sessions-jupyter": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss notebook sessions-jupyter <name>");
+            requireArgs(a, 1, commandUsage("notebook", "sessions-jupyter"));
             return c.notebooks.listJupyterSessions(a[0], f["project-key"]);
         },
-        usage: "dss notebook sessions-jupyter <name> [--project-key KEY]",
         description: "List active kernel sessions for a Jupyter notebook.",
         examples: ["dss notebook sessions-jupyter my_notebook",],
     },
@@ -82,7 +78,7 @@ export const notebookCommands = {
         handler: async (c, a, f) => {
             const pk = f["project-key"];
             if (f["all"] === true) {
-                requireNoArgs(a, "dss notebook unload-jupyter --all [--dry-run] [--project-key KEY]");
+                requireNoArgs(a, commandUsage("notebook", "unload-jupyter"));
                 if (executionMode(f).dryRun) {
                     const planned = [];
                     for (const notebook of await c.notebooks.listJupyter(pk, { active: true, })) {
@@ -106,7 +102,7 @@ export const notebookCommands = {
                 const unloaded = await c.notebooks.unloadJupyterAll(pk);
                 return { unloaded, resource: "jupyter-notebook", all: true, };
             }
-            requireArgs(a, 2, "dss notebook unload-jupyter <name> <sessionId>");
+            requireArgs(a, 2, commandUsage("notebook", "unload-jupyter"));
             if (executionMode(f).dryRun) {
                 const sessions = await c.notebooks.listJupyterSessions(a[0], pk);
                 const current = sessions.find((session) => session.sessionId === a[1]);
@@ -124,7 +120,6 @@ export const notebookCommands = {
             await c.notebooks.unloadJupyter(a[0], a[1], pk);
             return { unloaded: a[0], sessionId: a[1], resource: "jupyter-notebook", };
         },
-        usage: "dss notebook unload-jupyter (<name> <sessionId>|--all) [--dry-run] [--project-key KEY]",
         description: "Unload a Jupyter notebook kernel session, or every session of every running notebook with --all.",
         examples: [
             "dss notebook unload-jupyter my_notebook SESSION_ID --dry-run",
@@ -133,22 +128,20 @@ export const notebookCommands = {
     },
     "list-sql": {
         handler: (c, _a, f) => c.notebooks.listSql(f["project-key"]),
-        usage: "dss notebook list-sql [--project-key KEY]",
         description: "List SQL notebooks.",
         examples: ["dss notebook list-sql",],
     },
     "get-sql": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss notebook get-sql <id>");
+            requireArgs(a, 1, commandUsage("notebook", "get-sql"));
             return c.notebooks.getSql(a[0], f["project-key"]);
         },
-        usage: "dss notebook get-sql <id> [--project-key KEY]",
         description: "Get a SQL notebook.",
         examples: ["dss notebook get-sql my_sql_notebook",],
     },
     "delete-sql": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook delete-sql <id>");
+            requireArgs(a, 1, commandUsage("notebook", "delete-sql"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.notebooks.getSql(a[0], pk));
@@ -161,22 +154,20 @@ export const notebookCommands = {
             await c.notebooks.deleteSql(a[0], pk);
             return { deleted: a[0], resource: "sql-notebook", };
         },
-        usage: "dss notebook delete-sql <id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a SQL notebook.",
         examples: ["dss notebook delete-sql my_sql_notebook --dry-run",],
     },
     "history-sql": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss notebook history-sql <id>");
+            requireArgs(a, 1, commandUsage("notebook", "history-sql"));
             return c.notebooks.getSqlHistory(a[0], f["project-key"]);
         },
-        usage: "dss notebook history-sql <id> [--project-key KEY]",
         description: "Get query history for a SQL notebook.",
         examples: ["dss notebook history-sql my_sql_notebook",],
     },
     "save-jupyter": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook save-jupyter <name> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("notebook", "save-jupyter"));
             const data = jsonInput(f);
             if (!data) {
                 throw new UsageError("--data, --data-file, or --stdin is required (notebook JSON content).");
@@ -203,7 +194,6 @@ export const notebookCommands = {
                 hash: result.hash,
             };
         },
-        usage: "dss notebook save-jupyter <name> (--data '{...}' | --data-file PATH | --stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
         description: "Save content to a Jupyter notebook, creating it if missing. Reports created versus updated and the persisted content hash; --expect-hash aborts with a stale-read error when the stored content hash changed.",
         examples: [
             "dss notebook save-jupyter my_notebook --data-file notebook.json --dry-run",
@@ -212,7 +202,7 @@ export const notebookCommands = {
     },
     "save-sql": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook save-sql <id> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("notebook", "save-sql"));
             const data = jsonInput(f);
             if (!data) {
                 throw new UsageError("--data, --data-file, or --stdin is required (SQL notebook content JSON).");
@@ -243,13 +233,12 @@ export const notebookCommands = {
                 hash: result.hash,
             };
         },
-        usage: "dss notebook save-sql <id> (--data '{...}' | --data-file PATH | --stdin) [--expect-hash SHA256] [--dry-run] [--project-key KEY]",
         description: "Save content to a SQL notebook, creating it if missing. On create DSS allocates the notebook id: `saved` is the persisted id to use for every later read/update/delete, and `requested` echoes the handle, which becomes the display name. Reports created versus updated and the persisted content hash; --expect-hash rejects a stale read before writing and refuses a missing notebook.",
         examples: ["dss notebook save-sql my_sql_notebook --data-file content.json --dry-run",],
     },
     "clear-sql-history": {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss notebook clear-sql-history <id>");
+            requireArgs(a, 1, commandUsage("notebook", "clear-sql-history"));
             const pk = f["project-key"];
             const options = {
                 cellId: f["cell-id"],
@@ -272,11 +261,10 @@ export const notebookCommands = {
             await c.notebooks.clearSqlHistory(a[0], options);
             return { cleared: a[0], resource: "sql-notebook", };
         },
-        usage: "dss notebook clear-sql-history <id> [--cell-id CID] [--retain N] [--dry-run] [--project-key KEY]",
         description: "Clear query history for a SQL notebook.",
         examples: [
             "dss notebook clear-sql-history my_sql_notebook --dry-run",
             "dss notebook clear-sql-history my_sql_notebook --cell-id CELL1 --retain 5",
         ],
     },
-};
+});