dataiku-sdk 0.1.1 → 0.2.0

package/dist/src/cli.js

@@ -1,12 +1,27 @@
 #!/usr/bin/env node
 import { readFileSync, } from "node:fs";
+import { writeFile, } from "node:fs/promises";
 import { dirname, 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 { DataikuError, } from "./errors.js";
+import { AGENTS, detectAgents, installSkill, } from "./skill.js";
 // ---------------------------------------------------------------------------
 // Utility helpers
 // ---------------------------------------------------------------------------
+const CLI_VERSION = (() => {
+    try {
+        const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+})();
 function num(v) {
     if (typeof v !== "string")
         return undefined;
@@ -18,6 +33,122 @@ function json(v) {
         return undefined;
     return JSON.parse(v);
 }
+function jsonInput(flags) {
+    if (flags["stdin"] === true) {
+        return JSON.parse(readFileSync(0, "utf-8"));
+    }
+    if (typeof flags["data-file"] === "string") {
+        return JSON.parse(readFileSync(flags["data-file"], "utf-8"));
+    }
+    if (typeof flags["data"] === "string") {
+        return JSON.parse(flags["data"]);
+    }
+    return undefined;
+}
+async function resolveFolderId(client, nameOrId, flags) {
+    return client.folders.resolveId(nameOrId, flags["project-key"]);
+}
+function formatLineDiff(remoteName, localPath, remoteContent, localContent) {
+    if (localContent === remoteContent) {
+        return "No differences.";
+    }
+    const localLines = localContent.split("\n");
+    const remoteLines = remoteContent.split("\n");
+    const lines = [`--- remote:${remoteName}`, `+++ local:${localPath}`, "",];
+    const maxLen = Math.max(localLines.length, remoteLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        const remoteLine = remoteLines[i];
+        const localLine = localLines[i];
+        if (remoteLine === localLine)
+            continue;
+        if (remoteLine !== undefined && localLine !== undefined) {
+            lines.push(`@@ line ${String(i + 1)} @@`);
+            lines.push(`- ${remoteLine}`);
+            lines.push(`+ ${localLine}`);
+            continue;
+        }
+        if (remoteLine !== undefined) {
+            lines.push(`- ${remoteLine}`);
+            continue;
+        }
+        lines.push(`+ ${localLine}`);
+    }
+    return lines.join("\n");
+}
+function parseOutputFormat(v) {
+    if (v === undefined)
+        return "json";
+    if (v === "json" || v === "quiet" || v === "table" || v === "tsv")
+        return v;
+    throw new UsageError(`Invalid --format value: ${String(v)}. Use json, tsv, table, or quiet.`);
+}
+function writeTable(items) {
+    if (items.length === 0)
+        return;
+    const keys = Object.keys(items[0]);
+    const maxWidths = keys.map((k) => {
+        const values = items.map((item) => String(item[k] ?? ""));
+        return Math.min(40, Math.max(k.length, ...values.map((v) => v.length)));
+    });
+    process.stdout.write(`${keys.map((k, i) => k.padEnd(maxWidths[i])).join("  ")}\n`);
+    process.stdout.write(`${maxWidths.map((w) => "-".repeat(w)).join("  ")}\n`);
+    for (const item of items) {
+        const row = keys.map((k, i) => {
+            const val = String(item[k] ?? "");
+            return (val.length > maxWidths[i]
+                ? `${val.slice(0, maxWidths[i] - 1)}\u2026`
+                : val).padEnd(maxWidths[i]);
+        });
+        process.stdout.write(`${row.join("  ")}\n`);
+    }
+}
+function writeCommandResult(result, format) {
+    if (result === undefined || result === null) {
+        if (format !== "quiet") {
+            process.stdout.write(`${JSON.stringify({ ok: true, }, null, 2)}\n`);
+        }
+        return;
+    }
+    if (typeof result === "string") {
+        if (format !== "quiet") {
+            process.stdout.write(result);
+            if (!result.endsWith("\n"))
+                process.stdout.write("\n");
+        }
+        return;
+    }
+    if (format === "quiet")
+        return;
+    const isArrayOfObjects = Array.isArray(result)
+        && result.every((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+    if (format === "tsv" && isArrayOfObjects) {
+        const items = result;
+        if (items.length === 0)
+            return;
+        const keys = Object.keys(items[0]);
+        process.stdout.write(`${keys.join("\t")}\n`);
+        for (const item of items) {
+            process.stdout.write(`${keys.map((key) => String(item[key] ?? "")).join("\t")}\n`);
+        }
+        return;
+    }
+    if (format === "table" && isArrayOfObjects) {
+        writeTable(result);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+const BOOLEAN_FLAGS = new Set(["help", "verbose", "version", "stdin", "global", "list-agents",]);
+const SHORT_FLAGS = {
+    h: "help",
+    v: "verbose",
+    V: "version",
+    f: "format",
+    o: "output",
+};
 function parseArgs(argv) {
     const positional = [];
     const flags = {};
@@ -34,16 +165,43 @@ function parseArgs(argv) {
                 flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
             }
             else {
-                const next = argv[i + 1];
-                if (next !== undefined && !next.startsWith("--")) {
-                    flags[arg.slice(2)] = next;
-                    i++;
+                const flagName = arg.slice(2);
+                if (BOOLEAN_FLAGS.has(flagName)) {
+                    flags[flagName] = true;
                 }
                 else {
-                    flags[arg.slice(2)] = true;
+                    const next = argv[i + 1];
+                    if (next !== undefined && !next.startsWith("-")) {
+                        flags[flagName] = next;
+                        i++;
+                    }
+                    else {
+                        flags[flagName] = true;
+                    }
                 }
             }
         }
+        else if (arg.length === 2 && arg[0] === "-" && arg[1] !== "-") {
+            const long = SHORT_FLAGS[arg[1]];
+            if (long) {
+                if (BOOLEAN_FLAGS.has(long)) {
+                    flags[long] = true;
+                }
+                else {
+                    const next = argv[i + 1];
+                    if (next !== undefined && !next.startsWith("-")) {
+                        flags[long] = next;
+                        i++;
+                    }
+                    else {
+                        flags[long] = true;
+                    }
+                }
+            }
+            else {
+                positional.push(arg);
+            }
+        }
         else {
             positional.push(arg);
         }
@@ -142,14 +300,14 @@ const commands = {
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss dataset update <name> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss dataset update <name> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.datasets.update(a[0], data, f["project-key"]);
             },
-            usage: "dss dataset update <name> --data '{...}' [--project-key KEY]",
+            usage: "dss dataset update <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
     },
     recipe: {
@@ -178,37 +336,98 @@ const commands = {
                 requireArgs(a, 1, "dss recipe download <name>");
                 return c.recipes.download(a[0], {
                     outputPath: f["output"],
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss recipe download <name> [--output PATH]",
+            usage: "dss recipe download <name> [--output PATH] [--project-key KEY]",
+        },
+        "download-code": {
+            handler: (c, a, f) => {
+                requireArgs(a, 1, "dss recipe download-code <name>");
+                return c.recipes.downloadCode(a[0], {
+                    outputPath: f["output"],
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe download-code <name> [--output PATH] [--project-key KEY]",
         },
         create: {
             handler: (c, _a, f) => {
                 const type = f["type"];
                 if (!type) {
-                    throw new UsageError("--type is required. Usage: dss recipe create --type TYPE --input DS");
+                    throw new UsageError("--type is required. Usage: dss recipe create --type TYPE --input DS --output DS");
+                }
+                const outputDataset = f["output"];
+                if (!outputDataset) {
+                    throw new UsageError("--output is required. Usage: dss recipe create --type TYPE --input DS --output DS");
                 }
                 return c.recipes.create({
                     type,
                     name: f["name"],
                     inputDatasets: f["input"] ? [f["input"],] : undefined,
-                    outputDataset: f["output"],
+                    outputDataset,
                     outputConnection: f["output-connection"],
                     projectKey: f["project-key"],
                 });
             },
-            usage: "dss recipe create --type TYPE --input DS [--output DS] [--output-connection CONN] [--project-key KEY]",
+            usage: "dss recipe create --type TYPE --input DS --output DS [--output-connection CONN] [--project-key KEY]",
+        },
+        diff: {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss recipe diff <name> --file PATH");
+                const filePath = f["file"];
+                if (!filePath) {
+                    throw new UsageError("--file is required. Usage: dss recipe diff <name> --file PATH");
+                }
+                const result = await c.recipes.get(a[0], {
+                    includePayload: true,
+                    projectKey: f["project-key"],
+                });
+                if (!result.payload) {
+                    throw new Error(`Recipe "${a[0]}" has no code payload to diff.`);
+                }
+                const localContent = readFileSync(filePath, "utf-8");
+                return formatLineDiff(a[0], filePath, result.payload, localContent);
+            },
+            usage: "dss recipe diff <name> --file PATH [--project-key KEY]",
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss recipe update <name> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss recipe update <name> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.recipes.update(a[0], data, f["project-key"]);
             },
-            usage: "dss recipe update <name> --data '{...}' [--project-key KEY]",
+            usage: "dss recipe update <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
+        },
+        "get-payload": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss recipe get-payload <name>");
+                const payload = await c.recipes.getPayload(a[0], {
+                    projectKey: f["project-key"],
+                });
+                if (typeof f["output"] === "string") {
+                    await writeFile(f["output"], payload, "utf-8");
+                    return f["output"];
+                }
+                return payload;
+            },
+            usage: "dss recipe get-payload <name> [--output PATH] [--project-key KEY]",
+        },
+        "set-payload": {
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss recipe set-payload <name> --file PATH");
+                const filePath = f["file"];
+                if (!filePath)
+                    throw new UsageError("--file is required.");
+                const content = readFileSync(filePath, "utf-8");
+                await c.recipes.setPayload(a[0], content, {
+                    projectKey: f["project-key"],
+                });
+            },
+            usage: "dss recipe set-payload <name> --file PATH [--project-key KEY]",
         },
     },
     job: {
@@ -316,14 +535,14 @@ const commands = {
         },
         update: {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss scenario update <id> --data '{...}'");
-                const data = json(f["data"]);
+                requireArgs(a, 1, "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
                 if (!data) {
-                    throw new UsageError("--data is required. Usage: dss scenario update <id> --data '{...}'");
+                    throw new UsageError("--data, --data-file, or --stdin is required. Usage: dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin]");
                 }
                 return c.scenarios.update(a[0], data, f["project-key"]);
             },
-            usage: "dss scenario update <id> --data '{...}' [--project-key KEY]",
+            usage: "dss scenario update <id> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
     },
     folder: {
@@ -332,41 +551,44 @@ const commands = {
             usage: "dss folder list [--project-key KEY]",
         },
         get: {
-            handler: (c, a, f) => {
-                requireArgs(a, 1, "dss folder get <id>");
-                return c.folders.get(a[0], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss folder get <name-or-id>");
+                return c.folders.get(await resolveFolderId(c, a[0], f), f["project-key"]);
             },
-            usage: "dss folder get <id> [--project-key KEY]",
+            usage: "dss folder get <name-or-id> [--project-key KEY]",
         },
         contents: {
-            handler: (c, a, _f) => {
-                requireArgs(a, 1, "dss folder contents <id>");
-                return c.folders.contents(a[0]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 1, "dss folder contents <name-or-id>");
+                return c.folders.contents(await resolveFolderId(c, a[0], f), {
+                    projectKey: f["project-key"],
+                });
             },
-            usage: "dss folder contents <id>",
+            usage: "dss folder contents <name-or-id> [--project-key KEY]",
         },
         download: {
-            handler: (c, a, f) => {
-                requireArgs(a, 2, "dss folder download <id> <path>");
-                return c.folders.download(a[0], a[1], {
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss folder download <name-or-id> <path>");
+                return c.folders.download(await resolveFolderId(c, a[0], f), a[1], {
                     localPath: f["output"],
+                    projectKey: f["project-key"],
                 });
             },
-            usage: "dss folder download <id> <path> [--output PATH]",
+            usage: "dss folder download <name-or-id> <path> [--output PATH] [--project-key KEY]",
         },
         upload: {
-            handler: (c, a, f) => {
-                requireArgs(a, 3, "dss folder upload <id> <path> <localPath>");
-                return c.folders.upload(a[0], a[1], a[2], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 3, "dss folder upload <name-or-id> <path> <localPath>");
+                return c.folders.upload(await resolveFolderId(c, a[0], f), a[1], a[2], f["project-key"]);
             },
-            usage: "dss folder upload <id> <path> <localPath> [--project-key KEY]",
+            usage: "dss folder upload <name-or-id> <path> <localPath> [--project-key KEY]",
         },
         "delete-file": {
-            handler: (c, a, f) => {
-                requireArgs(a, 2, "dss folder delete-file <id> <path>");
-                return c.folders.deleteFile(a[0], a[1], f["project-key"]);
+            handler: async (c, a, f) => {
+                requireArgs(a, 2, "dss folder delete-file <name-or-id> <path>");
+                return c.folders.deleteFile(await resolveFolderId(c, a[0], f), a[1], f["project-key"]);
             },
-            usage: "dss folder delete-file <id> <path> [--project-key KEY]",
+            usage: "dss folder delete-file <name-or-id> <path> [--project-key KEY]",
         },
     },
     variable: {
@@ -378,8 +600,10 @@ const commands = {
             handler: (c, _a, f) => c.variables.set({
                 standard: json(f["standard"]),
                 local: json(f["local"]),
+                replace: f["replace"] === true,
+                projectKey: f["project-key"],
             }),
-            usage: 'dss variable set --standard \'{"k":"v"}\' --local \'{"k":"v"}\'',
+            usage: 'dss variable set --standard \'{"k":"v"}\' --local \'{"k":"v"}\' [--replace] [--project-key KEY]',
         },
     },
     connection: {
@@ -492,23 +716,25 @@ const commands = {
         },
         "save-jupyter": {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss notebook save-jupyter <name> --data '{...}'");
-                const data = json(f["data"]);
-                if (!data)
-                    throw new UsageError("--data is required (notebook JSON content)");
+                requireArgs(a, 1, "dss notebook save-jupyter <name> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
+                if (!data) {
+                    throw new UsageError("--data, --data-file, or --stdin is required (notebook JSON content).");
+                }
                 return c.notebooks.saveJupyter(a[0], data, f["project-key"]);
             },
-            usage: "dss notebook save-jupyter <name> --data '{...}' [--project-key KEY]",
+            usage: "dss notebook save-jupyter <name> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
         "save-sql": {
             handler: (c, a, f) => {
-                requireArgs(a, 1, "dss notebook save-sql <id> --data '{...}'");
-                const data = json(f["data"]);
-                if (!data)
-                    throw new UsageError("--data is required (SQL notebook content JSON)");
+                requireArgs(a, 1, "dss notebook save-sql <id> [--data '{...}' | --data-file PATH | --stdin]");
+                const data = jsonInput(f);
+                if (!data) {
+                    throw new UsageError("--data, --data-file, or --stdin is required (SQL notebook content JSON).");
+                }
                 return c.notebooks.saveSql(a[0], data, f["project-key"]);
             },
-            usage: "dss notebook save-sql <id> --data '{...}' [--project-key KEY]",
+            usage: "dss notebook save-sql <id> [--data '{...}' | --data-file PATH | --stdin] [--project-key KEY]",
         },
         "clear-sql-history": {
             handler: (c, a, f) => {
@@ -526,19 +752,35 @@ const commands = {
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
-const RESOURCE_NAMES = Object.keys(commands).sort();
+const RESOURCE_NAMES = [...Object.keys(commands), "auth", "install-skill",].sort();
 function printTopLevelHelp() {
     const lines = [
         "Usage: dss <resource> <action> [args...] [--flags]",
         "",
         "Global flags:",
-        "  --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)",
-        "  --help               Show help",
+        "  -h, --help               Show help",
+        "  -v, --verbose            Log HTTP requests to stderr",
+        "  -V, --version            Show version",
+        "  -f, --format FORMAT      Output format: json|tsv|table|quiet",
+        "  -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         Request timeout in ms  (default: 30000)",
         "",
         "Resources:",
         ...RESOURCE_NAMES.map((r) => `  ${r}`),
+        "",
+        "Quick start:",
+        "  dss auth login                         Save DSS credentials",
+        "  dss auth status                        Verify connection",
+        "  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`);
 }
@@ -604,11 +846,133 @@ function loadEnvFile() {
     }
 }
 // ---------------------------------------------------------------------------
+// Auth commands (run before client creation)
+// ---------------------------------------------------------------------------
+const AUTH_ACTIONS = {
+    login: {
+        handler: async (flags) => {
+            let { url, apiKey, projectKey, } = resolveCredentials(flags);
+            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;
+            }
+            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);
+            if (!result.valid) {
+                process.stderr.write(`✗ Failed\n`);
+                throw new DataikuError(0, "Authentication Failed", result.error ?? "Credential validation failed");
+            }
+            process.stderr.write("\u2713 Connected\n");
+            saveCredentials({ url, apiKey, projectKey, });
+            process.stderr.write(`Credentials saved to ${getCredentialsPath()}\n`);
+        },
+        usage: "dss auth login [--url URL] [--api-key KEY] [--project-key KEY]",
+    },
+    status: {
+        handler: async (_flags) => {
+            const creds = loadCredentials();
+            if (!creds) {
+                process.stderr.write("No saved credentials. Run: dss auth login\n");
+                return;
+            }
+            const lines = [
+                `URL:         ${creds.url}`,
+                `API key:     ${maskApiKey(creds.apiKey)}`,
+                `Project key: ${creds.projectKey ?? "(not set)"}`,
+            ];
+            for (const line of lines)
+                process.stderr.write(`${line}\n`);
+            const result = await validateCredentials(creds.url, creds.apiKey);
+            if (result.valid) {
+                process.stderr.write("Connection:  \u2713 Valid\n");
+            }
+            else {
+                process.stderr.write(`Connection:  \u2717 Failed (${result.error ?? "unknown error"})\n`);
+            }
+            process.stderr.write(`Config:      ${getCredentialsPath()}\n`);
+        },
+        usage: "dss auth status",
+    },
+    logout: {
+        handler: async (_flags) => {
+            deleteCredentials();
+            process.stderr.write("Credentials removed.\n");
+        },
+        usage: "dss auth logout",
+    },
+};
+// ---------------------------------------------------------------------------
+// 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());
+        });
+    });
+}
+function promptSecret(label) {
+    return new Promise((res, rej) => {
+        const muted = new Writable({
+            write(_chunk, _encoding, cb) {
+                cb();
+            },
+        });
+        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());
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Credential resolution
+// ---------------------------------------------------------------------------
+function resolveCredentials(flags) {
+    let url = flags["url"];
+    let apiKey = flags["api-key"];
+    let projectKey = flags["project-key"];
+    url ??= process.env.DATAIKU_URL;
+    apiKey ??= process.env.DATAIKU_API_KEY;
+    projectKey ??= process.env.DATAIKU_PROJECT_KEY;
+    if (!url || !apiKey) {
+        const saved = loadCredentials();
+        if (saved) {
+            url ??= saved.url;
+            apiKey ??= saved.apiKey;
+            projectKey ??= saved.projectKey;
+        }
+    }
+    return { url: url ?? "", apiKey: apiKey ?? "", projectKey, };
+}
+// ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 async function main() {
     loadEnvFile();
     const { positional, flags, } = parseArgs(process.argv.slice(2));
+    // --version
+    if (flags["version"] === true) {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        process.exit(0);
+    }
     // Top-level help
     if (positional.length === 0 || (positional.length === 0 && flags["help"])) {
         printTopLevelHelp();
@@ -617,13 +981,91 @@ async function main() {
         process.exit(1);
     }
     const resource = positional[0];
+    // Auth commands — dispatched before client creation
+    if (resource === "auth") {
+        const action = positional[1];
+        if (!action || flags["help"] === true) {
+            const lines = [
+                "Usage: dss auth <action> [--flags]",
+                "",
+                "Actions:",
+                ...Object.entries(AUTH_ACTIONS).map(([name, meta,]) => `  ${name}  \u2192  ${meta.usage}`),
+            ];
+            process.stderr.write(`${lines.join("\n")}\n`);
+            process.exit(flags["help"] === true ? 0 : 1);
+        }
+        const authMeta = AUTH_ACTIONS[action];
+        if (!authMeta) {
+            process.stderr.write(`Unknown action: auth ${action}\nAvailable: ${Object.keys(AUTH_ACTIONS).join(", ")}\n`);
+            process.exit(1);
+        }
+        await authMeta.handler(flags);
+        return;
+    }
+    // install-skill — dispatched before client creation
+    if (resource === "install-skill") {
+        if (flags["help"] === true) {
+            const lines = [
+                "Usage: dss install-skill [--global] [--agent NAME] [--list-agents]",
+                "",
+                "Install the dataiku-dss agent skill for detected coding agents.",
+                "",
+                "Flags:",
+                "  --global         Install to user-level global scope (default: project)",
+                "  --agent NAME     Target a specific agent: claude, codex, cursor, pi, omp",
+                "  --list-agents    Print detected agents and exit",
+            ];
+            process.stderr.write(`${lines.join("\n")}\n`);
+            process.exit(0);
+        }
+        const listOnly = flags["list-agents"] === true;
+        const agentFilter = typeof flags["agent"] === "string" ? flags["agent"] : undefined;
+        const isGlobal = flags["global"] === true;
+        // Resolve target agents
+        let targets;
+        if (agentFilter) {
+            const def = AGENTS[agentFilter];
+            if (!def) {
+                throw new UsageError(`Unknown agent: ${agentFilter}. Available: ${Object.keys(AGENTS).join(", ")}`);
+            }
+            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);
+        }
+        if (targets.length === 0) {
+            throw new UsageError("No coding agents detected. Install one (claude, codex, cursor, pi, omp) or use --agent NAME.");
+        }
+        const scope = isGlobal ? "global" : "project";
+        process.stderr.write(`Installing dataiku-dss skill (${scope} scope):\n`);
+        const results = installSkill(targets, { global: isGlobal, cwd: process.cwd(), });
+        for (const r of results) {
+            process.stderr.write(`  ${r.agent}  \u2192  ${r.path}\n`);
+        }
+        if (results.length > 0) {
+            process.stderr.write(`\nDone. ${results.length} skill(s) installed.\n`);
+        }
+        return;
+    }
     // Unknown resource
     if (!commands[resource]) {
         if (flags["help"]) {
             printTopLevelHelp();
             process.exit(0);
         }
-        process.stderr.write(`Unknown resource: ${resource}\nAvailable: ${RESOURCE_NAMES.join(", ")}\n`);
+        process.stderr.write(`Unknown resource: ${resource} \nAvailable: ${RESOURCE_NAMES.join(", ")} \n`);
         process.exit(1);
     }
     // Resource-level help
@@ -639,7 +1081,7 @@ async function main() {
     const actionMeta = commands[resource][action];
     // Unknown action
     if (!actionMeta) {
-        process.stderr.write(`Unknown action: ${resource} ${action}\nAvailable actions for ${resource}: ${Object.keys(commands[resource]).join(", ")}\n`);
+        process.stderr.write(`Unknown action: ${resource} ${action} \nAvailable actions for ${resource}: ${Object.keys(commands[resource]).join(", ")} \n`);
         process.exit(1);
     }
     // Action-level help
@@ -647,29 +1089,30 @@ async function main() {
         printActionHelp(resource, action);
         process.exit(0);
     }
-    // Validate config
-    const url = flags["url"] ?? process.env.DATAIKU_URL ?? "";
-    const apiKey = flags["api-key"] ?? process.env.DATAIKU_API_KEY ?? "";
+    // Resolve credentials: flags > env > saved > .env
+    const { url, apiKey, projectKey, } = resolveCredentials(flags);
     if (!url) {
-        process.stderr.write(`${JSON.stringify({ error: "Missing Dataiku URL. Set DATAIKU_URL or pass --url.", }, null, 2)}\n`);
-        process.exit(1);
+        throw new UsageError("Missing Dataiku URL. Set DATAIKU_URL, pass --url, or run: dss auth login");
     }
     if (!apiKey) {
-        process.stderr.write(`${JSON.stringify({ error: "Missing API key. Set DATAIKU_API_KEY or pass --api-key.", }, null, 2)}\n`);
-        process.exit(1);
+        throw new UsageError("Missing API key. Set DATAIKU_API_KEY, pass --api-key, or run: dss auth login");
     }
+    const requestTimeoutMs = num(flags["timeout"]) ?? undefined;
     const client = new DataikuClient({
         url,
         apiKey,
-        projectKey: flags["project-key"] ?? process.env.DATAIKU_PROJECT_KEY,
+        projectKey,
+        verbose: flags["verbose"] === true,
+        requestTimeoutMs,
     });
     const args = positional.slice(2);
+    const format = parseOutputFormat(flags["format"]);
     const result = await actionMeta.handler(client, args, flags);
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    writeCommandResult(result, format);
 }
 main().catch((err) => {
     if (err instanceof UsageError) {
-        process.stderr.write(`${err.message}\n`);
+        process.stderr.write(`${err.message} \n`);
         process.exit(1);
     }
     if (err instanceof DataikuError) {
@@ -680,10 +1123,10 @@ main().catch((err) => {
         };
         if (err.retryHint)
             payload.retryHint = err.retryHint;
-        process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
-        process.exit(1);
+        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.stderr.write(`${JSON.stringify({ error: message, }, null, 2)} \n`);
     process.exit(1);
 });