dataiku-sdk 0.6.1 → 0.7.0

package/dist/src/cli.js

@@ -3,17 +3,15 @@ import { createHash, } from "node:crypto";
 import { readFileSync, } from "node:fs";
 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";
 import { validateCredentials, } from "./auth.js";
 import { DataikuClient, } from "./client.js";
-import { deleteCredentials, getCredentialsPath, loadCredentials, maskApiKey, saveCredentials, } from "./config.js";
+import { getCredentialsPath, loadCredentials, 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 { AGENTS, detectAgents, findWorkspaceRoot, installSkill, planSkillInstalls, } from "./skill.js";
 import { appendCleanupLedgerEntry, readCleanupLedger, } from "./utils/cleanup-ledger.js";
 import { deepMerge, } from "./utils/deep-merge.js";
 import { sanitizeFileName, } from "./utils/sanitize.js";
@@ -73,10 +71,10 @@ function gitRevision(packageRoot) {
 }
 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;
-})();
+const CLI_GIT_REVISION = gitRevision(PACKAGE_ROOT);
+function cliVersionResult() {
+    return { version: CLI_VERSION, gitRevision: CLI_GIT_REVISION ?? null, };
+}
 function num(v) {
     if (typeof v !== "string")
         return undefined;
@@ -340,6 +338,336 @@ function flowZoneDetailSummary(zone) {
         items: flowZoneItems(zone),
     };
 }
+function optionalStringField(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+function requiredStringArray(value, source) {
+    if (!Array.isArray(value)) {
+        throw new UsageError(`${source} must be an array of strings.`, "validation_failed");
+    }
+    return value.map((item, index) => {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new UsageError(`${source}[${index}] must be a non-empty string.`, "validation_failed");
+        }
+        return item.trim();
+    });
+}
+function finiteNumberField(record, key, source) {
+    const value = record[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new UsageError(`${source}.${key} must be a finite number.`, "validation_failed");
+    }
+    return value;
+}
+function flowZonePlanColor(value, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !/^#[0-9a-fA-F]{6}$/.test(value.trim())) {
+        throw new UsageError(`${source} must be a hex color like #2ab1ac.`, "validation_failed");
+    }
+    return value.trim();
+}
+function flowZonePlanPosition(value, source) {
+    if (value === undefined)
+        return undefined;
+    const record = plainRecord(value);
+    if (!record) {
+        throw new UsageError(`${source} must be an object with x and y.`, "validation_failed");
+    }
+    return {
+        x: finiteNumberField(record, "x", source),
+        y: finiteNumberField(record, "y", source),
+    };
+}
+function flowZoneCurrentPosition(zone) {
+    const record = zone;
+    const position = plainRecord(record.position);
+    if (!position)
+        return undefined;
+    const x = position.x;
+    const y = position.y;
+    return typeof x === "number" && Number.isFinite(x) && typeof y === "number" && Number.isFinite(y)
+        ? { x, y, }
+        : undefined;
+}
+function flowZoneSamePosition(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.x === b.x && a.y === b.y;
+}
+function parseFlowZonePlanItem(value, source) {
+    if (typeof value === "string")
+        return parseFlowZoneObject(value);
+    const record = plainRecord(value);
+    if (!record) {
+        throw new UsageError(`${source} must be TYPE:ID or an object.`, "validation_failed");
+    }
+    const object = optionalStringField(record, ["object",]);
+    if (object)
+        return parseFlowZoneObject(object);
+    const objectType = optionalStringField(record, ["objectType", "type",]);
+    const objectId = optionalStringField(record, ["objectId", "id", "name",]);
+    if (!objectType || !objectId) {
+        throw new UsageError(`${source} must include objectType/type and objectId/id, or object as TYPE:ID.`, "validation_failed");
+    }
+    const projectKey = optionalStringField(record, ["projectKey", "project",]);
+    return {
+        objectType: flowZoneObjectType(objectType),
+        objectId,
+        ...(projectKey ? { projectKey, } : {}),
+    };
+}
+function addFlowZonePlanTypedItems(items, record, key, objectType, source) {
+    if (record[key] === undefined)
+        return;
+    for (const objectId of requiredStringArray(record[key], `${source}.${key}`)) {
+        items.push({ objectType, objectId, });
+    }
+}
+function flowZoneItemKey(item) {
+    return `${item.projectKey ?? ""}\0${item.objectType}\0${item.objectId}`;
+}
+function flowZonePlanLabel(plan) {
+    return plan.id ?? plan.name ?? "<unknown>";
+}
+function dedupeFlowZonePlanItems(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = flowZoneItemKey(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
+function flowZonePlanItemKeys(plan) {
+    const keys = new Set();
+    for (const zone of plan.zones) {
+        for (const item of zone.items)
+            keys.add(flowZoneItemKey(item));
+    }
+    return keys;
+}
+function validateUniqueFlowZoneAssignments(plan) {
+    const seen = new Map();
+    for (const zone of plan.zones) {
+        const label = flowZonePlanLabel(zone);
+        for (const item of zone.items) {
+            const key = flowZoneItemKey(item);
+            const previous = seen.get(key);
+            if (previous) {
+                throw new UsageError(`Flow object ${item.objectType}:${item.objectId} is assigned to both "${previous}" and "${label}".`, "validation_failed");
+            }
+            seen.set(key, label);
+        }
+    }
+}
+function parseFlowZoneOrganizePlan(input) {
+    const zones = input.zones;
+    if (!Array.isArray(zones) || zones.length === 0) {
+        throw new UsageError("Flow zone organize plan must include a non-empty zones array.", "validation_failed");
+    }
+    const plan = {
+        zones: zones.map((value, index) => {
+            const source = `zones[${index}]`;
+            const record = plainRecord(value);
+            if (!record)
+                throw new UsageError(`${source} must be an object.`, "validation_failed");
+            const id = optionalStringField(record, ["id", "zoneId",]);
+            const name = optionalStringField(record, ["name",]);
+            if (!id && !name) {
+                throw new UsageError(`${source} must include name or id.`, "validation_failed");
+            }
+            const items = [];
+            const rawItems = record.items ?? record.objects;
+            if (rawItems !== undefined) {
+                if (!Array.isArray(rawItems)) {
+                    throw new UsageError(`${source}.items must be an array.`, "validation_failed");
+                }
+                rawItems.forEach((item, itemIndex) => {
+                    items.push(parseFlowZonePlanItem(item, `${source}.items[${itemIndex}]`));
+                });
+            }
+            addFlowZonePlanTypedItems(items, record, "datasets", "DATASET", source);
+            addFlowZonePlanTypedItems(items, record, "recipes", "RECIPE", source);
+            addFlowZonePlanTypedItems(items, record, "folders", "MANAGED_FOLDER", source);
+            addFlowZonePlanTypedItems(items, record, "savedModels", "SAVED_MODEL", source);
+            addFlowZonePlanTypedItems(items, record, "modelEvaluationStores", "MODEL_EVALUATION_STORE", source);
+            addFlowZonePlanTypedItems(items, record, "streamingEndpoints", "STREAMING_ENDPOINT", source);
+            addFlowZonePlanTypedItems(items, record, "labelingTasks", "LABELING_TASK", source);
+            addFlowZonePlanTypedItems(items, record, "knowledgeBanks", "RETRIEVABLE_KNOWLEDGE", source);
+            return {
+                ...(id ? { id, } : {}),
+                ...(name ? { name, } : {}),
+                ...(record.color !== undefined
+                    ? { color: flowZonePlanColor(record.color, `${source}.color`), }
+                    : {}),
+                ...(record.position !== undefined
+                    ? { position: flowZonePlanPosition(record.position, `${source}.position`), }
+                    : {}),
+                items: dedupeFlowZonePlanItems(items),
+            };
+        }),
+    };
+    validateUniqueFlowZoneAssignments(plan);
+    return plan;
+}
+function readFlowZoneOrganizePlan(flags, usage) {
+    const data = typeof flags["file"] === "string"
+        ? parseJsonObject(readFileSync(flags["file"], "utf-8"), flags["file"])
+        : jsonInput(flags);
+    if (!data) {
+        throw new UsageError(`--data, --data-file, --file, or --stdin is required. Usage: ${usage}`, "missing_required_flag");
+    }
+    return parseFlowZoneOrganizePlan(data);
+}
+function findFlowZoneForPlan(zones, plan) {
+    if (plan.id) {
+        const byId = zones.find((zone) => zone.id === plan.id);
+        if (byId)
+            return byId;
+    }
+    if (!plan.name)
+        return undefined;
+    const byName = zones.filter((zone) => zone.name === plan.name);
+    if (byName.length > 1) {
+        throw new UsageError(`Multiple flow zones named "${plan.name}" exist; use id.`, "validation_failed");
+    }
+    return byName[0];
+}
+function ensureFlowZonePlanTarget(plan, existing) {
+    if (existing || plan.name)
+        return;
+    throw new UsageError(`Flow zone ${plan.id ?? "<unknown>"} was not found and cannot be created without name.`, "validation_failed");
+}
+function flowZoneExplicitItems(zone) {
+    return (zone.items ?? []).map((item) => ({
+        objectId: item.objectId,
+        objectType: item.objectType,
+        ...(item.projectKey ? { projectKey: item.projectKey, } : {}),
+    }));
+}
+function flowZonePruneItems(existing, plannedItemKeys) {
+    if (!existing)
+        return [];
+    return flowZoneExplicitItems(existing).filter((item) => !plannedItemKeys.has(flowZoneItemKey(item)));
+}
+function flowZoneOrganizeStep(plan, existing, sync, plannedItemKeys) {
+    ensureFlowZonePlanTarget(plan, existing);
+    const update = {};
+    if (existing && plan.name && plan.name !== existing.name)
+        update.name = plan.name;
+    if (existing && plan.color && plan.color !== existing.color)
+        update.color = plan.color;
+    if (existing && plan.position !== undefined
+        && !flowZoneSamePosition(flowZoneCurrentPosition(existing), plan.position)) {
+        update.position = plan.position;
+    }
+    const pruneItems = sync ? flowZonePruneItems(existing, plannedItemKeys) : [];
+    return {
+        target: {
+            ...(plan.id ? { id: plan.id, } : {}),
+            ...(plan.name ? { name: plan.name, } : {}),
+            ...(plan.color ? { color: plan.color, } : {}),
+            ...(plan.position ? { position: plan.position, } : {}),
+        },
+        ...(existing ? { existing: flowZoneSummary(existing), } : { create: true, }),
+        ...(Object.keys(update).length > 0 ? { update, } : {}),
+        moveItems: plan.items,
+        ...(pruneItems.length > 0 ? { pruneItems, } : {}),
+    };
+}
+function flowZoneValidationBucket(index, objectType) {
+    switch (objectType) {
+        case "DATASET":
+            return index.datasets;
+        case "RECIPE":
+            return index.recipes;
+        case "MANAGED_FOLDER":
+            return index.folders;
+        case "SAVED_MODEL":
+        case "MODEL_EVALUATION_STORE":
+        case "STREAMING_ENDPOINT":
+        case "LABELING_TASK":
+        case "RETRIEVABLE_KNOWLEDGE":
+            return index.all;
+    }
+}
+async function flowZoneValidationIndex(client, projectKey) {
+    const result = await client.projects.map({
+        projectKey,
+        maxNodes: 100_000,
+        maxEdges: 100_000,
+    });
+    const index = {
+        projectKey: result.map.projectKey,
+        all: new Set(),
+        datasets: new Set(),
+        recipes: new Set(),
+        folders: new Set(),
+    };
+    for (const node of result.map.nodes) {
+        index.all.add(node.id);
+        switch (node.kind) {
+            case "dataset":
+                index.datasets.add(node.id);
+                break;
+            case "recipe":
+                index.recipes.add(node.id);
+                break;
+            case "folder":
+                index.folders.add(node.id);
+                break;
+            case "other":
+                break;
+        }
+    }
+    return index;
+}
+async function validateFlowZoneOrganizeObjects(client, plan, projectKey) {
+    const indexes = new Map();
+    const missing = [];
+    const getIndex = async (itemProjectKey) => {
+        const requestedProjectKey = itemProjectKey ?? projectKey;
+        const cacheKey = requestedProjectKey ?? "";
+        const cached = indexes.get(cacheKey);
+        if (cached)
+            return cached;
+        const index = await flowZoneValidationIndex(client, requestedProjectKey);
+        indexes.set(cacheKey, index);
+        return index;
+    };
+    for (const zone of plan.zones) {
+        for (const item of zone.items) {
+            const index = await getIndex(item.projectKey);
+            const bucket = flowZoneValidationBucket(index, item.objectType);
+            if (bucket.has(item.objectId))
+                continue;
+            missing.push({
+                zone: flowZonePlanLabel(zone),
+                objectId: item.objectId,
+                objectType: item.objectType,
+                ...(item.projectKey ? { projectKey: item.projectKey, } : {}),
+                reason: `Object not found in project ${item.projectKey ?? index.projectKey}.`,
+            });
+        }
+    }
+    return { valid: missing.length === 0, missing, };
+}
+function throwFlowZoneValidationError(validation) {
+    if (validation.valid)
+        return;
+    const first = validation.missing[0];
+    const suffix = validation.missing.length > 1 ? ` and ${validation.missing.length - 1} more` : "";
+    throw new UsageError(`Flow zone organize validation failed: ${first?.objectType}:${first?.objectId} in zone "${first?.zone}" was not found${suffix}.`, "validation_failed");
+}
 async function resolveFlowZoneIdFromFlags(client, flags, projectKey) {
     const zoneId = typeof flags["zone-id"] === "string" ? flags["zone-id"].trim() : "";
     if (zoneId)
@@ -553,7 +881,24 @@ function json(v, source = "JSON flag") {
         return undefined;
     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] [--output PATH|--output-file PATH] [--request-timeout MS] [--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] [--preview N] [--request-timeout MS] [--project-key KEY]";
+const DEFAULT_SQL_PREVIEW_ROWS = 5;
+/**
+ * Parse `--preview N` into a non-negative row count. Rejects non-integers,
+ * negatives, and empty values loudly so a bad flag never silently degrades to a
+ * default. `--preview 0` is valid and yields an empty preview (explicit opt-out).
+ */
+function parseSqlPreviewCount(value) {
+    if (typeof value !== "string") {
+        throw new UsageError(`--preview requires an integer value. Usage: ${SQL_QUERY_USAGE}`, "validation_failed");
+    }
+    const trimmed = value.trim();
+    const parsed = Number(trimmed);
+    if (trimmed.length === 0 || !Number.isInteger(parsed) || parsed < 0) {
+        throw new UsageError(`--preview must be a non-negative integer (got "${value}"). Usage: ${SQL_QUERY_USAGE}`, "validation_failed");
+    }
+    return parsed;
+}
 function readStdinText() {
     return readFileSync(0, "utf-8");
 }
@@ -713,12 +1058,36 @@ function resolveSqlInput(args, flags) {
     if (sources.length > 1) {
         throw new UsageError(`Choose exactly one SQL input source: --sql, --sql-file, --stdin, or one positional SQL argument. Usage: ${SQL_QUERY_USAGE}`);
     }
-    const query = sources[0].read();
+    const query = stripUtf8Bom(sources[0].read());
     if (query.trim().length === 0) {
         throw new UsageError(`SQL input from ${sources[0].label} must not be empty. Usage: ${SQL_QUERY_USAGE}`);
     }
     return query;
 }
+const CODE_RUN_USAGE = "dss code run (--file PATH | --stdin) [--env ENV] [--timeout MS] [--keep] [--full-log] [--project-key KEY]";
+function resolveCodeInput(args, flags) {
+    if (args.length > 0) {
+        throw new UsageError(`code run takes no positional arguments; pass the script via --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
+    }
+    const sources = [];
+    if (typeof flags["file"] === "string") {
+        sources.push({ label: "--file", read: () => readFileSync(flags["file"], "utf-8"), });
+    }
+    if (flags["stdin"] === true) {
+        sources.push({ label: "--stdin", read: readStdinText, });
+    }
+    if (sources.length === 0) {
+        throw new UsageError(`Python source is required: pass --file PATH or --stdin. Usage: ${CODE_RUN_USAGE}`);
+    }
+    if (sources.length > 1) {
+        throw new UsageError(`Choose exactly one Python source: --file or --stdin. Usage: ${CODE_RUN_USAGE}`);
+    }
+    const script = stripUtf8Bom(sources[0].read());
+    if (script.trim().length === 0) {
+        throw new UsageError(`Python source from ${sources[0].label} must not be empty. Usage: ${CODE_RUN_USAGE}`);
+    }
+    return script;
+}
 async function resolveFolderId(client, nameOrId, flags) {
     return client.folders.resolveId(nameOrId, flags["project-key"]);
 }
@@ -749,8 +1118,40 @@ function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
     }
     return lines.join("\n");
 }
+let outputFieldProjection;
+function resolveFieldPath(source, field) {
+    let current = source;
+    for (const segment of field.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current))
+            return null;
+        current = current[segment];
+    }
+    return current ?? null;
+}
+function pickResultFields(item, fields) {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+        return item;
+    const source = item;
+    const picked = {};
+    for (const field of fields)
+        picked[field] = resolveFieldPath(source, field);
+    return picked;
+}
+/**
+ * Project the top-level fields callers asked for via --fields. Arrays are mapped
+ * element-wise; scalars and string results pass through untouched. Requested keys
+ * that are absent become null so every row keeps a stable, predictable shape.
+ */
+function projectResultFields(result, fields) {
+    if (Array.isArray(result))
+        return result.map((item) => pickResultFields(item, fields));
+    return pickResultFields(result, fields);
+}
 function writeCommandResult(result) {
-    process.stdout.write(`${JSON.stringify(result ?? { ok: true, }, null, 2)}\n`);
+    const projected = outputFieldProjection
+        ? projectResultFields(result, outputFieldProjection)
+        : result;
+    process.stdout.write(`${JSON.stringify(projected ?? { ok: true, }, null, 2)}\n`);
 }
 function transientBodyWithTargetContext(body, target, elapsedMs) {
     try {
@@ -770,7 +1171,7 @@ function transientBodyWithTargetContext(body, target, elapsedMs) {
 }
 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 new DataikuError(error.status, error.statusText, transientBodyWithTargetContext(error.body, target, elapsedMs), error.retry, error.requestId);
     }
     throw error;
 }
@@ -790,6 +1191,27 @@ function commandFailureExitCode(result) {
         return 4;
     return undefined;
 }
+class CommandResultFailure extends Error {
+    result;
+    exitCode;
+    constructor(result, exitCode) {
+        super(commandFailureMessage(result));
+        this.name = "CommandResultFailure";
+        this.result = result;
+        this.exitCode = exitCode;
+    }
+}
+function commandFailureMessage(result) {
+    if (isFailedWaitResult(result)) {
+        const record = result;
+        const state = typeof record.state === "string" ? record.state : record.outcome;
+        return `Command completed with failed long-running result${state ? `: ${state}` : ""}.`;
+    }
+    if (result && typeof result === "object" && result.unchanged === false) {
+        return "Command completed with failed assertion result.";
+    }
+    return "Command completed with failed result.";
+}
 function isNotFoundError(error) {
     if (error instanceof DataikuError)
         return error.category === "not_found";
@@ -810,6 +1232,22 @@ async function readIfExists(reader) {
 function skipResult(resource, id, reason, extra = {}) {
     return { skipped: id, reason, resource, ...extra, };
 }
+function recipeRoleInputItems(recipe, role) {
+    const inputs = recipe["inputs"];
+    if (!inputs || typeof inputs !== "object")
+        return [];
+    const roleEntry = inputs[role];
+    if (!roleEntry || typeof roleEntry !== "object")
+        return [];
+    const items = roleEntry["items"];
+    return Array.isArray(items) ? items : [];
+}
+function recipeInputItemRef(item) {
+    if (!item || typeof item !== "object")
+        return undefined;
+    const ref = item["ref"];
+    return typeof ref === "string" && ref.length > 0 ? ref : undefined;
+}
 function planResult(resource, action, options) {
     return {
         plan: true,
@@ -1007,7 +1445,6 @@ function cleanupLedgerEntry(resource, action, args, flags, result, projectKey) {
 // Arg parsing
 // ---------------------------------------------------------------------------
 const BOOLEAN_FLAGS = new Set([
-    "help",
     "verbose",
     "version",
     "stdin",
@@ -1031,7 +1468,6 @@ const BOOLEAN_FLAGS = new Set([
     "if-not-exists",
     "if-exists",
     "json",
-    "report-json",
     "no-wait",
     "force-rebuild",
     "latest",
@@ -1040,9 +1476,13 @@ const BOOLEAN_FLAGS = new Set([
     "no-backup",
     "payload-only",
     "allow-same-path",
+    "sync",
+    "validate-objects",
+    "errors-only",
+    "keep",
+    "full-log",
 ]);
 const SHORT_FLAGS = {
-    h: "help",
     v: "verbose",
     V: "version",
     o: "output",
@@ -1057,6 +1497,7 @@ const FLAG_ALIASES = {
     "zone-name": "zone",
 };
 const VALUE_FLAGS = new Set([
+    "fields",
     "activity",
     "agent",
     "api-key",
@@ -1080,6 +1521,7 @@ const VALUE_FLAGS = new Set([
     "database",
     "dataset",
     "file",
+    "env",
     "install-core-packages",
     "folder",
     "input",
@@ -1115,6 +1557,7 @@ const VALUE_FLAGS = new Set([
     "partition",
     "parent",
     "path",
+    "preview",
     "project-key",
     "recipe",
     "request-timeout",
@@ -1122,6 +1565,7 @@ const VALUE_FLAGS = new Set([
     "results-per-page",
     "record-cleanup",
     "rule-id",
+    "role",
     "retries",
     "poll-interval",
     "python-interpreter",
@@ -1165,6 +1609,8 @@ const KNOWN_LONG_FLAGS = new Set([
     ...Object.values(FLAG_ALIASES),
 ]);
 function normalizeLongFlag(rawFlagName) {
+    if (rawFlagName === "help")
+        throw unsupportedHelpFlag();
     const flagName = FLAG_ALIASES[rawFlagName] ?? rawFlagName;
     if (!KNOWN_LONG_FLAGS.has(rawFlagName) && !KNOWN_LONG_FLAGS.has(flagName)) {
         throw new UsageError(`Unknown flag: --${rawFlagName}`, "unknown_flag");
@@ -1231,6 +1677,8 @@ function parseArgs(argv) {
                 }
             }
             else {
+                if (arg[1] === "h")
+                    throw unsupportedHelpFlag();
                 throw new UsageError(`Unknown flag: -${arg[1]}`, "unknown_flag");
             }
         }
@@ -2097,6 +2545,110 @@ const commands = {
                 "dss flow-zone move ZONE_ID --object SAVED_MODEL:model_id",
             ],
         },
+        organize: {
+            handler: async (c, _a, f) => {
+                const usage = "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]";
+                const pk = f["project-key"];
+                const plan = readFlowZoneOrganizePlan(f, usage);
+                const sync = f["sync"] === true;
+                const validateObjects = f["validate-objects"] === true;
+                const zones = await c.flowZones.list(pk);
+                const plannedItemKeys = flowZonePlanItemKeys(plan);
+                const planned = plan.zones.map((zonePlan) => flowZoneOrganizeStep(zonePlan, findFlowZoneForPlan(zones, zonePlan), sync, plannedItemKeys));
+                const validation = validateObjects
+                    ? await validateFlowZoneOrganizeObjects(c, plan, pk)
+                    : undefined;
+                if (validation)
+                    throwFlowZoneValidationError(validation);
+                const itemCount = plan.zones.reduce((count, zonePlan) => count + zonePlan.items.length, 0);
+                const pruneItemCount = planned.reduce((count, step) => {
+                    const pruneItems = Array.isArray(step.pruneItems) ? step.pruneItems : [];
+                    return count + pruneItems.length;
+                }, 0);
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "organize",
+                        resource: "flow-zone",
+                        projectKey: pk,
+                        sync,
+                        validateObjects,
+                        zoneCount: plan.zones.length,
+                        itemCount,
+                        pruneItemCount,
+                        ...(validation ? { validation, } : {}),
+                        planned,
+                    };
+                }
+                const currentZones = [...zones,];
+                const created = [];
+                const updated = [];
+                const moved = [];
+                const pruned = [];
+                for (const zonePlan of plan.zones) {
+                    let zone = findFlowZoneForPlan(currentZones, zonePlan);
+                    ensureFlowZonePlanTarget(zonePlan, zone);
+                    const pruneItems = sync ? flowZonePruneItems(zone, plannedItemKeys) : [];
+                    if (!zone) {
+                        zone = await c.flowZones.create({
+                            name: zonePlan.name,
+                            color: zonePlan.color,
+                            position: zonePlan.position,
+                            projectKey: pk,
+                        });
+                        currentZones.push(zone);
+                        created.push(zone);
+                    }
+                    else {
+                        const patch = {
+                            ...(zonePlan.name && zonePlan.name !== zone.name ? { name: zonePlan.name, } : {}),
+                            ...(zonePlan.color && zonePlan.color !== zone.color ? { color: zonePlan.color, } : {}),
+                            ...(zonePlan.position !== undefined
+                                && !flowZoneSamePosition(flowZoneCurrentPosition(zone), zonePlan.position)
+                                ? { position: zonePlan.position, }
+                                : {}),
+                            projectKey: pk,
+                        };
+                        if (patch.name !== undefined || patch.color !== undefined || patch.position !== undefined) {
+                            zone = await c.flowZones.update(zone.id, patch);
+                            const index = currentZones.findIndex((candidate) => candidate.id === zone.id);
+                            if (index !== -1)
+                                currentZones[index] = zone;
+                            updated.push(zone);
+                        }
+                    }
+                    if (zonePlan.items.length > 0) {
+                        await c.flowZones.moveItems(zone.id, zonePlan.items, pk);
+                        moved.push({ zoneId: zone.id, name: zone.name, items: zonePlan.items, });
+                    }
+                    if (pruneItems.length > 0) {
+                        await c.flowZones.moveItems("default", pruneItems, pk);
+                        pruned.push({ zoneId: "default", fromZoneId: zone.id, name: zone.name, items: pruneItems, });
+                    }
+                }
+                return {
+                    organized: true,
+                    action: "organize",
+                    resource: "flow-zone",
+                    projectKey: pk,
+                    sync,
+                    validateObjects,
+                    zoneCount: plan.zones.length,
+                    itemCount,
+                    pruneItemCount,
+                    created,
+                    updated,
+                    moved,
+                    pruned,
+                };
+            },
+            usage: "dss flow-zone organize (--data JSON|--data-file PATH|--file PATH|--stdin) [--sync] [--validate-objects] [--dry-run] [--project-key KEY]",
+            description: "Create/update flow zones and move objects from a declarative visual organization plan.",
+            examples: [
+                "dss flow-zone organize --file flow-zones.json --dry-run",
+                `dss flow-zone organize --data '{"zones":[{"name":"Raw","color":"#64748b","datasets":["raw_orders"]}]}'`,
+            ],
+        },
         graph: {
             handler: (c, a, f) => {
                 requireArgs(a, 1, "dss flow-zone graph <id>");
@@ -2204,10 +2756,11 @@ const commands = {
                 return c.datasets.download(a[0], {
                     outputPath: f["output"],
                     projectKey: f["project-key"],
+                    limit: num(f["limit"]),
                 });
             },
-            usage: "dss dataset download <name> [--output PATH] [--project-key KEY]",
-            description: "Download dataset contents as CSV.",
+            usage: "dss dataset download <name> [--output PATH] [--limit N] [--project-key KEY]",
+            description: "Download up to --limit rows (default 100k) as CSV; returns { path, rows, truncated, limit } so truncation is visible.",
             examples: ["dss dataset download orders", "dss dataset download orders --output ./data/",],
         },
         create: {
@@ -2660,6 +3213,87 @@ const commands = {
                 "cat settings.json | dss recipe update compute_orders --stdin",
             ],
         },
+        "add-input": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss recipe add-input <recipe> <dataset> [--role ROLE] [--if-not-exists] [--dry-run] [--project-key KEY]");
+                const role = f["role"] ?? "main";
+                const pk = f["project-key"];
+                const { recipe, } = await c.recipes.get(a[0], { projectKey: pk, });
+                const items = recipeRoleInputItems(recipe, role);
+                const present = items.some((item) => recipeInputItemRef(item) === a[1]);
+                if (present) {
+                    if (f["if-not-exists"] === true) {
+                        return skipResult("recipe", a[0], "exists", { dataset: a[1], role, });
+                    }
+                    throw new UsageError(`Dataset "${a[1]}" is already a "${role}" input of recipe "${a[0]}".`, "validation_failed");
+                }
+                const nextItems = [...items, { ref: a[1], deps: [], },];
+                const inputs = nextItems.map(recipeInputItemRef).filter((ref) => Boolean(ref));
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "add-input",
+                        resource: "recipe",
+                        recipe: a[0],
+                        dataset: a[1],
+                        role,
+                        inputs,
+                    };
+                }
+                await c.recipes.update(a[0], { recipe: { inputs: { [role]: { items: nextItems, }, }, }, }, pk);
+                return { updated: a[0], resource: "recipe", action: "add-input", role, dataset: a[1], inputs, };
+            },
+            usage: "dss recipe add-input <recipe> <dataset> [--role ROLE] [--if-not-exists] [--dry-run] [--project-key KEY]",
+            description: "Add a dataset as a recipe input by appending one item to the current inputs (no need to resend the whole list).",
+            examples: [
+                "dss recipe add-input compute_orders extra_lookup",
+                "dss recipe add-input compute_orders extra_lookup --if-not-exists --dry-run",
+            ],
+        },
+        "remove-input": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss recipe remove-input <recipe> <dataset> [--role ROLE] [--if-exists] [--dry-run] [--project-key KEY]");
+                const role = f["role"] ?? "main";
+                const pk = f["project-key"];
+                const { recipe, } = await c.recipes.get(a[0], { projectKey: pk, });
+                const items = recipeRoleInputItems(recipe, role);
+                const present = items.some((item) => recipeInputItemRef(item) === a[1]);
+                if (!present) {
+                    if (f["if-exists"] === true) {
+                        return skipResult("recipe", a[0], "missing", { dataset: a[1], role, });
+                    }
+                    throw new UsageError(`Dataset "${a[1]}" is not a "${role}" input of recipe "${a[0]}".`, "validation_failed");
+                }
+                const nextItems = items.filter((item) => recipeInputItemRef(item) !== a[1]);
+                const inputs = nextItems.map(recipeInputItemRef).filter((ref) => Boolean(ref));
+                if (f["dry-run"] === true) {
+                    return {
+                        dryRun: true,
+                        action: "remove-input",
+                        resource: "recipe",
+                        recipe: a[0],
+                        dataset: a[1],
+                        role,
+                        inputs,
+                    };
+                }
+                await c.recipes.update(a[0], { recipe: { inputs: { [role]: { items: nextItems, }, }, }, }, pk);
+                return {
+                    updated: a[0],
+                    resource: "recipe",
+                    action: "remove-input",
+                    role,
+                    dataset: a[1],
+                    inputs,
+                };
+            },
+            usage: "dss recipe remove-input <recipe> <dataset> [--role ROLE] [--if-exists] [--dry-run] [--project-key KEY]",
+            description: "Remove a dataset from a recipe's inputs by dropping one item from the current inputs.",
+            examples: [
+                "dss recipe remove-input compute_orders stale_lookup",
+                "dss recipe remove-input compute_orders stale_lookup --if-exists --dry-run",
+            ],
+        },
         "get-payload": {
             handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss recipe get-payload <name>");
@@ -2673,7 +3307,7 @@ const commands = {
                 return payload;
             },
             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.",
+            description: "Print the recipe code payload as JSON; use --raw for raw bytes, not JSON.",
             examples: [
                 "dss recipe get-payload compute_orders --raw",
                 "dss recipe get-payload compute_orders -o code.py",
@@ -2687,7 +3321,7 @@ const commands = {
                 });
             },
             usage: "dss recipe cat <name> [--raw] [--project-key KEY]",
-            description: "Print a recipe code payload; combine with --raw for shell pipes and diffs.",
+            description: "Print a recipe code payload as JSON; use --raw for raw bytes, not JSON.",
             examples: ["dss recipe cat compute_orders --raw",],
         },
         "set-payload": {
@@ -2870,17 +3504,29 @@ const commands = {
             examples: ["dss job summary JOB_ID --max-log-lines 200",],
         },
         log: {
-            handler: (c, a, f) => {
+            handler: async (c, a, f) => {
                 requireArgs(a, 1, "dss job log <id>");
-                return c.jobs.log(a[0], {
+                const logFilter = f["errors-only"] === true
+                    ? "errors"
+                    : jobLogFilterFromFlag(f["log-filter"]);
+                const log = await c.jobs.log(a[0], {
                     activity: f["activity"],
                     logId: f["log-id"],
+                    logFilter,
                     maxLogLines: maxLogLinesFromFlags(f),
                     projectKey: f["project-key"],
                 });
+                const outputFile = f["output"]
+                    ?? f["output-file"];
+                if (!outputFile)
+                    return log;
+                const outputPath = resolve(outputFile);
+                await mkdir(dirname(outputPath), { recursive: true, });
+                await writeFile(outputPath, log.endsWith("\n") ? log : `${log}\n`, "utf-8");
+                return outputPath;
             },
-            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.",
+            usage: "dss job log <id> [--activity ACTIVITY_ID] [--log-id LOG_ID] [--log-filter stdout|stderr|user|errors] [--errors-only] [--max-lines N|--max-log-lines N] [--output PATH] [--project-key KEY]",
+            description: "Get public API job log output. Use --errors-only (or --log-filter errors) to surface just error/traceback lines, and --output PATH to write the log to a file (stdout returns the path). --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",
@@ -3749,12 +4395,21 @@ const commands = {
     sql: {
         query: {
             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}`);
                 }
+                const outputFile = f["output"]
+                    ?? f["output-file"];
+                const previewProvided = f["preview"] !== undefined;
+                if (previewProvided && !outputFile) {
+                    throw new UsageError(`--preview requires --output or --output-file. Usage: ${SQL_QUERY_USAGE}`, "validation_failed");
+                }
+                const previewCount = previewProvided
+                    ? parseSqlPreviewCount(f["preview"])
+                    : DEFAULT_SQL_PREVIEW_ROWS;
+                const query = resolveSqlInput(a, f);
                 const result = await c.sql.query({
                     query,
                     connection,
@@ -3762,8 +4417,6 @@ const commands = {
                     database: f["database"],
                     projectKey: f["project-key"],
                 });
-                const outputFile = f["output"]
-                    ?? f["output-file"];
                 if (!outputFile)
                     return result;
                 const outputPath = resolve(outputFile);
@@ -3774,6 +4427,7 @@ const commands = {
                     schema: result.schema,
                     columns: result.columns ?? result.schema,
                     rowCount: result.rows.length,
+                    preview: result.rows.slice(0, previewCount),
                     outputPath,
                     written: outputPath,
                 };
@@ -3785,6 +4439,40 @@ const commands = {
                 "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",
+                "dss sql query --sql-file query.sql --connection my_pg --output results.json --preview 10",
+            ],
+        },
+    },
+    code: {
+        run: {
+            handler: async (c, a, f) => {
+                const script = resolveCodeInput(a, f);
+                const run = await c.scenarios.runScript(script, {
+                    envName: f["env"],
+                    projectKey: f["project-key"],
+                    timeoutMs: num(f["timeout"]),
+                    keepScenario: f["keep"] === true,
+                });
+                const result = {
+                    outcome: run.outcome,
+                    success: run.success,
+                    runId: run.runId,
+                    elapsedMs: run.elapsedMs,
+                    pollCount: run.pollCount,
+                    output: run.output ?? "",
+                };
+                if (f["full-log"] === true || run.output === undefined) {
+                    result.log = run.log;
+                }
+                return result;
+            },
+            usage: CODE_RUN_USAGE,
+            description: "Run one-off Python in a DSS code env via a throwaway custom-python scenario; returns the script's captured output (stdout+stderr) plus outcome/success. Pass --full-log for the raw DSS run log. Exits 4 on a non-SUCCESS outcome.",
+            examples: [
+                "dss code run --file inspect.py",
+                "dss code run --file inspect.py --env py39_pandas",
+                "cat snippet.py | dss code run --stdin",
+                "dss code run --file inspect.py --full-log",
             ],
         },
     },
@@ -4016,7 +4704,7 @@ const commands = {
     },
 };
 // ---------------------------------------------------------------------------
-// Help
+// Agent-facing command inventory
 // ---------------------------------------------------------------------------
 const RESOURCE_NAMES = [
     ...Object.keys(commands),
@@ -4027,87 +4715,37 @@ const RESOURCE_NAMES = [
     "install-skill",
 ]
     .sort();
-function printTopLevelHelp() {
-    const lines = [
-        "Usage: dss <resource> <action> [args...] [--flags]",
-        "",
-        "Global flags:",
-        "  -h, --help               Show help",
-        "  -v, --verbose            Log HTTP requests to stderr",
-        "  -V, --version            Show version",
-        "      --json               Emit JSON output (default)",
-        "  -o, --output PATH        Write output to file (recipe get-payload)",
-        "      --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, 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",
-        "      --if-exists          Skip delete if resource is already missing",
-        "      --insecure           Disable TLS certificate verification",
-        "      --ca-cert PATH       Extra PEM CA bundle (env: NODE_EXTRA_CA_CERTS)",
-        "",
-        "Resources:",
-        ...RESOURCE_NAMES.map((r) => `  ${r}`),
-        "",
-        "Quick start:",
-        "  dss auth login                         Save DSS credentials",
-        "  dss auth status                        Verify connection",
-        "  dss doctor                            Run JSON connectivity diagnostics",
-        "  dss project list                       List accessible projects",
-        "  dss dataset list                       List datasets in default project",
-        "  dss dataset preview <name>             Preview dataset rows as CSV",
-        "  dss recipe get-payload <name>          Print recipe code to stdout",
-        "  dss recipe download-code <name>        Download recipe code to a file",
-        "  dss job log <id>                       View job log output",
-        "  dss install-skill                      Install agent skill for coding agents",
-    ];
-    process.stderr.write(`${lines.join("\n")}\n`);
-}
-function printResourceHelp(resource) {
-    const actions = commands[resource];
-    if (!actions)
-        return;
-    const maxName = Math.max(...Object.keys(actions).map((n) => n.length));
-    const lines = [
-        `Usage: dss ${resource} <action> [args...] [--flags]`,
-        "",
-        "Actions:",
-        ...Object.entries(actions).map(([name, meta,]) => `  ${name.padEnd(maxName + 2)}${meta.description ?? meta.usage}`),
-        "",
-        `Run 'dss ${resource} <action> --help' for details and examples.`,
-    ];
-    process.stderr.write(`${lines.join("\n")}\n`);
-}
-function printActionHelp(resource, action) {
-    const meta = commands[resource]?.[action];
-    if (!meta)
-        return;
-    const lines = [];
-    if (meta.description)
-        lines.push(meta.description, "");
-    lines.push(`Usage: ${meta.usage}`);
-    if (meta.examples && meta.examples.length > 0) {
-        lines.push("", "Examples:");
-        for (const ex of meta.examples)
-            lines.push(`  ${ex}`);
-    }
-    process.stderr.write(`${lines.join("\n")}\n`);
-}
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
 class UsageError extends Error {
     code;
     hint;
-    constructor(message, code = "usage_error", hint) {
+    details;
+    constructor(message, code = "usage_error", hint, details) {
         super(message);
         this.name = "UsageError";
         this.code = code;
         this.hint = hint;
+        this.details = details;
     }
 }
+const COMMANDS_RUN_HINT = "Use `dss commands run` for machine-readable command discovery.";
+function unsupportedHelpFlag() {
+    return new UsageError("Help screens are not supported.", "usage_error", COMMANDS_RUN_HINT, { command: "dss commands run", });
+}
+function noCommandError() {
+    return new UsageError("No command provided.", "usage_error", COMMANDS_RUN_HINT, { command: "dss commands run", resources: RESOURCE_NAMES, });
+}
+function missingActionError(resource, validActions, usage) {
+    return new UsageError(`Missing action for ${resource}.`, "usage_error", usage ?? COMMANDS_RUN_HINT, { resource, validActions, });
+}
+function unknownResourceError(resource) {
+    return new UsageError(`Unknown resource: ${resource}.`, "usage_error", COMMANDS_RUN_HINT, { resource, validResources: RESOURCE_NAMES, });
+}
+function unknownActionError(resource, action, validActions) {
+    return new UsageError(`Unknown action: ${resource} ${action ?? ""}`.trim(), "usage_error", COMMANDS_RUN_HINT, { resource, action, validActions, });
+}
 function requireArgs(args, count, usage) {
     if (args.length < count) {
         throw new UsageError(`Expected ${count} argument(s), got ${args.length}.\nUsage: ${usage}`, "missing_required_arg");
@@ -4116,12 +4754,18 @@ function requireArgs(args, count, usage) {
 // ---------------------------------------------------------------------------
 // .env auto-loading
 // ---------------------------------------------------------------------------
+function dataikuEnvironmentEnabled() {
+    return process.env.DATAIKU_DISABLE_ENV !== "1";
+}
 function loadEnvFile() {
-    if (process.env.DATAIKU_DISABLE_ENV === "1")
+    if (!dataikuEnvironmentEnabled())
         return;
+    // The invocation cwd takes precedence over the CLI install/root directory, so a
+    // project-local .env where `dss` is invoked overrides defaults shipped beside the
+    // CLI. First writer wins below, so cwd must be listed first.
     const dirs = [
-        resolve(dirname(fileURLToPath(import.meta.url)), ".."),
         process.cwd(),
+        resolve(dirname(fileURLToPath(import.meta.url)), ".."),
     ];
     for (const dir of dirs) {
         try {
@@ -4151,81 +4795,42 @@ const AUTH_ACTIONS = {
     login: {
         handler: async (flags) => {
             const tlsSettings = resolveTlsSettings(flags);
-            let { url, apiKey, projectKey, } = resolveCredentials(flags);
+            const useEnv = dataikuEnvironmentEnabled();
+            const url = typeof flags["url"] === "string"
+                ? flags["url"]
+                : useEnv
+                    ? process.env.DATAIKU_URL ?? ""
+                    : "";
+            const apiKey = typeof flags["api-key"] === "string"
+                ? flags["api-key"]
+                : useEnv
+                    ? process.env.DATAIKU_API_KEY ?? ""
+                    : "";
+            const projectKey = typeof flags["project-key"] === "string"
+                ? flags["project-key"]
+                : useEnv
+                    ? process.env.DATAIKU_PROJECT_KEY
+                    : undefined;
             if (!url || !apiKey) {
-                if (!process.stdin.isTTY) {
-                    throw new UsageError("Missing --url and/or --api-key. Provide them as flags or run interactively.");
-                }
-                if (!url)
-                    url = await promptLine("DSS URL: ");
-                if (!apiKey)
-                    apiKey = await promptSecret("API key: ");
-                if (!projectKey)
-                    projectKey = (await promptLine("Project key (optional): ")) || undefined;
+                throw new UsageError("Missing --url and/or --api-key for auth login.", "missing_required_flag", "Pass --url and --api-key, or set DATAIKU_URL and DATAIKU_API_KEY.", { requiredFlags: ["url", "api-key",], env: ["DATAIKU_URL", "DATAIKU_API_KEY",], });
             }
-            if (!url)
-                throw new UsageError("URL is required.");
-            if (!apiKey)
-                throw new UsageError("API key is required.");
-            process.stderr.write("Validating credentials... ");
             const result = await validateCredentials(url, apiKey, tlsSettings);
             if (!result.valid) {
-                process.stderr.write("Failed\n");
                 if (result.dataikuError)
                     throw result.dataikuError;
                 throw new DataikuError(0, "Authentication Failed", result.error ?? "Credential validation failed");
             }
-            process.stderr.write("Connected\n");
+            const path = getCredentialsPath();
             saveCredentials({ url, apiKey, projectKey, ...tlsSettings, });
-            process.stderr.write(`Credentials saved to ${getCredentialsPath()}\n`);
+            return { saved: true, path, };
         },
-        usage: "dss auth login [--url URL] [--api-key KEY] [--project-key KEY] [--insecure] [--ca-cert PATH]",
-        description: "Save DSS credentials (interactive or via flags).",
+        usage: "dss auth login --url URL --api-key KEY [--project-key KEY] [--insecure] [--ca-cert PATH]",
+        description: "Validate and save DSS credentials from flags or environment variables.",
         examples: [
             "dss auth login --url https://dss.example.com --api-key YOUR_KEY",
             "dss auth login --url https://dss.example.com --api-key YOUR_KEY --project-key MYPROJ",
         ],
-    },
-    status: {
-        handler: async (flags) => {
-            const creds = loadCredentials();
-            if (!creds) {
-                process.stderr.write("No saved credentials. Run: dss auth login\n");
-                process.exit(1);
-            }
-            const tlsSettings = resolveTlsSettings(flags, creds);
-            const lines = [
-                `URL:         ${creds.url}`,
-                `API key:     ${maskApiKey(creds.apiKey)}`,
-                `Project key: ${creds.projectKey ?? "(not set)"}`,
-                `TLS verify:  ${tlsSettings.tlsRejectUnauthorized === false ? "disabled" : "strict"}`,
-                `CA cert:     ${tlsSettings.caCertPath ?? "(default trust store)"}`,
-            ];
-            for (const line of lines)
-                process.stderr.write(`${line}\n`);
-            const result = await validateCredentials(creds.url, creds.apiKey, tlsSettings);
-            if (result.valid) {
-                process.stderr.write("Connection:  valid\n");
-            }
-            else {
-                process.stderr.write(`Connection:  failed (${result.error ?? "unknown error"})\n`);
-                process.stderr.write(`Config:      ${getCredentialsPath()}\n`);
-                process.exit(1);
-            }
-            process.stderr.write(`Config:      ${getCredentialsPath()}\n`);
-        },
-        usage: "dss auth status [--insecure] [--ca-cert PATH]",
-        description: "Show saved credentials and verify the connection.",
-        examples: ["dss auth status",],
-    },
-    logout: {
-        handler: async (_flags) => {
-            deleteCredentials();
-            process.stderr.write("Credentials removed.\n");
-        },
-        usage: "dss auth logout",
-        description: "Remove saved credentials.",
-        examples: ["dss auth logout",],
+        requiredFlags: ["url", "api-key",],
     },
 };
 function errorDetails(error) {
@@ -4477,7 +5082,7 @@ async function runDoctor(flags) {
         ok: credentialsOk,
         message: credentialsOk
             ? "Dataiku URL and API key are configured."
-            : "Missing Dataiku URL and/or API key. Set DATAIKU_URL/DATAIKU_API_KEY, pass flags, or run dss auth login.",
+            : "Missing Dataiku URL and/or API key. Set DATAIKU_URL/DATAIKU_API_KEY or pass --url/--api-key.",
     });
     let accessibleProjects;
     if (credentialsOk) {
@@ -4556,13 +5161,13 @@ async function runDoctor(flags) {
 async function runFixtures(flags) {
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     if (!url) {
-        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL, pass --url, or run: dss auth login");
+        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL or pass --url.", "missing_required_flag");
     }
     if (!apiKey) {
-        throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
+        throw new UsageError("Missing API key. Set DATAIKU_API_KEY or pass --api-key.", "missing_required_flag");
     }
     if (!projectKey) {
-        throw new UsageError("Missing project key. Set DATAIKU_PROJECT_KEY, pass --project-key, or run: dss auth login", "missing_required_flag");
+        throw new UsageError("Missing project key. Set DATAIKU_PROJECT_KEY or pass --project-key.", "missing_required_flag");
     }
     currentCommandContext.projectKey = projectKey;
     const requestTimeoutMs = num(flags["request-timeout"]);
@@ -4636,7 +5241,7 @@ const PROJECT_SCOPED_RESOURCES = new Set([
     "variable",
     "wiki",
 ]);
-const GLOBAL_AGENT_FLAGS = ["help", "json", "report-json", "verbose",];
+const GLOBAL_AGENT_FLAGS = ["json", "verbose", "fields",];
 const AUTHENTICATED_AGENT_FLAGS = [
     "url",
     "api-key",
@@ -4645,9 +5250,12 @@ const AUTHENTICATED_AGENT_FLAGS = [
     "insecure",
     "ca-cert",
 ];
-const COMMANDS_USAGE = "dss commands [--json]";
+const COMMANDS_USAGE = "dss commands run [--json]";
 const COMMANDS_DESCRIPTION = "Print the machine-readable command registry for agent planning.";
-const COMMANDS_EXAMPLES = ["dss commands", "dss commands --json",];
+const COMMANDS_EXAMPLES = ["dss commands run", "dss commands run --json",];
+const VERSION_USAGE = "dss version";
+const VERSION_DESCRIPTION = "Print the CLI version and git revision as JSON.";
+const VERSION_EXAMPLES = ["dss version", "dss --version",];
 const INSTALL_SKILL_USAGE = "dss install-skill [--global] [--agent NAME] [--target PATH] [--list-agents] [--dry-run] [--plan]";
 const INSTALL_SKILL_DESCRIPTION = "Install the dataiku-dss agent skill for detected coding agents.";
 const INSTALL_SKILL_EXAMPLES = [
@@ -4666,6 +5274,22 @@ const FIXTURES_EXAMPLES = [
     "dss fixtures --json",
     "dss fixtures --json --allow-types Filesystem,Inline",
 ];
+const ALLOWED_CLEANUP_ACTIONS = new Set([
+    // Must mirror every cleanup.argv shape emitted by cleanupLedgerEntry().
+    "dataset delete",
+    "recipe delete",
+    "scenario delete",
+    "flow-zone delete",
+    "wiki delete",
+    "dashboard delete",
+    "insight delete",
+    "data-quality delete-rule",
+    "code-env delete",
+    "folder delete-file",
+]);
+function isAllowedCleanupAction(resource, action) {
+    return ALLOWED_CLEANUP_ACTIONS.has(`${resource} ${action}`);
+}
 function uniqueStrings(values) {
     return [...new Set(values),];
 }
@@ -4730,26 +5354,33 @@ function extractPositionals(usage) {
 function inferSideEffect(resource, action) {
     if (resource === "auth")
         return "auth";
-    if (resource === "doctor" || resource === "commands" || resource === "fixtures")
+    if (resource === "doctor" || resource === "commands" || resource === "fixtures"
+        || resource === "version") {
         return "read";
+    }
     if (resource === "install-skill")
         return "write";
     if (resource === "data-quality" && action === "compute")
         return "write";
     if (READ_ACTIONS.has(action))
         return "read";
-    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout)/
+    if (/^(create|clone|restore|update|delete|set|save|upload|run|build|abort|move|refresh|clear|unload|install|login|logout|add|remove)/
         .test(action)) {
         return "write";
     }
     return "read";
 }
 function inferRequiresAuth(resource) {
-    return resource !== "auth" && resource !== "commands" && resource !== "install-skill";
+    return resource !== "auth"
+        && resource !== "commands"
+        && resource !== "install-skill"
+        && resource !== "version";
 }
 function inferRequiresProject(resource, action, usage) {
-    if (resource === "doctor" || resource === "commands" || resource === "install-skill")
+    if (resource === "auth" || resource === "doctor" || resource === "commands"
+        || resource === "install-skill" || resource === "version") {
         return false;
+    }
     if (PROJECT_SCOPED_RESOURCES.has(resource))
         return true;
     if (resource === "project" && action !== "list")
@@ -4777,13 +5408,16 @@ const STRING_OUTPUT_ACTIONS = new Set([
     "cat",
     "log",
     "log-url",
-    "preview",
 ]);
 function inferOutputShape(resource, action) {
-    if (resource === "auth" || resource === "install-skill")
-        return "void";
+    if (resource === "auth" || resource === "commands" || resource === "install-skill"
+        || resource === "version") {
+        return "object";
+    }
     if (ARRAY_OUTPUT_ACTIONS.has(action))
         return "array";
+    if (resource === "dataset" && action === "download")
+        return "object";
     if (STRING_OUTPUT_ACTIONS.has(action))
         return "string";
     return "object";
@@ -4798,8 +5432,107 @@ function inferInputContract(usage) {
 function stripOptionalUsageGroups(usage) {
     return usage.replace(/\[[^\]]*\]/g, " ");
 }
-function extractRequiredUsageFlags(usage) {
-    return extractUsageFlags(stripOptionalUsageGroups(usage));
+function stripAllUsageGroups(usage) {
+    return usage.replace(/\[[^\]]*\]/g, " ").replace(/\([^)]*\)/g, " ");
+}
+function topLevelParenGroups(usage) {
+    const groups = [];
+    let depth = 0;
+    let current = "";
+    for (const char of usage) {
+        if (char === "(") {
+            if (depth > 0)
+                current += char;
+            else
+                current = "";
+            depth++;
+        }
+        else if (char === ")") {
+            depth--;
+            if (depth === 0)
+                groups.push(current);
+            else
+                current += char;
+        }
+        else if (depth > 0) {
+            current += char;
+        }
+    }
+    return groups;
+}
+function splitTopLevelChoices(group) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const char of group) {
+        if (char === "[" || char === "(")
+            depth++;
+        else if (char === "]" || char === ")")
+            depth--;
+        if (char === "|" && depth === 0) {
+            parts.push(current);
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+function flagsInUsageFragment(fragment) {
+    return extractUsageFlags(fragment.replace(/\[[^\]]*\]/g, " "));
+}
+/**
+ * Split required usage flags into unconditional flags and mutually-exclusive
+ * choice groups. A required `(--a X | --b Y)` group becomes a requiredOneOf entry
+ * (pick exactly one alternative; an alternative listing several flags must be
+ * supplied together) instead of marking every flag as unconditionally required.
+ */
+function deriveRequiredUsage(usage) {
+    const requiredFlags = extractUsageFlags(stripAllUsageGroups(usage));
+    const requiredOneOf = [];
+    for (const group of topLevelParenGroups(usage)) {
+        const alternatives = splitTopLevelChoices(group);
+        if (alternatives.length <= 1) {
+            requiredFlags.push(...flagsInUsageFragment(group));
+            continue;
+        }
+        const oneOf = alternatives
+            .map((alternative) => flagsInUsageFragment(alternative))
+            .filter((alternativeFlags) => alternativeFlags.length > 0);
+        if (oneOf.length > 1)
+            requiredOneOf.push({ oneOf, });
+        else if (oneOf.length === 1)
+            requiredFlags.push(...oneOf[0]);
+    }
+    return { requiredFlags: uniqueStrings(requiredFlags), requiredOneOf, };
+}
+const GLOBAL_FLAG_VALUE_HINTS = {
+    url: { valueType: "URL", },
+    fields: { valueType: "CSV", },
+    "api-key": { valueType: "KEY", },
+    "request-timeout": { valueType: "MS", },
+    retries: { valueType: "N", },
+    "ca-cert": { valueType: "PATH", },
+    "project-key": { valueType: "KEY", },
+    "record-cleanup": { valueType: "PATH", },
+};
+/** Derive a value placeholder (and enum members) for each value flag from its usage token. */
+function extractFlagValueHints(usage) {
+    const hints = new Map();
+    for (const match of usage.matchAll(/--([a-z0-9-]+)\s+([a-z]+(?:\|[a-z]+)+)/g)) {
+        const flag = FLAG_ALIASES[match[1]] ?? match[1];
+        if (!hints.has(flag)) {
+            hints.set(flag, { valueType: "enum", enumValues: match[2].split("|"), });
+        }
+    }
+    for (const match of usage.matchAll(/--([a-z0-9-]+)\s+(<[^>]+>|[A-Z][A-Za-z0-9_]*)/g)) {
+        const flag = FLAG_ALIASES[match[1]] ?? match[1];
+        if (!hints.has(flag))
+            hints.set(flag, { valueType: match[2], });
+    }
+    return hints;
 }
 function inferPayloadSchema(inputContract) {
     if (!inputContract.stdin && !inputContract.dataFlag && !inputContract.dataFileFlag) {
@@ -4852,6 +5585,8 @@ function inferAsyncKind(resource, action) {
     }
     if (resource === "data-quality" && action === "compute")
         return "future";
+    if (resource === "code" && action === "run")
+        return "future";
     return "none";
 }
 function inferIdempotency(sideEffect, action, usage) {
@@ -4861,6 +5596,8 @@ function inferIdempotency(sideEffect, action, usage) {
         return "if-not-exists";
     if (action.startsWith("delete") && usage.includes("--if-exists"))
         return "if-exists";
+    if (/^(clear|refresh|set|save)/.test(action))
+        return "convergent";
     return "none";
 }
 function inferCleanupHint(resource, action) {
@@ -4891,12 +5628,18 @@ function buildRegistryEntry(resource, action, meta) {
         ...(requiresAuth ? AUTHENTICATED_AGENT_FLAGS : []),
         ...(requiresProject ? ["project-key",] : []),
     ]);
+    const derivedRequired = deriveRequiredUsage(meta.usage);
     const requiredFlags = meta.requiredFlags
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.requiredFlags
-        ?? extractRequiredUsageFlags(meta.usage);
+        ?? derivedRequired.requiredFlags;
+    const requiredOneOf = meta.requiredOneOf
+        ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.requiredOneOf
+        ?? derivedRequired.requiredOneOf;
+    const oneOfFlags = new Set(requiredOneOf.flatMap((choice) => choice.oneOf.flat()));
     const optionalFlags = meta.optionalFlags
         ?? EXPLICIT_REGISTRY_OVERRIDES[registryKey(resource, action)]?.optionalFlags
-        ?? flags.filter((flag) => !requiredFlags.includes(flag));
+        ?? flags.filter((flag) => !requiredFlags.includes(flag) && !oneOfFlags.has(flag));
+    const valueHints = extractFlagValueHints(meta.usage);
     const inputContract = inferInputContract(meta.usage);
     const cleanupHint = inferCleanupHint(resource, action);
     const payloadSchema = meta.payloadSchema
@@ -4913,7 +5656,20 @@ function buildRegistryEntry(resource, action, meta) {
         usage: meta.usage,
         description: meta.description,
         examples: meta.examples,
-        flags: flags.map((name) => ({ name, kind: flagKind(name), })),
+        flags: flags.map((name) => {
+            const kind = flagKind(name);
+            if (kind === "boolean")
+                return { name, kind, };
+            const hint = valueHints.get(name) ?? GLOBAL_FLAG_VALUE_HINTS[name];
+            if (!hint)
+                return { name, kind, };
+            return {
+                name,
+                kind,
+                valueType: hint.valueType,
+                ...(hint.enumValues ? { enumValues: hint.enumValues, } : {}),
+            };
+        }),
         positionals: extractPositionals(meta.usage),
         sideEffect,
         requiresAuth,
@@ -4929,6 +5685,7 @@ function buildRegistryEntry(resource, action, meta) {
         dryRun: meta.usage.includes("--dry-run"),
         requiredFlags: uniqueStrings(requiredFlags),
         optionalFlags: uniqueStrings(optionalFlags),
+        ...(requiredOneOf.length > 0 ? { requiredOneOf, } : {}),
         ...(payloadSchema ? { payloadSchema, } : {}),
         ...(examplePayload !== undefined ? { examplePayload, } : {}),
         ...(cleanupCommand ? { cleanupCommand, } : {}),
@@ -4952,6 +5709,14 @@ function buildCommandRegistry() {
             examples: COMMANDS_EXAMPLES,
         }),
     };
+    registry.version = {
+        run: buildRegistryEntry("version", "run", {
+            handler: async () => undefined,
+            usage: VERSION_USAGE,
+            description: VERSION_DESCRIPTION,
+            examples: VERSION_EXAMPLES,
+        }),
+    };
     registry["install-skill"] = {
         run: buildRegistryEntry("install-skill", "run", {
             handler: async () => undefined,
@@ -4976,6 +5741,16 @@ function buildCommandRegistry() {
             examples: FIXTURES_EXAMPLES,
         }),
     };
+    registry.batch = {
+        run: buildRegistryEntry("batch", "run", {
+            handler: async () => undefined,
+            usage: BATCH_USAGE,
+            description: BATCH_DESCRIPTION,
+            examples: BATCH_EXAMPLES,
+            examplePayload: BATCH_EXAMPLE_PAYLOAD,
+            payloadSchema: { stdin: true, dataFlag: true, dataFileFlag: true, jsonShape: "array", },
+        }),
+    };
     registry.auth = {};
     for (const [action, meta,] of Object.entries(AUTH_ACTIONS)) {
         registry.auth[action] = buildRegistryEntry("auth", action, {
@@ -4983,6 +5758,7 @@ function buildCommandRegistry() {
             usage: meta.usage,
             description: meta.description,
             examples: meta.examples,
+            requiredFlags: meta.requiredFlags,
         });
     }
     return registry;
@@ -5605,10 +6381,10 @@ async function runCleanup(flags) {
     }
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     if (!url) {
-        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL, pass --url, or run: dss auth login");
+        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL or pass --url.", "missing_required_flag");
     }
     if (!apiKey) {
-        throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
+        throw new UsageError("Missing API key. Set DATAIKU_API_KEY or pass --api-key.", "missing_required_flag");
     }
     const requestTimeoutMs = num(flags["request-timeout"]);
     const retryMaxAttempts = num(flags["retries"]);
@@ -5628,7 +6404,8 @@ async function runCleanup(flags) {
         try {
             const parsed = parseArgs(entry.cleanup.argv);
             const [resource, action, ...args] = parsed.positional;
-            if (!resource || !action || !commands[resource]?.[action]) {
+            if (!resource || !action || !isAllowedCleanupAction(resource, action)
+                || !commands[resource]?.[action]) {
                 throw new UsageError(`Invalid cleanup argv: ${entry.cleanup.argv.join(" ")}`);
             }
             const result = await commands[resource][action].handler(client, args, parsed.flags);
@@ -5654,35 +6431,128 @@ async function runCleanup(flags) {
         exitCode: failures.length > 0 ? 2 : 0,
     };
 }
-// ---------------------------------------------------------------------------
-// Interactive prompts
-// ---------------------------------------------------------------------------
-function promptLine(label) {
-    return new Promise((res, rej) => {
-        const rl = createInterface({ input: process.stdin, output: process.stderr, });
-        rl.on("close", () => rej(new UsageError("Input closed before a value was provided.")));
-        rl.question(label, (answer) => {
-            rl.close();
-            res(answer.trim());
-        });
+const BATCH_USAGE = "dss batch (--data JSON|--data-file PATH|--stdin) [--continue-on-error] [--dry-run]";
+const BATCH_DESCRIPTION = "Run a sequence of dss commands from a JSON array of argv arrays. Fail-fast by default; returns one envelope with a per-step ok/result/error and exits non-zero if any step failed.";
+const BATCH_HINT = 'Pass a JSON array of argv arrays, e.g. [["dataset","list"],["recipe","update","r","--data-file","p.json"]].';
+const BATCH_EXAMPLE_PAYLOAD = [
+    ["recipe", "set-payload", "compute_orders", "--file", "code.py", "--no-backup",],
+    ["recipe", "update", "compute_orders", "--data-file", "env.json",],
+    ["dataset", "update", "orders", "--data-file", "ds.json",],
+];
+const BATCH_EXAMPLES = [
+    "dss batch --data-file steps.json",
+    "dss batch --stdin --continue-on-error",
+];
+function parseBatchSteps(payload) {
+    if (!Array.isArray(payload)) {
+        throw new UsageError("Batch payload must be a JSON array of command-argument arrays.", "validation_failed", BATCH_HINT, { example: BATCH_EXAMPLE_PAYLOAD, });
+    }
+    return payload.map((step, index) => {
+        if (!Array.isArray(step) || !step.every((token) => typeof token === "string")) {
+            throw new UsageError(`Batch step ${index} must be an array of string arguments.`, "validation_failed", BATCH_HINT);
+        }
+        return step;
     });
 }
-function promptSecret(label) {
-    return new Promise((res, rej) => {
-        const muted = new Writable({
-            write(_chunk, _encoding, cb) {
-                cb();
-            },
+async function runBatch(flags) {
+    const payload = unknownJsonInput(flags);
+    if (payload === undefined) {
+        throw new UsageError(`Provide steps via --data, --data-file, or --stdin. Usage: ${BATCH_USAGE}`, "missing_required_flag", BATCH_HINT);
+    }
+    const steps = parseBatchSteps(payload);
+    if (flags["dry-run"] === true) {
+        const planned = steps.map((argv, index) => {
+            const { positional, } = parseArgs(argv);
+            const resource = positional[0];
+            const action = positional[1];
+            const runnable = Boolean(resource && action && commands[resource]?.[action]);
+            return { index, args: argv, resource, action, runnable, };
+        });
+        return {
+            result: { dryRun: true, total: steps.length, steps: planned, },
+            exitCode: planned.every((step) => step.runnable) ? 0 : 1,
+        };
+    }
+    const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
+    if (!url) {
+        throw new UsageError("Missing Dataiku URL.", "missing_required_flag", "Set DATAIKU_URL or pass --url.", {
+            requiredFlags: ["url",],
+            env: ["DATAIKU_URL",],
         });
-        const rl = createInterface({ input: process.stdin, output: muted, terminal: true, });
-        rl.on("close", () => rej(new UsageError("Input closed before a value was provided.")));
-        process.stderr.write(label);
-        rl.question("", (answer) => {
-            rl.close();
-            process.stderr.write("\n");
-            res(answer.trim());
+    }
+    if (!apiKey) {
+        throw new UsageError("Missing API key.", "missing_required_flag", "Set DATAIKU_API_KEY or pass --api-key.", {
+            requiredFlags: ["api-key",],
+            env: ["DATAIKU_API_KEY",],
         });
+    }
+    const client = new DataikuClient({
+        url,
+        apiKey,
+        projectKey,
+        verbose: flags["verbose"] === true,
+        requestTimeoutMs: num(flags["request-timeout"]),
+        retryMaxAttempts: num(flags["retries"]),
+        tlsRejectUnauthorized,
+        caCertPath,
     });
+    const continueOnError = flags["continue-on-error"] === true;
+    const results = [];
+    let firstFailureExit;
+    for (let index = 0; index < steps.length; index++) {
+        const argv = steps[index];
+        const { positional, flags: stepFlags, } = parseArgs(argv);
+        const resource = positional[0];
+        const action = positional[1];
+        if (firstFailureExit !== undefined && !continueOnError) {
+            results.push({ index, args: argv, resource, action, ok: null, skipped: true, });
+            continue;
+        }
+        currentCommandContext = {
+            resource,
+            action,
+            projectKey: typeof stepFlags["project-key"] === "string" ? stepFlags["project-key"] : projectKey,
+        };
+        try {
+            if (!resource)
+                throw noCommandError();
+            const resourceActions = commands[resource];
+            if (!resourceActions)
+                throw unknownResourceError(resource);
+            if (!action) {
+                throw missingActionError(resource, Object.keys(resourceActions), `dss ${resource} <action>`);
+            }
+            const meta = resourceActions[action];
+            if (!meta)
+                throw unknownActionError(resource, action, Object.keys(resourceActions));
+            const result = await meta.handler(client, positional.slice(2), stepFlags);
+            const failureExitCode = commandFailureExitCode(result);
+            if (failureExitCode !== undefined)
+                throw new CommandResultFailure(result, failureExitCode);
+            const stepFieldsFlag = stepFlags["fields"];
+            const stepFields = typeof stepFieldsFlag === "string"
+                ? stepFieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0)
+                : [];
+            const stepResult = stepFields.length > 0 ? projectResultFields(result, stepFields) : result;
+            results.push({ index, args: argv, resource, action, ok: true, result: stepResult, });
+        }
+        catch (error) {
+            const envelope = buildErrorReport(error);
+            results.push({ index, args: argv, resource, action, ok: false, error: envelope, });
+            if (firstFailureExit === undefined)
+                firstFailureExit = envelope.exitCode;
+        }
+    }
+    const ok = firstFailureExit === undefined;
+    return {
+        result: {
+            ok,
+            total: steps.length,
+            completed: results.filter((step) => step.ok !== null).length,
+            steps: results,
+        },
+        exitCode: ok ? 0 : firstFailureExit ?? 2,
+    };
 }
 // ---------------------------------------------------------------------------
 // Credential resolution
@@ -5695,12 +6565,15 @@ function resolveCredentials(flags) {
     let apiKey = hasApiKeyFlag ? flags["api-key"] : undefined;
     let projectKey = hasProjectKeyFlag ? flags["project-key"] : undefined;
     const saved = loadCredentials();
-    if (!hasUrlFlag)
-        url ??= process.env.DATAIKU_URL;
-    if (!hasApiKeyFlag)
-        apiKey ??= process.env.DATAIKU_API_KEY;
-    if (!hasProjectKeyFlag)
-        projectKey ??= process.env.DATAIKU_PROJECT_KEY;
+    const useEnv = dataikuEnvironmentEnabled();
+    if (useEnv) {
+        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) {
         if (!hasUrlFlag)
             url ??= saved.url;
@@ -5717,10 +6590,6 @@ function resolveCredentials(flags) {
     };
 }
 let currentCommandContext = {};
-function isReportJsonRequested() {
-    return process.env.DSS_REPORT_JSON === "1"
-        || process.argv.slice(2).some((arg) => arg === "--report-json" || arg.startsWith("--report-json="));
-}
 function rawFlagValue(argv, flagName) {
     const longFlag = `--${flagName}`;
     for (let index = 0; index < argv.length; index++) {
@@ -5734,6 +6603,12 @@ function rawFlagValue(argv, flagName) {
     }
     return undefined;
 }
+function commandIsProjectScoped(resource, action) {
+    if (!resource)
+        return false;
+    const usage = commands[resource]?.[action ?? ""]?.usage ?? "";
+    return inferRequiresProject(resource, action ?? "", usage);
+}
 function rawCommandContext() {
     const argv = process.argv.slice(2);
     const positionals = [];
@@ -5758,13 +6633,19 @@ function rawCommandContext() {
         }
         positionals.push(arg);
     }
+    const resource = currentCommandContext.resource ?? positionals[0];
+    const action = currentCommandContext.action ?? positionals[1];
+    const explicitProjectKey = rawFlagValue(argv, "project-key") ?? rawFlagValue(argv, "project");
+    const ambientProjectKey = dataikuEnvironmentEnabled()
+        ? process.env.DATAIKU_PROJECT_KEY
+        : undefined;
     return {
-        resource: currentCommandContext.resource ?? positionals[0],
-        action: currentCommandContext.action ?? positionals[1],
-        projectKey: currentCommandContext.projectKey
-            ?? rawFlagValue(argv, "project-key")
-            ?? rawFlagValue(argv, "project")
-            ?? process.env.DATAIKU_PROJECT_KEY,
+        resource,
+        action,
+        projectKey: explicitProjectKey
+            ?? (commandIsProjectScoped(resource, action)
+                ? currentCommandContext.projectKey ?? ambientProjectKey
+                : undefined),
     };
 }
 function requestIdFromBody(body) {
@@ -5777,26 +6658,52 @@ function requestIdFromBody(body) {
         return undefined;
     }
 }
+function errorExitCode(err) {
+    if (err instanceof CommandResultFailure)
+        return err.exitCode;
+    if (err instanceof UsageError)
+        return 1;
+    if (err instanceof DataikuError)
+        return err.category === "transient" ? 3 : 2;
+    return 2;
+}
 function buildErrorReport(err) {
     const context = rawCommandContext();
+    const exitCode = errorExitCode(err);
     if (err instanceof UsageError) {
         return {
+            ok: false,
+            error: err.message,
             code: err.code,
             category: "usage",
-            message: err.message,
+            exitCode,
             ...(err.hint ? { hint: err.hint, } : {}),
+            ...(err.details ? { details: err.details, } : {}),
+            ...context,
+        };
+    }
+    if (err instanceof CommandResultFailure) {
+        return {
+            ok: false,
+            error: err.message,
+            code: "long_running_failure",
+            category: "dss",
+            exitCode: err.exitCode,
+            details: { result: err.result, },
             ...context,
         };
     }
     if (err instanceof DataikuError) {
         return {
+            ok: false,
+            error: err.message,
             code: dataikuErrorCode(err.category),
             category: "dss",
-            message: err.message,
+            exitCode,
             hint: err.retryHint,
             status: err.status,
             retryable: err.retryable,
-            requestId: requestIdFromBody(err.body),
+            requestId: err.requestId ?? requestIdFromBody(err.body),
             details: {
                 dssCategory: err.category,
                 statusText: err.statusText,
@@ -5808,190 +6715,109 @@ function buildErrorReport(err) {
     }
     const message = err instanceof Error ? err.message : String(err);
     return {
+        ok: false,
+        error: message,
         code: "internal_error",
         category: "internal",
-        message,
+        exitCode,
         ...context,
     };
 }
 function writeErrorReport(err) {
     process.stderr.write(`${JSON.stringify(buildErrorReport(err), null, 2)}\n`);
 }
-function commandRegistryEntry(resource, action) {
-    return buildCommandRegistry()[resource]?.[action];
-}
-function writeReportHelp(resource, action) {
-    const entry = commandRegistryEntry(resource, action);
-    if (entry) {
-        process.stderr.write(`${JSON.stringify(entry, null, 2)}\n`);
-        return;
-    }
-    process.stderr.write(`${JSON.stringify({
-        code: "usage_error",
-        category: "usage",
-        message: `No registry entry for ${resource} ${action}.`,
-        resource,
-        action,
-    }, null, 2)}\n`);
-}
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 async function main() {
     loadEnvFile();
     const { positional, flags, } = parseArgs(process.argv.slice(2));
-    // --version
-    if (flags["version"] === true) {
-        process.stdout.write(`${CLI_VERSION_LABEL}\n`);
-        process.exit(0);
+    const fieldsFlag = flags["fields"];
+    if (typeof fieldsFlag === "string") {
+        const selected = fieldsFlag.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+        if (selected.length > 0)
+            outputFieldProjection = selected;
     }
-    // Top-level help
-    if (positional.length === 0 || (positional.length === 0 && flags["help"])) {
-        printTopLevelHelp();
-        if (flags["help"])
-            process.exit(0);
-        process.exit(1);
+    if (flags["version"] === true) {
+        writeCommandResult(cliVersionResult());
+        return;
     }
+    if (positional.length === 0)
+        throw noCommandError();
     const resource = positional[0];
     currentCommandContext = {
         resource,
         action: positional[1],
         projectKey: typeof flags["project-key"] === "string"
             ? flags["project-key"]
-            : process.env.DATAIKU_PROJECT_KEY,
+            : dataikuEnvironmentEnabled()
+                ? process.env.DATAIKU_PROJECT_KEY
+                : undefined,
     };
     if (resource === "doctor") {
         const action = positional[1];
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true)
-                writeReportHelp("doctor", "run");
-            else
-                printActionHelp("doctor", "run");
-            process.exit(0);
-        }
+        currentCommandContext.action = action ?? "run";
         if (action !== undefined && action !== "run") {
-            throw new UsageError("Usage: dss doctor [--project-key KEY] [--capabilities] [--fast]");
+            throw unknownActionError("doctor", action, ["run",]);
         }
         const { result, exitCode, } = await runDoctor(flags);
         writeCommandResult(result);
-        process.exit(exitCode);
+        if (exitCode !== 0)
+            process.exit(exitCode);
+        return;
     }
-    // Auth commands — dispatched before client creation
     if (resource === "auth") {
         const action = positional[1];
+        const validActions = Object.keys(AUTH_ACTIONS);
         if (!action) {
-            const maxName = Math.max(...Object.keys(AUTH_ACTIONS).map((n) => n.length));
-            const lines = [
-                "Usage: dss auth <action> [--flags]",
-                "",
-                "Actions:",
-                ...Object.entries(AUTH_ACTIONS).map(([name, meta,]) => `  ${name.padEnd(maxName + 2)}${meta.description ?? meta.usage}`),
-                "",
-                "Run 'dss auth <action> --help' for details and examples.",
-            ];
-            process.stderr.write(`${lines.join("\n")}\n`);
-            process.exit(flags["help"] === true ? 0 : 1);
+            throw missingActionError("auth", validActions, "dss auth login --url URL --api-key KEY");
         }
+        currentCommandContext.action = action;
         const authMeta = AUTH_ACTIONS[action];
-        if (!authMeta) {
-            if (flags["report-json"] === true) {
-                throw new UsageError(`Unknown action: auth ${action}. Available: ${Object.keys(AUTH_ACTIONS).join(", ")}`);
-            }
-            process.stderr.write(`Unknown action: auth ${action}\nAvailable: ${Object.keys(AUTH_ACTIONS).join(", ")}\n`);
-            process.exit(1);
-        }
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true) {
-                writeReportHelp("auth", action);
-            }
-            else {
-                const lines = [];
-                if (authMeta.description)
-                    lines.push(authMeta.description, "");
-                lines.push(`Usage: ${authMeta.usage}`);
-                if (authMeta.examples && authMeta.examples.length > 0) {
-                    lines.push("", "Examples:");
-                    for (const ex of authMeta.examples)
-                        lines.push(`  ${ex}`);
-                }
-                process.stderr.write(`${lines.join("\n")}\n`);
-            }
-            process.exit(0);
-        }
-        await authMeta.handler(flags);
+        if (!authMeta)
+            throw unknownActionError("auth", action, validActions);
+        const result = await authMeta.handler(flags);
+        writeCommandResult(result);
         return;
     }
-    // install-skill — dispatched before client creation
     if (resource === "install-skill") {
-        const installSkillAction = positional[1];
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true) {
-                writeReportHelp("install-skill", "run");
-            }
-            else {
-                const lines = [
-                    `Usage: ${INSTALL_SKILL_USAGE}`,
-                    "",
-                    INSTALL_SKILL_DESCRIPTION,
-                    "",
-                    "Flags:",
-                    "  --global         Install to user-level global scope (default: project)",
-                    "  --agent NAME     Target a specific agent: claude, codex, cursor, pi, omp",
-                    "  --target PATH    Project directory to install into (default: workspace root)",
-                    "  --list-agents    Print detected agents and exit",
-                    "  --dry-run        Print planned skill installs without writing files",
-                    "  --plan           Print planned skill installs without writing files",
-                ];
-                process.stderr.write(`${lines.join("\n")}\n`);
-            }
-            process.exit(0);
-        }
-        if (installSkillAction !== undefined && installSkillAction !== "run") {
-            throw new UsageError(`Usage: ${INSTALL_SKILL_USAGE}`);
+        const action = positional[1];
+        currentCommandContext.action = action ?? "run";
+        if (action !== undefined && action !== "run") {
+            throw unknownActionError("install-skill", action, ["run",]);
         }
-        const listOnly = flags["list-agents"] === true;
         const agentFilter = typeof flags["agent"] === "string" ? flags["agent"] : undefined;
         const isGlobal = flags["global"] === true;
         const targetDir = typeof flags["target"] === "string" ? flags["target"] : undefined;
-        // Resolve target agents
-        let targets;
-        if (agentFilter) {
+        const targets = (() => {
+            if (!agentFilter)
+                return detectAgents();
             const def = AGENTS[agentFilter];
             if (!def) {
-                throw new UsageError(`Unknown agent: ${agentFilter}. Available: ${Object.keys(AGENTS).join(", ")}`);
+                throw new UsageError(`Unknown agent: ${agentFilter}.`, "usage_error", COMMANDS_RUN_HINT, { agent: agentFilter, validAgents: Object.keys(AGENTS), });
             }
-            targets = [{ id: agentFilter, def, via: "flag", },];
-        }
-        else {
-            targets = detectAgents();
-        }
-        if (listOnly) {
-            if (targets.length === 0) {
-                process.stderr.write("No coding agents detected.\n");
-            }
-            else {
-                process.stderr.write("Detected agents:\n");
-                for (const t of targets) {
-                    process.stderr.write(`  ${t.id}  (${t.def.name}, via ${t.via})\n`);
-                }
-            }
-            process.exit(0);
+            return [{ id: agentFilter, def, via: "flag", },];
+        })();
+        if (flags["list-agents"] === true) {
+            writeCommandResult({
+                agents: targets.map((target) => ({
+                    id: target.id,
+                    name: target.def.name,
+                    via: target.via,
+                })),
+            });
+            return;
         }
         if (targets.length === 0) {
-            throw new UsageError("No coding agents detected. Install one (claude, codex, cursor, pi, omp) or use --agent NAME.");
+            throw new UsageError("No coding agents detected.", "usage_error", "Use --agent NAME to choose one of the supported agents.", { validAgents: Object.keys(AGENTS), });
         }
         const scope = isGlobal ? "global" : "project";
         const cwd = targetDir ?? (isGlobal ? process.cwd() : findWorkspaceRoot(process.cwd()));
+        const installed = planSkillInstalls(targets, { global: isGlobal, cwd, });
         if (flags["plan"] === true) {
             writeCommandResult(planResult("install-skill", "run", {
                 identifiers: { scope, target: cwd, },
-                payload: {
-                    agents: targets.map((target) => ({
-                        id: target.id,
-                        name: target.def.name,
-                        via: target.via,
-                    })),
-                },
+                payload: { installed, },
                 idempotency: "none",
                 asyncKind: "none",
                 exitCodesOnFailure: { usage: 1, error: 2, transient: 3, },
@@ -5999,163 +6825,93 @@ async function main() {
             }));
             return;
         }
-        if (flags["dry-run"] === true) {
-            writeCommandResult({
-                dryRun: true,
-                action: "install-skill",
-                resource: "install-skill",
-                scope,
-                target: cwd,
-                agents: targets.map((target) => ({
-                    id: target.id,
-                    name: target.def.name,
-                    via: target.via,
-                })),
-            });
-            return;
-        }
-        process.stderr.write(`Installing dataiku-dss skill (${scope} scope):\n`);
-        const results = installSkill(targets, { global: isGlobal, cwd, });
-        for (const r of results) {
-            process.stderr.write(`  ${r.agent}  ->  ${r.path}\n`);
-        }
-        if (results.length > 0) {
-            process.stderr.write(`\nDone. ${results.length} skill(s) installed.\n`);
-        }
+        writeCommandResult({
+            scope,
+            target: cwd,
+            installed: flags["dry-run"] === true
+                ? installed
+                : installSkill(targets, { global: isGlobal, cwd, }),
+            ...(flags["dry-run"] === true ? { dryRun: true, } : {}),
+        });
         return;
     }
-    // commands — machine-readable introspection (no auth needed)
     if (resource === "commands") {
         const action = positional[1];
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true) {
-                writeReportHelp("commands", "run");
-            }
-            else {
-                const lines = [
-                    `Usage: ${COMMANDS_USAGE}`,
-                    "",
-                    COMMANDS_DESCRIPTION,
-                    "",
-                    "Examples:",
-                    ...COMMANDS_EXAMPLES.map((example) => `  ${example}`),
-                ];
-                process.stderr.write(`${lines.join("\n")}\n`);
-            }
-            process.exit(0);
-        }
+        if (!action)
+            throw missingActionError("commands", ["run",], COMMANDS_USAGE);
+        currentCommandContext.action = action;
+        if (action !== "run")
+            throw unknownActionError("commands", action, ["run",]);
+        writeCommandResult(buildCommandRegistry());
+        return;
+    }
+    if (resource === "version") {
+        const action = positional[1];
+        currentCommandContext.action = action ?? "run";
         if (action !== undefined && action !== "run") {
-            throw new UsageError(`Usage: ${COMMANDS_USAGE}`);
+            throw unknownActionError("version", action, ["run",]);
         }
-        writeCommandResult(buildCommandRegistry());
+        writeCommandResult(cliVersionResult());
         return;
     }
     if (resource === "cleanup") {
         const action = positional[1];
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true) {
-                writeReportHelp("cleanup", "run");
-            }
-            else {
-                const lines = [
-                    `Usage: ${CLEANUP_USAGE}`,
-                    "",
-                    CLEANUP_DESCRIPTION,
-                    "",
-                    "Examples:",
-                    ...CLEANUP_EXAMPLES.map((example) => `  ${example}`),
-                ];
-                process.stderr.write(`${lines.join("\n")}\n`);
-            }
-            process.exit(0);
-        }
+        currentCommandContext.action = action ?? "run";
         if (action !== undefined && action !== "run") {
-            throw new UsageError(`Usage: ${CLEANUP_USAGE}`);
+            throw unknownActionError("cleanup", action, ["run",]);
         }
         const { result, exitCode, } = await runCleanup(flags);
         writeCommandResult(result);
-        process.exit(exitCode);
+        if (exitCode !== 0)
+            process.exit(exitCode);
+        return;
     }
     if (resource === "fixtures") {
         const action = positional[1];
-        currentCommandContext.action = "run";
-        if (flags["help"] === true) {
-            if (flags["report-json"] === true) {
-                writeReportHelp("fixtures", "run");
-            }
-            else {
-                const lines = [
-                    `Usage: ${FIXTURES_USAGE}`,
-                    "",
-                    FIXTURES_DESCRIPTION,
-                    "",
-                    "Examples:",
-                    ...FIXTURES_EXAMPLES.map((example) => `  ${example}`),
-                ];
-                process.stderr.write(`${lines.join("\n")}\n`);
-            }
-            process.exit(0);
-        }
+        currentCommandContext.action = action ?? "run";
         if (action !== undefined && action !== "run") {
-            throw new UsageError(`Usage: ${FIXTURES_USAGE}`);
+            throw unknownActionError("fixtures", action, ["run",]);
         }
         const result = await runFixtures(flags);
         writeCommandResult(result);
         return;
     }
-    // Unknown resource
-    if (!commands[resource]) {
-        if (flags["help"]) {
-            printTopLevelHelp();
-            process.exit(0);
-        }
-        if (flags["report-json"] === true) {
-            throw new UsageError(`Unknown resource: ${resource}. Available: ${RESOURCE_NAMES.join(", ")}`);
-        }
-        process.stderr.write(`Unknown resource: ${resource} \nAvailable: ${RESOURCE_NAMES.join(", ")} \n`);
-        process.exit(1);
-    }
-    // Resource-level help
-    if (positional.length === 1 || flags["help"] === true) {
-        if (positional.length === 1) {
-            printResourceHelp(resource);
-            if (flags["help"])
-                process.exit(0);
-            process.exit(1);
-        }
-    }
-    const action = positional[1];
-    const actionMeta = commands[resource][action];
-    // Unknown action
-    if (!actionMeta) {
-        if (flags["report-json"] === true) {
-            throw new UsageError(`Unknown action: ${resource} ${action}. Available actions for ${resource}: ${Object.keys(commands[resource]).join(", ")}`);
+    if (resource === "batch") {
+        const action = positional[1];
+        currentCommandContext.action = action ?? "run";
+        if (action !== undefined && action !== "run") {
+            throw unknownActionError("batch", action, ["run",]);
         }
-        process.stderr.write(`Unknown action: ${resource} ${action} \nAvailable actions for ${resource}: ${Object.keys(commands[resource]).join(", ")} \n`);
-        process.exit(1);
+        const { result, exitCode, } = await runBatch(flags);
+        writeCommandResult(result);
+        if (exitCode !== 0)
+            process.exit(exitCode);
+        return;
     }
-    // Action-level help
-    if (flags["help"] === true) {
-        if (flags["report-json"] === true)
-            writeReportHelp(resource, action);
-        else
-            printActionHelp(resource, action);
-        process.exit(0);
+    if (!commands[resource])
+        throw unknownResourceError(resource);
+    const resourceActions = commands[resource];
+    if (positional.length === 1) {
+        throw missingActionError(resource, Object.keys(resourceActions), `dss ${resource} <action> [args...]`);
     }
+    const action = positional[1];
+    currentCommandContext.action = action;
+    const actionMeta = resourceActions[action];
+    if (!actionMeta)
+        throw unknownActionError(resource, action, Object.keys(resourceActions));
     const args = positional.slice(2);
     if (flags["plan"] === true) {
         const plan = buildMutationPlan(resource, action, actionMeta, args, flags);
         writeCommandResult(plan);
         return;
     }
-    // Resolve credentials: flags > env > saved > .env
     const { url, apiKey, projectKey, tlsRejectUnauthorized, caCertPath, } = resolveCredentials(flags);
     currentCommandContext.projectKey = projectKey;
     if (!url) {
-        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL, pass --url, or run: dss auth login");
+        throw new UsageError("Missing Dataiku URL.", "missing_required_flag", "Set DATAIKU_URL or pass --url.", { requiredFlags: ["url",], env: ["DATAIKU_URL",], });
     }
     if (!apiKey) {
-        throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
+        throw new UsageError("Missing API key.", "missing_required_flag", "Set DATAIKU_API_KEY or pass --api-key.", { requiredFlags: ["api-key",], env: ["DATAIKU_API_KEY",], });
     }
     const requestTimeoutMs = num(flags["request-timeout"]);
     const retryMaxAttempts = num(flags["retries"]);
@@ -6180,41 +6936,17 @@ async function main() {
         if (entry)
             await appendCleanupLedgerEntry(flags["record-cleanup"], entry);
     }
-    if (flags["raw"] === true && typeof result === "string") {
+    const failureExitCode = commandFailureExitCode(result);
+    if (failureExitCode !== undefined)
+        throw new CommandResultFailure(result, failureExitCode);
+    if (flags["raw"] === true && typeof result === "string" && typeof flags["output"] !== "string") {
         process.stdout.write(result);
     }
     else {
         writeCommandResult(result);
     }
-    const failureExitCode = commandFailureExitCode(result);
-    if (failureExitCode !== undefined)
-        process.exit(failureExitCode);
 }
 main().catch((err) => {
-    if (isReportJsonRequested()) {
-        writeErrorReport(err);
-        if (err instanceof UsageError)
-            process.exit(1);
-        if (err instanceof DataikuError)
-            process.exit(err.category === "transient" ? 3 : 2);
-        process.exit(2);
-    }
-    if (err instanceof UsageError) {
-        process.stderr.write(`${JSON.stringify({ error: err.message, code: "usage", }, null, 2)}\n`);
-        process.exit(1);
-    }
-    if (err instanceof DataikuError) {
-        const payload = {
-            error: err.message,
-            category: err.category,
-            retryable: err.retryable,
-        };
-        if (err.retryHint)
-            payload.retryHint = err.retryHint;
-        process.stderr.write(`${JSON.stringify(payload, null, 2)} \n`);
-        process.exit(err.category === "transient" ? 3 : 2);
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`${JSON.stringify({ error: message, }, null, 2)} \n`);
-    process.exit(1);
+    writeErrorReport(err);
+    process.exit(errorExitCode(err));
 });