dataiku-sdk 3.4.0 → 3.6.0

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

@@ -1,15 +1,14 @@
 import { deepMerge, } from "../../utils/deep-merge.js";
+import { isRecord, } from "../../utils/records.js";
 import { compareStrings, stableHash, } from "../../utils/stable-hash.js";
 import { jsonInput, num, schemaColumnsInput, unknownJsonInput, } from "../coerce.js";
 import { executionMode, } from "../flags.js";
 import { datasetSourceSummary, } from "../helpers/dataset.js";
 import { moveCreatedItemsToZone, resolveFlowZoneIdFromFlags, } from "../helpers/flow-zone.js";
 import { enqueueCliWarning, readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
 const MAX_SCHEMA_DIFFERENCES = 50;
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function appendSchemaPath(parent, key) {
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
         ? (parent ? `${parent}.${key}` : key)
@@ -20,7 +19,7 @@ function collectSchemaDifferences(expected, actual, path, acc) {
     // subtrees (any key order) match exactly and are never descended into.
     if (stableHash(expected) === stableHash(actual))
         return;
-    if (isPlainObject(expected) && isPlainObject(actual)) {
+    if (isRecord(expected) && isRecord(actual)) {
         const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual),]),].sort(compareStrings);
         for (const key of keys) {
             const nextPath = appendSchemaPath(path, key);
@@ -97,82 +96,74 @@ export function compareDatasetSchemas(expected, actual) {
         differencesTruncated: acc.items.length < acc.total,
     };
 }
-export const datasetCommands = {
+export const datasetCommands = withUsage("dataset", {
     list: {
         handler: (c, _a, f) => c.datasets.list(f["project-key"]),
-        usage: "dss dataset list [--project-key KEY]",
         description: "List all datasets in a project.",
         examples: ["dss dataset list", "dss dataset list --project-key MYPROJ",],
     },
     rename: {
         handler: async (c, a, f) => {
-            requireArgs(a, 2, "dss dataset rename <oldName> <newName> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("dataset", "rename"));
             await c.datasets.rename(a[0], a[1], f["project-key"]);
             return { renamed: a[0], to: a[1], };
         },
-        usage: "dss dataset rename <oldName> <newName> [--project-key KEY]",
         description: "Rename a dataset (updates downstream flow references).",
         examples: ["dss dataset rename old_ds new_ds",],
     },
     "list-partitions": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset list-partitions <name> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("dataset", "list-partitions"));
             return c.datasets.listPartitions(a[0], f["project-key"]);
         },
-        usage: "dss dataset list-partitions <name> [--project-key KEY]",
         description: "List the partitions of a partitioned dataset.",
         examples: ["dss dataset list-partitions events",],
     },
     clear: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("dataset", "clear"));
             const partitions = f["partitions"];
             await c.datasets.clear(a[0], partitions, f["project-key"]);
             return { cleared: a[0], partitions: partitions ?? "ALL", };
         },
-        usage: "dss dataset clear <name> [--partitions SPEC] [--project-key KEY]",
         description: "Clear a dataset's data (all, or a partition spec); keeps the dataset.",
         examples: ["dss dataset clear staging", "dss dataset clear events --partitions 2024-01",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset get <name>");
+            requireArgs(a, 1, commandUsage("dataset", "get"));
             return c.datasets.get(a[0], f["project-key"]);
         },
-        usage: "dss dataset get <name> [--project-key KEY]",
         description: "Get full settings for a dataset.",
         examples: ["dss dataset get orders", "dss dataset get orders --project-key MYPROJ",],
     },
     schema: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset schema <name>");
+            requireArgs(a, 1, commandUsage("dataset", "schema"));
             return c.datasets.schema(a[0], f["project-key"]);
         },
-        usage: "dss dataset schema <name> [--project-key KEY]",
         description: "Show the column schema of a dataset.",
         examples: ["dss dataset schema orders",],
     },
     source: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset source <name>");
+            requireArgs(a, 1, commandUsage("dataset", "source"));
             return datasetSourceSummary(await c.datasets.get(a[0], f["project-key"]));
         },
-        usage: "dss dataset source <name> [--project-key KEY]",
         description: "Show backing connection, catalog/schema/table, path, and format for a dataset.",
         examples: ["dss dataset source orders",],
     },
     files: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset files <name> [--project-key KEY]");
+            requireArgs(a, 1, commandUsage("dataset", "files"));
             return c.datasets.listUploadedFiles(a[0], f["project-key"]);
         },
-        usage: "dss dataset files <name> [--project-key KEY]",
         description: "List files stored by an UploadedFiles dataset.",
         examples: ["dss dataset files uploaded_input",],
     },
     "upload-file": {
         handler: (c, a, f) => {
-            const usage = "dss dataset upload-file <name> <localPath> --file-name NAME [--project-key KEY]";
+            const usage = commandUsage("dataset", "upload-file");
             requireArgs(a, 2, usage);
             const fileName = f["file-name"];
             if (!fileName || fileName.trim() === "") {
@@ -183,7 +174,6 @@ export const datasetCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss dataset upload-file <name> <localPath> --file-name NAME [--project-key KEY]",
         description: "Add one new file to an UploadedFiles dataset and verify the stored byte length.",
         examples: [
             "dss dataset upload-file uploaded_input ./input.csv --file-name input.csv",
@@ -191,7 +181,7 @@ export const datasetCommands = {
     },
     "refresh-schema": {
         handler: async (c, a, f) => {
-            const usage = "dss dataset refresh-schema <name> [--data JSON | --data-file PATH | --stdin] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("dataset", "refresh-schema");
             requireArgs(a, 1, usage);
             const columns = schemaColumnsInput(f, usage);
             const pk = f["project-key"];
@@ -209,7 +199,6 @@ export const datasetCommands = {
             await c.datasets.updateSchema(a[0], columns, pk);
             return { updated: a[0], resource: "dataset", schema: { columns, }, };
         },
-        usage: "dss dataset refresh-schema <name> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Replace a dataset schema through the DSS schema endpoint.",
         examples: [
             `dss dataset refresh-schema orders --data '{"columns":[{"name":"id","type":"bigint"}]}' --dry-run`,
@@ -217,16 +206,15 @@ export const datasetCommands = {
     },
     "validate-build": {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset validate-build <name>");
+            requireArgs(a, 1, commandUsage("dataset", "validate-build"));
             return c.datasets.validateBuildSettings(a[0], f["project-key"]);
         },
-        usage: "dss dataset validate-build <name> [--project-key KEY]",
         description: "Check common dataset settings that can make file-backed builds fail.",
         examples: ["dss dataset validate-build orders",],
     },
     preview: {
         handler: async (c, a, f) => {
-            const previewUsage = "dss dataset preview <name> [--max-rows N] [--rows N] [--project-key KEY] [--timeout MS]";
+            const previewUsage = commandUsage("dataset", "preview");
             requireArgs(a, 1, previewUsage);
             const maxRows = num(f["max-rows"], "--max-rows");
             if (maxRows !== undefined && (!Number.isSafeInteger(maxRows) || maxRows <= 0 || maxRows > 500)) {
@@ -251,13 +239,12 @@ export const datasetCommands = {
             }
             return result;
         },
-        usage: "dss dataset preview <name> [--max-rows N] [--rows N] [--project-key KEY] [--timeout MS]",
         description: "Preview dataset rows (--rows is an alias for --max-rows). Returns { columns, rows, rowCount, truncated, limit }; when the dataset has more rows than the cap, truncated is true and a dataset_preview_truncated warning is written to stderr.",
         examples: ["dss dataset preview orders", "dss dataset preview orders --rows 5",],
     },
     "assert-count": {
         handler: async (c, a, f) => {
-            const assertUsage = "dss dataset assert-count <dataset> --expected N [--project-key KEY]";
+            const assertUsage = commandUsage("dataset", "assert-count");
             requireArgs(a, 1, assertUsage);
             const expected = num(f["expected"], "--expected");
             if (expected === undefined || !Number.isSafeInteger(expected) || expected < 0) {
@@ -267,13 +254,12 @@ export const datasetCommands = {
             const result = await c.datasets.assertRowCount(a[0], expected, f["project-key"]);
             return { ...result, dataset: a[0], };
         },
-        usage: "dss dataset assert-count <dataset> --expected N [--project-key KEY]",
         description: "Stream the dataset and assert it holds exactly --expected rows, probing at most N+1 rows. Returns { satisfied, expected, count, exact }; a mismatch exits 4 with assertion_failed.",
         examples: ["dss dataset assert-count orders --expected 1000",],
     },
     "assert-schema": {
         handler: async (c, a, f) => {
-            const assertUsage = "dss dataset assert-schema <dataset> (--data JSON | --data-file PATH | --stdin) [--project-key KEY]";
+            const assertUsage = commandUsage("dataset", "assert-schema");
             requireArgs(a, 1, assertUsage);
             const expected = unknownJsonInput(f);
             if (expected === undefined) {
@@ -291,7 +277,6 @@ export const datasetCommands = {
                 differences: comparison.differences,
             };
         },
-        usage: "dss dataset assert-schema <dataset> (--data JSON | --data-file PATH | --stdin) [--project-key KEY]",
         description: "Assert the dataset's full schema equals the expected schema object; reports concise per-path differences with sha256 subtree hashes. A mismatch exits 4 with assertion_failed.",
         examples: [
             `dss dataset assert-schema orders --data-file expected-schema.json`,
@@ -300,16 +285,15 @@ export const datasetCommands = {
     },
     metadata: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset metadata <name>");
+            requireArgs(a, 1, commandUsage("dataset", "metadata"));
             return c.datasets.metadata(a[0], f["project-key"]);
         },
-        usage: "dss dataset metadata <name> [--project-key KEY]",
         description: "Get dataset-level metadata.",
         examples: ["dss dataset metadata orders",],
     },
     "metadata-set": {
         handler: async (c, a, f) => {
-            const usage = "dss dataset metadata-set <name> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("dataset", "metadata-set");
             requireArgs(a, 1, usage);
             // Validated identically for live, --plan, and --dry-run: the JSON
             // input replaces the server metadata object verbatim (faithful PUT;
@@ -334,7 +318,6 @@ export const datasetCommands = {
             const updated = await c.datasets.updateMetadata(a[0], metadata, pk);
             return { updated: a[0], resource: "dataset", metadata: updated, };
         },
-        usage: "dss dataset metadata-set <name> (--data JSON | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Replace dataset-level metadata with the given JSON object (faithful PUT: GET, edit, PUT full object; no merge).",
         examples: [
             `dss dataset metadata-set orders --data '{"label":"Orders","tags":["prod"]}' --dry-run`,
@@ -348,7 +331,7 @@ export const datasetCommands = {
             const connection = f["connection"];
             const dsType = f["type"];
             if (!name || !dsType) {
-                throw new UsageError("--name and --type are required. Usage: dss dataset create --name NAME --type TYPE [--connection CONN]");
+                throw new UsageError(`--name and --type are required. Usage: ${commandUsage("dataset", "create")}`);
             }
             if (!connection && dsType.toLowerCase() !== "uploadedfiles") {
                 throw new UsageError("--connection is required unless --type is UploadedFiles.");
@@ -382,7 +365,6 @@ export const datasetCommands = {
             const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "DATASET", },], pk);
             return { created: name, resource: "dataset", ...moved, };
         },
-        usage: "dss dataset create --name NAME --type TYPE [--connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a new dataset. UploadedFiles uses the server's default upload connection when omitted.",
         examples: [
             "dss dataset create --name uploads --type UploadedFiles",
@@ -392,7 +374,7 @@ export const datasetCommands = {
     },
     "create-managed": {
         handler: async (c, _a, f) => {
-            const usage = "dss dataset create-managed --name NAME --connection CONN [--type-option-id ID] [--format-option-id ID] [--copy-partitioning-from REF] [--partitioning-folder] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("dataset", "create-managed");
             const name = f["name"];
             if (!name || name.trim() === "") {
                 throw new UsageError(`--name is required. Usage: ${usage}`);
@@ -446,7 +428,6 @@ export const datasetCommands = {
                 creationSettings: created.creationSettings,
             };
         },
-        usage: "dss dataset create-managed --name NAME --connection CONN [--type-option-id ID] [--format-option-id ID] [--copy-partitioning-from REF] [--partitioning-folder] [--dry-run] [--project-key KEY]",
         description: "Create a managed dataset via the dedicated endpoint: DSS derives storage/format details; you pick name, connection, and optional type/format/partitioning options.",
         examples: [
             "dss dataset create-managed --name orders_copy --connection filesystem_managed",
@@ -456,16 +437,15 @@ export const datasetCommands = {
     },
     info: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss dataset info <name>");
+            requireArgs(a, 1, commandUsage("dataset", "info"));
             return c.datasets.info(a[0], f["project-key"]);
         },
-        usage: "dss dataset info <name> [--project-key KEY]",
         description: "Get the full info object for a dataset (type, parameters, last build information, schema, etc.).",
         examples: ["dss dataset info orders", "dss dataset info orders --project-key MYPROJ",],
     },
     "column-lineage": {
         handler: (c, a, f) => {
-            const usage = "dss dataset column-lineage <name> <column> [--max-dataset-count N] [--project-key KEY]";
+            const usage = commandUsage("dataset", "column-lineage");
             requireArgs(a, 2, usage);
             const maxDatasetCount = num(f["max-dataset-count"], "--max-dataset-count");
             if (maxDatasetCount !== undefined
@@ -478,7 +458,6 @@ export const datasetCommands = {
                 projectKey: f["project-key"],
             });
         },
-        usage: "dss dataset column-lineage <name> <column> [--max-dataset-count N] [--project-key KEY]",
         description: "Get the full column lineage (auto-computed and manual) of a column; includes local and foreign project relations.",
         examples: [
             "dss dataset column-lineage orders customer_id",
@@ -487,7 +466,7 @@ export const datasetCommands = {
     },
     download: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset download <name>");
+            requireArgs(a, 1, commandUsage("dataset", "download"));
             const result = await c.datasets.download(a[0], {
                 outputPath: f["output"],
                 projectKey: f["project-key"],
@@ -516,7 +495,6 @@ export const datasetCommands = {
             }
             return result;
         },
-        usage: "dss dataset download <name> [--output PATH] [--limit N] [--raw-data] [--project-key KEY]",
         description: "Download up to --limit rows (default 100k) as CSV and return { path, rows, truncated, limit }. Formula-like cells are neutralized for spreadsheets; --raw-data preserves exact bytes. Warnings report truncation and the default output path.",
         examples: [
             "dss dataset download orders",
@@ -526,7 +504,7 @@ export const datasetCommands = {
     },
     clone: {
         handler: async (c, a, f) => {
-            const usage = "dss dataset clone <source> <target> [--path PATH] [--table TABLE] [--metastore-table TABLE] [--allow-same-path] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("dataset", "clone");
             requireArgs(a, 2, usage);
             const pk = f["project-key"];
             const opts = {
@@ -556,7 +534,6 @@ export const datasetCommands = {
             const moved = await moveCreatedItemsToZone(c, f, [{ objectId: a[1], objectType: "DATASET", },], pk);
             return { ...cloned, resource: "dataset", ...moved, };
         },
-        usage: "dss dataset clone <source> <target> [--path PATH] [--table TABLE] [--metastore-table TABLE] [--allow-same-path] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]",
         description: "Clone dataset settings into a new dataset, with storage/table overrides.",
         examples: [
             "dss dataset clone source_ds experiment_ds --path /dataiku/TEST/experiment_ds --dry-run",
@@ -565,7 +542,7 @@ export const datasetCommands = {
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset delete <name>");
+            requireArgs(a, 1, commandUsage("dataset", "delete"));
             const pk = f["project-key"];
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.datasets.get(a[0], pk));
@@ -578,16 +555,15 @@ export const datasetCommands = {
             await c.datasets.delete(a[0], pk);
             return { deleted: a[0], resource: "dataset", };
         },
-        usage: "dss dataset delete <name> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a dataset.",
         examples: ["dss dataset delete orders", "dss dataset delete orders --if-exists",],
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+            requireArgs(a, 1, commandUsage("dataset", "update"));
             const data = jsonInput(f);
             if (!data) {
-                throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${commandUsage("dataset", "update")}`);
             }
             const pk = f["project-key"];
             if (executionMode(f).dryRun) {
@@ -598,11 +574,10 @@ export const datasetCommands = {
             await c.datasets.update(a[0], data, pk);
             return { updated: a[0], resource: "dataset", };
         },
-        usage: "dss dataset update <name> (--data '{...}' | --data-file PATH | --stdin) [--dry-run] [--project-key KEY]",
         description: "Update dataset settings via JSON merge.",
         examples: [
             'dss dataset update orders --data \'{"tags":["production"]}\' --dry-run',
             "echo '{\"tags\":[]}' | dss dataset update orders --stdin",
         ],
     },
-};
+});

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

@@ -1,26 +1,25 @@
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const discussionCommands = {
+export const discussionCommands = withUsage("discussion", {
     list: {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss discussion list <objectType> <objectId> [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("discussion", "list"));
             return c.discussions.list(a[0], a[1], f["project-key"]);
         },
-        usage: "dss discussion list <objectType> <objectId> [--project-key KEY]",
         description: "List discussions attached to a project object.",
         examples: ["dss discussion list DATASET customers",],
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 3, "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]");
+            requireArgs(a, 3, commandUsage("discussion", "get"));
             return c.discussions.get(a[0], a[1], a[2], f["project-key"]);
         },
-        usage: "dss discussion get <objectType> <objectId> <discussionId> [--project-key KEY]",
         description: "Get one discussion with its replies.",
         examples: ["dss discussion get DATASET customers d123",],
     },
     create: {
         handler: (c, a, f) => {
-            requireArgs(a, 2, "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]");
+            requireArgs(a, 2, commandUsage("discussion", "create"));
             const topic = f["topic"];
             const reply = f["reply"];
             if (!topic || !reply) {
@@ -28,20 +27,18 @@ export const discussionCommands = {
             }
             return c.discussions.create(a[0], a[1], topic, reply, f["project-key"]);
         },
-        usage: "dss discussion create <objectType> <objectId> --topic TEXT --reply TEXT [--project-key KEY]",
         description: "Create a discussion with its first reply.",
         examples: ["dss discussion create DATASET customers --topic Schema --reply Please-review",],
     },
     reply: {
         handler: (c, a, f) => {
-            requireArgs(a, 3, "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]");
+            requireArgs(a, 3, commandUsage("discussion", "reply"));
             const text = f["text"];
             if (!text)
                 throw new UsageError("--text is required.", "missing_required_flag");
             return c.discussions.reply(a[0], a[1], a[2], text, f["project-key"]);
         },
-        usage: "dss discussion reply <objectType> <objectId> <discussionId> --text TEXT [--project-key KEY]",
         description: "Add a reply to an existing discussion.",
         examples: ["dss discussion reply DATASET customers d123 --text Done",],
     },
-};
+});

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

@@ -1,11 +1,11 @@
-export const doctorCommands = {
+import { withUsage, } from "../syntax.js";
+export const doctorCommands = withUsage("doctor", {
     run: {
         handler: async (_c, _a, f) => {
             const { runDoctor, } = await import("../doctor.js");
             return (await runDoctor(f)).result;
         },
-        usage: "dss doctor [--project-key KEY] [--capabilities] [--fast]",
         description: "Run JSON diagnostics for DSS credentials, connectivity, and project access.",
         examples: ["dss doctor", "dss doctor --project-key MYPROJ", "dss doctor --capabilities --fast",],
     },
-};
+});

package/dist/src/cli/commands/flow-zone.js

@@ -3,8 +3,9 @@ import { deepMerge, } from "../../utils/deep-merge.js";
 import { executionMode, } from "../flags.js";
 import { ensureFlowZonePlanTarget, findFlowZoneForPlan, flowZoneColor, flowZoneContains, flowZoneCurrentPosition, flowZoneDetailSummary, flowZoneId, flowZoneMoveDelta, flowZoneMoveItems, flowZoneName, flowZoneOrganizeStep, flowZonePlanFromZones, flowZonePlanItemKeys, flowZonePruneItems, flowZoneSamePosition, flowZoneSummary, readFlowZoneOrganizePlan, resolveFlowZoneIdFromFlags, throwFlowZoneValidationError, validateFlowZoneOrganizeObjects, } from "../helpers/flow-zone.js";
 import { readIfExists, skipResult, } from "../output.js";
+import { commandUsage, withUsage, } from "../syntax.js";
 import { requireArgs, UsageError, } from "../usage.js";
-export const flowZoneCommands = {
+export const flowZoneCommands = withUsage("flow-zone", {
     list: {
         handler: async (c, _a, f) => {
             const zones = await c.flowZones.list(f["project-key"]);
@@ -14,7 +15,6 @@ export const flowZoneCommands = {
             const object = objects.length === 1 ? objects[0] : undefined;
             return zones.map((zone) => flowZoneSummary(zone, object));
         },
-        usage: "dss flow-zone list [--summary] [--object TYPE:ID] [--project-key KEY]",
         description: "List flow zones in a project, optionally as compact summaries.",
         examples: ["dss flow-zone list", "dss flow-zone list --summary --object RECIPE:compute_orders",],
     },
@@ -38,7 +38,6 @@ export const flowZoneCommands = {
                 .filter((zone) => flowZoneContains(zone, object))
                 .map((zone) => flowZoneSummary(zone, object));
         },
-        usage: "dss flow-zone find [name-or-id] [--object TYPE:ID | --dataset DS | --recipe R | --folder F] [--project-key KEY]",
         description: "Find flow zones by name/id or by contained flow object.",
         examples: [
             "dss flow-zone find ATH_SNW_MAP_FRG49",
@@ -48,10 +47,9 @@ export const flowZoneCommands = {
     },
     get: {
         handler: (c, a, f) => {
-            requireArgs(a, 1, "dss flow-zone get <id>");
+            requireArgs(a, 1, commandUsage("flow-zone", "get"));
             return c.flowZones.get(flowZoneId(a[0]), f["project-key"]);
         },
-        usage: "dss flow-zone get <id> [--project-key KEY]",
         description: "Get a flow zone by id.",
         examples: ["dss flow-zone get ZONE_ID",],
     },
@@ -84,7 +82,6 @@ export const flowZoneCommands = {
             const created = await c.flowZones.create(payload);
             return { created: created.id, resource: "flow-zone", ...created, };
         },
-        usage: "dss flow-zone create --name NAME [--color #RRGGBB] [--if-not-exists] [--dry-run] [--project-key KEY]",
         description: "Create a flow zone.",
         examples: [
             "dss flow-zone create --name Exports",
@@ -93,7 +90,7 @@ export const flowZoneCommands = {
     },
     update: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss flow-zone update <id> [--name NAME] [--color #RRGGBB]");
+            requireArgs(a, 1, commandUsage("flow-zone", "update"));
             if (typeof f["name"] !== "string" && typeof f["color"] !== "string") {
                 throw new UsageError("--name and/or --color is required.");
             }
@@ -111,13 +108,12 @@ export const flowZoneCommands = {
             }
             return c.flowZones.update(zoneId, patch);
         },
-        usage: "dss flow-zone update <id> [--name NAME] [--color #RRGGBB] [--dry-run] [--project-key KEY]",
         description: "Update flow zone settings.",
         examples: ["dss flow-zone update ZONE_ID --name Exports --color '#2ab1ac' --dry-run",],
     },
     delete: {
         handler: async (c, a, f) => {
-            requireArgs(a, 1, "dss flow-zone delete <id>");
+            requireArgs(a, 1, commandUsage("flow-zone", "delete"));
             const zoneId = flowZoneId(a[0]);
             if (executionMode(f).dryRun || f["if-exists"] === true) {
                 const current = await readIfExists(() => c.flowZones.get(zoneId, f["project-key"]));
@@ -130,7 +126,6 @@ export const flowZoneCommands = {
             await c.flowZones.delete(zoneId, f["project-key"]);
             return { deleted: zoneId, resource: "flow-zone", };
         },
-        usage: "dss flow-zone delete <id> [--if-exists] [--dry-run] [--project-key KEY]",
         description: "Delete a flow zone. DSS moves zone items back to the default zone.",
         examples: [
             "dss flow-zone delete ZONE_ID --dry-run",
@@ -142,7 +137,7 @@ export const flowZoneCommands = {
             const pk = f["project-key"];
             const zoneId = a[0] ? flowZoneId(a[0]) : await resolveFlowZoneIdFromFlags(c, f, pk);
             if (!zoneId) {
-                throw new UsageError("A zone id or --zone/--zone-id is required. Usage: dss flow-zone move <id> [--dataset DS] [--recipe R] [--folder F] [--object TYPE:ID]");
+                throw new UsageError(`A zone id or --zone/--zone-id is required. Usage: ${commandUsage("flow-zone", "move")}`);
             }
             const items = flowZoneMoveItems(f);
             if (items.length === 0) {
@@ -159,7 +154,6 @@ export const flowZoneCommands = {
             }
             return c.flowZones.moveItems(zoneId, items, pk);
         },
-        usage: "dss flow-zone move [id] [--zone ZONE|--zone-id ID] [--dataset DS[,DS2]] [--recipe R] [--folder F] [--object TYPE:ID] [--dry-run] [--project-key KEY]",
         description: "Move datasets, recipes, managed folders, or other flow objects into a zone by id or --zone name.",
         examples: [
             "dss flow-zone move ZONE_ID --dataset orders --dry-run",
@@ -177,13 +171,12 @@ export const flowZoneCommands = {
             ]);
             return flowZonePlanFromZones(zones, topologyFingerprint);
         },
-        usage: "dss flow-zone plan [--project-key KEY]",
         description: "Export current visual flow-zone organization as an organize-compatible plan.",
         examples: ["dss flow-zone plan --project-key MYPROJ",],
     },
     organize: {
         handler: async (c, _a, f) => {
-            const usage = "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]";
+            const usage = commandUsage("flow-zone", "organize");
             const pk = f["project-key"];
             const plan = readFlowZoneOrganizePlan(f, usage);
             const sync = f["sync"] === true;
@@ -292,7 +285,6 @@ export const flowZoneCommands = {
                 pruned,
             };
         },
-        usage: "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]",
         description: "Create/update flow zones and move objects from a declarative visual organization plan.",
         examples: [
             "dss flow-zone organize --file flow-zones.json --dry-run",
@@ -304,8 +296,7 @@ export const flowZoneCommands = {
             const id = a[0] === undefined ? undefined : flowZoneId(a[0]);
             return c.flowZones.graph(id, f["project-key"]);
         },
-        usage: "dss flow-zone graph [<id>] [--project-key KEY]",
         description: "Get the full flow graph or the graph for a single flow zone.",
         examples: ["dss flow-zone graph", "dss flow-zone graph ZONE_ID",],
     },
-};
+});