dataiku-sdk 0.5.1 → 0.6.1

package/dist/src/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
+import { createHash, } from "node:crypto";
 import { readFileSync, } from "node:fs";
-import { writeFile, } from "node:fs/promises";
-import { dirname, resolve, } from "node:path";
+import { mkdir, writeFile, } from "node:fs/promises";
+import { dirname, join, resolve, } from "node:path";
 import { createInterface, } from "node:readline";
 import { Writable, } from "node:stream";
 import { fileURLToPath, } from "node:url";
@@ -9,29 +10,72 @@ import { validateCredentials, } from "./auth.js";
 import { DataikuClient, } from "./client.js";
 import { deleteCredentials, getCredentialsPath, loadCredentials, maskApiKey, saveCredentials, } from "./config.js";
 import { DataikuError, dataikuErrorCode, } from "./errors.js";
+import { buildDatasetCloneSettings, } from "./resources/datasets.js";
+import { parseJobLogProgress, } from "./resources/jobs.js";
+import { scenarioUpdatePreview, } from "./resources/scenarios.js";
 import { AGENTS, detectAgents, findWorkspaceRoot, installSkill, } from "./skill.js";
 import { appendCleanupLedgerEntry, readCleanupLedger, } from "./utils/cleanup-ledger.js";
 import { deepMerge, } from "./utils/deep-merge.js";
+import { sanitizeFileName, } from "./utils/sanitize.js";
 // ---------------------------------------------------------------------------
 // Utility helpers
 // ---------------------------------------------------------------------------
-const CLI_VERSION = (() => {
-    try {
-        let dir = dirname(fileURLToPath(import.meta.url));
-        for (let i = 0; i < 5; i++) {
-            const candidate = resolve(dir, "package.json");
-            try {
-                return JSON.parse(readFileSync(candidate, "utf-8")).version;
-            }
-            catch {
-                dir = dirname(dir);
-            }
+function findPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+        try {
+            readFileSync(resolve(dir, "package.json"), "utf-8");
+            return dir;
+        }
+        catch {
+            dir = dirname(dir);
         }
+    }
+    return undefined;
+}
+function packageVersion(packageRoot) {
+    if (!packageRoot)
         return "unknown";
+    try {
+        return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf-8")).version;
     }
     catch {
         return "unknown";
     }
+}
+function gitDirectory(packageRoot) {
+    try {
+        const gitFile = readFileSync(resolve(packageRoot, ".git"), "utf-8").trim();
+        if (gitFile.startsWith("gitdir:")) {
+            return resolve(packageRoot, gitFile.slice("gitdir:".length).trim());
+        }
+    }
+    catch {
+        // Normal checkouts have a .git directory, not a .git file.
+    }
+    return resolve(packageRoot, ".git");
+}
+function gitRevision(packageRoot) {
+    if (!packageRoot)
+        return undefined;
+    try {
+        const gitDir = gitDirectory(packageRoot);
+        const head = readFileSync(resolve(gitDir, "HEAD"), "utf-8").trim();
+        if (!head.startsWith("ref:"))
+            return head.slice(0, 7);
+        const ref = head.slice("ref:".length).trim();
+        const full = readFileSync(resolve(gitDir, ref), "utf-8").trim();
+        return full.slice(0, 7);
+    }
+    catch {
+        return undefined;
+    }
+}
+const PACKAGE_ROOT = findPackageRoot();
+const CLI_VERSION = packageVersion(PACKAGE_ROOT);
+const CLI_VERSION_LABEL = (() => {
+    const revision = gitRevision(PACKAGE_ROOT);
+    return revision ? `${CLI_VERSION}+g${revision}` : CLI_VERSION;
 })();
 function num(v) {
     if (typeof v !== "string")
@@ -43,18 +87,166 @@ function jobBuildTargetType(v) {
     if (v === undefined)
         return "DATASET";
     if (typeof v !== "string") {
-        throw new UsageError("Invalid --type value for job build. Use DATASET or MANAGED_FOLDER.", "invalid_enum");
+        throw new UsageError("Invalid job target type. Use dataset or managed-folder.", "invalid_enum");
     }
     const normalized = v.trim().toUpperCase().replace(/-/g, "_");
     if (normalized === "DATASET" || normalized === "MANAGED_FOLDER")
         return normalized;
-    throw new UsageError("Invalid --type value for job build. Use DATASET or MANAGED_FOLDER.", "invalid_enum");
+    throw new UsageError("Invalid job target type. Use dataset or managed-folder.", "invalid_enum");
+}
+function jobBuildTargetTypeFromFlags(flags) {
+    return jobBuildTargetType(flags["target-type"] ?? flags["type"]);
+}
+function maxLogLinesFromFlags(flags) {
+    return num(flags["max-log-lines"] ?? flags["max-lines"]);
+}
+function jobLogFilterFromFlag(v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new UsageError("Invalid --log-filter value. Use stdout, stderr, user, or errors.", "invalid_enum");
+    }
+    const normalized = v.trim().toLowerCase();
+    if (normalized === "stdout" || normalized === "stderr" || normalized === "user"
+        || normalized === "errors") {
+        return normalized;
+    }
+    throw new UsageError("Invalid --log-filter value. Use stdout, stderr, user, or errors.", "invalid_enum");
+}
+function recipeBackupPath(recipeName, backupDir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(backupDir, `${sanitizeFileName(recipeName, "recipe")}-${stamp}.recipe-backup.json`);
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function normalizeLineEndings(value) {
+    return value.replace(/\r\n/g, "\n");
+}
+function stableJson(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    const entries = Object.entries(value).sort(([a,], [b,]) => a.localeCompare(b));
+    return `{${entries.map(([key, item,]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+function stableHash(value) {
+    return sha256Hex(stableJson(value));
+}
+function recipeCodeEnv(recipe) {
+    const params = recipe.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return undefined;
+    return params.envSelection;
+}
+function recipeGraph(recipe) {
+    return {
+        inputs: recipe.inputs,
+        outputs: recipe.outputs,
+    };
+}
+function recipeBackupDocument(recipeName, projectKey, current) {
+    return {
+        resource: "recipe",
+        recipeName,
+        projectKey,
+        createdAt: new Date().toISOString(),
+        versionTag: current.recipe.versionTag,
+        payloadHash: sha256Hex(current.payload ?? ""),
+        graphHash: stableHash(recipeGraph(current.recipe)),
+        normalizedPayloadHash: sha256Hex(normalizeLineEndings(current.payload ?? "")),
+        codeEnvHash: stableHash(recipeCodeEnv(current.recipe)),
+        codeEnv: recipeCodeEnv(current.recipe),
+        recipe: current.recipe,
+        payload: current.payload ?? "",
+    };
+}
+function readRecipeBackup(backupPath) {
+    const raw = readFileSync(backupPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && parsed.resource === "recipe")
+            return parsed;
+    }
+    catch {
+        // Backward-compatible payload-only backups are handled below.
+    }
+    return {
+        resource: "recipe",
+        recipeName: "unknown",
+        payloadHash: sha256Hex(raw),
+        payload: raw,
+    };
+}
+function recipeRunShouldWait(flags) {
+    if (flags["wait"] === true && flags["no-wait"] === true) {
+        throw new UsageError("--wait and --no-wait are mutually exclusive.", "invalid_enum");
+    }
+    const waitImplied = flags["include-logs"] === true
+        || flags["summary"] === true
+        || flags["timeout"] !== undefined
+        || flags["poll-interval"] !== undefined;
+    if (flags["no-wait"] === true && waitImplied) {
+        throw new UsageError("--include-logs, --summary, --timeout, and --poll-interval require waiting; remove --no-wait.", "invalid_enum");
+    }
+    return flags["no-wait"] !== true && (flags["wait"] === true || waitImplied);
 }
 function splitCsvFlag(v) {
     if (typeof v !== "string")
         return [];
     return v.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 }
+function recipeInputDatasetsFromFlags(flags) {
+    const inputs = splitCsvFlag(flags["input"]);
+    return inputs.length > 0 ? inputs : undefined;
+}
+function rewritePairsFromFlags(flags, flagName) {
+    const rewrites = {};
+    for (const spec of splitCsvFlag(flags[flagName])) {
+        const idx = spec.indexOf("=");
+        if (idx <= 0 || idx === spec.length - 1) {
+            throw new UsageError(`--${flagName} values must use FROM=TO.`, "invalid_enum");
+        }
+        const from = spec.slice(0, idx).trim();
+        const to = spec.slice(idx + 1).trim();
+        if (!from || !to)
+            throw new UsageError(`--${flagName} values must use FROM=TO.`, "invalid_enum");
+        rewrites[from] = to;
+    }
+    return rewrites;
+}
+function plainRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function datasetSourceSummary(details) {
+    const params = details.params ?? {};
+    return {
+        resource: "dataset",
+        name: details.name,
+        projectKey: details.projectKey,
+        type: details.type,
+        managed: details.managed,
+        connection: params.connection,
+        catalog: params.catalog,
+        schema: params.schema,
+        table: params.table,
+        path: params.path,
+        folderSmartId: params.folderSmartId,
+        formatType: details.formatType,
+    };
+}
+function requiredStringFlag(flags, name, usage) {
+    const value = flags[name];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError(`--${name} is required. Usage: ${usage}`, "missing_required_flag");
+    }
+    return value.trim();
+}
 function flowZoneId(value) {
     const trimmed = value.trim();
     if (!trimmed)
@@ -125,27 +317,298 @@ function flowZoneMoveItems(flags) {
     }
     return items;
 }
-function json(v) {
+function flowZoneItems(zone) {
+    return [...(zone.items ?? []), ...(zone.shared ?? []),];
+}
+function flowZoneContains(zone, object) {
+    return flowZoneItems(zone).some((item) => item.objectId === object.objectId
+        && item.objectType === object.objectType
+        && (object.projectKey === undefined || item.projectKey === object.projectKey));
+}
+function flowZoneSummary(zone, object) {
+    const items = flowZoneItems(zone);
+    return {
+        id: zone.id,
+        name: zone.name,
+        itemCount: items.length,
+        ...(object ? { containsMatchingObject: flowZoneContains(zone, object), } : {}),
+    };
+}
+function flowZoneDetailSummary(zone) {
+    return {
+        ...flowZoneSummary(zone),
+        items: flowZoneItems(zone),
+    };
+}
+async function resolveFlowZoneIdFromFlags(client, flags, projectKey) {
+    const zoneId = typeof flags["zone-id"] === "string" ? flags["zone-id"].trim() : "";
+    if (zoneId)
+        return zoneId;
+    const zone = typeof flags["zone"] === "string" ? flags["zone"].trim() : "";
+    if (!zone)
+        return undefined;
+    const zones = await client.flowZones.list(projectKey);
+    const match = zones.find((candidate) => candidate.id === zone || candidate.name === zone);
+    if (!match)
+        throw new UsageError(`Flow zone not found: ${zone}`, "invalid_enum");
+    return match.id;
+}
+async function moveCreatedItemsToZone(client, flags, items, projectKey) {
+    const zoneId = await resolveFlowZoneIdFromFlags(client, flags, projectKey);
+    if (!zoneId || items.length === 0)
+        return {};
+    await client.flowZones.moveItems(zoneId, items, projectKey);
+    return { zoneId, moved: items, };
+}
+function nestedValue(value, path) {
+    let current = value;
+    for (const key of path) {
+        const record = plainRecord(current);
+        if (!record)
+            return undefined;
+        current = record[key];
+    }
+    return current;
+}
+function stringPath(value, path) {
+    const item = nestedValue(value, path);
+    return typeof item === "string" && item.length > 0 ? item : undefined;
+}
+function numberPath(value, path) {
+    const item = nestedValue(value, path);
+    return typeof item === "number" && Number.isFinite(item) ? item : undefined;
+}
+function firstNumberPath(value, paths) {
+    for (const path of paths) {
+        const item = numberPath(value, path);
+        if (item !== undefined)
+            return item;
+    }
+    return undefined;
+}
+function jobSummaryId(job, fallback) {
+    return stringPath(job, ["baseStatus", "def", "id",])
+        ?? stringPath(job, ["def", "id",])
+        ?? stringPath(job, ["id",])
+        ?? fallback
+        ?? "unknown";
+}
+function jobSummaryType(job) {
+    return stringPath(job, ["baseStatus", "def", "type",])
+        ?? stringPath(job, ["def", "type",])
+        ?? stringPath(job, ["type",])
+        ?? "unknown";
+}
+function jobSummaryState(job) {
+    return stringPath(job, ["baseStatus", "state",])
+        ?? stringPath(job, ["state",])
+        ?? "unknown";
+}
+function filteredJobList(jobs, flags) {
+    const state = typeof flags["state"] === "string" ? flags["state"].trim().toUpperCase() : "";
+    const contains = typeof flags["contains"] === "string"
+        ? flags["contains"].trim().toLowerCase()
+        : "";
+    const output = typeof flags["output"] === "string" ? flags["output"].trim().toLowerCase() : "";
+    let result = jobs.filter((job) => {
+        if (state && jobSummaryState(job).toUpperCase() !== state)
+            return false;
+        const text = JSON.stringify(job).toLowerCase();
+        if (contains && !text.includes(contains))
+            return false;
+        if (output && !text.includes(output))
+            return false;
+        return true;
+    });
+    const limit = flags["latest"] === true ? 1 : num(flags["limit"]);
+    if (limit !== undefined)
+        result = result.slice(0, Math.max(0, limit));
+    return result;
+}
+function maxNumber(values) {
+    return values.length === 0 ? 0 : Math.max(...values);
+}
+function collectWarningCounts(value, inActivity, counts) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectWarningCounts(item, inActivity, counts);
+        return;
+    }
+    const record = plainRecord(value);
+    if (!record)
+        return;
+    for (const [key, item,] of Object.entries(record)) {
+        const lower = key.toLowerCase();
+        const nextInActivity = inActivity || lower.includes("activit");
+        if (lower.includes("warn")) {
+            const target = nextInActivity ? counts.activity : counts.dss;
+            if (typeof item === "number" && Number.isFinite(item))
+                target.push(item);
+            else if (Array.isArray(item))
+                target.push(item.length);
+        }
+        collectWarningCounts(item, nextInActivity, counts);
+    }
+}
+function jobWarningSummary(details, log) {
+    const counts = { dss: [], activity: [], };
+    collectWarningCounts(details, false, counts);
+    const warningLines = log
+        ? log.split(/\r?\n/).map((line) => line.trim()).filter((line) => /\bwarn(?:ing)?\b/i.test(line))
+        : [];
+    return {
+        dssSummaryWarningCount: maxNumber(counts.dss),
+        activityWarningCount: maxNumber(counts.activity),
+        logWarnLineCount: warningLines.length,
+        sampledWarningMessages: warningLines.slice(0, 5),
+    };
+}
+function jobDurationMs(details) {
+    const started = firstNumberPath(details, [
+        ["baseStatus", "startTime",],
+        ["baseStatus", "start",],
+        ["startTime",],
+        ["start",],
+    ]);
+    const ended = firstNumberPath(details, [
+        ["baseStatus", "endTime",],
+        ["baseStatus", "end",],
+        ["endTime",],
+        ["end",],
+    ]);
+    return started !== undefined && ended !== undefined && ended >= started
+        ? ended - started
+        : undefined;
+}
+async function jobInspectionSummary(client, jobId, flags) {
+    const projectKey = flags["project-key"];
+    const details = await client.jobs.get(jobId, projectKey);
+    let log;
+    let logError;
+    try {
+        log = await client.jobs.log(jobId, {
+            activity: flags["activity"],
+            logId: flags["log-id"],
+            maxLogLines: maxLogLinesFromFlags(flags),
+            projectKey,
+        });
+    }
+    catch (error) {
+        logError = error instanceof Error ? error.message : String(error);
+    }
+    const durationMs = jobDurationMs(details);
+    const progress = log ? parseJobLogProgress(log, durationMs) : undefined;
+    const logLines = log
+        ? log.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0)
+        : [];
+    const maxSummaryLines = Math.max(1, maxLogLinesFromFlags(flags) ?? 20);
+    const outputs = nestedValue(details, ["baseStatus", "def", "outputs",])
+        ?? nestedValue(details, ["def", "outputs",])
+        ?? details.outputs;
+    return {
+        resource: "job",
+        jobId: jobSummaryId(details, jobId),
+        state: jobSummaryState(details),
+        type: jobSummaryType(details),
+        ...(durationMs !== undefined ? { durationMs, } : {}),
+        ...(outputs !== undefined ? { outputs, } : {}),
+        warnings: jobWarningSummary(details, log),
+        ...(progress
+            ? {
+                progress,
+                latestUsefulProgressLine: progress.lastProgressLine,
+                doneLine: progress.doneLine,
+            }
+            : {}),
+        logSummary: {
+            lineCount: logLines.length,
+            lines: logLines.slice(-maxSummaryLines),
+            ...(logError ? { error: logError, } : {}),
+        },
+    };
+}
+function stripUtf8Bom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function parseJsonValue(text, source) {
+    try {
+        return JSON.parse(stripUtf8Bom(text));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Invalid JSON in ${source}: ${message}`, "validation_failed");
+    }
+}
+function expectJsonObject(value, source) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    throw new UsageError(`Expected JSON object in ${source}.`, "validation_failed");
+}
+function parseJsonObject(text, source) {
+    return expectJsonObject(parseJsonValue(text, source), source);
+}
+function json(v, source = "JSON flag") {
     if (typeof v !== "string")
         return undefined;
-    return JSON.parse(v);
+    return parseJsonObject(v, source);
 }
-const SQL_QUERY_USAGE = "dss sql query [SQL | --sql QUERY | --sql-file PATH | --sql - | --stdin] (--connection CONN | --dataset FULL_NAME) [--database DB] [--project-key KEY]";
+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] [--request-timeout MS] [--project-key KEY]";
 function readStdinText() {
     return readFileSync(0, "utf-8");
 }
 function jsonInput(flags) {
-    if (flags["stdin"] === true) {
-        return JSON.parse(readStdinText());
-    }
+    if (flags["stdin"] === true)
+        return parseJsonObject(readStdinText(), "stdin");
     if (typeof flags["data-file"] === "string") {
-        return JSON.parse(readFileSync(flags["data-file"], "utf-8"));
+        return parseJsonObject(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
     }
-    if (typeof flags["data"] === "string") {
-        return JSON.parse(flags["data"]);
+    if (typeof flags["data"] === "string")
+        return parseJsonObject(flags["data"], "--data");
+    return undefined;
+}
+function unknownJsonInput(flags) {
+    if (flags["stdin"] === true)
+        return parseJsonValue(readStdinText(), "stdin");
+    if (typeof flags["data-file"] === "string") {
+        return parseJsonValue(readFileSync(flags["data-file"], "utf-8"), flags["data-file"]);
     }
+    if (typeof flags["data"] === "string")
+        return parseJsonValue(flags["data"], "--data");
     return undefined;
 }
+function schemaColumnsInput(flags, usage) {
+    const input = unknownJsonInput(flags);
+    if (input === undefined) {
+        throw new UsageError(`--data, --data-file, or --stdin is required. Usage: ${usage}`);
+    }
+    const columns = Array.isArray(input)
+        ? input
+        : input && typeof input === "object" && Array.isArray(input.columns)
+            ? input.columns
+            : undefined;
+    if (!columns) {
+        throw new UsageError("Schema input must be an array of columns or an object with a columns array.");
+    }
+    return columns.map((column, index) => {
+        if (!column || typeof column !== "object" || Array.isArray(column)) {
+            throw new UsageError(`Schema column at index ${index} must be an object.`);
+        }
+        const record = column;
+        if (typeof record.name !== "string" || record.name.length === 0) {
+            throw new UsageError(`Schema column at index ${index} is missing string field "name".`);
+        }
+        if (typeof record.type !== "string" || record.type.length === 0) {
+            throw new UsageError(`Schema column "${record.name}" is missing string field "type".`);
+        }
+        return {
+            ...record,
+            name: record.name,
+            type: record.type,
+            ...(typeof record.comment === "string" ? { comment: record.comment, } : {}),
+        };
+    });
+}
 function textInput(flags) {
     if (typeof flags["content"] === "string")
         return flags["content"];
@@ -155,7 +618,7 @@ function textInput(flags) {
 }
 function requiredJsonInput(flags, message) {
     const data = jsonInput(flags);
-    if (!data)
+    if (data === undefined)
         throw new UsageError(message);
     return data;
 }
@@ -289,6 +752,28 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
 function writeCommandResult(result) {
     process.stdout.write(`${JSON.stringify(result ?? { ok: true, }, null, 2)}\n`);
 }
+function transientBodyWithTargetContext(body, target, elapsedMs) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const record = parsed;
+            const message = typeof record.message === "string" && record.message.length > 0
+                ? `Target: ${target}\nElapsed: ${elapsedMs}ms\n${record.message}`
+                : `Target: ${target}\nElapsed: ${elapsedMs}ms`;
+            return JSON.stringify({ ...record, message, target, elapsedMs, });
+        }
+    }
+    catch {
+        // Non-JSON DSS bodies are wrapped as text below.
+    }
+    return `Target: ${target}\nElapsed: ${elapsedMs}ms\n${body}`;
+}
+function addTransientTargetContext(error, target, elapsedMs) {
+    if (error instanceof DataikuError && error.category === "transient") {
+        throw new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry);
+    }
+    throw error;
+}
 function isFailedWaitResult(result) {
     if (result === null || typeof result !== "object" || Array.isArray(result))
         return false;
@@ -299,7 +784,11 @@ function isFailedWaitResult(result) {
         && (typeof record.state === "string" || typeof record.outcome === "string");
 }
 function commandFailureExitCode(result) {
-    return isFailedWaitResult(result) ? 4 : undefined;
+    if (isFailedWaitResult(result))
+        return 4;
+    if (result && typeof result === "object" && result.unchanged === false)
+        return 4;
+    return undefined;
 }
 function isNotFoundError(error) {
     if (error instanceof DataikuError)
@@ -331,6 +820,7 @@ function planResult(resource, action, options) {
         ...(options.method ? { method: options.method, } : {}),
         ...(options.endpoint ? { endpoint: options.endpoint, } : {}),
         ...(options.payload !== undefined ? { payload: options.payload, } : {}),
+        ...(options.localWrites !== undefined ? { localWrites: options.localWrites, } : {}),
         ...(options.wait !== undefined ? { wait: options.wait, } : {}),
         idempotency: options.idempotency,
         async: options.asyncKind,
@@ -360,7 +850,7 @@ function resultRecord(result) {
         : {};
 }
 function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
-    if (!(action.startsWith("create") || action === "upload"))
+    if (!(action.startsWith("create") || action === "clone" || action === "upload"))
         return undefined;
     const record = resultRecord(result);
     if (record.skipped !== undefined)
@@ -380,6 +870,16 @@ function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
                 cleanup: { argv: ["dataset", "delete", name, "--if-exists", ...withProject,], },
             };
         }
+        case "dataset.clone": {
+            const name = stringField(record, ["target", "created", "name",]) ?? args[1];
+            if (!name)
+                return undefined;
+            return {
+                ...base,
+                name,
+                cleanup: { argv: ["dataset", "delete", name, "--if-exists", ...withProject,], },
+            };
+        }
         case "recipe.create": {
             const name = stringField(record, ["created", "recipeName", "name",])
                 ?? flags["name"];
@@ -391,6 +891,17 @@ function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
                 cleanup: { argv: ["recipe", "delete", name, "--if-exists", ...withProject,], },
             };
         }
+        case "recipe.clone": {
+            const name = stringField(record, ["recipeName", "target", "created", "name",])
+                ?? flags["name"];
+            if (!name)
+                return undefined;
+            return {
+                ...base,
+                name,
+                cleanup: { argv: ["recipe", "delete", name, "--if-exists", ...withProject,], },
+            };
+        }
         case "scenario.create": {
             const id = args[0];
             return {
@@ -504,9 +1015,11 @@ const BOOLEAN_FLAGS = new Set([
     "global",
     "list-agents",
     "include-raw",
+    "raw",
     "include-payload",
     "no-payload",
     "include-logs",
+    "summary",
     "replace",
     "dry-run",
     "plan",
@@ -521,7 +1034,12 @@ const BOOLEAN_FLAGS = new Set([
     "report-json",
     "no-wait",
     "force-rebuild",
+    "latest",
+    "copy-output-settings",
     "continue-on-error",
+    "no-backup",
+    "payload-only",
+    "allow-same-path",
 ]);
 const SHORT_FLAGS = {
     h: "help",
@@ -536,17 +1054,22 @@ const FLAG_ALIASES = {
     "skip-tls-verify": "insecure",
     "extra-ca-certs": "ca-cert",
     explain: "plan",
+    "zone-name": "zone",
 };
 const VALUE_FLAGS = new Set([
     "activity",
     "agent",
     "api-key",
     "build-mode",
+    "backup-dir",
+    "backup",
     "ca-cert",
+    "catalog",
     "cell-id",
     "allow-types",
     "color",
     "connection",
+    "contains",
     "content",
     "content-type",
     "data",
@@ -560,6 +1083,7 @@ const VALUE_FLAGS = new Set([
     "install-core-packages",
     "folder",
     "input",
+    "from",
     "knowledge-bank",
     "labeling-task",
     "lang",
@@ -568,17 +1092,23 @@ const VALUE_FLAGS = new Set([
     "local",
     "max-edges",
     "max-lines",
+    "max-log-lines",
     "listed",
     "max-nodes",
     "max-rows",
+    "limit",
     "max-timestamp",
     "only-monitored",
     "min-timestamp",
     "mode",
+    "log-filter",
+    "log-id",
     "model-evaluation-store",
     "name",
     "object",
+    "metastore-table",
     "output",
+    "output-file",
     "output-connection",
     "output-folder",
     "page",
@@ -592,18 +1122,41 @@ const VALUE_FLAGS = new Set([
     "results-per-page",
     "record-cleanup",
     "rule-id",
+    "retries",
     "poll-interval",
     "python-interpreter",
+    "replace-input",
+    "replace-output",
+    "replace-payload-text",
     "retain",
     "saved-model",
     "sql",
+    "schema",
     "sql-file",
     "standard",
+    "state",
     "streaming-endpoint",
     "target",
+    "target-type",
     "timeout",
+    "table",
     "type",
     "url",
+    "until",
+    "to",
+    "zone",
+    "zone-id",
+]);
+const REPEATABLE_VALUE_FLAGS = new Set([
+    "dataset",
+    "folder",
+    "input",
+    "object",
+    "package",
+    "recipe",
+    "replace-input",
+    "replace-output",
+    "replace-payload-text",
 ]);
 const KNOWN_LONG_FLAGS = new Set([
     ...BOOLEAN_FLAGS,
@@ -627,6 +1180,14 @@ function requireFlagValue(flagLabel, next) {
     }
     return next;
 }
+function setParsedFlagValue(flags, flagName, value) {
+    const current = flags[flagName];
+    if (REPEATABLE_VALUE_FLAGS.has(flagName) && typeof current === "string" && current.length > 0) {
+        flags[flagName] = `${current},${value}`;
+        return;
+    }
+    flags[flagName] = value;
+}
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -642,7 +1203,7 @@ function parseArgs(argv) {
             if (eqIdx !== -1) {
                 const raw = arg.slice(2, eqIdx);
                 const flagName = normalizeLongFlag(raw);
-                flags[flagName] = arg.slice(eqIdx + 1);
+                setParsedFlagValue(flags, flagName, arg.slice(eqIdx + 1));
             }
             else {
                 const rawFlagName = arg.slice(2);
@@ -652,7 +1213,7 @@ function parseArgs(argv) {
                 }
                 else {
                     const next = requireFlagValue(`--${rawFlagName}`, argv[i + 1]);
-                    flags[flagName] = next;
+                    setParsedFlagValue(flags, flagName, next);
                     i++;
                 }
             }
@@ -665,7 +1226,7 @@ function parseArgs(argv) {
                 }
                 else {
                     const next = requireFlagValue(`-${arg[1]}`, argv[i + 1]);
-                    flags[long] = next;
+                    setParsedFlagValue(flags, long, next);
                     i++;
                 }
             }
@@ -1374,10 +1935,45 @@ const commands = {
     },
     "flow-zone": {
         list: {
-            handler: (c, _a, f) => c.flowZones.list(f["project-key"]),
-            usage: "dss flow-zone list [--project-key KEY]",
-            description: "List flow zones in a project.",
-            examples: ["dss flow-zone list",],
+            handler: async (c, _a, f) => {
+                const zones = await c.flowZones.list(f["project-key"]);
+                if (f["summary"] !== true)
+                    return zones;
+                const objects = flowZoneMoveItems(f);
+                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",],
+        },
+        find: {
+            handler: async (c, a, f) => {
+                const zones = await c.flowZones.list(f["project-key"]);
+                const objects = flowZoneMoveItems(f);
+                const query = a[0]?.trim();
+                if (query && objects.length === 0) {
+                    const normalized = query.toLowerCase();
+                    return zones
+                        .filter((zone) => zone.id.toLowerCase().includes(normalized)
+                        || zone.name.toLowerCase().includes(normalized))
+                        .map((zone) => flowZoneDetailSummary(zone));
+                }
+                if (objects.length !== 1) {
+                    throw new UsageError("Exactly one zone name/id or object is required. Use <name>, --object TYPE:ID, --dataset DS, or --recipe R.");
+                }
+                const object = objects[0];
+                return zones
+                    .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",
+                "dss flow-zone find --object RECIPE:compute_orders",
+                "dss flow-zone find --dataset orders",
+            ],
         },
         get: {
             handler: (c, a, f) => {
@@ -1472,7 +2068,11 @@ const commands = {
         },
         move: {
             handler: async (c, a, f) => {
-                requireArgs(a, 1, "dss flow-zone move <id> [--dataset DS] [--recipe R] [--folder F] [--object TYPE:ID]");
+                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]");
+                }
                 const items = flowZoneMoveItems(f);
                 if (items.length === 0) {
                     throw new UsageError("At least one object is required. Use --dataset, --recipe, --folder, or --object TYPE:ID.");
@@ -1482,17 +2082,17 @@ const commands = {
                         dryRun: true,
                         action: "move",
                         resource: "flow-zone",
-                        id: flowZoneId(a[0]),
+                        id: zoneId,
                         items,
                     };
                 }
-                return c.flowZones.moveItems(flowZoneId(a[0]), items, f["project-key"]);
+                return c.flowZones.moveItems(zoneId, items, pk);
             },
-            usage: "dss flow-zone move <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.",
+            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",
-                "dss flow-zone move ZONE_ID --dataset raw_orders,clean_orders --recipe prepare_orders",
+                "dss flow-zone move --zone ATH_SNW_MAP_FRG49 --dataset raw_orders,clean_orders --recipe prepare_orders",
                 "dss flow-zone move ZONE_ID --folder FOLDER_ID",
                 "dss flow-zone move ZONE_ID --object SAVED_MODEL:model_id",
             ],
@@ -1532,6 +2132,50 @@ const commands = {
             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>");
+                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",],
+        },
+        "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]";
+                requireArgs(a, 1, usage);
+                const columns = schemaColumnsInput(f, usage);
+                const pk = f["project-key"];
+                if (f["dry-run"] === true) {
+                    const current = await c.datasets.schema(a[0], pk);
+                    return {
+                        dryRun: true,
+                        action: "refresh-schema",
+                        resource: "dataset",
+                        name: a[0],
+                        current,
+                        next: { columns, },
+                    };
+                }
+                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`,
+            ],
+        },
+        "validate-build": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss dataset validate-build <name>");
+                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: (c, a, f) => {
                 requireArgs(a, 1, "dss dataset preview <name>");
@@ -1581,6 +2225,7 @@ const commands = {
                     dsType,
                     projectKey: pk,
                 };
+                const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
                 if (f["if-not-exists"] === true || f["dry-run"] === true) {
                     const list = await c.datasets.list(pk);
                     const existing = list.find((d) => d.name === name);
@@ -1595,17 +2240,57 @@ const commands = {
                             name,
                             payload,
                             ...(existing ? { current: existing, } : {}),
+                            ...(zoneId ? { zoneId, zoneMove: [{ objectId: name, objectType: "DATASET", },], } : {}),
                         };
                     }
                 }
                 await c.datasets.create(payload);
-                return { created: name, resource: "dataset", };
+                const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "DATASET", },], pk);
+                return { created: name, resource: "dataset", ...moved, };
             },
-            usage: "dss dataset create --name NAME --connection CONN --type TYPE [--if-not-exists] [--dry-run] [--project-key KEY]",
+            usage: "dss dataset create --name NAME --connection CONN --type TYPE [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--project-key KEY]",
             description: "Create a new dataset.",
             examples: [
                 "dss dataset create --name orders --connection filesystem --type Filesystem",
-                "dss dataset create --name orders --connection filesystem --type Filesystem --dry-run",
+                "dss dataset create --name orders --connection filesystem --type Filesystem --zone Experiments --dry-run",
+            ],
+        },
+        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]";
+                requireArgs(a, 2, usage);
+                const pk = f["project-key"];
+                const opts = {
+                    projectKey: pk,
+                    path: f["path"],
+                    table: f["table"],
+                    metastoreTableName: f["metastore-table"],
+                    allowSamePath: f["allow-same-path"] === true,
+                };
+                const current = await c.datasets.get(a[0], pk);
+                const next = buildDatasetCloneSettings(current, a[1], pk ?? c.resolveProjectKey(pk), opts);
+                const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "clone",
+                        resource: "dataset",
+                        source: a[0],
+                        target: a[1],
+                        current,
+                        next,
+                        ...(zoneId ? { zoneId, zoneMove: [{ objectId: a[1], objectType: "DATASET", },], } : {}),
+                    };
+                }
+                const cloned = await c.datasets.clone(a[0], a[1], opts);
+                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",
+                "dss dataset clone source_ds experiment_ds --allow-same-path",
             ],
         },
         delete: {
@@ -1674,6 +2359,60 @@ const commands = {
                 "dss recipe get compute_orders --include-payload",
             ],
         },
+        "validate-graph": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss recipe validate-graph <name>");
+                return c.recipes.validateGraph(a[0], {
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe validate-graph <name> [--project-key KEY]",
+            description: "Validate declared recipe input/output graph references before building.",
+            examples: ["dss recipe validate-graph compute_orders",],
+        },
+        run: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss recipe run <name>");
+                const pk = f["project-key"];
+                const wait = recipeRunShouldWait(f);
+                const options = {
+                    buildMode: f["build-mode"],
+                    includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    partition: f["partition"],
+                    pollIntervalMs: num(f["poll-interval"]),
+                    projectKey: pk,
+                    timeoutMs: num(f["timeout"]),
+                    summary: f["summary"] === true,
+                    wait,
+                };
+                if (f["dry-run"] === true) {
+                    const outputs = await c.recipes.resolveRunOutputs(a[0], {
+                        partition: options.partition,
+                        projectKey: pk,
+                    });
+                    return {
+                        dryRun: true,
+                        action: "run",
+                        resource: "recipe",
+                        recipe: a[0],
+                        outputs,
+                        ...options,
+                        endpoint: encodedProjectEndpoint(c, pk, "/jobs/"),
+                        method: "POST",
+                    };
+                }
+                return c.recipes.run(a[0], options);
+            },
+            usage: "dss recipe run <name> [--wait|--no-wait] [--build-mode MODE] [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
+            description: "Run a recipe by resolving its outputs and submitting the correct dataset or managed-folder build job.",
+            examples: [
+                "dss recipe run compute_orders --wait",
+                "dss recipe run compute_exports --include-logs --log-filter stdout --summary --timeout 600000",
+                "dss recipe run compute_exports --dry-run",
+            ],
+        },
         delete: {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe delete <name>");
@@ -1742,15 +2481,20 @@ const commands = {
                 }
                 const name = f["name"];
                 const pk = f["project-key"];
+                const inputDatasets = recipeInputDatasetsFromFlags(f);
                 const payload = {
                     type,
                     name,
-                    inputDatasets: f["input"] ? [f["input"],] : undefined,
+                    inputDatasets,
                     outputDataset,
                     outputFolder,
                     outputConnection: f["output-connection"],
                     projectKey: pk,
                 };
+                const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+                const zoneMove = zoneId && name
+                    ? [{ objectId: name, objectType: "RECIPE", },]
+                    : undefined;
                 if ((f["if-not-exists"] === true || f["dry-run"] === true) && name) {
                     const list = await c.recipes.list(pk);
                     const existing = list.find((r) => r.name === name);
@@ -1764,24 +2508,106 @@ const commands = {
                             resource: "recipe",
                             name,
                             payload,
+                            ...(zoneId ? { zoneId, zoneMove, } : {}),
                             ...(existing ? { current: existing, } : {}),
                         };
                     }
                 }
                 if (f["dry-run"] === true) {
-                    return { dryRun: true, action: "create", resource: "recipe", payload, };
+                    return {
+                        dryRun: true,
+                        action: "create",
+                        resource: "recipe",
+                        payload,
+                        ...(zoneId ? { zoneId, zoneMove, } : {}),
+                    };
                 }
                 const created = await c.recipes.create(payload);
-                return { created: created.recipeName, resource: "recipe", ...created, };
+                const createdName = created.recipeName;
+                const moved = await moveCreatedItemsToZone(c, f, [{
+                        objectId: createdName,
+                        objectType: "RECIPE",
+                    },], pk);
+                return { created: createdName, resource: "recipe", ...created, ...moved, };
             },
-            usage: "dss recipe create --type TYPE --input DS (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--if-not-exists] [--dry-run] [--project-key KEY]",
-            description: "Create a recipe with a dataset output, or use --output-folder with --output-connection for a managed-folder output.",
+            usage: "dss recipe create --type TYPE --input DS[,DS2] (--output DS | --output-folder FOLDER_ID) [--name NAME] [--output-connection CONN] [--zone ZONE|--zone-id ID] [--if-not-exists] [--dry-run] [--project-key KEY]",
+            description: "Create a recipe with one or more inputs and a dataset or managed-folder output.",
             examples: [
-                "dss recipe create --type python --input orders --output orders_clean",
-                "dss recipe create --type python --input orders --output orders_clean --output-connection filesystem",
+                "dss recipe create --type python --input raw_orders,lookup --output orders_clean",
+                "dss recipe create --type python --input orders --input customers --output orders_clean --zone Experiments",
                 "dss recipe create --type python --input orders --output-folder LT7TUHJ8 --output-connection filesystem --dry-run",
             ],
         },
+        clone: {
+            handler: async (c, a, f) => {
+                const usage = "dss recipe clone [source|--from SOURCE] (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]";
+                const fromFlag = typeof f["from"] === "string" ? f["from"].trim() : "";
+                const sourceName = a[0] ?? fromFlag;
+                if (!sourceName) {
+                    throw new UsageError(`Source recipe is required. Usage: ${usage}`, "missing_required_flag");
+                }
+                if (a[0] && fromFlag && a[0] !== fromFlag) {
+                    throw new UsageError("Positional source and --from must match when both are provided.", "invalid_enum");
+                }
+                const pk = f["project-key"];
+                const toFlag = typeof f["to"] === "string" ? f["to"].trim() : "";
+                const nameFlag = typeof f["name"] === "string" ? f["name"].trim() : "";
+                const name = toFlag || nameFlag;
+                if (!name) {
+                    throw new UsageError(`--name or --to is required. Usage: ${usage}`, "missing_required_flag");
+                }
+                const inputRewrites = rewritePairsFromFlags(f, "replace-input");
+                const outputRewrites = rewritePairsFromFlags(f, "replace-output");
+                const payloadTextRewrites = rewritePairsFromFlags(f, "replace-payload-text");
+                const opts = {
+                    projectKey: pk,
+                    name,
+                    outputDataset: f["output"],
+                    outputRewrites,
+                    inputRewrites,
+                    payloadTextRewrites,
+                    copyOutputSettings: f["copy-output-settings"] === true,
+                    outputPath: f["path"],
+                    metastoreTableName: f["metastore-table"],
+                };
+                const source = await c.recipes.get(sourceName, { includePayload: true, projectKey: pk, });
+                const outputItems = Object.values((source.recipe.outputs ?? {})).flatMap((role) => role.items ?? []).filter((item) => typeof item.ref === "string");
+                const plannedOutputRewrites = { ...outputRewrites, };
+                if (opts.outputDataset !== undefined && outputItems.length === 1) {
+                    plannedOutputRewrites[outputItems[0].ref] = opts.outputDataset;
+                }
+                if (opts.copyOutputSettings === true
+                    && Object.keys(plannedOutputRewrites).length > 1
+                    && (opts.outputPath !== undefined || opts.metastoreTableName !== undefined)) {
+                    throw new UsageError("Cannot reuse --path or --metastore-table for multiple cloned output datasets.", "invalid_enum");
+                }
+                const zoneId = await resolveFlowZoneIdFromFlags(c, f, pk);
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "clone",
+                        resource: "recipe",
+                        source: sourceName,
+                        target: name,
+                        inputRewrites,
+                        outputRewrites: plannedOutputRewrites,
+                        copyOutputSettings: opts.copyOutputSettings,
+                        payloadTextRewrites,
+                        current: source,
+                        ...(zoneId ? { zoneId, zoneMove: [{ objectId: name, objectType: "RECIPE", },], } : {}),
+                    };
+                }
+                const cloned = await c.recipes.clone(sourceName, opts);
+                const moved = await moveCreatedItemsToZone(c, f, [{ objectId: name, objectType: "RECIPE", },], pk);
+                return { ...cloned, resource: "recipe", ...moved, };
+            },
+            usage: "dss recipe clone [source|--from SOURCE] (--name NAME|--to NAME) [--replace-input FROM=TO] [--replace-output FROM=TO] [--replace-payload-text FROM=TO] [--output DATASET] [--copy-output-settings] [--path PATH] [--metastore-table TABLE] [--zone ZONE|--zone-id ID] [--dry-run] [--project-key KEY]",
+            description: "Clone a recipe graph/settings/payload into a separate experiment recipe.",
+            examples: [
+                "dss recipe clone compute_orders --name compute_orders_opt --output orders_opt --copy-output-settings --dry-run",
+                "dss recipe clone compute_orders --name compute_orders_opt --output orders_opt --zone Experiments",
+            ],
+        },
         diff: {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe diff <name> --file PATH");
@@ -1846,13 +2672,24 @@ const commands = {
                 }
                 return payload;
             },
-            usage: "dss recipe get-payload <name> [--output PATH] [--project-key KEY]",
-            description: "Print the recipe code payload to stdout.",
+            usage: "dss recipe get-payload <name> [--raw] [--output PATH] [--project-key KEY]",
+            description: "Print the recipe code payload to stdout; use --raw for pipeable code bytes.",
             examples: [
-                "dss recipe get-payload compute_orders",
+                "dss recipe get-payload compute_orders --raw",
                 "dss recipe get-payload compute_orders -o code.py",
             ],
         },
+        cat: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss recipe cat <name> [--raw]");
+                return c.recipes.getPayload(a[0], {
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe cat <name> [--raw] [--project-key KEY]",
+            description: "Print a recipe code payload; combine with --raw for shell pipes and diffs.",
+            examples: ["dss recipe cat compute_orders --raw",],
+        },
         "set-payload": {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe set-payload <name> --file PATH");
@@ -1860,11 +2697,17 @@ const commands = {
                 if (!filePath)
                     throw new UsageError("--file is required.");
                 const content = readFileSync(filePath, "utf-8");
+                const pk = f["project-key"];
+                const shouldBackup = f["no-backup"] !== true;
+                const backupDir = shouldBackup
+                    ? f["backup-dir"] ?? join(process.cwd(), ".dss-backups", "recipes")
+                    : undefined;
+                const backupPath = backupDir ? recipeBackupPath(a[0], backupDir) : undefined;
+                const current = await c.recipes.get(a[0], {
+                    projectKey: pk,
+                    includePayload: true,
+                });
                 if (f["dry-run"] === true) {
-                    const current = await c.recipes.get(a[0], {
-                        projectKey: f["project-key"],
-                        includePayload: true,
-                    });
                     return {
                         dryRun: true,
                         action: "set-payload",
@@ -1873,24 +2716,140 @@ const commands = {
                         file: filePath,
                         current,
                         next: { ...current, payload: content, },
+                        ...(backupPath ? { backupPath, backup: recipeBackupDocument(a[0], pk, current), } : {}),
                     };
                 }
-                await c.recipes.setPayload(a[0], content, {
+                if (backupDir && backupPath) {
+                    await mkdir(backupDir, { recursive: true, });
+                    await writeFile(backupPath, `${JSON.stringify(recipeBackupDocument(a[0], pk, current), null, 2)}\n`, "utf-8");
+                }
+                await c.recipes.replace(a[0], { ...current, payload: content, }, pk);
+                return {
+                    updated: a[0],
+                    resource: "recipe",
+                    file: filePath,
+                    backupCreated: backupPath !== undefined,
+                    ...(backupPath ? { backupPath, } : {}),
+                };
+            },
+            usage: "dss recipe set-payload <name> --file PATH [--backup-dir DIR|--no-backup] [--dry-run] [--project-key KEY]",
+            description: "Upload recipe code from a local file, backing up payload, graph, settings, and version metadata by default.",
+            examples: [
+                "dss recipe set-payload compute_orders --file code.py --dry-run",
+                "dss recipe set-payload compute_orders --file code.py --backup-dir ./backups",
+                "dss recipe set-payload compute_orders --file code.py --no-backup",
+            ],
+        },
+        restore: {
+            handler: async (c, a, f) => {
+                const usage = "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]";
+                requireArgs(a, 1, usage);
+                const backupPath = requiredStringFlag(f, "backup", usage);
+                const backup = readRecipeBackup(backupPath);
+                const payload = typeof backup.payload === "string" ? backup.payload : "";
+                const pk = f["project-key"];
+                const current = await c.recipes.get(a[0], { includePayload: true, projectKey: pk, });
+                const backupRecipe = backup.recipe && typeof backup.recipe === "object" && !Array.isArray(backup.recipe)
+                    ? backup.recipe
+                    : undefined;
+                const restoredRecipe = backupRecipe
+                    ? { ...backupRecipe, name: a[0], ...(pk ? { projectKey: pk, } : {}), }
+                    : undefined;
+                const next = f["payload-only"] === true || !restoredRecipe
+                    ? { ...current, payload, }
+                    : { ...current, recipe: restoredRecipe, payload, };
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "restore",
+                        resource: "recipe",
+                        name: a[0],
+                        backupPath,
+                        current,
+                        next,
+                    };
+                }
+                await c.recipes.replace(a[0], next, pk);
+                return {
+                    restored: a[0],
+                    resource: "recipe",
+                    backupPath,
+                    payloadOnly: f["payload-only"] === true,
+                };
+            },
+            usage: "dss recipe restore <name> --backup FILE [--payload-only] [--dry-run] [--project-key KEY]",
+            description: "Restore a recipe from a set-payload backup.",
+            examples: [
+                "dss recipe restore compute_orders --backup .dss-backups/recipes/backup.recipe-backup.json --dry-run",
+            ],
+        },
+        "assert-unchanged": {
+            handler: async (c, a, f) => {
+                const usage = "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]";
+                requireArgs(a, 1, usage);
+                const backupPath = requiredStringFlag(f, "since", usage);
+                const backup = readRecipeBackup(backupPath);
+                const current = await c.recipes.get(a[0], {
+                    includePayload: true,
                     projectKey: f["project-key"],
                 });
-                return { updated: a[0], resource: "recipe", file: filePath, };
+                const payloadHash = sha256Hex(current.payload ?? "");
+                const normalizedPayloadHash = sha256Hex(normalizeLineEndings(current.payload ?? ""));
+                const expectedPayloadHash = typeof backup.payloadHash === "string"
+                    ? backup.payloadHash
+                    : undefined;
+                const expectedNormalizedPayloadHash = typeof backup.normalizedPayloadHash === "string"
+                    ? backup.normalizedPayloadHash
+                    : typeof backup.payload === "string"
+                        ? sha256Hex(normalizeLineEndings(backup.payload))
+                        : undefined;
+                const checks = [
+                    {
+                        name: "payload",
+                        expected: expectedPayloadHash,
+                        actual: payloadHash,
+                        unchanged: expectedPayloadHash === payloadHash
+                            || (expectedNormalizedPayloadHash !== undefined
+                                && expectedNormalizedPayloadHash === normalizedPayloadHash),
+                        normalizedExpected: expectedNormalizedPayloadHash,
+                        normalizedActual: normalizedPayloadHash,
+                    },
+                    {
+                        name: "graph",
+                        expected: backup.graphHash,
+                        actual: stableHash(recipeGraph(current.recipe)),
+                        unchanged: backup.graphHash === stableHash(recipeGraph(current.recipe)),
+                    },
+                    {
+                        name: "codeEnv",
+                        expected: backup.codeEnvHash,
+                        actual: stableHash(recipeCodeEnv(current.recipe)),
+                        unchanged: backup.codeEnvHash === stableHash(recipeCodeEnv(current.recipe)),
+                    },
+                ].filter((check) => typeof check.expected === "string");
+                const failures = checks.filter((check) => !check.unchanged);
+                return {
+                    unchanged: failures.length === 0,
+                    resource: "recipe",
+                    name: a[0],
+                    backupPath,
+                    checks,
+                    failures,
+                };
             },
-            usage: "dss recipe set-payload <name> --file PATH [--dry-run] [--project-key KEY]",
-            description: "Upload recipe code from a local file.",
-            examples: ["dss recipe set-payload compute_orders --file code.py --dry-run",],
+            usage: "dss recipe assert-unchanged <name> --since BACKUP [--project-key KEY]",
+            description: "Compare current recipe payload, graph, and code env against a backup.",
+            examples: [
+                "dss recipe assert-unchanged compute_orders --since .dss-backups/recipes/backup.recipe-backup.json",
+            ],
         },
     },
     job: {
         list: {
-            handler: (c, _a, f) => c.jobs.list(f["project-key"]),
-            usage: "dss job list [--project-key KEY]",
-            description: "List recent jobs.",
-            examples: ["dss job list",],
+            handler: async (c, _a, f) => filteredJobList(await c.jobs.list(f["project-key"]), f),
+            usage: "dss job list [--state STATE] [--contains TEXT] [--output ID] [--latest] [--limit N] [--project-key KEY]",
+            description: "List recent jobs, optionally filtered for automation.",
+            examples: ["dss job list --state DONE --latest", "dss job list --contains WLM225S --limit 10",],
         },
         get: {
             handler: (c, a, f) => {
@@ -1901,17 +2860,42 @@ const commands = {
             description: "Get job details.",
             examples: ["dss job get JOB_ID",],
         },
+        summary: {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss job summary <id>");
+                return jobInspectionSummary(c, a[0], f);
+            },
+            usage: "dss job summary <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--max-lines N|--max-log-lines N] [--project-key KEY]",
+            description: "Summarize job state, outputs, warnings, progress, and useful terminal log lines.",
+            examples: ["dss job summary JOB_ID --max-log-lines 200",],
+        },
         log: {
             handler: (c, a, f) => {
                 requireArgs(a, 1, "dss job log <id>");
                 return c.jobs.log(a[0], {
                     activity: f["activity"],
-                    maxLogLines: num(f["max-lines"]),
+                    logId: f["log-id"],
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss job log <id> [--activity NAME] [--max-lines N]",
-            description: "Get log output for a job.",
-            examples: ["dss job log JOB_ID", "dss job log JOB_ID --activity main --max-lines 200",],
+            usage: "dss job log <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--max-lines N|--max-log-lines N] [--project-key KEY]",
+            description: "Get public API job log output. --log-id is accepted for UI parity but DSS API-key auth cannot select browser-only cat-activity-log files.",
+            examples: [
+                "dss job log JOB_ID",
+                "dss job log JOB_ID --activity main --max-log-lines 200",
+            ],
+        },
+        "log-url": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss job log-url <url>");
+                return c.jobs.logFromUrl(a[0], { maxLogLines: maxLogLinesFromFlags(f), });
+            },
+            usage: "dss job log-url <url> [--max-lines N|--max-log-lines N]",
+            description: "Fetch a DSS cat-activity-log URL pasted from the UI.",
+            examples: [
+                'dss job log-url "https://dss/dip/api/flow/jobs/cat-activity-log?projectKey=TEST&jobId=JOB&activityId=A&logId=L"',
+            ],
         },
         build: {
             handler: async (c, a, f) => {
@@ -1919,8 +2903,9 @@ const commands = {
                 const pk = f["project-key"];
                 const options = {
                     buildMode: f["build-mode"],
+                    partition: f["partition"],
                     pollIntervalMs: num(f["poll-interval"]),
-                    targetType: jobBuildTargetType(f["type"]),
+                    targetType: jobBuildTargetTypeFromFlags(f),
                     timeoutMs: num(f["timeout"]),
                 };
                 if (f["dry-run"] === true) {
@@ -1939,12 +2924,12 @@ const commands = {
                 }
                 return c.jobs.build(a[0], { ...options, projectKey: pk, });
             },
-            usage: "dss job build <target> [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--wait] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
+            usage: "dss job build <target> [--target-type dataset|managed-folder] [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--wait] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
             description: "Start a dataset or managed-folder build, optionally waiting for completion.",
             examples: [
                 "dss job build orders",
                 "dss job build orders --build-mode RECURSIVE_BUILD --wait",
-                "dss job build LT7TUHJ8 --type MANAGED_FOLDER --dry-run",
+                "dss job build LT7TUHJ8 --target-type managed-folder --dry-run",
             ],
         },
         "build-and-wait": {
@@ -1954,9 +2939,13 @@ const commands = {
                 const options = {
                     buildMode: f["build-mode"],
                     includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    partition: f["partition"],
                     pollIntervalMs: num(f["poll-interval"]),
                     timeoutMs: num(f["timeout"]),
-                    targetType: jobBuildTargetType(f["type"]),
+                    summary: f["summary"] === true,
+                    targetType: jobBuildTargetTypeFromFlags(f),
                 };
                 if (f["dry-run"] === true) {
                     return {
@@ -1971,13 +2960,13 @@ const commands = {
                 }
                 return c.jobs.buildAndWait(a[0], { ...options, projectKey: pk, });
             },
-            usage: "dss job build-and-wait <target> [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--include-logs] [--timeout MS] [--poll-interval MS] [--dry-run] [--project-key KEY]",
+            usage: "dss job build-and-wait <target> [--target-type dataset|managed-folder] [--type DATASET|MANAGED_FOLDER] [--build-mode MODE] [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--partition PARTITION] [--dry-run] [--project-key KEY]",
             description: "Build a dataset or managed folder and wait for completion.",
             examples: [
                 "dss job build-and-wait orders",
-                "dss job build-and-wait orders --include-logs",
+                "dss job build-and-wait orders --include-logs --log-filter stdout --summary",
                 "dss job build-and-wait orders --timeout 300000",
-                "dss job build-and-wait LT7TUHJ8 --type MANAGED_FOLDER --dry-run",
+                "dss job build-and-wait LT7TUHJ8 --target-type managed-folder --dry-run",
             ],
         },
         wait: {
@@ -1985,13 +2974,58 @@ const commands = {
                 requireArgs(a, 1, "dss job wait <id>");
                 return c.jobs.wait(a[0], {
                     includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
                     pollIntervalMs: num(f["poll-interval"]),
                     timeoutMs: num(f["timeout"]),
+                    summary: f["summary"] === true,
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss job wait <id> [--include-logs] [--timeout MS] [--poll-interval MS]",
+            usage: "dss job wait <id> [--include-logs] [--log-filter stdout|stderr|user|errors] [--summary] [--max-log-lines N] [--timeout MS] [--poll-interval MS]",
             description: "Wait for an existing job to complete.",
-            examples: ["dss job wait JOB_ID", "dss job wait JOB_ID --include-logs --timeout 60000",],
+            examples: [
+                "dss job wait JOB_ID",
+                "dss job wait JOB_ID --include-logs --log-filter stdout --summary --timeout 60000",
+            ],
+        },
+        monitor: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss job monitor <id...>");
+                const options = {
+                    includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    pollIntervalMs: num(f["poll-interval"]),
+                    timeoutMs: num(f["timeout"]),
+                    summary: f["summary"] !== false,
+                    projectKey: f["project-key"],
+                };
+                const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+                return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            },
+            usage: "dss job monitor <id...> [--summary] [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
+            description: "Monitor one or more existing jobs and summarize progress counters from logs.",
+            examples: ["dss job monitor JOB_ID --summary", "dss job monitor JOB1 JOB2 --until all-done",],
+        },
+        watch: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss job watch <id...>");
+                const options = {
+                    includeLogs: f["include-logs"] === true,
+                    logFilter: jobLogFilterFromFlag(f["log-filter"]),
+                    maxLogLines: maxLogLinesFromFlags(f),
+                    pollIntervalMs: num(f["poll-interval"]),
+                    timeoutMs: num(f["timeout"]),
+                    summary: true,
+                    projectKey: f["project-key"],
+                };
+                const jobs = await Promise.all(a.map((jobId) => c.jobs.wait(jobId, options)));
+                return a.length === 1 ? jobs[0] : { jobs, until: f["until"] ?? "all-done", };
+            },
+            usage: "dss job watch <id...> [--include-logs] [--log-filter stdout|stderr|user|errors] [--max-log-lines N] [--timeout MS] [--poll-interval MS] [--until all-done] [--project-key KEY]",
+            description: "Watch one or more existing jobs with progress extraction enabled.",
+            examples: ["dss job watch JOB_ID", "dss job watch JOB1 JOB2 --until all-done",],
         },
         abort: {
             handler: async (c, a, f) => {
@@ -2028,7 +3062,7 @@ const commands = {
                 return c.scenarios.get(a[0], { projectKey: f["project-key"], });
             },
             usage: "dss scenario get <id> [--project-key KEY]",
-            description: "Get scenario definition.",
+            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: {
@@ -2159,21 +3193,46 @@ const commands = {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
                 const data = jsonInput(f);
-                if (!data) {
+                if (data === undefined) {
                     throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 const pk = f["project-key"];
                 if (f["dry-run"] === true) {
                     const current = await c.scenarios.get(a[0], { projectKey: pk, });
-                    const next = deepMerge(current, data);
-                    return { dryRun: true, action: "update", resource: "scenario", id: a[0], current, next, };
+                    const preview = scenarioUpdatePreview(current, data);
+                    return {
+                        dryRun: true,
+                        action: "update",
+                        resource: "scenario",
+                        id: a[0],
+                        canonicalEditableFields: preview.canonicalEditableFields,
+                        normalization: preview.normalization,
+                        normalizedData: preview.normalizedData,
+                        changes: preview.changes,
+                        unchangedPaths: preview.unchangedPaths,
+                        current: preview.current,
+                        next: preview.next,
+                    };
                 }
-                await c.scenarios.update(a[0], data, pk);
-                return { updated: a[0], resource: "scenario", };
+                const result = await c.scenarios.update(a[0], data, pk);
+                return {
+                    updated: a[0],
+                    resource: "scenario",
+                    verified: result.verified,
+                    changed: result.changes.length > 0,
+                    canonicalEditableFields: result.canonicalEditableFields,
+                    normalization: result.normalization,
+                    ...(result.normalization.length > 0 ? { normalizedData: result.normalizedData, } : {}),
+                    changes: result.changes,
+                    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.",
-            examples: ["dss scenario update my_scenario --data-file settings.json --dry-run",],
+            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',
+                "dss scenario update my_scenario --data-file settings.json --dry-run",
+            ],
         },
     },
     folder: {
@@ -2297,13 +3356,24 @@ const commands = {
         contents: {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss folder contents <name-or-id>");
-                return c.folders.contents(await resolveFolderId(c, a[0], f), {
-                    projectKey: f["project-key"],
-                });
+                const startedAt = Date.now();
+                let folderId = a[0];
+                try {
+                    folderId = await resolveFolderId(c, a[0], f);
+                    return await c.folders.contents(folderId, {
+                        projectKey: f["project-key"],
+                    });
+                }
+                catch (error) {
+                    addTransientTargetContext(error, `folder:${folderId}`, Date.now() - startedAt);
+                }
             },
-            usage: "dss folder contents <name-or-id> [--project-key KEY]",
+            usage: "dss folder contents <name-or-id> [--retries N] [--request-timeout MS] [--project-key KEY]",
             description: "List files in a managed folder.",
-            examples: ["dss folder contents my_folder",],
+            examples: [
+                "dss folder contents my_folder",
+                "dss folder contents my_folder --retries 8 --request-timeout 60000",
+            ],
         },
         download: {
             handler: async (c, a, f) => {
@@ -2425,6 +3495,40 @@ const commands = {
             description: "List connections with inferred types and metadata.",
             examples: ["dss connection infer", "dss connection infer --mode rich",],
         },
+        schemas: {
+            handler: (c, _a, f) => {
+                const connection = f["connection"];
+                if (!connection) {
+                    throw new UsageError("--connection is required. Usage: dss connection schemas --connection CONN");
+                }
+                return c.connections.schemas({
+                    connection,
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss connection schemas --connection CONN [--project-key KEY]",
+            description: "List schemas in a SQL connection.",
+            examples: ["dss connection schemas --connection ATHENA_CONN --project-key MYPROJ",],
+        },
+        tables: {
+            handler: (c, _a, f) => {
+                const connection = f["connection"];
+                if (!connection) {
+                    throw new UsageError("--connection is required. Usage: dss connection tables --connection CONN");
+                }
+                return c.connections.tables({
+                    connection,
+                    catalog: f["catalog"],
+                    schema: f["schema"],
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss connection tables --connection CONN [--catalog CATALOG] [--schema SCHEMA] [--project-key KEY]",
+            description: "List importable tables in a SQL connection, optionally scoped by catalog and schema.",
+            examples: [
+                "dss connection tables --connection ATHENA_CONN --schema analytics --project-key MYPROJ",
+            ],
+        },
     },
     "code-env": {
         list: {
@@ -2644,20 +3748,35 @@ const commands = {
     },
     sql: {
         query: {
-            handler: (c, a, f) => {
+            handler: async (c, a, f) => {
                 const query = resolveSqlInput(a, f);
                 const connection = f["connection"];
                 const datasetFullName = f["dataset"];
                 if ((connection ? 1 : 0) + (datasetFullName ? 1 : 0) !== 1) {
                     throw new UsageError(`Pass exactly one of --connection or --dataset. Usage: ${SQL_QUERY_USAGE}`);
                 }
-                return c.sql.query({
+                const result = await c.sql.query({
                     query,
                     connection,
                     datasetFullName,
                     database: f["database"],
                     projectKey: f["project-key"],
                 });
+                const outputFile = f["output"]
+                    ?? f["output-file"];
+                if (!outputFile)
+                    return result;
+                const outputPath = resolve(outputFile);
+                await mkdir(dirname(outputPath), { recursive: true, });
+                await writeFile(outputPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+                return {
+                    queryId: result.queryId,
+                    schema: result.schema,
+                    columns: result.columns ?? result.schema,
+                    rowCount: result.rows.length,
+                    outputPath,
+                    written: outputPath,
+                };
             },
             usage: SQL_QUERY_USAGE,
             description: "Run a SQL query against a DSS connection or dataset.",
@@ -2665,6 +3784,7 @@ const commands = {
                 "dss sql query 'SELECT * FROM orders LIMIT 10' --connection my_pg",
                 "dss sql query --sql-file query.sql --connection my_pg",
                 "echo 'SELECT 1' | dss sql query --stdin --dataset MYPROJ.orders",
+                "dss sql query --sql-file query.sql --connection my_pg --output results.json --request-timeout 120000",
             ],
         },
     },
@@ -2920,7 +4040,7 @@ function printTopLevelHelp() {
         "      --url URL            Dataiku DSS base URL (env: DATAIKU_URL)",
         "      --api-key KEY        API key              (env: DATAIKU_API_KEY)",
         "      --project-key KEY    Default project key   (env: DATAIKU_PROJECT_KEY)",
-        "      --timeout MS         Operation timeout (build-and-wait, run-and-wait)",
+        "      --timeout MS         Operation timeout (build-and-wait, run-and-wait, recipe run)",
         "      --request-timeout MS HTTP request timeout in ms (default: 30000)",
         "      --dry-run            Preview destructive actions without executing",
         "      --if-not-exists      Skip create if resource already exists",
@@ -2997,6 +4117,8 @@ function requireArgs(args, count, usage) {
 // .env auto-loading
 // ---------------------------------------------------------------------------
 function loadEnvFile() {
+    if (process.env.DATAIKU_DISABLE_ENV === "1")
+        return;
     const dirs = [
         resolve(dirname(fileURLToPath(import.meta.url)), ".."),
         process.cwd(),
@@ -3168,6 +4290,19 @@ async function probeDoctorPermission(probe) {
         return { status: permissionStatusForError(error), details: errorDetails(error), };
     }
 }
+async function probeReadOnlyPrerequisiteForMutation(probe, readAction) {
+    const readProbe = await probeDoctorPermission(probe);
+    if (readProbe.status !== "yes")
+        return readProbe;
+    return {
+        status: "unknown",
+        details: {
+            reason: "mutation capability was not verified because doctor capabilities are read-only",
+            readAction,
+            readStatus: "yes",
+        },
+    };
+}
 function missingProjectPermission() {
     return {
         status: "unknown",
@@ -3273,21 +4408,21 @@ async function doctorCapabilities(client, projectKey, accessibleProjects, flags)
             ? probeDoctorPermission(() => client.projects.get(probeProjectKey))
             : Promise.resolve(missingProjectPermission()),
         canMutateProject: () => probeProjectKey
-            ? probeDoctorPermission(() => client.variables.get(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.variables.get(probeProjectKey), "variables.get")
             : Promise.resolve(missingProjectPermission()),
         canCreateFolder: () => probeProjectKey
-            ? probeDoctorPermission(() => client.folders.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.folders.list(probeProjectKey), "folders.list")
             : Promise.resolve(missingProjectPermission()),
         canRunJobs: () => probeProjectKey
-            ? probeDoctorPermission(() => client.jobs.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.jobs.list(probeProjectKey), "jobs.list")
             : Promise.resolve(missingProjectPermission()),
         canCreateScenario: () => probeProjectKey
-            ? probeDoctorPermission(() => client.scenarios.list(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.scenarios.list(probeProjectKey), "scenarios.list")
             : Promise.resolve(missingProjectPermission()),
         canSaveJupyter: () => probeProjectKey
-            ? probeDoctorPermission(() => client.notebooks.listJupyter(probeProjectKey))
+            ? probeReadOnlyPrerequisiteForMutation(() => client.notebooks.listJupyter(probeProjectKey), "notebooks.listJupyter")
             : Promise.resolve(missingProjectPermission()),
-        canMutateConnection: () => probeDoctorPermission(() => client.connections.list()),
+        canMutateConnection: () => probeReadOnlyPrerequisiteForMutation(() => client.connections.list(), "connections.list"),
     };
     const permissions = {};
     const permissionDetails = {};
@@ -3347,12 +4482,14 @@ async function runDoctor(flags) {
     let accessibleProjects;
     if (credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"]);
+        const retryMaxAttempts = num(flags["retries"]);
         const client = new DataikuClient({
             url,
             apiKey,
             projectKey,
             verbose: flags["verbose"] === true,
             requestTimeoutMs,
+            retryMaxAttempts,
             tlsRejectUnauthorized,
             caCertPath,
         });
@@ -3400,13 +4537,14 @@ async function runDoctor(flags) {
     const result = { ok: checks.every((check) => check.ok), checks, context, };
     if (flags["capabilities"] === true && credentialsOk) {
         const requestTimeoutMs = num(flags["request-timeout"]);
+        const retryMaxAttempts = num(flags["retries"]) ?? 1;
         const client = new DataikuClient({
             url,
             apiKey,
             projectKey,
             verbose: flags["verbose"] === true,
             requestTimeoutMs,
-            retryMaxAttempts: 1,
+            retryMaxAttempts,
             tlsRejectUnauthorized,
             caCertPath,
         });
@@ -3428,19 +4566,21 @@ async function runFixtures(flags) {
     }
     currentCommandContext.projectKey = projectKey;
     const requestTimeoutMs = num(flags["request-timeout"]);
+    const retryMaxAttempts = num(flags["retries"]) ?? 1;
     const client = new DataikuClient({
         url,
         apiKey,
         projectKey,
         verbose: flags["verbose"] === true,
         requestTimeoutMs,
-        retryMaxAttempts: 1,
+        retryMaxAttempts,
         tlsRejectUnauthorized,
         caCertPath,
     });
     return discoverFixtureReport(client, projectKey, flags);
 }
 const READ_ACTIONS = new Set([
+    "cat",
     "contents",
     "diff",
     "download",
@@ -3461,13 +4601,18 @@ const READ_ACTIONS = new Set([
     "list-jupyter",
     "list-sql",
     "log",
+    "log-url",
     "map",
     "metadata",
     "peek",
+    "source",
+    "summary",
     "wait",
+    "watch",
     "preview",
     "query",
     "schema",
+    "schemas",
     "sessions-jupyter",
     "status",
     "rules",
@@ -3492,7 +4637,14 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "wiki",
 ]);
 const GLOBAL_AGENT_FLAGS = ["help", "json", "report-json", "verbose",];
-const AUTHENTICATED_AGENT_FLAGS = ["url", "api-key", "request-timeout", "insecure", "ca-cert",];
+const AUTHENTICATED_AGENT_FLAGS = [
+    "url",
+    "api-key",
+    "request-timeout",
+    "retries",
+    "insecure",
+    "ca-cert",
+];
 const COMMANDS_USAGE = "dss commands [--json]";
 const COMMANDS_DESCRIPTION = "Print the machine-readable command registry for agent planning.";
 const COMMANDS_EXAMPLES = ["dss commands", "dss commands --json",];
@@ -3586,7 +4738,7 @@ function inferSideEffect(resource, action) {
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|update|delete|set|save|upload|run|build|abort|move|clear|unload|install|login|logout)/
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout)/
         .test(action)) {
         return "write";
     }
@@ -3606,12 +4758,14 @@ function inferRequiresProject(resource, action, usage) {
 }
 const ARRAY_OUTPUT_ACTIONS = new Set([
     "history",
+    "find",
     "infer",
     "last-results",
     "list",
     "list-jupyter",
     "list-sql",
     "rules",
+    "schemas",
     "sessions-jupyter",
     "usages",
 ]);
@@ -3620,7 +4774,9 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "download",
     "download-code",
     "get-payload",
+    "cat",
     "log",
+    "log-url",
     "preview",
 ]);
 function inferOutputShape(resource, action) {
@@ -3661,7 +4817,7 @@ function inferExitCodes(asyncKind) {
     };
 }
 function cleanupCommandFromDeleteUsage(resource, action) {
-    if (!action.startsWith("create"))
+    if (!(action.startsWith("create") || action === "clone"))
         return undefined;
     const deleteAction = action === "create-rule" ? "delete-rule" : "delete";
     const deleteUsage = commands[resource]?.[deleteAction]?.usage;
@@ -3684,7 +4840,10 @@ function inferDestructiveLevel(sideEffect, action) {
     return "reversible";
 }
 function inferAsyncKind(resource, action) {
-    if (resource === "job" && ["build", "build-and-wait", "wait",].includes(action))
+    if (resource === "job" && ["build", "build-and-wait", "wait", "monitor", "watch",].includes(action)) {
+        return "job";
+    }
+    if (resource === "recipe" && action === "run")
         return "job";
     if (resource === "future" && ["get", "peek", "wait", "abort",].includes(action))
         return "future";
@@ -3705,7 +4864,7 @@ function inferIdempotency(sideEffect, action, usage) {
     return "none";
 }
 function inferCleanupHint(resource, action) {
-    if (!action.startsWith("create"))
+    if (!(action.startsWith("create") || action === "clone"))
         return undefined;
     if (resource === "code-env")
         return "Delete with `dss code-env delete <lang> <name> --if-exists`.";
@@ -3762,7 +4921,8 @@ function buildRegistryEntry(resource, action, meta) {
         outputShape: inferOutputShape(resource, action),
         inputContract,
         destructive,
-        producesLocalFile: meta.usage.includes("--output PATH"),
+        producesLocalFile: meta.usage.includes("--output PATH")
+            || meta.usage.includes("--output-file PATH"),
         mutatesDss,
         async: asyncKind,
         idempotency: inferIdempotency(sideEffect, action, meta.usage),
@@ -3853,7 +5013,7 @@ function requiredPlanFlag(flags, name, usage) {
 }
 function optionalJsonFlag(flags, name) {
     const value = flags[name];
-    return typeof value === "string" ? JSON.parse(value) : undefined;
+    return typeof value === "string" ? parseJsonObject(value, `--${name}`) : undefined;
 }
 function requiredPlanJsonInput(flags, usage) {
     return requiredJsonInput(flags, `--data, --data-file, or --stdin is required. Usage: ${usage}`);
@@ -3874,9 +5034,20 @@ function querySuffix(params) {
     return raw ? `?${raw}` : "";
 }
 function jobBuildPayload(target, projectKey, flags) {
-    const targetType = jobBuildTargetType(flags["type"]);
+    const targetType = jobBuildTargetTypeFromFlags(flags);
+    const partition = flags["partition"];
+    const output = { projectKey, id: target, type: targetType, };
+    if (targetType === "DATASET") {
+        if (partition !== undefined)
+            output.partition = partition;
+    }
+    else {
+        output.targetManagedFolderProjectKey = projectKey;
+        output.targetManagedFolder = target;
+        output.targetPartition = partition ?? "NP";
+    }
     const payload = {
-        outputs: [{ projectKey, id: target, type: targetType, },],
+        outputs: [output,],
         type: flags["build-mode"] ?? "NON_RECURSIVE_FORCED_BUILD",
     };
     if (flags["force-rebuild"] === true && targetType === "DATASET") {
@@ -4062,9 +5233,9 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
         case "flow-zone.move":
             return {
                 method: "POST",
-                endpoint: projectEndpoint(`/flow/zones/${encodeURIComponent(id)}/move-to`),
+                endpoint: projectEndpoint(`/flow/zones/${encodeURIComponent(id)}/add-items`),
                 identifiers: { id, },
-                payload: { items: flowZoneMoveItems(flags), },
+                payload: flowZoneMoveItems(flags),
             };
         case "dataset.create": {
             const name = requiredPlanFlag(flags, "name", entry.usage);
@@ -4083,6 +5254,15 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                 endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}`),
                 identifiers: { name: id, },
             };
+        case "dataset.refresh-schema": {
+            const columns = schemaColumnsInput(flags, entry.usage);
+            return {
+                method: "PUT",
+                endpoint: projectEndpoint(`/datasets/${encodeURIComponent(id)}/schema`),
+                identifiers: { name: id, },
+                payload: { columns, },
+            };
+        }
         case "dataset.update":
             return {
                 method: "PUT",
@@ -4124,6 +5304,19 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                 },
             };
         }
+        case "recipe.run":
+            return {
+                method: "POST",
+                endpoint: projectEndpoint("/jobs/"),
+                identifiers: { recipe: id, },
+                payload: {
+                    recipe: id,
+                    outputResolution: "dynamic",
+                    projectKey,
+                    partition: flags["partition"],
+                },
+                wait: recipeRunShouldWait(flags),
+            };
         case "recipe.update":
             return {
                 method: "PUT",
@@ -4131,13 +5324,27 @@ function commandPlanShape(resource, action, args, flags, entry, projectKey) {
                 identifiers: { name: id, },
                 payload: requiredPlanJsonInput(flags, entry.usage),
             };
-        case "recipe.set-payload":
+        case "recipe.set-payload": {
+            const file = requiredPlanFlag(flags, "file", entry.usage);
+            const backupDir = flags["no-backup"] === true
+                ? undefined
+                : flags["backup-dir"]
+                    ?? join(process.cwd(), ".dss-backups", "recipes");
+            const backupPath = backupDir ? recipeBackupPath(id, backupDir) : undefined;
             return {
                 method: "PUT",
-                endpoint: projectEndpoint(`/recipes/${encodeURIComponent(id)}/payload`),
+                endpoint: projectEndpoint(`/recipes/${encodeURIComponent(id)}`),
                 identifiers: { name: id, },
-                payload: { file: flags["file"], content: textInput(flags), },
+                payload: {
+                    file,
+                    content: textInput(flags),
+                    ...(backupPath ? { backupPath, } : {}),
+                },
+                ...(backupPath
+                    ? { localWrites: [{ path: backupPath, source: "remote recipe backup", before: "PUT", },], }
+                    : {}),
             };
+        }
         case "job.build":
         case "job.build-and-wait":
             return {
@@ -4404,12 +5611,14 @@ async function runCleanup(flags) {
         throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
     }
     const requestTimeoutMs = num(flags["request-timeout"]);
+    const retryMaxAttempts = num(flags["retries"]);
     const client = new DataikuClient({
         url,
         apiKey,
         projectKey,
         verbose: flags["verbose"] === true,
         requestTimeoutMs,
+        retryMaxAttempts,
         tlsRejectUnauthorized,
         caCertPath,
     });
@@ -4479,17 +5688,26 @@ function promptSecret(label) {
 // Credential resolution
 // ---------------------------------------------------------------------------
 function resolveCredentials(flags) {
-    let url = flags["url"];
-    let apiKey = flags["api-key"];
-    let projectKey = flags["project-key"];
+    const hasUrlFlag = Object.hasOwn(flags, "url");
+    const hasApiKeyFlag = Object.hasOwn(flags, "api-key");
+    const hasProjectKeyFlag = Object.hasOwn(flags, "project-key");
+    let url = hasUrlFlag ? flags["url"] : undefined;
+    let apiKey = hasApiKeyFlag ? flags["api-key"] : undefined;
+    let projectKey = hasProjectKeyFlag ? flags["project-key"] : undefined;
     const saved = loadCredentials();
-    url ??= process.env.DATAIKU_URL;
-    apiKey ??= process.env.DATAIKU_API_KEY;
-    projectKey ??= process.env.DATAIKU_PROJECT_KEY;
+    if (!hasUrlFlag)
+        url ??= process.env.DATAIKU_URL;
+    if (!hasApiKeyFlag)
+        apiKey ??= process.env.DATAIKU_API_KEY;
+    if (!hasProjectKeyFlag)
+        projectKey ??= process.env.DATAIKU_PROJECT_KEY;
     if (saved) {
-        url ||= saved.url;
-        apiKey ||= saved.apiKey;
-        projectKey ??= saved.projectKey;
+        if (!hasUrlFlag)
+            url ??= saved.url;
+        if (!hasApiKeyFlag)
+            apiKey ??= saved.apiKey;
+        if (!hasProjectKeyFlag)
+            projectKey ??= saved.projectKey;
     }
     return {
         url: url ?? "",
@@ -4624,7 +5842,7 @@ async function main() {
     const { positional, flags, } = parseArgs(process.argv.slice(2));
     // --version
     if (flags["version"] === true) {
-        process.stdout.write(`${CLI_VERSION}\n`);
+        process.stdout.write(`${CLI_VERSION_LABEL}\n`);
         process.exit(0);
     }
     // Top-level help
@@ -4940,12 +6158,14 @@ async function main() {
         throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
     }
     const requestTimeoutMs = num(flags["request-timeout"]);
+    const retryMaxAttempts = num(flags["retries"]);
     const client = new DataikuClient({
         url,
         apiKey,
         projectKey,
         verbose: flags["verbose"] === true,
         requestTimeoutMs,
+        retryMaxAttempts,
         tlsRejectUnauthorized,
         caCertPath,
     });
@@ -4960,7 +6180,12 @@ async function main() {
         if (entry)
             await appendCleanupLedgerEntry(flags["record-cleanup"], entry);
     }
-    writeCommandResult(result);
+    if (flags["raw"] === true && typeof result === "string") {
+        process.stdout.write(result);
+    }
+    else {
+        writeCommandResult(result);
+    }
     const failureExitCode = commandFailureExitCode(result);
     if (failureExitCode !== undefined)
         process.exit(failureExitCode);