@get-dx/cli 0.1.2 → 0.1.4

package/README.md

@@ -2,27 +2,28 @@
 
 AI-Native CLI for interacting with DX.
 
+<img width="800" height="423" alt="cli-demo" src="https://github.com/user-attachments/assets/a89f7d53-2617-413e-84df-07293149e9c8" />
+
 ## Install
 
-```bash
-npm install --global @get-dx/cli
+```shell
+npm install -g @get-dx/cli
 ```
 
-## Commands
-
-- `dx auth login --token <account-web-api-token>`
-- `dx auth logout`
-- `dx auth status`
-- `dx catalog entities info <identifier>`
+## Getting started
 
-## Agent Provenance
+Interactively login and install the AI agent skill:
 
-The CLI can automatically attach agent metadata from:
+```shell
+dx init
+```
 
-- `DX_AGENT_NAME`
-- `DX_AGENT_SESSION_ID`
+Show help text:
 
-Explicit `--agent` and `--agent-session-id` flags take precedence over the environment.
+```shell
+dx --help
+dx <subcommand> --help
+```
 
 ## Logging
 
@@ -30,15 +31,6 @@ Set `DX_LOG_LEVEL` to one of `debug`, `info`, `warn`, or `error` to enable CLI l
 
 Logs are always written to `stderr`. They are human-readable by default, and switch to JSON when `--json` is present or `stderr` is not a TTY.
 
-Deferred in this repo version:
-
-- `dx init`
-- `dx scorecards list|get|create|update`
-- `dx catalog entities list|create|update`
-- `dx workflows list`
-- `dx workflows trigger`
-- `dx studio query`
-
 ## Developing the CLI
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { Command, Option } from "commander";
 import { authCommand } from "./commands/auth.js";
 import { catalogCommand } from "./commands/catalog.js";
+import { initCommand } from "./commands/init.js";
 import { scorecardsCommand } from "./commands/scorecards.js";
 import { studioCommand } from "./commands/studio.js";
 import { handleError } from "./commandHelpers.js";
@@ -29,6 +30,7 @@ function createProgram() {
         .addOption(new Option("--agent-session-id <id>", "Agent session ID to send as an HTTP header"));
     program.addCommand(authCommand());
     program.addCommand(catalogCommand());
+    program.addCommand(initCommand());
     program.addCommand(scorecardsCommand());
     program.addCommand(studioCommand());
     applyExitOverride(program);
@@ -43,7 +45,7 @@ function createProgram() {
  */
 function applyExitOverride(cmd) {
     cmd.exitOverride();
-    cmd.configureOutput({ writeErr: () => { } });
+    cmd.configureOutput({ outputError: () => { } });
     for (const sub of cmd.commands) {
         applyExitOverride(sub);
     }

package/dist/commandHelpers.js

@@ -58,6 +58,10 @@ export function handleError(error, command, argv) {
         if (error instanceof HttpError) {
             process.stderr.write(`The API returned an error with status code ${error.status}:\n\n${JSON.stringify(error.body, null, 2)}\n`);
         }
+        else if (error instanceof CommanderError &&
+            (error.code === "commander.help" || error.message === "(outputHelp)")) {
+            // Commander already printed the relevant help text.
+        }
         else {
             process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         }

package/dist/commands/auth.js

@@ -15,7 +15,7 @@ export function authCommand() {
         .description("Manage DX authentication");
     auth
         .command("login")
-        .requiredOption("--token <token>", "Account web API token")
+        .requiredOption("--token <token>", "Account web API token or personal access token")
         .action(wrapAction(async (commandOptions, command) => {
         const context = getContext(command);
         const baseUrl = resolveBaseUrl();
@@ -62,7 +62,8 @@ export function authCommand() {
     }));
     return auth;
 }
-async function getAuthInfo(runtime) {
+// TODO: should we move this somewhere more central, since `init` needs it?
+export async function getAuthInfo(runtime) {
     const response = await request(runtime, "/auth.info", {
         method: "GET",
     });

package/dist/commands/authRendering.js

@@ -34,6 +34,8 @@ function tokenTypeName(tokenType) {
     switch (tokenType) {
         case "account_web_api_token":
             return "Account-level web API token";
+        case "personal_access_token":
+            return "Personal access token";
         default:
             throw new Error(`Unknown token type: ${tokenType}`);
     }

package/dist/commands/init.js

@@ -0,0 +1,194 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { input, password, confirm } from "@inquirer/prompts";
+import { Command } from "commander";
+import { execa } from "execa";
+import { buildRuntime, buildRuntimeSafe } from "../runtime.js";
+import { getAuthInfo } from "./auth.js";
+import { renderAuthInfo } from "./authRendering.js";
+import { getContext } from "../commandHelpers.js";
+import { wrapAction } from "../commandHelpers.js";
+import { renderRichText } from "../renderers.js";
+import * as ui from "../ui.js";
+import { CliError } from "../errors.js";
+import { persistBaseUrl } from "../config.js";
+import { setToken } from "../secrets.js";
+function parseHostname(raw) {
+    const normalized = raw.trim().replace(/\/$/, "");
+    if (!normalized || normalized === "app.getdx.com") {
+        return { type: "cloud" };
+    }
+    try {
+        const url = new URL(normalized.startsWith("http") ? normalized : `https://${normalized}`);
+        const host = url.hostname;
+        const dedicatedMatch = host.match(/^(.+)\.getdx\.io$/);
+        if (dedicatedMatch) {
+            return { type: "dedicated", accountName: dedicatedMatch[1] };
+        }
+        if (host) {
+            return { type: "managed", uiBaseUrl: url.origin };
+        }
+    }
+    catch {
+        // fall through to invalid
+    }
+    return { type: "invalid" };
+}
+// FIXME: make this WAY more glam
+// Choose a more interesting ASCII art font from https://patorjk.com/software/taag/
+const WELCOME_BANNER = ui.indent(`\
+▄▄▄▄▄     ▄▄▄  ▄▄▄
+██▀▀▀██    ██▄▄██
+██    ██    ████
+██    ██     ██
+██    ██    ████
+██▄▄▄██    ██  ██
+▀▀▀▀▀     ▀▀▀  ▀▀▀
+`, 2);
+export function initCommand() {
+    const init = new Command()
+        .name("init")
+        .description("Initialize the DX CLI")
+        .action(wrapAction(async (_commandOptions, command) => {
+        const context = getContext(command);
+        let runtime = buildRuntimeSafe(context);
+        ensureInteractive();
+        showWelcomeBanner();
+        runtime = await ensureLoggedIn(runtime);
+        await optionallySetupSkill(runtime);
+        renderRichText([
+            ui.blankLine(),
+            ui.p(`${ui.success(ui.GLYPHS.CHECK)} Done! You are now ready to use the DX CLI.`),
+        ]);
+    }));
+    return init;
+}
+function ensureInteractive() {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new CliError("`dx init` must be run interactively");
+    }
+}
+function showWelcomeBanner() {
+    renderRichText([ui.p(ui.success(WELCOME_BANNER))]);
+}
+async function ensureLoggedIn(runtime) {
+    renderRichText([ui.h1(`Checking if you are logged in...`), ui.blankLine()]);
+    if (runtime) {
+        let authInfo = null;
+        try {
+            authInfo = await getAuthInfo(runtime);
+        }
+        catch (_error) {
+            // Do nothing, we don't mind if this fails
+        }
+        if (authInfo) {
+            renderAuthInfo(authInfo, runtime.token, runtime.baseUrl);
+            return runtime;
+        }
+    }
+    renderRichText([ui.p(`You are not logged in yet.`), ui.blankLine()]);
+    let parsed = { type: "invalid" };
+    while (parsed.type === "invalid") {
+        const raw = await input({
+            message: "What is your DX hostname? (leave blank for app.getdx.com)",
+        });
+        parsed = parseHostname(raw);
+        if (parsed.type === "invalid") {
+            renderRichText([
+                ui.p(ui.error(`Could not recognise that hostname. Please try again.`)),
+            ]);
+        }
+    }
+    switch (parsed.type) {
+        case "cloud":
+            return await attemptLogin("https://api.getdx.com", "https://app.getdx.com");
+        case "dedicated": {
+            const { accountName } = parsed;
+            return await attemptLogin(`https://api.${accountName}.getdx.io`, `https://${accountName}.getdx.io`);
+        }
+        case "managed": {
+            const apiBaseUrl = await input({
+                message: "What is your API base URL?",
+            });
+            if (!apiBaseUrl) {
+                throw new CliError("API base URL is required");
+            }
+            return await attemptLogin(apiBaseUrl, parsed.uiBaseUrl);
+        }
+    }
+}
+async function attemptLogin(apiBaseUrl, _uiBaseUrl) {
+    const token = await password({
+        message: "Paste your account web API token here:",
+        mask: true,
+    });
+    if (!token) {
+        throw new CliError("Account web API token is required");
+    }
+    const context = createEmptyContext();
+    const runtime = buildRuntime(context, {
+        baseUrl: apiBaseUrl,
+        token,
+    });
+    renderRichText([ui.blankLine(), ui.p(`Attempting login...`), ui.blankLine()]);
+    const response = await getAuthInfo(runtime);
+    if (!response.ok) {
+        throw new CliError(`Login failed`);
+    }
+    persistBaseUrl(apiBaseUrl);
+    setToken(apiBaseUrl, token);
+    renderAuthInfo(response, token, apiBaseUrl);
+    return runtime;
+}
+async function optionallySetupSkill(runtime) {
+    renderRichText([
+        ui.blankLine(),
+        ui.h1(`Checking for the DX skill...`),
+        ui.blankLine(),
+    ]);
+    const skillPath = join(homedir(), ".agents", "skills", "dx-cli");
+    const skillInstalled = await access(skillPath)
+        .then(() => true)
+        .catch(() => false);
+    if (skillInstalled) {
+        renderRichText([ui.p(`The DX skill is already installed.`)]);
+        runtime.logger.debug("To update: npx skills update dx-cli --global");
+        runtime.logger.debug("To uninstall: npx skills remove dx-cli --global");
+        return;
+    }
+    renderRichText([
+        ui.p(`The DX skill is not installed. Would you like to install it?`),
+        ui.p("This will run the following command:", false),
+        ui.codeBlock("npx --yes -- skills@latest add get-dx/cli --global"),
+        ui.blankLine(),
+    ]);
+    const setupSkill = await confirm({
+        message: "Continue?",
+        default: true,
+    });
+    if (!setupSkill) {
+        renderRichText([
+            ui.p(`Skipping the DX skill setup. You can always do this later.`),
+        ]);
+        return;
+    }
+    renderRichText([ui.p(`Setting up the DX skill...`)]);
+    // NOTE: if the user chooses "no" for the final confirmation prompt, `skills` still exits with a 0 status.
+    // We are also not able to pipe the output without also breaking interactivity.
+    const result = await execa({
+        stdout: "inherit",
+        stderr: "inherit",
+        stdin: "inherit",
+    }) `npx --yes -- skills@latest add get-dx/cli --global`;
+    runtime.logger.debug("To update: npx skills update dx-cli --global");
+    runtime.logger.debug("To uninstall: npx skills remove dx-cli --global");
+    if (result.exitCode !== 0) {
+        throw new CliError(`Failed to setup the DX skill: ${result.stderr}`);
+    }
+}
+function createEmptyContext() {
+    return {
+        json: false,
+    };
+}

package/dist/commands/studio/query.js

@@ -21,6 +21,7 @@ export function queryCommand() {
         .description("Execute a Data Studio SQL query and wait for the results")
         .argument("<sql>", "SQL query to execute")
         .option("--output <filename>", "Save the full result set as CSV to a file")
+        .option("--variable <key=value>", "Set a template variable referenced in the SQL (can be repeated; use comma-separated values for arrays)", (val, prev) => [...prev, val], [])
         .addHelpText("afterAll", createExampleText([
         {
             label: "Run a query and print the results as a table",
@@ -28,21 +29,30 @@ export function queryCommand() {
         },
         {
             label: "Run a query and print the JSON results payload",
-            command: "dx studio query 'SELECT id, name FROM github_repos LIMIT 5' --json",
+            command: "dx studio query 'SELECT id, name FROM github_repositories LIMIT 5' --json",
         },
         {
             label: "Run a query and save the full result set as CSV",
             command: "dx studio query 'SELECT * FROM github_pulls' --output pulls.csv",
         },
+        {
+            label: "Run a parameterized query with a scalar variable",
+            command: "dx studio query 'SELECT * FROM github_repositories WHERE name = $name' --variable name=my-repo",
+        },
+        {
+            label: "Run a parameterized query with an array variable",
+            command: "dx studio query 'SELECT * FROM github_repositories WHERE id IN ($repo_ids)' --variable repo_ids=1,2,3",
+        },
     ]))
         .action(wrapAction(async (sql, options, command) => {
         const context = getContext(command);
         if (context.json && options.output) {
             throw new CliError("--output cannot be used with --json", EXIT_CODES.ARGUMENT_ERROR);
         }
+        const variables = parseVariables(options.variable);
         const runtime = buildRuntime(context);
         const progress = new QueryProgressReporter();
-        const queryRun = await executeQuery(runtime, progress, sql);
+        const queryRun = await executeQuery(runtime, progress, sql, variables);
         await waitForQuery(runtime, progress, queryRun.id);
         if (options.output) {
             await downloadStudioQueryResultsCsv(runtime, queryRun.id, options.output);
@@ -58,11 +68,11 @@ export function queryCommand() {
         }
     }));
 }
-async function executeQuery(runtime, progress, sql) {
+async function executeQuery(runtime, progress, sql, variables) {
     try {
         renderRunningQuery(sql);
         progress.start(ui.bold("Submitting query"));
-        const executeResponse = await executeStudioQuery(runtime, sql);
+        const executeResponse = await executeStudioQuery(runtime, sql, variables);
         const queryRun = executeResponse.body.query_run;
         await waitForRetryAfter(executeResponse.retryAfterMs);
         return queryRun;
@@ -115,10 +125,10 @@ function renderRunningQuery(sql) {
 function renderPendingQueryStatus(queryRunId) {
     return `${ui.bold("Query running")} ${ui.dim(`(${queryRunId})`)}`;
 }
-async function executeStudioQuery(runtime, sql) {
+async function executeStudioQuery(runtime, sql, variables) {
     return request(runtime, "/studio.queryRuns.execute", {
         method: "POST",
-        body: { sql },
+        body: variables ? { sql, variables } : { sql },
     });
 }
 async function getStudioQueryRun(runtime, id) {
@@ -262,6 +272,24 @@ async function writeResponseBodyToFile(response, filename) {
         reader.releaseLock();
     }
 }
+function parseVariables(vars) {
+    if (vars.length === 0)
+        return undefined;
+    const result = {};
+    for (const v of vars) {
+        const eqIdx = v.indexOf("=");
+        if (eqIdx === -1) {
+            throw new CliError(`Invalid variable format: "${v}". Expected key=value.`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const key = v.slice(0, eqIdx);
+        const raw = v.slice(eqIdx + 1);
+        const parts = raw.includes(",") ? raw.split(",") : [raw];
+        const coerced = parts.map((p) => p !== "" && !isNaN(Number(p)) ? Number(p) : p);
+        result[key] =
+            coerced.length === 1 ? coerced[0] : coerced;
+    }
+    return result;
+}
 function buildFailedQueryError(error) {
     if (!error) {
         return new CliError("Query failed.", 1);

package/dist/logger.js

@@ -1,3 +1,4 @@
+import pc from "picocolors";
 const LOG_LEVELS = ["debug", "info", "warn", "error"];
 const LOG_LEVEL_PRIORITY = {
     debug: 10,
@@ -66,5 +67,17 @@ function writeLog(configuredLevel, options, level, message, fields) {
     const renderedFields = entry.fields && Object.keys(entry.fields).length > 0
         ? ` ${JSON.stringify(entry.fields)}`
         : "";
-    process.stderr.write(`${entry.time} ${entry.level.toUpperCase()} ${entry.message}${renderedFields}\n`);
+    process.stderr.write(`${pc.dim(entry.time)} ${colorizeLevel(entry.level)} ${entry.message}${pc.dim(renderedFields)}\n`);
+}
+function colorizeLevel(level) {
+    switch (level) {
+        case "debug":
+            return pc.blue("DEBUG");
+        case "info":
+            return pc.bold("INFO");
+        case "warn":
+            return pc.yellow("WARN");
+        case "error":
+            return pc.red("ERROR");
+    }
 }

package/dist/runtime.js

@@ -6,9 +6,9 @@ import cliPackage from "../package.json" with { type: "json" };
 export function buildLogger(context) {
     return createLogger({ json: context.json || !process.stderr.isTTY });
 }
-export function buildRuntime(context) {
-    const baseUrl = resolveBaseUrl();
-    const token = getToken(baseUrl);
+export function buildRuntime(context, overrides) {
+    const baseUrl = overrides?.baseUrl ?? resolveBaseUrl();
+    const token = overrides?.token ?? getToken(baseUrl);
     if (!token) {
         throw new CliError("No API token configured. Run `dx auth login --token <token>` or set DX_API_TOKEN.");
     }
@@ -20,3 +20,17 @@ export function buildRuntime(context) {
         logger: buildLogger(context),
     };
 }
+export function buildRuntimeSafe(context, overrides) {
+    const baseUrl = overrides?.baseUrl ?? resolveBaseUrl();
+    const token = overrides?.token ?? getToken(baseUrl);
+    if (!token) {
+        return null;
+    }
+    return {
+        baseUrl,
+        token,
+        context,
+        version: cliPackage.version,
+        logger: buildLogger(context),
+    };
+}

package/dist/secrets.js

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execaSync } from "execa";
 import { CliError } from "./errors.js";
 const SERVICE = "dx-cli";
 export function getToken(baseUrl) {
@@ -26,14 +26,21 @@ function macosSecretStore() {
     return {
         get(baseUrl) {
             try {
-                return execFileSync("security", ["find-generic-password", "-s", SERVICE, "-a", baseUrl, "-w"], { encoding: "utf8" }).trim();
+                return execaSync("security", [
+                    "find-generic-password",
+                    "-s",
+                    SERVICE,
+                    "-a",
+                    baseUrl,
+                    "-w",
+                ]).stdout.trim();
             }
             catch {
                 return null;
             }
         },
         set(baseUrl, token) {
-            execFileSync("security", [
+            execaSync("security", [
                 "add-generic-password",
                 "-U",
                 "-s",
@@ -46,7 +53,7 @@ function macosSecretStore() {
         },
         delete(baseUrl) {
             try {
-                execFileSync("security", [
+                execaSync("security", [
                     "delete-generic-password",
                     "-s",
                     SERVICE,
@@ -64,14 +71,20 @@ function linuxSecretStore() {
     return {
         get(baseUrl) {
             try {
-                return execFileSync("secret-tool", ["lookup", "service", SERVICE, "account", baseUrl], { encoding: "utf8" }).trim();
+                return execaSync("secret-tool", [
+                    "lookup",
+                    "service",
+                    SERVICE,
+                    "account",
+                    baseUrl,
+                ]).stdout.trim();
             }
             catch {
                 return null;
             }
         },
         set(baseUrl, token) {
-            execFileSync("secret-tool", ["store", "--label=dx-cli", "service", SERVICE, "account", baseUrl], { input: token });
+            execaSync("secret-tool", ["store", "--label=dx-cli", "service", SERVICE, "account", baseUrl], { input: token });
         },
         delete(_baseUrl) {
             throw new CliError("Linux token deletion is not supported by secret-tool in this implementation");

package/dist/ui/blocks.js

@@ -82,6 +82,16 @@ export class DescriptionListItemContainer extends AbstractBlock {
         this.options = options;
     }
 }
+export class CodeBlock extends AbstractBlock {
+    text;
+    constructor(text) {
+        super();
+        this.text = text;
+    }
+    render() {
+        return pc.cyan(this.text) + "\n";
+    }
+}
 export class JsonBlock extends AbstractBlock {
     value;
     constructor(value) {

package/dist/ui.js

@@ -2,7 +2,7 @@ import dayjs from "dayjs";
 import relativeTimePlugin from "dayjs/plugin/relativeTime.js";
 import pc from "picocolors";
 export { GLYPHS } from "./ui/glyphs.js";
-import { DescriptionListBlock, DescriptionListItemContainer, HeadingBlock, JsonBlock, ListItemContainer, ParagraphBlock, UnorderedListBlock, } from "./ui/blocks.js";
+import { DescriptionListBlock, DescriptionListItemContainer, HeadingBlock, JsonBlock, ListItemContainer, ParagraphBlock, UnorderedListBlock, CodeBlock, } from "./ui/blocks.js";
 dayjs.extend(relativeTimePlugin);
 // Block-level elements
 export function h1(text) {
@@ -49,9 +49,15 @@ export function dli(term, detailItems) {
         return new DescriptionListItemContainer(term, detailItems);
     }
 }
+export function codeBlock(text) {
+    return new CodeBlock(text);
+}
 export function json(value) {
     return new JsonBlock(value);
 }
+export function blankLine() {
+    return new ParagraphBlock("", false);
+}
 // Inline elements
 export function bold(text) {
     return pc.bold(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {
@@ -16,7 +16,7 @@
   "homepage": "https://github.com/get-dx/cli#readme",
   "license": "Apache-2.0",
   "engines": {
-    "node": "20.x"
+    "node": "^20.0.0 || ^22.0.0 || ^24.0.0"
   },
   "private": false,
   "publishConfig": {
@@ -38,8 +38,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.1",
     "commander": "^14.0.1",
     "dayjs": "^1.11.20",
+    "execa": "^9.6.1",
     "picocolors": "^1.1.1",
     "yaml": "^2.8.3"
   },