@get-dx/cli 0.1.7 → 0.2.1

package/dist/authCodeCallbackServer.js

@@ -0,0 +1,79 @@
+import { createServer } from "node:http";
+import { CliError } from "./errors.js";
+export class AuthCodeCallbackServer {
+    server = null;
+    address = null;
+    async start() {
+        await new Promise((resolve, reject) => {
+            const srv = createServer();
+            srv.on("error", reject);
+            srv.listen(0, "127.0.0.1", () => {
+                this.server = srv;
+                const { address, port } = srv.address();
+                this.address = `http://${address}:${port}`;
+                resolve();
+            });
+        });
+    }
+    getAddress() {
+        if (!this.address) {
+            throw new Error("Unreachable: server not started");
+        }
+        return this.address;
+    }
+    async listenForCode(onCodeReceipt) {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                reject(new Error("Unreachable: server not started"));
+                return;
+            }
+            this.server.on("request", async (req, res) => {
+                this.stop();
+                const url = new URL(req.url ?? "/", this.address);
+                const code = url.searchParams.get("code");
+                const state = url.searchParams.get("state");
+                if (!code) {
+                    const message = "Authentication failed: no code received";
+                    res.writeHead(500, { "Content-Type": "text/plain" }).end(message);
+                    resolve({ type: "ERROR", error: new CliError(message) });
+                    return;
+                }
+                let result;
+                try {
+                    result = await onCodeReceipt(state ?? "", code);
+                }
+                catch (err) {
+                    const message = err instanceof Error
+                        ? err.message
+                        : "Authentication failed: unknown error";
+                    res.writeHead(500, { "Content-Type": "text/plain" }).end(message);
+                    resolve({
+                        type: "ERROR",
+                        error: err instanceof Error ? err : new CliError(message),
+                    });
+                    return;
+                }
+                if (result.type === "SUCCESS") {
+                    if (result.redirectUri) {
+                        res.writeHead(302, { Location: result.redirectUri }).end();
+                    }
+                    else {
+                        res
+                            .writeHead(200, { "Content-Type": "text/plain" })
+                            .end("Authentication successful");
+                    }
+                }
+                else {
+                    res
+                        .writeHead(500, { "Content-Type": "text/plain" })
+                        .end(result.error.message);
+                }
+                resolve(result);
+            });
+        });
+    }
+    stop() {
+        this.server?.close();
+        this.server = null;
+    }
+}

package/dist/cli.js

@@ -5,6 +5,7 @@ import { initCommand } from "./commands/init.js";
 import { scorecardsCommand } from "./commands/scorecards.js";
 import { studioCommand } from "./commands/studio.js";
 import { teamsCommand } from "./commands/teams.js";
+import { workflowsCommand } from "./commands/workflows.js";
 import { handleError } from "./commandHelpers.js";
 import cliPackage from "../package.json" with { type: "json" };
 export async function run(argv = process.argv) {
@@ -35,6 +36,7 @@ function createProgram() {
     program.addCommand(scorecardsCommand());
     program.addCommand(studioCommand());
     program.addCommand(teamsCommand());
+    program.addCommand(workflowsCommand());
     applyExitOverride(program);
     return program;
 }

package/dist/commandHelpers.js

@@ -1,3 +1,4 @@
+import pc from "picocolors";
 import { CommanderError } from "commander";
 import { CliError, EXIT_CODES, HttpError } from "./errors.js";
 export function getContext(command) {
@@ -56,14 +57,14 @@ export function handleError(error, command, argv) {
     }
     else {
         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`);
+            process.stderr.write(pc.red(`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`);
+            process.stderr.write(pc.red(`${error instanceof Error ? error.message : String(error)}\n`));
         }
     }
     const exitCode = (() => {

package/dist/commands/auth.js

@@ -1,11 +1,13 @@
+import { password, select } from "@inquirer/prompts";
 import { Command } from "commander";
 import { deleteToken, setToken } from "../secrets.js";
 import { renderJson } from "../renderers.js";
 import { renderAuthInfo, renderLoggedOut } from "./authRendering.js";
-import { wrapAction } from "../commandHelpers.js";
-import { getContext } from "../commandHelpers.js";
-import { persistBaseUrl, resolveBaseUrl } from "../config.js";
+import { getContext, wrapAction } from "../commandHelpers.js";
+import { persistBaseUrl, resolveBaseUrl, resolveUiUrl } from "../config.js";
+import { CliError } from "../errors.js";
 import { request } from "../http.js";
+import { loginViaBrowser } from "../loginViaBrowser.js";
 import { buildLogger, buildRuntime } from "../runtime.js";
 import cliPackage from "../../package.json" with { type: "json" };
 import { maskToken } from "../ui.js";
@@ -15,25 +17,50 @@ export function authCommand() {
         .description("Manage DX authentication");
     auth
         .command("login")
-        .requiredOption("--token <token>", "Account web API token or personal access token")
+        .option("--token <token>", "Account web API token or personal access token. Omit this option to login interactively by web browser or pasting.")
         .action(wrapAction(async (commandOptions, command) => {
         const context = getContext(command);
         const baseUrl = resolveBaseUrl();
+        let token = commandOptions.token;
+        if (!token) {
+            if (!process.stdin.isTTY || !process.stderr.isTTY) {
+                throw new CliError("`dx auth login` without `--token` requires an interactive terminal; pass `--token` for non-interactive use");
+            }
+            const method = await select({
+                message: "How would you like to log in?",
+                choices: [
+                    { name: "Open browser", value: "browser" },
+                    { name: "Paste API token", value: "token" },
+                ],
+            });
+            if (method === "browser") {
+                token = await loginViaBrowser(resolveUiUrl(baseUrl));
+            }
+            else {
+                token = await password({
+                    message: "Paste your account web API token here:",
+                    mask: true,
+                });
+            }
+            if (!token) {
+                throw new CliError("Account web API token or personal access token is required");
+            }
+        }
         const runtime = {
             baseUrl,
-            token: commandOptions.token,
+            token,
             context,
             version: cliPackage.version,
             logger: buildLogger(context),
         };
         const response = await getAuthInfo(runtime);
         persistBaseUrl(baseUrl);
-        setToken(baseUrl, commandOptions.token);
+        setToken(baseUrl, token);
         if (context.json) {
             renderJson({ ...response, base_url: baseUrl });
             return;
         }
-        renderAuthInfo(response, commandOptions.token, baseUrl);
+        renderAuthInfo(response, token, baseUrl);
     }));
     auth.command("logout").action(wrapAction(async (_options, command) => {
         const context = getContext(command);

package/dist/commands/catalog/entities.js

@@ -21,6 +21,7 @@ export function entitiesCommand() {
         .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
         .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
         .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties.", (val, prev) => [...prev, val], [])
+        .option("--alias <kv>", "Set an alias value as key=value. Repeat for multiple aliases.", (val, prev) => [...prev, val], [])
         .addHelpText("afterAll", createExampleText([
         {
             label: "Create a new service entity",
@@ -38,6 +39,10 @@ export function entitiesCommand() {
             label: "Create with properties",
             command: 'dx catalog entities create --type service --identifier my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
         },
+        {
+            label: "Create with aliases",
+            command: "dx catalog entities create --type service --identifier my-service --alias github_repo=12345",
+        },
     ]))
         .action(wrapAction(async (options, command) => {
         if (!options.identifier) {
@@ -47,7 +52,7 @@ export function entitiesCommand() {
             throw new CliError("--type is required", EXIT_CODES.ARGUMENT_ERROR);
         }
         const runtime = buildRuntime(getContext(command));
-        const properties = await resolvePropertiesForEntityType(runtime, options.type, options.property);
+        const resolvedValues = await resolveValuesForEntityType(runtime, options.type, options.property, options.alias);
         const response = await createEntity(runtime, options.identifier, {
             type: options.type,
             name: options.name,
@@ -58,7 +63,7 @@ export function entitiesCommand() {
             owner_user_ids: options.ownerUserIds
                 ?.split(",")
                 .map((s) => s.trim()),
-            properties,
+            ...resolvedValues,
         });
         if (runtime.context.json) {
             renderJson(response);
@@ -100,6 +105,7 @@ export function entitiesCommand() {
         .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
         .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
         .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties. Use value null to remove a property.", (val, prev) => [...prev, val], [])
+        .option("--alias <kv>", "Set an alias value as key=value. Repeat for multiple aliases. Use value null to remove an alias.", (val, prev) => [...prev, val], [])
         .addHelpText("afterAll", createExampleText([
         {
             label: "Rename an entity",
@@ -113,13 +119,17 @@ export function entitiesCommand() {
             label: "Update properties",
             command: 'dx catalog entities update my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
         },
+        {
+            label: "Update aliases",
+            command: "dx catalog entities update my-service --alias github_repo=12345",
+        },
     ]))
         .action(wrapAction(async (identifier, options, command) => {
         const runtime = buildRuntime(getContext(command));
-        const properties = await resolvePropertiesForExistingEntity(runtime, identifier, options.property);
+        const resolvedValues = await resolveValuesForExistingEntity(runtime, identifier, options.property, options.alias);
         const response = await updateEntity(runtime, identifier, {
             ...getEntityMutationOptionValues(options),
-            properties,
+            ...resolvedValues,
         });
         if (runtime.context.json) {
             renderJson(response);
@@ -138,6 +148,7 @@ export function entitiesCommand() {
         .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
         .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
         .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties. Use value null to remove a property.", (val, prev) => [...prev, val], [])
+        .option("--alias <kv>", "Set an alias value as key=value. Repeat for multiple aliases. Use value null to remove an alias.", (val, prev) => [...prev, val], [])
         .addHelpText("afterAll", createExampleText([
         {
             label: "Create a new service entity if it does not exist",
@@ -151,6 +162,10 @@ export function entitiesCommand() {
             label: "Set properties while preserving omitted fields",
             command: 'dx catalog entities upsert --type service --identifier my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
         },
+        {
+            label: "Set aliases while preserving omitted fields",
+            command: "dx catalog entities upsert --type service --identifier my-service --alias github_repo=12345",
+        },
     ]))
         .action(wrapAction(async (options, command) => {
         if (!options.type) {
@@ -160,11 +175,11 @@ export function entitiesCommand() {
             throw new CliError("--identifier is required", EXIT_CODES.ARGUMENT_ERROR);
         }
         const runtime = buildRuntime(getContext(command));
-        const properties = await resolvePropertiesForEntityType(runtime, options.type, options.property);
+        const resolvedValues = await resolveValuesForEntityType(runtime, options.type, options.property, options.alias);
         const response = await upsertEntity(runtime, options.identifier, {
             type: options.type,
             ...getEntityMutationOptionValues(options),
-            properties,
+            ...resolvedValues,
         });
         if (runtime.context.json) {
             renderJson(response);
@@ -459,6 +474,33 @@ export function parsePropertyValue(prop, rawValue) {
             return rawValue;
     }
 }
+function parseEntityAliases(entityTypeIdentifier, rawAliases, knownAliases) {
+    const aliasKeys = Object.keys(knownAliases);
+    const aliasSet = new Set(aliasKeys);
+    const result = {};
+    for (const kv of rawAliases) {
+        const eqIndex = kv.indexOf("=");
+        if (eqIndex === -1) {
+            throw new CliError(`Invalid --alias "${kv}": expected format key=value`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const key = kv.slice(0, eqIndex);
+        const rawValue = kv.slice(eqIndex + 1);
+        if (!aliasSet.has(key)) {
+            const availableAliases = aliasKeys
+                .sort()
+                .map((k) => `\`${k}\``)
+                .join(", ");
+            const availableAliasesText = availableAliases.length > 0 ? availableAliases : "(none)";
+            throw new CliError(`Unknown alias \`${key}\` for entity type \`${entityTypeIdentifier}\`. Available aliases: ${availableAliasesText}`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (rawValue === "null") {
+            result[key] = [];
+            continue;
+        }
+        result[key] = [...(result[key] ?? []), { identifier: rawValue }];
+    }
+    return result;
+}
 // --- Include helpers ---
 const ENTITY_INCLUDE_SECTIONS = [
     "core",
@@ -487,22 +529,31 @@ function parseIncludeSections(include) {
     }
     return results;
 }
-async function resolvePropertiesForEntityType(runtime, entityTypeIdentifier, rawProperties) {
-    if (rawProperties.length === 0) {
-        return undefined;
+async function resolveValuesForEntityType(runtime, entityTypeIdentifier, rawProperties, rawAliases) {
+    if (rawProperties.length === 0 && rawAliases.length === 0) {
+        return {};
     }
     let entityTypeResponse;
     try {
         entityTypeResponse = await getEntityType(runtime, entityTypeIdentifier);
     }
     catch (err) {
-        throw wrapEntityTypeLookupError(entityTypeIdentifier, err);
+        throw wrapEntityTypeLookupError(entityTypeIdentifier, err, rawAliases.length > 0
+            ? "resolve property and alias values"
+            : "resolve property types");
+    }
+    const values = {};
+    if (rawProperties.length > 0) {
+        values.properties = parseEntityProperties(entityTypeIdentifier, rawProperties, entityTypeResponse.entity_type.properties);
     }
-    return parseEntityProperties(entityTypeIdentifier, rawProperties, entityTypeResponse.entity_type.properties);
+    if (rawAliases.length > 0) {
+        values.aliases = parseEntityAliases(entityTypeIdentifier, rawAliases, entityTypeResponse.entity_type.aliases);
+    }
+    return values;
 }
-async function resolvePropertiesForExistingEntity(runtime, identifier, rawProperties) {
-    if (rawProperties.length === 0) {
-        return undefined;
+async function resolveValuesForExistingEntity(runtime, identifier, rawProperties, rawAliases) {
+    if (rawProperties.length === 0 && rawAliases.length === 0) {
+        return {};
     }
     let entityResponse;
     try {
@@ -512,9 +563,23 @@ async function resolvePropertiesForExistingEntity(runtime, identifier, rawProper
         const exitCode = err instanceof HttpError && err.status !== undefined && err.status < 500
             ? EXIT_CODES.ARGUMENT_ERROR
             : EXIT_CODES.RETRY_RECOMMENDED;
-        throw new CliError(`Failed to fetch entity "${identifier}" to resolve property types: ${err instanceof Error ? err.message : String(err)}`, exitCode);
+        throw new CliError(`Failed to fetch entity "${identifier}" to resolve property and alias values: ${err instanceof Error ? err.message : String(err)}`, exitCode);
+    }
+    let entityTypeResponse;
+    try {
+        entityTypeResponse = await getEntityType(runtime, entityResponse.entity.type);
+    }
+    catch (err) {
+        throw wrapEntityTypeLookupError(entityResponse.entity.type, err, "resolve property and alias values");
+    }
+    const values = {};
+    if (rawProperties.length > 0) {
+        values.properties = parseEntityProperties(entityResponse.entity.type, rawProperties, entityTypeResponse.entity_type.properties);
+    }
+    if (rawAliases.length > 0) {
+        values.aliases = parseEntityAliases(entityResponse.entity.type, rawAliases, entityTypeResponse.entity_type.aliases);
     }
-    return resolvePropertiesForEntityType(runtime, entityResponse.entity.type, rawProperties);
+    return values;
 }
 function getEntityMutationOptionValues(options) {
     return {
@@ -549,13 +614,15 @@ function buildEntityMutationBody(identifier, params) {
         body.owner_user_ids = params.owner_user_ids;
     if (params.properties !== undefined)
         body.properties = params.properties;
+    if (params.aliases !== undefined)
+        body.aliases = params.aliases;
     return body;
 }
-function wrapEntityTypeLookupError(entityTypeIdentifier, err) {
+function wrapEntityTypeLookupError(entityTypeIdentifier, err, purpose = "resolve property types") {
     const exitCode = err instanceof HttpError && err.status !== undefined && err.status < 500
         ? EXIT_CODES.ARGUMENT_ERROR
         : EXIT_CODES.RETRY_RECOMMENDED;
-    return new CliError(`Failed to fetch entity type "${entityTypeIdentifier}" to resolve property types: ${err instanceof Error ? err.message : String(err)}`, exitCode);
+    return new CliError(`Failed to fetch entity type "${entityTypeIdentifier}" to ${purpose}: ${err instanceof Error ? err.message : String(err)}`, exitCode);
 }
 function uniqueSectionsInOrder(sections) {
     const seen = new Set();

package/dist/commands/catalog/entitiesRendering.js

@@ -238,6 +238,9 @@ function propertyValueContent(identifier, value) {
         const matchText = value.match_count === 1 ? "match" : "matches";
         return `File matching rule: ${ui.code(value.status)} (${value.match_count} ${matchText})`;
     }
+    else if (isOpenApiSpec(value)) {
+        return `OpenAPI spec`;
+    }
     else if (isUrl(value)) {
         return ui.link(value);
     }
@@ -284,3 +287,11 @@ function isFileMatchingRule(value) {
         typeof value.status === "string" &&
         ["FOUND_MATCHES", "NO_MATCHES", "FILE_NOT_FOUND"].includes(value.status));
 }
+function isOpenApiSpec(value) {
+    // TODO: consider switching to zod
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value === "object" &&
+        "info" in value &&
+        "paths" in value);
+}

package/dist/commands/init.js

@@ -1,12 +1,13 @@
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { input, password, confirm } from "@inquirer/prompts";
+import { input, password, confirm, select } 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 { loginViaBrowser } from "../loginViaBrowser.js";
 import { getContext } from "../commandHelpers.js";
 import { wrapAction } from "../commandHelpers.js";
 import { renderRichText } from "../renderers.js";
@@ -112,11 +113,24 @@ async function ensureLoggedIn(runtime, host) {
         }
     }
 }
-async function attemptLogin(apiBaseUrl, _uiBaseUrl) {
-    const token = await password({
-        message: "Paste your account web API token here:",
-        mask: true,
+async function attemptLogin(apiBaseUrl, uiBaseUrl) {
+    const method = await select({
+        message: "How would you like to log in?",
+        choices: [
+            { name: "Open browser", value: "browser" },
+            { name: "Paste API token", value: "token" },
+        ],
     });
+    let token;
+    if (method === "browser") {
+        token = await loginViaBrowser(uiBaseUrl);
+    }
+    else {
+        token = await password({
+            message: "Paste your account web API token here:",
+            mask: true,
+        });
+    }
     if (!token) {
         throw new CliError("Account web API token is required");
     }

package/dist/commands/scorecardsRendering.js

@@ -97,7 +97,7 @@ function entityFilterContent(scorecard) {
     else if (scorecard.entity_filter_type === "sql") {
         blocks.push(ui.p(`Filter: ${ui.code("sql")}`));
         if (scorecard.entity_filter_sql) {
-            blocks.push(truncatedSqlBlock(scorecard.entity_filter_sql));
+            blocks.push(ui.truncatedSqlBlock(scorecard.entity_filter_sql));
         }
         else {
             blocks.push(ui.p(ui.dim("(No SQL provided)")));
@@ -190,7 +190,7 @@ function checkContent(check, scorecardType) {
     }
     // Query
     blocks.push(ui.p(ui.bold("Query:")));
-    blocks.push(truncatedSqlBlock(check.sql));
+    blocks.push(ui.truncatedSqlBlock(check.sql));
     // Output settings
     if (check.output_enabled) {
         const outputParts = [`Output: ${ui.code(check.output_type ?? "unknown")}`];
@@ -202,18 +202,10 @@ function checkContent(check, scorecardType) {
     // Entity filter
     if (check.filter_sql) {
         blocks.push(ui.p(ui.bold("Entity filter:")));
-        blocks.push(truncatedSqlBlock(check.filter_sql));
+        blocks.push(ui.truncatedSqlBlock(check.filter_sql));
         if (check.filter_message) {
             blocks.push(ui.p(`Excluded message: ${ui.dim(check.filter_message)}`, false));
         }
     }
     return blocks;
 }
-function truncatedSqlBlock(sql) {
-    const lines = sql.split("\n");
-    const firstLine = lines[0];
-    const isLong = firstLine.length > 80 || lines.length > 1;
-    const truncated = firstLine.length > 80 ? firstLine.slice(0, 80) : firstLine;
-    const display = isLong ? truncated + ui.dim(" …") : truncated;
-    return ui.p(ui.code(display));
-}

package/dist/commands/studio/query.js

@@ -5,10 +5,10 @@ import { Command } from "commander";
 import { createExampleText, getContext, wrapAction, } from "../../commandHelpers.js";
 import { CliError, EXIT_CODES, HttpError } from "../../errors.js";
 import { request } from "../../http.js";
-import { renderJson } from "../../renderers.js";
+import { AsyncProgressReporter, renderJson, renderRichText, } from "../../renderers.js";
 import { buildRuntime } from "../../runtime.js";
 import * as ui from "../../ui.js";
-import { QueryProgressReporter, renderCsvSaved, renderQueryResultsTable, } from "./queryRendering.js";
+import { renderCsvSaved, renderQueryResultsTable } from "./queryRendering.js";
 const DEFAULT_RETRY_AFTER_MS = 1000;
 const PENDING_QUERY_RUN_STATUSES = new Set([
     "queued",
@@ -51,7 +51,7 @@ export function queryCommand() {
         }
         const variables = parseVariables(options.variable);
         const runtime = buildRuntime(context);
-        const progress = new QueryProgressReporter();
+        const progress = new AsyncProgressReporter();
         const queryRun = await executeQuery(runtime, progress, sql, variables);
         await waitForQuery(runtime, progress, queryRun.id);
         if (options.output) {
@@ -70,7 +70,9 @@ export function queryCommand() {
 }
 async function executeQuery(runtime, progress, sql, variables) {
     try {
-        renderRunningQuery(sql);
+        renderRichText([ui.p(`${ui.bold("Running:")} ${ui.code(sql)}`)], {
+            useStderr: true,
+        });
         progress.start(ui.bold("Submitting query"));
         const executeResponse = await executeStudioQuery(runtime, sql, variables);
         const queryRun = executeResponse.body.query_run;
@@ -119,9 +121,6 @@ async function waitForQuery(runtime, progress, queryRunId) {
         }
     }
 }
-function renderRunningQuery(sql) {
-    process.stderr.write(`${ui.bold("Running:")} ${ui.code(sql)}\n`);
-}
 function renderPendingQueryStatus(queryRunId) {
     return `${ui.bold("Query running")} ${ui.dim(`(${queryRunId})`)}`;
 }

package/dist/commands/studio/queryRendering.js

@@ -1,4 +1,3 @@
-import { clearLine, cursorTo } from "node:readline";
 import { renderRichText } from "../../renderers.js";
 import * as ui from "../../ui.js";
 export function renderQueryResultsTable(results) {
@@ -7,65 +6,6 @@ export function renderQueryResultsTable(results) {
 export function renderCsvSaved(filename) {
     renderRichText([ui.p(`Saved CSV results to ${ui.code(filename)}.`)]);
 }
-export class QueryProgressReporter {
-    enabled = Boolean(process.stderr.isTTY);
-    frames = [
-        "⠋",
-        "⠙",
-        "⠹",
-        "⠸",
-        "⠼",
-        "⠴",
-        "⠦",
-        "⠧",
-        "⠇",
-        "⠏",
-    ].map((frame) => ui.dim(frame));
-    timer;
-    frameIndex = 0;
-    currentMessage = "";
-    start(message) {
-        if (!this.enabled) {
-            return;
-        }
-        this.currentMessage = message;
-        this.render();
-        this.timer = setInterval(() => this.render(), 80);
-        this.timer.unref?.();
-    }
-    update(message) {
-        if (!this.enabled) {
-            return;
-        }
-        this.currentMessage = message;
-        this.render();
-    }
-    stop(finalMessage) {
-        if (!this.enabled) {
-            return;
-        }
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
-        if (finalMessage) {
-            this.clearCurrentLine();
-            process.stderr.write(`${finalMessage}\n`);
-            return;
-        }
-        this.clearCurrentLine();
-    }
-    render() {
-        const frame = this.frames[this.frameIndex % this.frames.length];
-        this.frameIndex += 1;
-        this.clearCurrentLine();
-        process.stderr.write(`${frame} ${this.currentMessage}`);
-    }
-    clearCurrentLine() {
-        clearLine(process.stderr, 0);
-        cursorTo(process.stderr, 0);
-    }
-}
 function formatAsciiTable(columns, rows) {
     if (columns.length === 0) {
         return "(Query returned no columns)";

package/dist/commands/workflows.js

@@ -0,0 +1,82 @@
+import { Command } from "commander";
+import { createExampleText, getContext, wrapAction, } from "../commandHelpers.js";
+import { CliError, EXIT_CODES } from "../errors.js";
+import { request } from "../http.js";
+import { renderJson } from "../renderers.js";
+import { buildRuntime } from "../runtime.js";
+import { renderWorkflowList } from "./workflowsRendering.js";
+const WORKFLOW_SCOPES = ["GLOBAL", "ENTITY"];
+export function workflowsCommand() {
+    const workflows = new Command()
+        .name("workflows")
+        .description("Manage Self-service workflow definitions");
+    workflows
+        .command("list")
+        .description("List Self-service workflows for the account")
+        .option("--scope <scope>", "Filter by workflow scope: GLOBAL or ENTITY (omit for both)")
+        .option("--entity-identifier <id>", "Catalog entity identifier; must be used with --scope ENTITY")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List workflows the token can trigger",
+            command: "dx workflows list",
+        },
+        {
+            label: "Entity-scoped workflows for a catalog entity",
+            command: "dx workflows list --scope ENTITY --entity-identifier acme-app",
+        },
+        {
+            label: "Same request as JSON",
+            command: "dx --json workflows list --scope ENTITY --entity-identifier acme-app",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const scope = parseOptionalScope(options.scope);
+        const entityIdentifier = parseOptionalTrimmed(options.entityIdentifier);
+        if (entityIdentifier && scope !== "ENTITY") {
+            throw new CliError("--entity-identifier requires --scope ENTITY", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(getContext(command));
+        const response = await listWorkflows(runtime, {
+            scope,
+            entity_identifier: entityIdentifier,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderWorkflowList(response.workflows);
+        }
+    }));
+    return workflows;
+}
+function parseOptionalTrimmed(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const t = value.trim();
+    return t.length > 0 ? t : undefined;
+}
+function parseOptionalScope(value) {
+    const raw = parseOptionalTrimmed(value);
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!WORKFLOW_SCOPES.includes(raw)) {
+        throw new CliError(`--scope must be one of: ${WORKFLOW_SCOPES.join(", ")}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return raw;
+}
+// --- API ---
+async function listWorkflows(runtime, params) {
+    const query = {};
+    if (params.scope !== undefined)
+        query.scope = params.scope;
+    if (params.entity_identifier !== undefined) {
+        query.entity_identifier = params.entity_identifier;
+    }
+    const response = await request(runtime, "/workflows.list", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}

package/dist/commands/workflowsRendering.js

@@ -0,0 +1,136 @@
+import { renderRichText } from "../renderers.js";
+import * as ui from "../ui.js";
+const WORKFLOW_SCOPE_LABELS = {
+    GLOBAL: "Global",
+    ENTITY: "Catalog entity",
+};
+const WORKFLOW_EXECUTION_TYPE_LABELS = {
+    SIMPLE: "Simple",
+    EVENT_DRIVEN: "Event-driven",
+};
+const WORKFLOW_TRIGGER_TYPE_LABELS = {
+    ANY: "All users",
+    APPROVAL: "All users with approval",
+    RUNNERS: "Selected teams and users",
+    ENTITY: "Entity owners only",
+};
+const WORKFLOW_TRIGGER_TYPE_DESCRIPTIONS = {
+    ANY: "All users can trigger this workflow run without approval.",
+    APPROVAL: "All users can request a workflow run, but a designated approver must accept before it runs.",
+    RUNNERS: "Only selected teams or users can trigger a workflow run.",
+    ENTITY: "Only users who directly own the entity, or belong to an owning team, can trigger a run.",
+};
+function workflowScopeLabel(scope) {
+    return WORKFLOW_SCOPE_LABELS[scope] ?? scope;
+}
+function workflowExecutionTypeLabel(executionType) {
+    return WORKFLOW_EXECUTION_TYPE_LABELS[executionType] ?? executionType;
+}
+function workflowTriggerTypeLabel(triggerType) {
+    return WORKFLOW_TRIGGER_TYPE_LABELS[triggerType] ?? triggerType;
+}
+function workflowTriggerTypeDescription(triggerType) {
+    return WORKFLOW_TRIGGER_TYPE_DESCRIPTIONS[triggerType] ?? "";
+}
+export function renderWorkflowList(workflows) {
+    const blocks = [
+        ui.h1("Workflows"),
+        ui.p(`Displaying ${ui.bold(workflows.length.toString())} workflows.`),
+    ];
+    for (const workflow of workflows) {
+        blocks.push(ui.h2(`${workflow.name} (${ui.code(workflow.identifier)})`));
+        blocks.push(ui.h3("Core attributes"));
+        blocks.push(...coreContent(workflow));
+        if (workflow.scope === "ENTITY") {
+            blocks.push(ui.h3("Entity filter"));
+            blocks.push(...entityFilterContent(workflow));
+        }
+        blocks.push(ui.h3("Parameters"));
+        blocks.push(...parametersContent(workflow));
+    }
+    renderRichText(blocks);
+}
+function coreContent(workflow) {
+    const blocks = [];
+    const description = workflow.description?.trim()
+        ? workflow.description
+        : ui.dim("(None)");
+    blocks.push(ui.dl([
+        ui.dli("Description", description),
+        ui.dli("Scope", workflowScopeLabel(workflow.scope)),
+        ui.dli("Execution type", workflowExecutionTypeLabel(workflow.execution_type)),
+        ui.dli("Who can run", `${workflowTriggerTypeLabel(workflow.trigger_type)}  ${ui.dim(workflowTriggerTypeDescription(workflow.trigger_type))}`),
+    ], { termWidth: 16 }));
+    return blocks;
+}
+function entityFilterContent(workflow) {
+    const blocks = [];
+    if (workflow.entity_filter_type === "ENTITY_TYPES") {
+        blocks.push(ui.p(`Filter type: ${ui.code("Entity types")}`));
+        if (workflow.entity_filter_type_identifiers &&
+            workflow.entity_filter_type_identifiers.length > 0) {
+            blocks.push(ui.ul(workflow.entity_filter_type_identifiers.map((identifier) => ui.li([ui.p(ui.code(identifier), false)]))));
+        }
+    }
+    else if (workflow.entity_filter_type === "SQL") {
+        blocks.push(ui.p(`Filter type: ${ui.code("SQL")}`));
+        if (workflow.entity_filter_sql) {
+            blocks.push(ui.truncatedSqlBlock(workflow.entity_filter_sql));
+        }
+    }
+    return blocks;
+}
+function parametersContent(workflow) {
+    if (workflow.parameters.length === 0) {
+        return [ui.p(ui.dim("(No parameters)"))];
+    }
+    return [
+        ui.ul(workflow.parameters.map((parameter) => ui.li(singleParameterContent(parameter)))),
+    ];
+}
+function singleParameterContent(parameter) {
+    const requiredPart = parameter.is_required ? `  ${ui.dim("required")}` : "";
+    const headline = `${ui.bold(parameter.name)} (${ui.code(parameter.identifier)})  ${ui.code(parameter.type)}${requiredPart}`;
+    const blocks = [ui.p(headline, false)];
+    const desc = parameter.description?.trim();
+    if (desc) {
+        blocks.push(ui.p(desc, false));
+    }
+    if (parameter.default_value !== null &&
+        parameter.default_value !== undefined &&
+        parameter.default_value !== "") {
+        blocks.push(ui.p(`Default: ${ui.code(formatParameterDefault(parameter.default_value))}`, false));
+    }
+    if (parameter.type === "SELECT") {
+        const options = selectParameterOptions(parameter.definition);
+        if (options.length > 0) {
+            blocks.push(ui.p("Options:", false));
+            blocks.push(ui.ul(options.map((value) => ui.li([ui.p(ui.code(value), false)]))));
+        }
+    }
+    return blocks;
+}
+function selectParameterOptions(definition) {
+    if (!definition || typeof definition !== "object") {
+        return [];
+    }
+    const raw = definition.options;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((item) => typeof item === "string");
+}
+function formatParameterDefault(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/config.js

@@ -30,6 +30,23 @@ export function resolveBaseUrl() {
     }
     return normalizeBaseUrl(readConfig().baseUrl || DEFAULT_BASE_URL);
 }
+/**
+ * Web UI origin for browser OAuth (`/cli/auth`), inferred from the API base URL.
+ * Dedicated and cloud hostnames map to their app origins; otherwise the API URL origin is used.
+ */
+export function resolveUiUrl(apiBaseUrl) {
+    const normalized = normalizeBaseUrl(apiBaseUrl);
+    const url = new URL(normalized);
+    const host = url.hostname;
+    if (host === "api.getdx.com") {
+        return "https://app.getdx.com";
+    }
+    const dedicated = host.match(/^api\.(.+)\.getdx\.io$/);
+    if (dedicated) {
+        return `https://${dedicated[1]}.getdx.io`;
+    }
+    return url.origin;
+}
 export function persistBaseUrl(baseUrl) {
     writeConfig({ ...readConfig(), baseUrl: normalizeBaseUrl(baseUrl) });
 }

package/dist/loginViaBrowser.js

@@ -0,0 +1,86 @@
+import { createHash, randomBytes } from "node:crypto";
+import open from "open";
+import { AuthCodeCallbackServer, } from "./authCodeCallbackServer.js";
+import { CliError } from "./errors.js";
+import { renderRichText } from "./renderers.js";
+import * as ui from "./ui.js";
+export async function loginViaBrowser(uiBaseUrl) {
+    const server = new AuthCodeCallbackServer();
+    await server.start();
+    const callbackUri = server.getAddress();
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    const params = new URLSearchParams({
+        callback_uri: callbackUri,
+        state,
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+    });
+    const authUrl = `${uiBaseUrl}/cli/auth?${params.toString()}`;
+    renderRichText([
+        ui.p(`Opening your browser to complete authentication...`),
+        ui.blankLine(),
+    ]);
+    try {
+        await open(authUrl);
+    }
+    catch {
+        renderRichText([
+            ui.p(`Failed to open browser automatically. Visit this URL to continue:`),
+            ui.blankLine(),
+            ui.codeBlock(authUrl),
+            ui.blankLine(),
+        ]);
+    }
+    renderRichText([ui.p(`Waiting for authentication in your browser...`)]);
+    const handleCodeReceipt = async (stateFromResponse, code) => {
+        const valid = validateState(stateFromResponse, state);
+        if (!valid) {
+            return {
+                type: "ERROR",
+                error: new CliError("Authentication failed: state mismatch"),
+            };
+        }
+        const tokenExchangeResponse = await exchangeCodeForToken(uiBaseUrl, code, codeVerifier);
+        if (!tokenExchangeResponse.ok) {
+            return {
+                type: "ERROR",
+                error: new CliError(`Authentication failed: token exchange failed with status ${tokenExchangeResponse.status}`),
+            };
+        }
+        const body = (await tokenExchangeResponse.json());
+        return {
+            type: "SUCCESS",
+            token: body.access_token,
+            redirectUri: body.redirect_uri,
+        };
+    };
+    const serverResult = await server.listenForCode(handleCodeReceipt);
+    if (serverResult.type === "ERROR")
+        throw serverResult.error;
+    return serverResult.token;
+}
+function validateState(stateFromResponse, originalState) {
+    return stateFromResponse === originalState;
+}
+async function exchangeCodeForToken(baseUrl, code, codeVerifier) {
+    return fetch(`${baseUrl}/cli/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ code, code_verifier: codeVerifier }),
+    });
+}
+// RFC 8252 §8.9: random string used to prevent CSRF-style attacks
+function generateState() {
+    return randomBytes(16).toString("base64url");
+}
+// RFC 7636 §4.1 — 32 random bytes base64url-encoded = 43 unreserved chars
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+// RFC 7636 §4.2 — SHA256 hex digest, base64-encoded without padding
+function generateCodeChallenge(codeVerifier) {
+    const hexDigest = createHash("sha256").update(codeVerifier).digest("hex");
+    return Buffer.from(hexDigest).toString("base64").replace(/=/g, "");
+}

package/dist/renderers.js

@@ -1,3 +1,5 @@
+import { clearLine, cursorTo } from "node:readline";
+import { dim } from "./ui.js";
 /**
  * Render an object in plain JSON formatting.
  *
@@ -11,7 +13,7 @@ export function renderJson(value) {
  *
  * Should be used when the `--flag` is NOT present.
  */
-export function renderRichText(blocks) {
+export function renderRichText(blocks, options) {
     const normalizedBlocks = blocks
         .filter((block) => block !== null)
         .flatMap((block) => {
@@ -25,5 +27,78 @@ export function renderRichText(blocks) {
         const blockContent = block.render();
         renderedBlocks.push(blockContent);
     }
-    process.stdout.write(renderedBlocks.join("\n"));
+    if (options?.useStderr) {
+        process.stderr.write(renderedBlocks.join("\n"));
+    }
+    else {
+        process.stdout.write(renderedBlocks.join("\n"));
+    }
+}
+/**
+ * Renders a TTY spinner and status on stderr for long-running async work. Does not
+ * use `renderRichText` because stdout is reserved for command results; stderr keeps
+ * auxiliary output separate from the primary stream.
+ */
+export class AsyncProgressReporter {
+    enabled = Boolean(process.stderr.isTTY);
+    intervalMs;
+    frames = [
+        "⠋",
+        "⠙",
+        "⠹",
+        "⠸",
+        "⠼",
+        "⠴",
+        "⠦",
+        "⠧",
+        "⠇",
+        "⠏",
+    ].map((frame) => dim(frame));
+    timer;
+    frameIndex = 0;
+    currentMessage = "";
+    constructor(options) {
+        this.intervalMs = options?.intervalMs ?? 80;
+    }
+    start(message) {
+        if (!this.enabled) {
+            return;
+        }
+        this.currentMessage = message;
+        this.render();
+        this.timer = setInterval(() => this.render(), this.intervalMs);
+        this.timer.unref?.();
+    }
+    update(message) {
+        if (!this.enabled) {
+            return;
+        }
+        this.currentMessage = message;
+        this.render();
+    }
+    stop(finalMessage) {
+        if (!this.enabled) {
+            return;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (finalMessage) {
+            this.clearCurrentLine();
+            process.stderr.write(`${finalMessage}\n`);
+            return;
+        }
+        this.clearCurrentLine();
+    }
+    render() {
+        const frame = this.frames[this.frameIndex % this.frames.length];
+        this.frameIndex += 1;
+        this.clearCurrentLine();
+        process.stderr.write(`${frame} ${this.currentMessage}`);
+    }
+    clearCurrentLine() {
+        clearLine(process.stderr, 0);
+        cursorTo(process.stderr, 0);
+    }
 }

package/dist/ui.js

@@ -58,6 +58,14 @@ export function json(value) {
 export function blankLine() {
     return new ParagraphBlock("", false);
 }
+export function truncatedSqlBlock(sql) {
+    const lines = sql.split("\n");
+    const firstLine = lines[0];
+    const isLong = firstLine.length > 80 || lines.length > 1;
+    const truncated = firstLine.length > 80 ? firstLine.slice(0, 80) : firstLine;
+    const display = isLong ? truncated + dim(" …") : truncated;
+    return p(code(display));
+}
 // Inline elements
 export function bold(text) {
     return pc.bold(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {
@@ -42,6 +42,7 @@
     "commander": "^14.0.1",
     "dayjs": "^1.11.20",
     "execa": "^9.6.1",
+    "open": "^11.0.0",
     "picocolors": "^1.1.1",
     "yaml": "^2.8.3"
   },