@sanity/workflow-cli 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @sanity/workflow-cli
+
+Command-line tool for deploying, inspecting, and administering Sanity workflow
+definitions and instances.
+
+> [!WARNING]
+> Early access, restricted. `retry-task` and `set-stage` are still stubs —
+> they print their parsed input and exit non-zero. The "wired" commands below
+> talk to a real Sanity dataset using `SANITY_*` env vars.
+
+## Run
+
+```bash
+pnpm --filter @sanity/workflow-cli dev <command> [...args]
+
+# Examples:
+pnpm --filter @sanity/workflow-cli dev --help
+pnpm --filter @sanity/workflow-cli dev deploy --dry-run
+pnpm --filter @sanity/workflow-cli dev list --in-flight
+pnpm --filter @sanity/workflow-cli dev show wf-instance.abc123
+```
+
+Copy the template and fill it in first: `cp ../../.env.example ../../.env`
+(from the repo root, `cp .env.example .env`). Env vars are read from
+the root `.env` (`SANITY_PROJECT_ID`, `SANITY_DATASET`,
+`SANITY_AUTH_TOKEN`). The dev script loads them via `tsx --env-file`.
+
+### Workflow target (resource + tags)
+
+The CLI targets one engine "resource" (a dataset, canvas, media
+library, or dashboard) tagged with one or more engine tags. Defaults
+match the bench fixtures the rest of this repo uses.
+
+| Env var                  | Default      | Allowed values                                          |
+| ------------------------ | ------------ | ------------------------------------------------------- |
+| `WORKFLOW_RESOURCE_TYPE` | `dataset`    | `dataset` / `canvas` / `media-library` / `dashboard`    |
+| `WORKFLOW_RESOURCE_ID`   | `test.test`  | any string                                              |
+| `WORKFLOW_TAG`           | _(required)_ | single environment tag, e.g. `prod` (`--tag` overrides) |
+| `WORKFLOW_DEFS`          | _(required)_ | module path or package exporting `allDefinitions`       |
+
+Invalid values fail with a clean error before the command runs.
+
+`WORKFLOW_DEFS` has no default — `deploy` is agnostic about which
+definitions it ships, so it must be told where to find them. Point it at a
+module (a path like `./src/workflows.ts`, or a package name) whose
+`allDefinitions` export is a `WorkflowDefinition[]`. This repo's own demo
+set lives in `@sanity/workflow-examples`, so `WORKFLOW_DEFS=@sanity/workflow-examples`
+deploys it.
+
+Run through the `dev` / `cli` scripts and this loads straight from
+TypeScript source — no build step between editing a definition and
+deploying it. Those scripts set `NODE_OPTIONS='--conditions=development'`
+and run under `tsx`, so a package specifier resolves to its `src/` via the
+`development` export condition and the `.ts` is transpiled on the fly. A
+built or standalone CLI instead resolves the package's compiled `dist`.
+
+> [!NOTE]
+> pnpm intercepts a handful of its own flag names (`--check`,
+> `--filter`, `--recursive`, …) when they appear after a script name.
+> To invoke `deploy --check`, run from inside the package or via
+> `pnpm exec`:
+>
+> ```bash
+> # from inside packages/workflow-cli
+> pnpm dev deploy --check
+>
+> # or, from anywhere
+> pnpm --filter @sanity/workflow-cli exec \
+>   env NODE_OPTIONS='--conditions=development' \
+>   tsx --env-file-if-exists=../../.env bin/dev.js deploy --check
+> ```
+>
+> `--dry-run` and `--only` don't collide with pnpm flags and work
+> through the normal `pnpm --filter … dev …` invocation.
+
+## Command status
+
+| Command                                    | Status                                                                                    |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `deploy`                                   | wired — calls `workflow.deployDefinitions` over the `WORKFLOW_DEFS` module                |
+| `deploy --check`                           | wired — runs `validateDefinition` over the local batch + a duplicate-id check             |
+| `deploy --dry-run`                         | wired — fetches existing docs and renders a coloured JSON diff per change                 |
+| `deploy --only <id>`                       | wired — filters deploy/check/dry-run to one `definition`                                  |
+| `list`                                     | wired — `client.fetch` over `workflow.instance` documents                                 |
+| `show <instance-id>`                       | wired — `client.getDocument`                                                              |
+| `diagnose <instance-id>`                   | wired — one `workflow.evaluate` call, classifies why the instance is/isn't progressing    |
+| `tail <instance-id>`                       | wired — `client.listen()` over the instance, prints new history entries                   |
+| `abort <instance-id>`                      | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards) |
+| `retry-task <instance-id> <task-id>`       | stub                                                                                      |
+| `move-stage <instance-id> --to <stage-id>` | wired — calls `workflow.setStage` (runs guards + onEnter effects)                         |
+| `fire-action <instance-id>`                | wired — `workflow.evaluate` lists actions; `workflow.fireAction` fires one                |
+| `set-stage <instance-id> --to <stage-id>`  | stub (engine has no guard-bypass path yet)                                                |
+| `definition list`                          | wired — `client.fetch` over `workflow.definition` documents                               |
+| `definition show <id>`                     | wired — `client.fetch`, latest version unless `--version`                                 |
+| `definition diff <id>`                     | wired — diffs the in-code definition against the deployed latest (`--version` to pin)     |
+| `definition delete <name>`                 | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)  |
+
+## Known gaps
+
+- **No `sanity workflow` plugin wiring yet.** The proposal targets the
+  Sanity CLI as a plugin host. The package publishes as a standalone
+  `sanity-workflows` binary today; plugging into `sanity` as an oclif
+  plugin is a separate piece of work.
+- **`set-stage` manual override.** The engine's `workflow.setStage`
+  always runs guards + effects; the proposal's "bypass" semantics
+  need engine work before this command can do anything useful.
+- **Actor identity.** Write paths default the actor to
+  `{ kind: "system", id: "workflow-cli" }` rather than resolving the real
+  user via `/users/me` (which a token-only CLI can't reach). `fire-action`
+  takes `--as <userId>` / `--as-role <role>` to attribute a fire to a real
+  user, so assignee- and role-gated action filters pass. Once we host inside
+  the Sanity CLI's auth flow, the real user can flow through everywhere.
+
+## Tech stack
+
+Mirrors the Sanity CLI's stack so the eventual plugin port is small:
+
+- [`@oclif/core`](https://oclif.io) for command definitions, flags,
+  help.
+- `@oclif/plugin-help` for help output.
+- `ora`, `boxen`, `log-symbols`, `console-table-printer`, `picocolors`
+  for terminal UX.
+- `diff` for the colored JSON unified diff in `deploy --dry-run`.

package/bin/run.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Production entry for the published package: loads the compiled commands
+// from ./dist/commands (per the `oclif.commands` field). The dev counterpart,
+// bin/dev.js, passes `development: true` to load TS sources instead.
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/commands/abort.d.ts

@@ -0,0 +1,30 @@
+import { Command } from '@oclif/core';
+export default class Abort extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        instanceId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+interface AbortOutcome {
+    fired: boolean;
+    instance: {
+        currentStage: string;
+        completedAt?: string | undefined;
+    };
+}
+/**
+ * Turn an `abortInstance` result into the spinner message. Pure so the
+ * fired / already-terminal permutations can be asserted without driving
+ * a real abort.
+ */
+export declare function abortReport(result: AbortOutcome): {
+    fired: boolean;
+    message: string;
+};
+export {};

package/dist/commands/abort.js

@@ -0,0 +1,62 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { workflow } from '@sanity/workflow-engine';
+import ora from 'ora';
+import pc from 'picocolors';
+import { loadClient } from "../lib/client.js";
+import { loadWorkflowConfig } from "../lib/config.js";
+import { fail } from "../lib/fail.js";
+import { tagFlags } from "../lib/flags.js";
+import { buildOperationArgs } from "../lib/operation-args.js";
+export default class Abort extends Command {
+    static description = 'Abort an in-flight workflow instance — a hard stop: pending effects are cancelled, stage guards lifted, and the instance is marked terminal where it stands.';
+    static examples = [
+        '<%= config.bin %> abort wf-instance.abc123',
+        "<%= config.bin %> abort wf-instance.abc123 --reason 'superseded by relaunch'",
+    ];
+    static args = {
+        instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        reason: Flags.string({ description: 'Reason for aborting (recorded in history).' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Abort);
+        const config = loadWorkflowConfig(flags.tag);
+        const client = loadClient();
+        const spinner = ora(`Aborting ${args.instanceId}…`).start();
+        try {
+            const result = await workflow.abortInstance({
+                client,
+                ...buildOperationArgs(config, args.instanceId, flags.reason),
+            });
+            const report = abortReport(result);
+            if (!report.fired) {
+                spinner.warn(report.message);
+                return;
+            }
+            spinner.succeed(report.message);
+        }
+        catch (error) {
+            spinner.fail('Abort rejected');
+            const message = error instanceof Error ? error.message : String(error);
+            fail('abortInstance error:', message);
+        }
+    }
+}
+/**
+ * Turn an `abortInstance` result into the spinner message. Pure so the
+ * fired / already-terminal permutations can be asserted without driving
+ * a real abort.
+ */
+export function abortReport(result) {
+    const stage = pc.bold(result.instance.currentStage);
+    if (!result.fired) {
+        const at = result.instance.completedAt ?? 'unknown';
+        return {
+            fired: false,
+            message: `abortInstance returned without firing — instance is already terminal (at ${stage} since ${at})`,
+        };
+    }
+    return { fired: true, message: `Aborted — instance hard-stopped at ${stage}` };
+}

package/dist/commands/definition/delete.d.ts

@@ -0,0 +1,36 @@
+import { Command } from '@oclif/core';
+import { type DeleteDefinitionArgs, type DeleteDefinitionResult } from '@sanity/workflow-engine';
+import { type WorkflowConfig } from '../../lib/config.ts';
+export default class DefinitionDelete extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        cascade: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * The shared engine args ({@link baseEngineArgs}) plus the delete-specific
+ * targeting. `version` and `reason` spread conditionally because the
+ * engine's optionals reject an explicit `undefined` under
+ * `exactOptionalPropertyTypes`.
+ */
+export declare function buildDeleteArgs(config: WorkflowConfig, name: string, flags: {
+    version?: number | undefined;
+    cascade: boolean;
+    reason?: string | undefined;
+}): Omit<DeleteDefinitionArgs, 'client'>;
+/** What the spinner names: the workflow, or one pinned version of it. */
+export declare function deleteTargetLabel(args: Pick<DeleteDefinitionArgs, 'definition' | 'version'>): string;
+/**
+ * Turn a `deleteDefinition` result into the spinner message. Pure so the
+ * version / cascade / guard permutations can be asserted without driving
+ * a real delete.
+ */
+export declare function deleteReport(result: DeleteDefinitionResult): string;

package/dist/commands/definition/delete.js

@@ -0,0 +1,86 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { workflow, } from '@sanity/workflow-engine';
+import ora from 'ora';
+import pc from 'picocolors';
+import { loadClient } from "../../lib/client.js";
+import { loadWorkflowConfig } from "../../lib/config.js";
+import { fail } from "../../lib/fail.js";
+import { tagFlags } from "../../lib/flags.js";
+import { baseEngineArgs } from "../../lib/operation-args.js";
+export default class DefinitionDelete extends Command {
+    static description = 'Delete a deployed workflow definition (every version, or one via --version). ' +
+        'Refuses while non-terminal instances exist unless --cascade aborts them first — ' +
+        'instances are aborted in place, never deleted.';
+    static examples = [
+        '<%= config.bin %> definition delete my-workflow',
+        '<%= config.bin %> definition delete my-workflow --version 2',
+        "<%= config.bin %> definition delete my-workflow --cascade --reason 'workflow retired'",
+    ];
+    static args = {
+        name: Args.string({ required: true, description: 'Workflow definition name.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        version: Flags.integer({
+            description: 'Delete only this deployed version (default: every version).',
+        }),
+        cascade: Flags.boolean({
+            description: 'Abort every non-terminal instance pinned to the targeted versions, then delete.',
+            default: false,
+        }),
+        reason: Flags.string({
+            description: 'Free-text reason — recorded on each cascade-abort history entry.',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(DefinitionDelete);
+        const config = loadWorkflowConfig(flags.tag);
+        const client = loadClient();
+        const deleteArgs = buildDeleteArgs(config, args.name, flags);
+        const spinner = ora(`Deleting definition ${deleteTargetLabel(deleteArgs)}…`).start();
+        try {
+            const result = await workflow.deleteDefinition({ client, ...deleteArgs });
+            spinner.succeed(deleteReport(result));
+        }
+        catch (error) {
+            spinner.fail('Delete rejected');
+            const message = error instanceof Error ? error.message : String(error);
+            fail('deleteDefinition error:', message);
+        }
+    }
+}
+/**
+ * The shared engine args ({@link baseEngineArgs}) plus the delete-specific
+ * targeting. `version` and `reason` spread conditionally because the
+ * engine's optionals reject an explicit `undefined` under
+ * `exactOptionalPropertyTypes`.
+ */
+export function buildDeleteArgs(config, name, flags) {
+    return {
+        ...baseEngineArgs(config),
+        definition: name,
+        cascade: flags.cascade,
+        ...(flags.version !== undefined ? { version: flags.version } : {}),
+        ...(flags.reason !== undefined ? { reason: flags.reason } : {}),
+    };
+}
+/** What the spinner names: the workflow, or one pinned version of it. */
+export function deleteTargetLabel(args) {
+    return args.version === undefined ? args.definition : `${args.definition} v${args.version}`;
+}
+/**
+ * Turn a `deleteDefinition` result into the spinner message. Pure so the
+ * version / cascade / guard permutations can be asserted without driving
+ * a real delete.
+ */
+export function deleteReport(result) {
+    const versions = result.deletedVersions.map((v) => `v${v}`).join(', ');
+    const parts = [`Deleted ${pc.bold(result.name)} ${versions}`];
+    if (result.abortedInstanceIds.length > 0) {
+        parts.push(`aborted ${result.abortedInstanceIds.length} instance(s)`);
+    }
+    if (result.deletedGuardCount > 0) {
+        parts.push(`removed ${result.deletedGuardCount} orphaned guard doc(s)`);
+    }
+    return parts.join(' — ');
+}

package/dist/commands/definition/diff.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class DefinitionDiff extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        definition: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/definition/diff.js

@@ -0,0 +1,57 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { diffEntry } from '@sanity/workflow-engine';
+import ora from 'ora';
+import { loadClient } from "../../lib/client.js";
+import { loadWorkflowConfig } from "../../lib/config.js";
+import { loadValidatedDefinition } from "../../lib/definitions.js";
+import { diffReport } from "../../lib/diff.js";
+import { fail } from "../../lib/fail.js";
+import { tagFlags } from "../../lib/flags.js";
+import { buildDefinitionShowQuery } from "./show.js";
+export default class DefinitionDiff extends Command {
+    static description = 'Diff an in-code definition against the deployed version (latest by default).';
+    static examples = [
+        '<%= config.bin %> definition diff productLaunch',
+        '<%= config.bin %> definition diff productLaunch --version 2',
+    ];
+    static args = {
+        definition: Args.string({ required: true, description: 'Workflow definition name.' }),
+    };
+    static flags = {
+        ...tagFlags,
+        version: Flags.integer({ description: 'Deployed version to diff against (default: latest).' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(DefinitionDiff);
+        const config = loadWorkflowConfig(flags.tag);
+        const def = await loadValidatedDefinition(args.definition);
+        const client = loadClient();
+        const spinner = ora(`Diffing ${args.definition} against deployed…`).start();
+        let deployed;
+        try {
+            deployed = await fetchDeployedDefinition(client, args.definition, config, flags.version);
+            spinner.succeed(`Diffed ${args.definition} v${def.version}`);
+        }
+        catch (error) {
+            spinner.fail('Diff failed');
+            throw error;
+        }
+        for (const line of diffReport([diffEntry(def, deployed, config)]))
+            this.log(line);
+    }
+}
+/**
+ * Fetch the deployed document to compare against. Unlike `deploy
+ * --dry-run` (which looks up the exact docId, so a version bump always
+ * reads as "create"), diff targets the deployed version that would be
+ * superseded — latest unless pinned via `version`. An absent latest is a
+ * legitimate "create" diff, but an absent *pinned* version is an error.
+ */
+async function fetchDeployedDefinition(client, name, config, version) {
+    const { groq, params } = buildDefinitionShowQuery({ name, tag: config.tag, version });
+    const deployed = await client.fetch(groq, params);
+    if (deployed === null && version !== undefined) {
+        fail(`No deployed definition "${name}" v${version}.`);
+    }
+    return deployed ?? undefined;
+}

package/dist/commands/definition/list.d.ts

@@ -0,0 +1,31 @@
+import { Command } from '@oclif/core';
+interface DefinitionListFlags {
+    tag?: string | undefined;
+    'workflow-id'?: string | undefined;
+    limit: number;
+}
+export interface DefinitionListRow {
+    _id: string;
+    name: string;
+    version: number;
+    title: string;
+    tag: string;
+    stageCount: number;
+    inFlightCount: number;
+    totalInstances: number;
+}
+export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
+    groq: string;
+    params: Record<string, unknown>;
+};
+export default class DefinitionList extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'workflow-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+export {};

package/dist/commands/definition/list.js

@@ -0,0 +1,83 @@
+import { Command, Flags } from '@oclif/core';
+import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { Table } from 'console-table-printer';
+import logSymbols from 'log-symbols';
+import { loadClient } from "../../lib/client.js";
+import { tagFlags } from "../../lib/flags.js";
+export function buildDefinitionListQuery(flags) {
+    const params = { limit: flags.limit };
+    const filters = [`_type == "${WORKFLOW_DEFINITION_TYPE}"`];
+    const instanceFilters = [
+        `_type == "${WORKFLOW_INSTANCE_TYPE}"`,
+        'definition == ^.name',
+        'pinnedVersion == ^.version',
+        // Correlate the count to each definition's own partition. Listing
+        // can span partitions (when `--tag` is omitted), and two partitions
+        // can hold a same-named, same-version definition — without this, one
+        // row's count would bleed in the other partition's instances.
+        'tag == ^.tag',
+    ];
+    if (flags.tag) {
+        params.tag = flags.tag;
+        filters.push(tagScopeFilter());
+    }
+    if (flags['workflow-id']) {
+        params.name = flags['workflow-id'];
+        filters.push('name == $name');
+    }
+    const instanceMatch = instanceFilters.join(' && ');
+    const groq = `*[${filters.join(' && ')}] | order(name asc, version desc) [0...$limit]{
+      _id,
+      name,
+      version,
+      title,
+      tag,
+      "stageCount": count(stages),
+      "inFlightCount": count(*[${instanceMatch} && !defined(completedAt)]),
+      "totalInstances": count(*[${instanceMatch}])
+    }`;
+    return { groq, params };
+}
+export default class DefinitionList extends Command {
+    static description = 'List deployed workflow definitions.';
+    static examples = [
+        '<%= config.bin %> definition list',
+        '<%= config.bin %> definition list --tag prod',
+    ];
+    static flags = {
+        ...tagFlags,
+        limit: Flags.integer({
+            description: 'The maximum number of definitions to return.',
+            default: 100,
+        }),
+        'workflow-id': Flags.string({
+            description: 'Filter to a single workflow definition name (e.g. product-launch)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DefinitionList);
+        const { groq, params } = buildDefinitionListQuery(flags);
+        const client = loadClient();
+        const rows = await client.fetch(groq, params);
+        if (!rows.length) {
+            this.log(`${logSymbols.info} no definitions found`);
+            return;
+        }
+        const table = new Table({
+            columns: [
+                { name: '_id', title: 'Definition ID', alignment: 'left' },
+                { name: 'title', title: 'Title', alignment: 'left' },
+                { name: 'name', title: 'Workflow', alignment: 'left' },
+                { name: 'tag', title: 'Tag', alignment: 'left' },
+                { name: 'version', title: 'Version', alignment: 'right' },
+                { name: 'stageCount', title: 'Total stages', alignment: 'right' },
+                { name: 'inFlightCount', title: 'Instances in flight', alignment: 'right' },
+                { name: 'totalInstances', title: 'Total instances', alignment: 'right' },
+            ],
+        });
+        for (const r of rows) {
+            table.addRow(r);
+        }
+        table.printTable();
+    }
+}

package/dist/commands/definition/show.d.ts

@@ -0,0 +1,33 @@
+import { Command } from '@oclif/core';
+import { type WorkflowDefinition } from '@sanity/workflow-engine';
+interface DefinitionShowFlags {
+    name: string;
+    tag?: string | undefined;
+    version?: number | undefined;
+}
+export declare function buildDefinitionShowQuery(flags: DefinitionShowFlags): {
+    groq: string;
+    params: Record<string, unknown>;
+};
+export default class DefinitionShow extends Command {
+    static description: string;
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+/**
+ * The boxed summary block at the top of `definition show` output. `columns`
+ * is the terminal width; values wrap to fit it so `boxen` never re-wraps them.
+ */
+export declare function definitionHeader(def: WorkflowDefinition, columns?: number): string;
+/**
+ * The body lines for `definition show`: every stage with its tasks and each
+ * task's actions. Pure so it can be asserted without driving the oclif command.
+ */
+export declare function describeDefinition(def: WorkflowDefinition): string[];
+export {};