@get-dx/cli 0.2.1 → 0.3.0

package/README.md

@@ -18,31 +18,44 @@ Interactively login and install the AI agent skill:
 dx init
 ```
 
-The CLI uses `app.getdx.com` as the hostname and `api.getdx.com` as the api base url by default.
+Show help text:
+
+```shell
+dx --help
+dx <subcommand> --help
+```
+
+### Customizing base URLs
 
-### Dedicated or managed deployments
+The CLI requires two base URLs to be configured. The default values are used for DX **cloud** deployments. Users of **dedicated** and **managed** deployments will need to specify these values explicitly when logging in.
 
-If your organization is on a dedicated or managed DX deployment, pass your custom hostname at init time:
+| Value            | How it is used                               | Env var           | Default value           |
+| ---------------- | -------------------------------------------- | ----------------- | ----------------------- |
+| **Web base URL** | Browser-based login and displaying web links | `DX_WEB_BASE_URL` | `https://app.getdx.com` |
+| **API base URL** | Making each API request to DX                | `DX_API_BASE_URL` | `https://api.getdx.com` |
+
+#### For dedicated deployments
+
+Set the env vars once when initializing:
 
 ```shell
-# Flag (dedicated instance at mycompany.getdx.io)
-dx init --host mycompany.getdx.io
+# Interactive login
+DX_WEB_BASE_URL="https://mycompany.getdx.io" DX_API_BASE_URL="https://api.mycompany.getdx.io" dx init
 
-# Env var — useful for CI or scripted setups
-DX_HOST=mycompany.getdx.io dx init
+# Non-interactive login for CI or remote agents
+DX_WEB_BASE_URL="https://mycompany.getdx.io" DX_API_BASE_URL="https://api.mycompany.getdx.io" dx auth login --token $DX_TOKEN
 ```
 
-The `DX_HOST` and `--host` values accept:
+#### For managed deployments
 
-- `app.getdx.com` — DX Cloud (default)
-- `<account>.getdx.io` — DX dedicated (derives `https://api.<account>.getdx.io` automatically)
-- Any custom domain — you will be prompted for the separate API base URL
-
-Show help text:
+Set the env vars once when initializing:
 
 ```shell
-dx --help
-dx <subcommand> --help
+# Interactive login
+DX_WEB_BASE_URL="https://dx.some-example-subdomain.example.com" DX_API_BASE_URL="https://api.dx.some-example-subdomain.example.com" dx init
+
+# Non-interactive login for CI or remote agents
+DX_WEB_BASE_URL="https://dx.some-example-subdomain.example.com" DX_API_BASE_URL="https://api.dx.some-example-subdomain.example.com" dx auth login --token $DX_TOKEN
 ```
 
 ## Logging

package/dist/cli.js

@@ -8,8 +8,10 @@ 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" };
+import { handleTemporaryBaseUrlMigration } from "./config.js";
 export async function run(argv = process.argv) {
     try {
+        handleTemporaryBaseUrlMigration(argv);
         const program = createProgram();
         if (argv.length <= 2) {
             program.outputHelp();

package/dist/commands/auth.js

@@ -4,12 +4,11 @@ import { deleteToken, setToken } from "../secrets.js";
 import { renderJson } from "../renderers.js";
 import { renderAuthInfo, renderLoggedOut } from "./authRendering.js";
 import { getContext, wrapAction } from "../commandHelpers.js";
-import { persistBaseUrl, resolveBaseUrl, resolveUiUrl } from "../config.js";
+import { persistBaseUrls, resolveApiBaseUrl, deriveBaseUrlsFromEnv, } 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 { buildRuntime } from "../runtime.js";
 import { maskToken } from "../ui.js";
 export function authCommand() {
     const auth = new Command()
@@ -20,7 +19,7 @@ export function authCommand() {
         .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();
+        const { apiBaseUrl, webBaseUrl } = deriveBaseUrlsFromEnv();
         let token = commandOptions.token;
         if (!token) {
             if (!process.stdin.isTTY || !process.stderr.isTTY) {
@@ -34,7 +33,7 @@ export function authCommand() {
                 ],
             });
             if (method === "browser") {
-                token = await loginViaBrowser(resolveUiUrl(baseUrl));
+                token = await loginViaBrowser(webBaseUrl);
             }
             else {
                 token = await password({
@@ -46,45 +45,51 @@ export function authCommand() {
                 throw new CliError("Account web API token or personal access token is required");
             }
         }
-        const runtime = {
-            baseUrl,
+        const runtime = buildRuntime(context, {
+            apiBaseUrl,
             token,
-            context,
-            version: cliPackage.version,
-            logger: buildLogger(context),
-        };
+            webBaseUrl,
+        });
         const response = await getAuthInfo(runtime);
-        persistBaseUrl(baseUrl);
-        setToken(baseUrl, token);
+        persistBaseUrls(apiBaseUrl, webBaseUrl);
+        setToken(apiBaseUrl, token);
         if (context.json) {
-            renderJson({ ...response, base_url: baseUrl });
+            renderJson({
+                ...response,
+                api_base_url: apiBaseUrl,
+                web_base_url: webBaseUrl,
+            });
             return;
         }
-        renderAuthInfo(response, token, baseUrl);
+        renderAuthInfo(response, token, apiBaseUrl);
     }));
     auth.command("logout").action(wrapAction(async (_options, command) => {
         const context = getContext(command);
-        const baseUrl = resolveBaseUrl();
-        deleteToken(baseUrl);
+        const apiBaseUrl = resolveApiBaseUrl();
+        deleteToken(apiBaseUrl);
         if (context.json) {
-            renderJson({ ok: true, base_url: baseUrl, logged_out: true });
+            renderJson({ ok: true, api_base_url: apiBaseUrl, logged_out: true });
         }
         else {
-            renderLoggedOut(baseUrl);
+            renderLoggedOut(apiBaseUrl);
         }
     }));
-    auth.command("status").action(wrapAction(async (_options, command) => {
+    auth
+        .command("status")
+        .alias("info")
+        .action(wrapAction(async (_options, command) => {
         const runtime = buildRuntime(getContext(command));
         const response = await getAuthInfo(runtime);
         if (runtime.context.json) {
             renderJson({
                 ...response,
                 token: maskToken(runtime.token),
-                base_url: runtime.baseUrl,
+                api_base_url: runtime.apiBaseUrl,
+                web_base_url: runtime.webBaseUrl,
             });
         }
         else {
-            renderAuthInfo(response, runtime.token, runtime.baseUrl);
+            renderAuthInfo(response, runtime.token, runtime.apiBaseUrl);
         }
     }));
     return auth;

package/dist/commands/catalog/entities.js

@@ -69,7 +69,7 @@ export function entitiesCommand() {
             renderJson(response);
         }
         else {
-            renderEntity(response.entity);
+            renderEntity(response.entity, runtime);
         }
     }));
     entities
@@ -135,7 +135,7 @@ export function entitiesCommand() {
             renderJson(response);
         }
         else {
-            renderEntity(response.entity, `${ui.success(ui.GLYPHS.CHECK)} Entity updated`);
+            renderEntity(response.entity, runtime, `${ui.success(ui.GLYPHS.CHECK)} Entity updated`);
         }
     }));
     entities
@@ -188,7 +188,7 @@ export function entitiesCommand() {
             const title = response.result === "created_new_entity"
                 ? `${ui.success(ui.GLYPHS.CHECK)} Created new entity`
                 : `${ui.success(ui.GLYPHS.CHECK)} Updated existing entity`;
-            renderEntity(response.entity, title);
+            renderEntity(response.entity, runtime, title);
         }
     }));
     entities
@@ -217,7 +217,7 @@ export function entitiesCommand() {
             renderJson(processedResponse);
         }
         else {
-            renderEntity(processedResponse.entity);
+            renderEntity(processedResponse.entity, runtime);
         }
     }));
     entities
@@ -260,7 +260,7 @@ export function entitiesCommand() {
             renderJson({ ...response, entities: processedEntities });
         }
         else {
-            renderEntityList(processedEntities, response.response_metadata?.next_cursor ?? null);
+            renderEntityList(processedEntities, response.response_metadata?.next_cursor ?? null, runtime);
         }
     }));
     entities
@@ -326,7 +326,7 @@ export function entitiesCommand() {
             renderJson(response);
         }
         else {
-            renderEntityScorecardList(response.scorecards, response.response_metadata?.next_cursor ?? null);
+            renderEntityScorecardList(response.scorecards, identifier, runtime, response.response_metadata?.next_cursor ?? null);
         }
     }));
     return entities;

package/dist/commands/catalog/entitiesRendering.js

@@ -1,7 +1,7 @@
 import dayjs from "dayjs";
 import { renderRichText } from "../../renderers.js";
 import * as ui from "../../ui.js";
-export function renderEntityList(entities, nextCursor) {
+export function renderEntityList(entities, nextCursor, runtime) {
     const blocks = [ui.h1("Entities")];
     blocks.push(ui.p(`Displaying ${ui.bold(entities.length.toString())} entities.`));
     if (nextCursor) {
@@ -19,7 +19,7 @@ export function renderEntityList(entities, nextCursor) {
         }
         if (entity.identifier) {
             blocks.push(ui.h3("Core attributes"));
-            blocks.push(...coreContent(entity));
+            blocks.push(...coreContent(entity, runtime));
         }
         if (entity.owner_teams || entity.owner_users) {
             blocks.push(ui.h3("Owners"));
@@ -36,11 +36,11 @@ export function renderEntityList(entities, nextCursor) {
     }
     renderRichText(blocks);
 }
-export function renderEntity(entity, title = "Entity Information") {
+export function renderEntity(entity, runtime, title = "Entity Information") {
     renderRichText([
         ui.h1(title),
         entity.identifier
-            ? [ui.h2("Core attributes"), ...coreContent(entity)]
+            ? [ui.h2("Core attributes"), ...coreContent(entity, runtime)]
             : null,
         entity.owner_teams ? [ui.h2("Owners"), ...ownersContent(entity)] : null,
         entity.properties
@@ -55,7 +55,7 @@ export function renderEntityDeleted(entity) {
         ui.p(`The entity ${ui.code(entity.identifier)} has been deleted.`),
     ]);
 }
-export function renderEntityScorecardList(scorecards, nextCursor) {
+export function renderEntityScorecardList(scorecards, entityIdentifier, runtime, nextCursor) {
     const blocks = [ui.h1("Scorecards")];
     blocks.push(ui.p(`Displaying ${ui.bold(scorecards.length.toString())} scorecards.`));
     if (nextCursor) {
@@ -63,7 +63,7 @@ export function renderEntityScorecardList(scorecards, nextCursor) {
     }
     for (const scorecard of scorecards) {
         blocks.push(ui.h2(scorecard.name));
-        blocks.push(...scorecardReportContent(scorecard));
+        blocks.push(...scorecardReportContent(scorecard, entityIdentifier, runtime));
     }
     renderRichText(blocks);
 }
@@ -79,8 +79,9 @@ export function renderEntityTaskList(tasks, nextCursor) {
     }
     renderRichText(blocks);
 }
-function scorecardReportContent(scorecard) {
+function scorecardReportContent(scorecard, entityIdentifier, runtime) {
     const blocks = [];
+    blocks.push(ui.p(ui.link(ui.webLink(`/catalog/${entityIdentifier}/scorecards?expanded=${scorecard.id}`, runtime))));
     if (scorecard.type === "POINTS") {
         const total = scorecard.points_meta?.points_total ?? 0;
         const achieved = scorecard.points_meta?.points_achieved ?? 0;
@@ -179,7 +180,7 @@ function dueDateText(completeBy) {
         return formattedDate;
     }
 }
-function coreContent(entity) {
+function coreContent(entity, runtime) {
     return [
         ui.dl([
             ui.dli("Name", [ui.p(entity.name ?? ui.dim("(None)"), false)]),
@@ -188,7 +189,10 @@ function coreContent(entity) {
             ui.dli("Created", [
                 ui.p(ui.timestampSummary(entity.created_at), false),
             ]),
-            ui.dli("Last updated", [ui.p(ui.timestampSummary(entity.updated_at))]),
+            ui.dli("Last updated", ui.timestampSummary(entity.updated_at)),
+            ui.dli("Web link", [
+                ui.p(ui.link(ui.webLink(`/catalog/${entity.identifier}`, runtime))),
+            ]),
             ui.dli("Description", [
                 ui.p(entity.description ?? ui.dim("(None)"), false),
             ]),

package/dist/commands/catalog/entityTypes.js

@@ -53,7 +53,7 @@ export function entityTypesCommand() {
             renderJson({ ok: true, entity_type: response.entity_type });
         }
         else {
-            renderEntityType(response.entity_type, `${ui.success(ui.GLYPHS.CHECK)} Entity type created`);
+            renderEntityType(response.entity_type, runtime, `${ui.success(ui.GLYPHS.CHECK)} Entity type created`);
         }
     }));
     entityTypes
@@ -106,7 +106,7 @@ export function entityTypesCommand() {
             renderJson(processedEntityType);
         }
         else {
-            renderEntityType(processedEntityType);
+            renderEntityType(processedEntityType, runtime);
         }
     }));
     entityTypes
@@ -200,7 +200,7 @@ export function entityTypesCommand() {
             renderJson({ ...response, entity_types: processedEntityTypes });
         }
         else {
-            renderEntityTypeList(processedEntityTypes, response.response_metadata?.next_cursor ?? null);
+            renderEntityTypeList(processedEntityTypes, response.response_metadata?.next_cursor ?? null, runtime);
         }
     }));
     entityTypes
@@ -245,7 +245,7 @@ export function entityTypesCommand() {
             renderJson({ ok: true, entity_type: response.entity_type });
         }
         else {
-            renderEntityType(response.entity_type, `${ui.success(ui.GLYPHS.CHECK)} Entity type updated`);
+            renderEntityType(response.entity_type, runtime, `${ui.success(ui.GLYPHS.CHECK)} Entity type updated`);
         }
     }));
     return entityTypes;

package/dist/commands/catalog/entityTypesRendering.js

@@ -1,6 +1,6 @@
 import { renderRichText } from "../../renderers.js";
 import * as ui from "../../ui.js";
-export function renderEntityTypeList(entityTypes, nextCursor) {
+export function renderEntityTypeList(entityTypes, nextCursor, runtime) {
     const blocks = [ui.h1("Entity Types")];
     blocks.push(ui.p(`Displaying ${ui.bold(entityTypes.length.toString())} entity types.`));
     if (nextCursor) {
@@ -18,7 +18,7 @@ export function renderEntityTypeList(entityTypes, nextCursor) {
         }
         if (entityType.identifier) {
             blocks.push(ui.h3("Core attributes"));
-            blocks.push(...coreContent(entityType));
+            blocks.push(...coreContent(entityType, runtime));
         }
         if (entityType.properties) {
             blocks.push(ui.h3("Properties"));
@@ -31,11 +31,11 @@ export function renderEntityTypeList(entityTypes, nextCursor) {
     }
     renderRichText(blocks);
 }
-export function renderEntityType(entityType, title = "Entity Type Information") {
+export function renderEntityType(entityType, runtime, title = "Entity Type Information") {
     renderRichText([
         ui.h1(title),
         entityType.identifier
-            ? [ui.h2("Core attributes"), ...coreContent(entityType)]
+            ? [ui.h2("Core attributes"), ...coreContent(entityType, runtime)]
             : null,
         entityType.properties
             ? [ui.h2("Properties"), ...propertiesContent(entityType.properties)]
@@ -51,25 +51,19 @@ export function renderEntityTypeDeleted(entityType) {
         ui.p(`The entity type ${ui.code(entityType.identifier)} has been deleted.`),
     ]);
 }
-function coreContent(entityType) {
+function coreContent(entityType, runtime) {
     return [
         ui.dl([
-            ui.dli("Name", [ui.p(entityType.name ?? ui.dim("(None)"), false)]),
-            ui.dli("Identifier", [ui.p(ui.code(entityType.identifier), false)]),
-            ui.dli("Description", [
-                ui.p(entityType.description || ui.dim("(None)"), false),
-            ]),
-            ui.dli("Icon", [ui.p(entityType.icon ?? ui.dim("(None)"), false)]),
-            ui.dli("Ordering", [
-                ui.p(entityType.ordering?.toString() ?? ui.dim("(None)"), false),
-            ]),
-            ui.dli("Created", [
-                ui.p(ui.timestampSummary(entityType.created_at), false),
-            ]),
-            ui.dli("Last updated", [
-                ui.p(ui.timestampSummary(entityType.updated_at)),
-            ]),
-        ], { termWidth: 14 }),
+            ui.dli("Name", entityType.name ?? ui.dim("(None)")),
+            ui.dli("Identifier", ui.code(entityType.identifier)),
+            ui.dli("Description", entityType.description || ui.dim("(None)")),
+            ui.dli("Icon", entityType.icon ?? ui.dim("(None)")),
+            ui.dli("Ordering", entityType.ordering?.toString() ?? ui.dim("(None)")),
+            ui.dli("Created", ui.timestampSummary(entityType.created_at)),
+            ui.dli("Last updated", ui.timestampSummary(entityType.updated_at)),
+            ui.dli("Entities link", ui.link(ui.webLink(`/catalog?type=${entityType.identifier}`, runtime))),
+            ui.dli("Settings link", ui.link(ui.webLink(`/catalog/manage/entitytypes/${entityType.identifier}`, runtime))),
+        ], { termWidth: 15 }),
     ];
 }
 function propertiesContent(properties) {

package/dist/commands/init.js

@@ -1,10 +1,10 @@
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { input, password, confirm, select } from "@inquirer/prompts";
+import { password, confirm, select } from "@inquirer/prompts";
 import { Command } from "commander";
 import { execa } from "execa";
-import { buildRuntime, buildRuntimeSafe } from "../runtime.js";
+import { buildLogger, buildRuntime, buildRuntimeSafe } from "../runtime.js";
 import { getAuthInfo } from "./auth.js";
 import { renderAuthInfo } from "./authRendering.js";
 import { loginViaBrowser } from "../loginViaBrowser.js";
@@ -13,29 +13,8 @@ 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 { deriveBaseUrlsFromEnv, persistBaseUrls } 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(`\
@@ -51,14 +30,12 @@ export function initCommand() {
     const init = new Command()
         .name("init")
         .description("Initialize the DX CLI")
-        .option("--host <hostname>", "DX hostname for dedicated or managed deployments (e.g. mycompany.getdx.io)")
         .action(wrapAction(async (commandOptions, command) => {
         const context = getContext(command);
         let runtime = buildRuntimeSafe(context);
         ensureInteractive();
         showWelcomeBanner();
-        const host = commandOptions.host || process.env.DX_HOST;
-        runtime = await ensureLoggedIn(runtime, host);
+        runtime = await ensureLoggedIn(context, runtime);
         await optionallySetupSkill(runtime);
         renderRichText([
             ui.blankLine(),
@@ -75,7 +52,7 @@ function ensureInteractive() {
 function showWelcomeBanner() {
     renderRichText([ui.p(ui.success(WELCOME_BANNER))]);
 }
-async function ensureLoggedIn(runtime, host) {
+async function ensureLoggedIn(context, runtime) {
     renderRichText([ui.h1(`Checking if you are logged in...`), ui.blankLine()]);
     if (runtime) {
         let authInfo = null;
@@ -86,34 +63,17 @@ async function ensureLoggedIn(runtime, host) {
             // Do nothing, we don't mind if this fails
         }
         if (authInfo) {
-            renderAuthInfo(authInfo, runtime.token, runtime.baseUrl);
+            renderAuthInfo(authInfo, runtime.token, runtime.apiBaseUrl);
             return runtime;
         }
     }
     renderRichText([ui.p(`You are not logged in yet.`), ui.blankLine()]);
-    const parsed = host ? parseHostname(host) : { type: "cloud" };
-    if (parsed.type === "invalid") {
-        throw new CliError(`Could not recognize hostname "${host}". Expected app.getdx.com, <account>.getdx.io, or a custom domain.`);
-    }
-    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);
-        }
-    }
+    const { apiBaseUrl, webBaseUrl } = deriveBaseUrlsFromEnv();
+    return await attemptLogin(apiBaseUrl, webBaseUrl, context);
 }
-async function attemptLogin(apiBaseUrl, uiBaseUrl) {
+async function attemptLogin(apiBaseUrl, webBaseUrl, context) {
+    const logger = buildLogger(context);
+    logger.debug("Attempting login", { apiBaseUrl, webBaseUrl });
     const method = await select({
         message: "How would you like to log in?",
         choices: [
@@ -123,7 +83,7 @@ async function attemptLogin(apiBaseUrl, uiBaseUrl) {
     });
     let token;
     if (method === "browser") {
-        token = await loginViaBrowser(uiBaseUrl);
+        token = await loginViaBrowser(webBaseUrl);
     }
     else {
         token = await password({
@@ -134,17 +94,17 @@ async function attemptLogin(apiBaseUrl, uiBaseUrl) {
     if (!token) {
         throw new CliError("Account web API token is required");
     }
-    const context = createEmptyContext();
     const runtime = buildRuntime(context, {
-        baseUrl: apiBaseUrl,
+        apiBaseUrl,
         token,
+        webBaseUrl,
     });
     renderRichText([ui.blankLine(), ui.p(`Attempting login...`), ui.blankLine()]);
     const response = await getAuthInfo(runtime);
     if (!response.ok) {
         throw new CliError(`Login failed`);
     }
-    persistBaseUrl(apiBaseUrl);
+    persistBaseUrls(apiBaseUrl, webBaseUrl);
     setToken(apiBaseUrl, token);
     renderAuthInfo(response, token, apiBaseUrl);
     return runtime;
@@ -195,8 +155,3 @@ async function optionallySetupSkill(runtime) {
         throw new CliError(`Failed to setup the DX skill: ${result.stderr}`);
     }
 }
-function createEmptyContext() {
-    return {
-        json: false,
-    };
-}

package/dist/commands/scorecards.js

@@ -53,7 +53,7 @@ export function scorecardsCommand() {
             renderJson({ ok: true, scorecard: response.scorecard });
         }
         else {
-            renderScorecard(response.scorecard, null, `${ui.success(ui.GLYPHS.CHECK)} Scorecard created`);
+            renderScorecard(response.scorecard, null, runtime, `${ui.success(ui.GLYPHS.CHECK)} Scorecard created`);
         }
     }));
     scorecards
@@ -110,7 +110,7 @@ export function scorecardsCommand() {
             renderJson({ ok: true, scorecard: processedScorecard });
         }
         else {
-            renderScorecard(response.scorecard, includeSections);
+            renderScorecard(response.scorecard, includeSections, runtime);
         }
     }));
     scorecards
@@ -211,7 +211,7 @@ export function scorecardsCommand() {
             renderJson({ ...response, scorecards: processedScorecards });
         }
         else {
-            renderScorecardList(response.scorecards, response.response_metadata?.next_cursor ?? null, includeSections);
+            renderScorecardList(response.scorecards, response.response_metadata?.next_cursor ?? null, includeSections, runtime);
         }
     }));
     scorecards
@@ -256,7 +256,7 @@ export function scorecardsCommand() {
             renderJson({ ok: true, scorecard: response.scorecard });
         }
         else {
-            renderScorecard(response.scorecard, null, `${ui.success(ui.GLYPHS.CHECK)} Scorecard updated`);
+            renderScorecard(response.scorecard, null, runtime, `${ui.success(ui.GLYPHS.CHECK)} Scorecard updated`);
         }
     }));
     return scorecards;

package/dist/commands/scorecardsRendering.js

@@ -1,6 +1,6 @@
 import { renderRichText } from "../renderers.js";
 import * as ui from "../ui.js";
-export function renderScorecardList(scorecards, nextCursor, includeSections) {
+export function renderScorecardList(scorecards, nextCursor, includeSections, runtime) {
     const shouldIncludeAll = includeSections === null;
     const blocks = [ui.h1("Scorecards")];
     blocks.push(ui.p(`Displaying ${ui.bold(scorecards.length.toString())} scorecards.`));
@@ -11,7 +11,7 @@ export function renderScorecardList(scorecards, nextCursor, includeSections) {
         blocks.push(ui.h2(`${scorecard.name} (${ui.code(scorecard.id)})`));
         if (shouldIncludeAll || includeSections.includes("core")) {
             blocks.push(ui.h3("Basic details"));
-            blocks.push(...basicDetailsContent(scorecard));
+            blocks.push(...basicDetailsContent(scorecard, runtime));
             blocks.push(ui.h3("Entity filter"));
             blocks.push(...entityFilterContent(scorecard));
             if (scorecard.type === "LEVEL") {
@@ -34,12 +34,12 @@ export function renderScorecardList(scorecards, nextCursor, includeSections) {
     }
     renderRichText(blocks);
 }
-export function renderScorecard(scorecard, includeSections, title = "Scorecard Information") {
+export function renderScorecard(scorecard, includeSections, runtime, title = "Scorecard Information") {
     const shouldIncludeAll = includeSections === null;
     const blocks = [ui.h1(title)];
     if (shouldIncludeAll || includeSections.includes("core")) {
         blocks.push(ui.h2("Basic details"));
-        blocks.push(...basicDetailsContent(scorecard));
+        blocks.push(...basicDetailsContent(scorecard, runtime));
         blocks.push(ui.h2("Entity filter"));
         blocks.push(...entityFilterContent(scorecard));
         if (scorecard.type === "LEVEL") {
@@ -61,7 +61,7 @@ export function renderScorecard(scorecard, includeSections, title = "Scorecard I
     }
     renderRichText(blocks);
 }
-function basicDetailsContent(scorecard) {
+function basicDetailsContent(scorecard, runtime) {
     const items = [
         ui.dli("ID", [ui.p(ui.code(scorecard.id), false)]),
         ui.dli("Name", [ui.p(scorecard.name, false)]),
@@ -74,6 +74,9 @@ function basicDetailsContent(scorecard) {
         ui.dli("Published", [
             ui.p(scorecard.published ? ui.success("Yes") : ui.dim("No (draft)"), false),
         ]),
+        ui.dli("Web link", [
+            ui.p(ui.link(ui.webLink(`/scorecards/${scorecard.id}`, runtime)), false),
+        ]),
     ];
     if (scorecard.tags && scorecard.tags.length > 0) {
         items.push(ui.dli("Tags", [

package/dist/commands/studio/query.js

@@ -144,13 +144,13 @@ async function getStudioQueryResults(runtime, id) {
     return response.body;
 }
 async function downloadStudioQueryResultsCsv(runtime, id, filename) {
-    const response = await fetchWithApiHeaders(runtime, `${runtime.baseUrl}/studio.queryRuns.results?id=${encodeURIComponent(id)}&format=csv`, { redirect: "manual" });
+    const response = await fetchWithApiHeaders(runtime, `${runtime.apiBaseUrl}/studio.queryRuns.results?id=${encodeURIComponent(id)}&format=csv`, { redirect: "manual" });
     if (response.status >= 300 && response.status < 400) {
         const location = response.headers.get("location");
         if (!location) {
             throw new HttpError("CSV download redirect did not include a Location header.", response.status);
         }
-        const downloadResponse = await fetchResponse(new URL(location, runtime.baseUrl).toString(), {
+        const downloadResponse = await fetchResponse(new URL(location, runtime.apiBaseUrl).toString(), {
             method: "GET",
             headers: buildDownloadHeaders(runtime, "text/csv"),
         });

package/dist/config.js

@@ -1,14 +1,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-const DEFAULT_BASE_URL = "https://api.getdx.com";
-export function getConfigDir() {
-    const xdg = process.env.XDG_CONFIG_HOME;
-    if (xdg) {
-        return path.join(xdg, "dx");
-    }
-    return path.join(os.homedir(), ".config", "dx");
-}
+import { CliError, EXIT_CODES } from "./errors.js";
+const DEFAULT_API_BASE_URL = "https://api.getdx.com";
+const DEFAULT_WEB_BASE_URL = "https://app.getdx.com";
+// --- Config file I/O ---------------------------------------------------------
 export function getConfigPath() {
     return path.join(getConfigDir(), "config.json");
 }
@@ -18,38 +14,184 @@ export function readConfig() {
         return {};
     }
     const content = fs.readFileSync(configPath, "utf8");
-    return JSON.parse(content);
+    const raw = JSON.parse(content);
+    const api = raw.apiBaseUrl;
+    const web = raw.webBaseUrl;
+    const stored = {};
+    if (web) {
+        stored.webBaseUrl = web;
+    }
+    if (api) {
+        stored.apiBaseUrl = api;
+    }
+    return stored;
+}
+/**
+ * Responsible for handling the migration from `baseUrl` to `apiBaseUrl` and `webBaseUrl`,
+ * so the upgrade to 0.3.x will be non-breaking for `cloud` and `dedicated` deployments.
+ *
+ * `managed` deployments will encounter an error and will have to reauthenticate.
+ *
+ * TODO: delete after 2026-07-01.
+ */
+export function handleTemporaryBaseUrlMigration(argv) {
+    if (!process.env.VITEST) {
+        // Running tests - we don't want our permanent tests to exercise this logic
+        return;
+    }
+    const COMMANDS_TO_SKIP_MIGRATION = ["login", "logout", "init"];
+    if (COMMANDS_TO_SKIP_MIGRATION.some((command) => argv.includes(command))) {
+        // Logging in or logging out: we need to ignore the current config file's contents
+        return;
+    }
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        // No config file, no need to migrate
+        return;
+    }
+    const content = fs.readFileSync(configPath, "utf8");
+    const raw = JSON.parse(content);
+    const api = raw.apiBaseUrl;
+    const web = raw.webBaseUrl;
+    if (api !== undefined && web !== undefined) {
+        // Already migrated, no need to do anything
+        return;
+    }
+    if (raw.baseUrl) {
+        // Legacy baseUrl is present, migrate to apiBaseUrl and webBaseUrl
+        const apiBaseUrl = raw.baseUrl;
+        let webBaseUrl;
+        if (apiBaseUrl.endsWith(".getdx.com")) {
+            // Migrate `cloud`
+            webBaseUrl = "https://app.getdx.com";
+            writeConfig({
+                apiBaseUrl: normalizeUrl(apiBaseUrl),
+                webBaseUrl: normalizeUrl(webBaseUrl),
+            });
+            return;
+        }
+        const dedicatedMatch = apiBaseUrl.match(/^api\.(.+)\.getdx\.io$/);
+        if (dedicatedMatch) {
+            // Migrate `dedicated`
+            webBaseUrl = `https://${dedicatedMatch[1]}.getdx.io`;
+            writeConfig({
+                apiBaseUrl: normalizeUrl(apiBaseUrl),
+                webBaseUrl: normalizeUrl(webBaseUrl),
+            });
+            return;
+        }
+        // Unable to automatically migrate `managed`
+        throw new CliError("Your on-disk DX CLI config is missing apiBaseUrl and webBaseUrl. Run `dx auth logout`, then login again via `dx init` or `dx auth login`.");
+    }
 }
 export function writeConfig(config) {
     fs.mkdirSync(getConfigDir(), { recursive: true });
     fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf8");
 }
-export function resolveBaseUrl() {
-    if (process.env.DX_BASE_URL) {
-        return normalizeBaseUrl(process.env.DX_BASE_URL);
+export function persistBaseUrls(apiBaseUrl, webBaseUrl) {
+    writeConfig({
+        ...readConfig(),
+        apiBaseUrl: normalizeUrl(apiBaseUrl),
+        webBaseUrl: normalizeUrl(webBaseUrl),
+    });
+}
+/** Strips trailing slashes from an HTTP(S) base URL string. */
+export function normalizeUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg) {
+        return path.join(xdg, "dx");
     }
-    return normalizeBaseUrl(readConfig().baseUrl || DEFAULT_BASE_URL);
+    return path.join(os.homedir(), ".config", "dx");
 }
+// --- Resolving URLs at command runtime ------------------------------------------------------
 /**
- * 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.
+ * Resolved API base URL for HTTP requests.
+ * Precedence: `DX_API_BASE_URL`, then persisted `apiBaseUrl`, then DX Cloud default.
  */
-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";
+export function resolveApiBaseUrl() {
+    if (process.env.DX_API_BASE_URL) {
+        return normalizeUrl(process.env.DX_API_BASE_URL);
     }
-    const dedicated = host.match(/^api\.(.+)\.getdx\.io$/);
-    if (dedicated) {
-        return `https://${dedicated[1]}.getdx.io`;
+    return normalizeUrl(readConfig().apiBaseUrl || DEFAULT_API_BASE_URL);
+}
+/**
+ * Resolved web-app base URL for CLI deep links and browser OAuth.
+ * Precedence: `DX_WEB_BASE_URL`, persisted `webBaseUrl`, then DX Cloud default.
+ */
+export function resolveWebBaseUrl() {
+    if (process.env.DX_WEB_BASE_URL) {
+        return normalizeUrl(process.env.DX_WEB_BASE_URL);
     }
-    return url.origin;
+    return normalizeUrl(readConfig().webBaseUrl || DEFAULT_WEB_BASE_URL);
 }
-export function persistBaseUrl(baseUrl) {
-    writeConfig({ ...readConfig(), baseUrl: normalizeBaseUrl(baseUrl) });
+// --- Deriving base URLs at login time -------------------------------------
+/**
+ * Derive the appropriate `apiBaseUrl` and `webBaseUrl` to persist into config,
+ * considering the `DX_API_BASE_URL` and `DX_WEB_BASE_URL` env vars if they are present.
+ *
+ * If the env vars are not set, we assume the user is configuring for a `cloud` deployment.
+ *
+ * If they are set, we parse them to determine whether the deployment is `cloud`, `dedicated`, or `managed`.
+ *
+ * If we fail to derive the base URLs, a `CliError` is thrown.
+ */
+export function deriveBaseUrlsFromEnv() {
+    const apiBaseUrlFromEnv = process.env.DX_API_BASE_URL;
+    const webBaseUrlFromEnv = process.env.DX_WEB_BASE_URL;
+    if (apiBaseUrlFromEnv && !webBaseUrlFromEnv) {
+        throw new CliError("DX_WEB_BASE_URL must be set when DX_API_BASE_URL is set", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    const parsed = webBaseUrlFromEnv
+        ? parseWebBaseUrl(webBaseUrlFromEnv)
+        : { type: "cloud" };
+    switch (parsed.type) {
+        case "cloud":
+            return {
+                apiBaseUrl: "https://api.getdx.com",
+                webBaseUrl: "https://app.getdx.com",
+            };
+        case "dedicated": {
+            const { accountName } = parsed;
+            return {
+                apiBaseUrl: `https://api.${accountName}.getdx.io`,
+                webBaseUrl: `https://${accountName}.getdx.io`,
+            };
+        }
+        case "managed": {
+            const apiBaseUrl = process.env.DX_API_BASE_URL;
+            if (!apiBaseUrl) {
+                throw new CliError("DX_API_BASE_URL must be specified when authenticating with a managed deployment");
+            }
+            return {
+                apiBaseUrl,
+                webBaseUrl: parsed.webAppUrl,
+            };
+        }
+        case "invalid":
+            throw new CliError(`Could not recognize web base URL "${parsed.input}". Expected https://app.getdx.com, https://<account>.getdx.io, or a custom domain.`);
+    }
 }
-function normalizeBaseUrl(baseUrl) {
-    return baseUrl.replace(/\/+$/, "");
+function parseWebBaseUrl(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", webAppUrl: url.origin };
+        }
+    }
+    catch {
+        // fall through to invalid
+    }
+    return { type: "invalid", input: raw };
 }

package/dist/http.js

@@ -23,7 +23,7 @@ export async function request(runtime, route, options = {}) {
             query.set(key, String(value));
         }
     });
-    const url = `${runtime.baseUrl}${route}${query.size > 0 ? `?${query.toString()}` : ""}`;
+    const url = `${runtime.apiBaseUrl}${route}${query.size > 0 ? `?${query.toString()}` : ""}`;
     const requestBody = options.body !== undefined ? JSON.stringify(options.body) : undefined;
     runtime.logger.debug("Sending HTTP request", {
         body: options.body ?? null,

package/dist/loginViaBrowser.js

@@ -4,7 +4,7 @@ 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) {
+export async function loginViaBrowser(webBaseUrl) {
     const server = new AuthCodeCallbackServer();
     await server.start();
     const callbackUri = server.getAddress();
@@ -17,7 +17,7 @@ export async function loginViaBrowser(uiBaseUrl) {
         code_challenge: codeChallenge,
         code_challenge_method: "S256",
     });
-    const authUrl = `${uiBaseUrl}/cli/auth?${params.toString()}`;
+    const authUrl = `${webBaseUrl}/cli/auth?${params.toString()}`;
     renderRichText([
         ui.p(`Opening your browser to complete authentication...`),
         ui.blankLine(),
@@ -42,7 +42,7 @@ export async function loginViaBrowser(uiBaseUrl) {
                 error: new CliError("Authentication failed: state mismatch"),
             };
         }
-        const tokenExchangeResponse = await exchangeCodeForToken(uiBaseUrl, code, codeVerifier);
+        const tokenExchangeResponse = await exchangeCodeForToken(webBaseUrl, code, codeVerifier);
         if (!tokenExchangeResponse.ok) {
             return {
                 type: "ERROR",
@@ -64,8 +64,8 @@ export async function loginViaBrowser(uiBaseUrl) {
 function validateState(stateFromResponse, originalState) {
     return stateFromResponse === originalState;
 }
-async function exchangeCodeForToken(baseUrl, code, codeVerifier) {
-    return fetch(`${baseUrl}/cli/token`, {
+async function exchangeCodeForToken(webBaseUrl, code, codeVerifier) {
+    return fetch(`${webBaseUrl}/cli/token`, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({ code, code_verifier: codeVerifier }),

package/dist/runtime.js

@@ -1,4 +1,4 @@
-import { resolveBaseUrl } from "./config.js";
+import { resolveApiBaseUrl, resolveWebBaseUrl } from "./config.js";
 import { CliError } from "./errors.js";
 import { getToken } from "./secrets.js";
 import { createLogger } from "./logger.js";
@@ -7,13 +7,15 @@ export function buildLogger(context) {
     return createLogger({ json: context.json || !process.stderr.isTTY });
 }
 export function buildRuntime(context, overrides) {
-    const baseUrl = overrides?.baseUrl ?? resolveBaseUrl();
-    const token = overrides?.token ?? getToken(baseUrl);
+    const apiBaseUrl = overrides?.apiBaseUrl ?? resolveApiBaseUrl();
+    const webBaseUrl = overrides?.webBaseUrl ?? resolveWebBaseUrl();
+    const token = overrides?.token ?? getToken(apiBaseUrl);
     if (!token) {
         throw new CliError("No API token configured. Run `dx auth login --token <token>` or set DX_API_TOKEN.");
     }
     return {
-        baseUrl,
+        apiBaseUrl,
+        webBaseUrl,
         token,
         context,
         version: cliPackage.version,
@@ -21,13 +23,15 @@ export function buildRuntime(context, overrides) {
     };
 }
 export function buildRuntimeSafe(context, overrides) {
-    const baseUrl = overrides?.baseUrl ?? resolveBaseUrl();
-    const token = overrides?.token ?? getToken(baseUrl);
+    const apiBaseUrl = overrides?.apiBaseUrl ?? resolveApiBaseUrl();
+    const webBaseUrl = overrides?.webBaseUrl ?? resolveWebBaseUrl();
+    const token = overrides?.token ?? getToken(apiBaseUrl);
     if (!token) {
         return null;
     }
     return {
-        baseUrl,
+        apiBaseUrl,
+        webBaseUrl,
         token,
         context,
         version: cliPackage.version,

package/dist/ui.js

@@ -121,3 +121,6 @@ export function maskToken(token) {
     }
     return `${token.slice(0, 4)}${"*".repeat(token.length - 8)}${token.slice(-4)}`;
 }
+export function webLink(path, runtime) {
+    return `${runtime.webBaseUrl}${path}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {