@get-dx/cli 0.6.2 → 0.8.0

package/dist/cli.js

@@ -6,6 +6,7 @@ import { scorecardsCommand } from "./commands/scorecards.js";
 import { snapshotsCommand } from "./commands/snapshots.js";
 import { studioCommand } from "./commands/studio.js";
 import { teamsCommand } from "./commands/teams.js";
+import { usersCommand } from "./commands/users.js";
 import { workflowRunsCommand } from "./commands/workflowRuns.js";
 import { workflowsCommand } from "./commands/workflows.js";
 import { handleError } from "./commandHelpers.js";
@@ -54,6 +55,7 @@ function createProgram() {
     program.addCommand(snapshotsCommand());
     program.addCommand(studioCommand());
     program.addCommand(teamsCommand());
+    program.addCommand(usersCommand());
     program.addCommand(workflowRunsCommand());
     program.addCommand(workflowsCommand());
     applyExitOverride(program);

package/dist/commands/catalog/entityTypes.js

@@ -14,9 +14,9 @@ export function entityTypesCommand() {
         .description("Manage catalog entity types");
     entityTypes
         .command("create")
-        .description("Create a new entity type from a YAML file or stdin. The `init` command can be used to generate a starting template.")
-        .option("--from-file <path>", "Read a YAML file and create an entity type from its contents")
-        .option("--from-stdin", "Read YAML from stdin and create an entity type from its contents")
+        .description("Create a new entity type from a YAML or JSON file or stdin. The `init` command can be used to generate a starting template.")
+        .option("--from-file <path>", "Read a YAML or JSON file and create an entity type from its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and create an entity type from its contents")
         .addHelpText("afterAll", createExampleText([
         {
             label: "Generate a blank template first",
@@ -205,10 +205,10 @@ export function entityTypesCommand() {
     }));
     entityTypes
         .command("update")
-        .description("Update an existing entity type from a YAML file or stdin. The `init` command can be used to initialize the entity type file.")
+        .description("Update an existing entity type from a YAML or JSON file or stdin. The `init` command can be used to initialize the entity type file.")
         .argument("<identifier>", "The unique identifier of the entity type")
-        .option("--from-file <path>", "Read a YAML file and update the entity type with its contents")
-        .option("--from-stdin", "Read YAML from stdin and update the entity type with its contents")
+        .option("--from-file <path>", "Read a YAML or JSON file and update the entity type with its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and update the entity type with its contents")
         .addHelpText("afterAll", createExampleText([
         {
             label: "Initialize a file first",

package/dist/commands/scorecards.js

@@ -14,9 +14,9 @@ export function scorecardsCommand() {
         .description("Manage scorecards");
     scorecards
         .command("create")
-        .description("Create a new scorecard from a YAML file or stdin. The `init` command can be used to generate a starting template.")
-        .option("--from-file <path>", "Read a YAML file and create a scorecard from its contents")
-        .option("--from-stdin", "Read YAML from stdin and create a scorecard from its contents")
+        .description("Create a new scorecard from a YAML or JSON file or stdin. The `init` command can be used to generate a starting template.")
+        .option("--from-file <path>", "Read a YAML or JSON file and create a scorecard from its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and create a scorecard from its contents")
         .addHelpText("afterAll", createExampleText([
         {
             label: "Generate a blank template first",
@@ -216,10 +216,10 @@ export function scorecardsCommand() {
     }));
     scorecards
         .command("update")
-        .description("Update an existing scorecard from a YAML file or stdin. The `init` command can be used to initialize the scorecard file.")
+        .description("Update an existing scorecard from a YAML or JSON file or stdin. The `init` command can be used to initialize the scorecard file.")
         .argument("<id>", "The unique ID of the scorecard")
-        .option("--from-file <path>", "Read a YAML file and update the scorecard with its contents")
-        .option("--from-stdin", "Read YAML from stdin and update the scorecard with its contents")
+        .option("--from-file <path>", "Read a YAML or JSON file and update the scorecard with its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and update the scorecard with its contents")
         .addHelpText("afterAll", createExampleText([
         {
             label: "Initialize a file first",

package/dist/commands/studio/reports.js

@@ -17,9 +17,9 @@ export function reportsCommand() {
         .description("Manage Data Studio reports");
     reports
         .command("create")
-        .description("Create a Data Studio report from a YAML file or stdin")
-        .option("--from-file <path>", "Read a YAML file and create a report from its contents")
-        .option("--from-stdin", "Read YAML from stdin and create a report from its contents")
+        .description("Create a Data Studio report from a YAML or JSON file or stdin")
+        .option("--from-file <path>", "Read a YAML or JSON file and create a report from its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and create a report from its contents")
         .addHelpText("afterAll", createNoteText(VARIABLES_NOTE_TEXT))
         .addHelpText("afterAll", createExampleText([
         {
@@ -175,10 +175,10 @@ export function reportsCommand() {
     }));
     reports
         .command("update")
-        .description("Update a Data Studio report from a YAML file or stdin. The `init` command can be used to initialize the report file.")
+        .description("Update a Data Studio report from a YAML or JSON file or stdin. The `init` command can be used to initialize the report file.")
         .argument("<id>", "Studio report ID")
-        .option("--from-file <path>", "Read a YAML file and update the report with its contents")
-        .option("--from-stdin", "Read YAML from stdin and update the report with its contents")
+        .option("--from-file <path>", "Read a YAML or JSON file and update the report with its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and update the report with its contents")
         .addHelpText("afterAll", createNoteText(VARIABLES_NOTE_TEXT))
         .addHelpText("afterAll", createExampleText([
         {

package/dist/commands/users/linkableAccounts.js

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { CliError, EXIT_CODES } from "../../errors.js";
+import { requestWithMessages } from "../../http.js";
+import { renderJson, renderRichText } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { SOURCES } from "./sources.js";
+export function linkableAccountsCommand() {
+    const linkableAccounts = new Command()
+        .name("linkableAccounts")
+        .description("Search accounts that can be linked to DX users");
+    linkableAccounts
+        .command("list")
+        .description("Search the accounts DX has imported from a source, and get the account IDs to pass to `dx users links` commands")
+        .requiredOption("--source <source>", `Source to search (${SOURCES})`)
+        .option("--query <query>", "Case-insensitive text to find in the account's name, email, or username")
+        .option("--external-id <id>", "Only return the account with this ID from the tool itself")
+        .option("--instance-id <id>", "Only return accounts from this instance, organization, workspace, or connection")
+        .option("--linked", "Only return accounts linked to a DX user")
+        .option("--unlinked", "Only return accounts not linked to a DX user")
+        .option("--page <n>", "Page number to return (default is 1)", (value) => parsePositiveIntOption(value, "--page"))
+        .option("--page-size <n>", "Max accounts per page (default and maximum is 100)", (value) => parsePositiveIntOption(value, "--page-size"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Search unlinked GitHub accounts matching a name",
+            command: "dx users linkableAccounts list --source github --query jane --unlinked",
+        },
+        {
+            label: "Find a Jira account by its Jira ID and return JSON",
+            command: "dx users linkableAccounts list --source jira --external-id 5b10ac8d82e05b22cc7d4ef5 --json",
+        },
+        {
+            label: "Fetch the next page of results",
+            command: "dx users linkableAccounts list --source github --page 2",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        if (options.linked && options.unlinked) {
+            throw new CliError("--linked and --unlinked are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listLinkableAccounts(runtime, {
+            source: options.source,
+            query: options.query,
+            external_id: options.externalId,
+            instance_id: options.instanceId,
+            linked: options.unlinked ? false : options.linked,
+            page: options.page,
+            page_size: options.pageSize,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderLinkableAccounts(response);
+        }
+    }));
+    return linkableAccounts;
+}
+const ERROR_MESSAGES = {
+    query_timeout: "The search timed out. Narrow it with --instance-id, --external-id, or a longer --query, then try again.",
+};
+async function listLinkableAccounts(runtime, params) {
+    return requestWithMessages(runtime, "/users.linkableAccounts.list", {
+        method: "GET",
+        query: params,
+    }, ERROR_MESSAGES);
+}
+function renderLinkableAccounts(response) {
+    const blocks = [ui.h1("Linkable Accounts")];
+    blocks.push(ui.p(`Displaying ${ui.bold(response.accounts.length.toString())} of ${ui.bold(response.total.toString())} accounts.`));
+    if (response.next_page) {
+        blocks.push(ui.p(`Next page: ${ui.code(response.next_page.toString())}`));
+    }
+    for (const account of response.accounts) {
+        blocks.push(ui.h2(`${account.label} (${ui.code(account.id)})`));
+        blocks.push(ui.dl([
+            ...accountDetailItems(account),
+            ui.dli("Linked user", account.linked_user_id
+                ? ui.code(account.linked_user_id)
+                : ui.dim("(Not linked)")),
+        ], { termWidth: 13 }));
+    }
+    renderRichText(blocks);
+}
+export function accountDetailItems(account) {
+    return [
+        ui.dli("Source", account.source),
+        ui.dli("External ID", formatCode(account.external_id)),
+        ui.dli("Instance ID", formatCode(account.instance_id)),
+        ui.dli("Name", account.name ?? ui.dim("(None)")),
+        ui.dli("Email", account.email ?? ui.dim("(None)")),
+        ui.dli("Username", account.username ?? ui.dim("(None)")),
+    ];
+}
+function formatCode(value) {
+    return value ? ui.code(value) : ui.dim("(None)");
+}

package/dist/commands/users/links.js

@@ -0,0 +1,205 @@
+import { Command } from "commander";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { requestWithMessages } from "../../http.js";
+import { renderJson, renderRichText } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { accountDetailItems } from "./linkableAccounts.js";
+import { SOURCES } from "./sources.js";
+export function linksCommand() {
+    const links = new Command()
+        .name("links")
+        .description("Manage the accounts linked to DX users");
+    links
+        .command("create")
+        .description("Link one account to a user, keeping the user's other linked accounts for that source")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the account comes from (${SOURCES})`)
+        .requiredOption("--account-id <id>", "Account ID to link, as returned by `dx users linkableAccounts list`")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Link a GitHub account to a user",
+            command: "dx users links create NTEyMDUw --source github --account-id 4812",
+        },
+        {
+            label: "Link an account and return JSON",
+            command: "dx users links create NTEyMDUw --source github --account-id 4812 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await createLink(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_id: options.accountId,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(`${ui.success(ui.GLYPHS.CHECK)} Linked ${options.source} account ${ui.code(options.accountId)} to user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    links
+        .command("delete")
+        .description("Unlink one account from a user, keeping the user's other linked accounts for that source")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the account comes from (${SOURCES})`)
+        .requiredOption("--account-id <id>", "Account ID to unlink")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Unlink a GitHub account from a user",
+            command: "dx users links delete NTEyMDUw --source github --account-id 4812",
+        },
+        {
+            label: "Unlink an account and return JSON",
+            command: "dx users links delete NTEyMDUw --source github --account-id 4812 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await deleteLink(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_id: options.accountId,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(`${ui.success(ui.GLYPHS.CHECK)} Unlinked ${options.source} account ${ui.code(options.accountId)} from user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    links
+        .command("list")
+        .description("List the accounts linked to a user")
+        .argument("<user-id>", "DX user ID")
+        .option("--source <source>", `Only return accounts from this source (${SOURCES})`)
+        .option("--page <n>", "Page number to return (default is 1)", (value) => parsePositiveIntOption(value, "--page"))
+        .option("--page-size <n>", "Max links per page (default and maximum is 100)", (value) => parsePositiveIntOption(value, "--page-size"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List every account linked to a user",
+            command: "dx users links list NTEyMDUw",
+        },
+        {
+            label: "List a user's GitHub accounts and return JSON",
+            command: "dx users links list NTEyMDUw --source github --json",
+        },
+        {
+            label: "Fetch the next page of links",
+            command: "dx users links list NTEyMDUw --page 2",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listLinks(runtime, {
+            user_id: userId,
+            source: options.source,
+            page: options.page,
+            page_size: options.pageSize,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderLinks(userId, response);
+        }
+    }));
+    links
+        .command("set")
+        .description("Replace every account linked to a user for one source. Accounts not in the list are unlinked.")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the accounts come from (${SOURCES})`)
+        .requiredOption("--account-ids <ids>", 'Comma-separated account IDs to link, up to 100. Pass "" to unlink every account for the source.')
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Link exactly these two GitHub accounts to a user",
+            command: "dx users links set NTEyMDUw --source github --account-ids 4812,4813",
+        },
+        {
+            label: "Unlink every GitHub account from a user",
+            command: 'dx users links set NTEyMDUw --source github --account-ids ""',
+        },
+        {
+            label: "Replace a user's Jira accounts and return JSON",
+            command: "dx users links set NTEyMDUw --source jira --account-ids 991 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const accountIds = options.accountIds
+            .split(",")
+            .map((id) => id.trim())
+            .filter((id) => id.length > 0);
+        const runtime = await buildRuntime(getContext(command));
+        const response = await setLinks(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_ids: accountIds,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(accountIds.length > 0
+                    ? `${ui.success(ui.GLYPHS.CHECK)} Set the ${options.source} accounts linked to user ${ui.code(userId)} to ${accountIds.map((id) => ui.code(id)).join(", ")}.`
+                    : `${ui.success(ui.GLYPHS.CHECK)} Unlinked every ${options.source} account from user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    return links;
+}
+const NOT_SYNCED = "This user hasn't synced to Data Cloud yet. Try again once their next sync finishes.";
+const ERROR_MESSAGES = {
+    link_update_in_progress: "Another link update for this user and source is still running. Try again in a few seconds.",
+    manual_link_conflict: "An account is manually linked to another user. Remove that link before linking it to this user.",
+    not_found: "The user or account wasn't found. Check the user ID, and look up account IDs with `dx users linkableAccounts list`.",
+    user_not_in_datacloud: NOT_SYNCED,
+    // users.links.set passes Data Cloud's own error string through instead of a code.
+    "User not found in datacloud": NOT_SYNCED,
+};
+async function createLink(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.create", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+async function deleteLink(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.delete", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+async function listLinks(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.list", {
+        method: "GET",
+        query: params,
+    }, ERROR_MESSAGES);
+}
+async function setLinks(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.set", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+function renderLinks(userId, response) {
+    const blocks = [ui.h1("Linked Accounts")];
+    blocks.push(ui.p(`Displaying ${ui.bold(response.links.length.toString())} of ${ui.bold(response.total.toString())} links for user ${ui.code(userId)}.`));
+    if (response.next_page) {
+        blocks.push(ui.p(`Next page: ${ui.code(response.next_page.toString())}`));
+    }
+    for (const link of response.links) {
+        blocks.push(ui.h2(link.account
+            ? `${link.account.label} (${ui.code(link.account_id)})`
+            : `${link.source} account (${ui.code(link.account_id)})`));
+        blocks.push(ui.dl(link.account
+            ? accountDetailItems(link.account)
+            : [ui.dli("Source", link.source)], { termWidth: 13 }));
+    }
+    renderRichText(blocks);
+}

package/dist/commands/users/sources.js

@@ -0,0 +1 @@
+export const SOURCES = "ado, amazon_kiro, bitbucket, bitbucket_server, claude_code, codex, cursor, github, gitlab, jira, linear, windsurf";

package/dist/commands/users.js

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { linkableAccountsCommand } from "./users/linkableAccounts.js";
+import { linksCommand } from "./users/links.js";
+export function usersCommand() {
+    const users = new Command().name("users").description("Manage DX users");
+    users.addCommand(linkableAccountsCommand());
+    users.addCommand(linksCommand());
+    return users;
+}

package/dist/commands/workflow-blank-template.yaml

@@ -0,0 +1,78 @@
+# Self-service workflow configuration
+#
+# Edit this file, then run:
+#
+# ```
+# dx workflows create --from-file <path>
+# ```
+
+# Unique per account. Letters, numbers, ".", "_" and "-" only; "new" is reserved.
+identifier: ""
+name: ""
+description: ""
+# icon: globe
+color: "#38bdf8"
+
+# scope: "GLOBAL" (not tied to a catalog entity) or "ENTITY" (run against an entity)
+scope: GLOBAL
+
+# execution_type: "SIMPLE" or "EVENT_DRIVEN"
+execution_type: SIMPLE
+
+# Who can trigger a run:
+#   ANY       - all users, no approval
+#   APPROVAL  - all users, but an approver must accept (set approver_user_ids)
+#   RUNNERS   - only selected users and teams (set runners)
+#   ENTITY    - only owners of the entity (requires scope: ENTITY)
+trigger_type: ANY
+# approver_user_ids: ["<active user id>"]   # at least one when APPROVAL
+# runners:                                  # at least one when RUNNERS
+#   - user_id: "<user id>"                  # each runner sets exactly one of
+#   - squad_id: "<team id>"                 # user_id or squad_id
+#     squad_linkage_id: null                # optional
+
+# Which entities the workflow can run against (only used when scope is ENTITY).
+# entity_filter_type: "ENTITY_TYPES" or "SQL"
+entity_filter_type: ENTITY_TYPES
+# Entity type identifiers (when entity_filter_type is "ENTITY_TYPES"; at least
+# one is required when scope is ENTITY)
+entity_filter_type_identifiers: []
+# SQL filter expression (required when scope is ENTITY and entity_filter_type is "SQL")
+# entity_filter_sql: ""
+
+# The HTTP request sent when the workflow runs.
+# The url, body, header values and form_data values can use variables:
+#   {{run.id}}, {{workflow.identifier}}, {{workflow.name}},
+#   {{triggered_by_user.id}}, {{triggered_by_user.name}}, {{triggered_by_user.email}},
+#   {{triggered_by_user.team_id}}, {{triggered_by_user.team_name}},
+#   {{entity.identifier}}, {{entity.name}} (scope: ENTITY only),
+#   {{data.<parameter identifier>}}, {{secret.<name>}}
+http_request:
+  # method: GET, POST, PUT, PATCH or DELETE
+  method: POST
+  url: "https://example.com/hooks/my-workflow"
+  headers:
+    Content-Type: application/json
+  # A string or null. Must be null when form_data is used.
+  body: |-
+    {"run_id": "{{run.id}}"}
+  # form_data:
+  #   - key: example
+  #     value: "{{data.example}}"
+
+# Inputs collected from the user when triggering a run. Each parameter needs an
+# identifier (letters, numbers, underscores), a name, a type and is_required.
+parameters: []
+# parameters:
+#   - identifier: environment
+#     name: Environment
+#     description: ""
+#     # type: STRING, INTEGER, FLOAT, BOOLEAN, SELECT, USER, TEAM, EMAIL or COMPUTED
+#     type: SELECT
+#     is_required: true
+#     default_value: staging
+#     # SELECT: {options: [...]}   COMPUTED: {sql: "..."}   other types: omit
+#     definition:
+#       options:
+#         - staging
+#         - production

package/dist/commands/workflows.js

@@ -1,15 +1,82 @@
+import fs from "fs";
 import { Command } from "commander";
+import { parse as parseYaml } from "yaml";
 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 { renderJson, renderRichText } from "../renderers.js";
 import { buildRuntime } from "../runtime.js";
-import { renderWorkflowList } from "./workflowsRendering.js";
+import * as ui from "../ui.js";
+import { renderWorkflowCreated, renderWorkflowList, } from "./workflowsRendering.js";
+const WORKFLOW_BLANK_TEMPLATE_YAML = fs.readFileSync(new URL("./workflow-blank-template.yaml", import.meta.url), "utf8");
 const WORKFLOW_SCOPES = ["GLOBAL", "ENTITY"];
 export function workflowsCommand() {
     const workflows = new Command()
         .name("workflows")
         .description("Manage Self-service workflow definitions");
+    workflows
+        .command("create")
+        .description("Create a Self-service workflow from a YAML or JSON file or stdin. The `init` command can be used to generate a starting template.")
+        .option("--from-file <path>", "Read a YAML or JSON file and create a workflow from its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and create a workflow from its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a workflow from a file",
+            command: "dx workflows create --from-file workflow.yaml",
+        },
+        {
+            label: "Create a workflow from stdin",
+            command: "cat workflow.json | dx workflows create --from-stdin",
+        },
+        {
+            label: "Same request with JSON output",
+            command: "dx --json workflows create --from-file workflow.yaml",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const modeCount = [options.fromFile, options.fromStdin].filter(Boolean).length;
+        if (modeCount === 0) {
+            throw new CliError("One of --from-file or --from-stdin is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (modeCount > 1) {
+            throw new CliError("--from-file and --from-stdin are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = await buildRuntime(getContext(command));
+        const raw = options.fromFile
+            ? readYamlFile(options.fromFile)
+            : await readYamlStdin();
+        const payload = parsePayloadObject(raw);
+        const response = await createWorkflow(runtime, payload);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderWorkflowCreated(response.workflow);
+        }
+    }));
+    workflows
+        .command("init")
+        .description("Write a blank Self-service workflow YAML template to a file")
+        .argument("<path>", "File path to write the YAML to")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Write a blank workflow template",
+            command: "dx workflows init ./my-workflow.yaml",
+        },
+    ]))
+        .action(wrapAction(async (path, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        fs.writeFileSync(path, WORKFLOW_BLANK_TEMPLATE_YAML, "utf8");
+        if (runtime.context.json) {
+            renderJson({ ok: true, path });
+        }
+        else {
+            renderRichText([
+                ui.p(`${ui.success(ui.GLYPHS.CHECK)} Blank template written to ${ui.code(path)}.`),
+                ui.p(`Edit the file, then run: ${ui.code(`dx workflows create --from-file ${path}`)}`),
+            ]);
+        }
+    }));
     workflows
         .command("list")
         .description("List Self-service workflows for the account")
@@ -49,6 +116,45 @@ export function workflowsCommand() {
     }));
     return workflows;
 }
+function readYamlFile(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new CliError(`Could not read file "${filePath}": ${err.message}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return parseYamlContent(content, `file "${filePath}"`);
+}
+async function readYamlStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => {
+            try {
+                resolve(parseYamlContent(Buffer.concat(chunks).toString("utf8"), "stdin"));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        process.stdin.on("error", (err) => reject(new CliError(`Failed to read from stdin: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR)));
+    });
+}
+function parseYamlContent(content, source) {
+    try {
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw new CliError(`Failed to parse YAML or JSON from ${source}: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+}
+function parsePayloadObject(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("Content must be a YAML or JSON object", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return raw;
+}
 function parseOptionalTrimmed(value) {
     if (typeof value !== "string") {
         return undefined;
@@ -67,6 +173,10 @@ function parseOptionalScope(value) {
     return raw;
 }
 // --- API ---
+export async function createWorkflow(runtime, payload) {
+    const response = await request(runtime, "/workflows.create", { method: "POST", body: payload });
+    return response.body;
+}
 export async function listWorkflows(runtime, params) {
     const query = {};
     if (params.scope !== undefined)

package/dist/commands/workflowsRendering.js

@@ -38,18 +38,30 @@ export function renderWorkflowList(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));
+        blocks.push(...workflowContent(workflow));
     }
     renderRichText(blocks);
 }
+export function renderWorkflowCreated(workflow) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Workflow created: ${ui.code(workflow.identifier)}`),
+        ...workflowContent(workflow),
+    ]);
+}
+function workflowContent(workflow) {
+    const blocks = [
+        ui.h2(`${workflow.name} (${ui.code(workflow.identifier)})`),
+        ui.h3("Core attributes"),
+        ...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));
+    return blocks;
+}
 function coreContent(workflow) {
     const blocks = [];
     const description = workflow.description?.trim()

package/dist/http.js

@@ -1,4 +1,4 @@
-import { HttpError } from "./errors.js";
+import { CliError, HttpError } from "./errors.js";
 export async function request(runtime, route, options = {}) {
     const method = options.method || "GET";
     const headers = new Headers({
@@ -72,6 +72,24 @@ export async function request(runtime, route, options = {}) {
     const body = parsedResponseBody;
     return retryAfterMs === undefined ? { body } : { body, retryAfterMs };
 }
+export async function requestWithMessages(runtime, route, options, messages) {
+    try {
+        const response = await request(runtime, route, options);
+        return response.body;
+    }
+    catch (error) {
+        throw runtime.context.json ? error : readableError(error, messages);
+    }
+}
+function readableError(error, messages) {
+    if (!(error instanceof HttpError)) {
+        return error;
+    }
+    const code = error.body?.error;
+    return typeof code === "string" && Object.hasOwn(messages, code)
+        ? new CliError(messages[code], error.exitCode)
+        : error;
+}
 /**
  * Flatten an error thrown by `fetch` into a single readable message.
  *

package/package.json

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