@sanity/workflow-cli 0.8.0 → 0.9.0

package/README.md

@@ -4,9 +4,9 @@ Command-line tool for deploying, inspecting, and administering Sanity workflow
 definitions and instances.
 
 > [!WARNING]
-> Early access, restricted. `retry-activity` 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.
+> Early access, restricted. The commands below talk to a real Sanity dataset,
+> configured by a `sanity.workflow.ts` file and authenticated with
+> `sanity login`.
 
 ## Run
 
@@ -20,39 +20,74 @@ 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.
+Authenticate once with `sanity login` (the CLI reads that session token); for
+CI, set `SANITY_AUTH_TOKEN` instead. Then create a `sanity.workflow.ts` in the
+directory you run from — see [Configuration](#configuration).
+
+## Configuration
+
+The CLI is configured by a `sanity.workflow.ts` (or `.js`/`.mjs`) discovered in
+the directory you run from. It exports a config built with
+`defineWorkflowConfig`, declaring one **deployment** per environment:
+
+```ts
+import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
+
+import {articleReview, urlDraft} from './src/workflows.ts'
+
+export default defineWorkflowConfig({
+  deployments: [
+    {
+      name: 'production',
+      tag: 'prod', // the environment partition the engine's docs are scoped to
+      workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
+      resourceAliases: [
+        // binds each `@<handle>:` a definition references to a physical resource
+        // in a DIFFERENT dataset from `workflowResource` (same-resource content
+        // needs no alias — see below)
+        {name: 'content', resource: {type: 'dataset', id: 'acme.content'}},
+        {name: 'assets', resource: {type: 'dataset', id: 'acme.assets'}},
+      ],
+      definitions: [articleReview, urlDraft], // the batch this deployment ships
+    },
+  ],
+})
+```
 
-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`.
+Pick a deployment with `--tag <tag>`; with a single deployment configured you
+can omit it, and with several configured a bare `deploy` fails asking for
+`--tag` or `--all-tags`. `--all-tags` deploys every deployment in the config in
+one run: a failure in one doesn't stop the rest — the run continues, prints a
+summary of what failed, and exits non-zero. The client's project + dataset are derived
+from the deployment's `workflowResource`, and `deploy` expands each
+definition's `@<handle>:` reference to the bound physical resource. An invalid
+config fails with a clean, path-prefixed error before the command runs.
+
+`resourceAliases` is only for content that lives in a _different_ resource from
+`workflowResource`. A definition can reference a document in the **same**
+resource by bare id, no alias needed — bare ids root at `workflowResource` at
+runtime. Rule of thumb: **different resource → bind an alias and reference it as
+`@<handle>:<id>`; same resource → use a bare id and omit `resourceAliases`
+entirely.** So the simplest single-dataset setup is just a `workflowResource`
+and `definitions`, with no `resourceAliases` at all.
+
+| Var                 | Purpose                                                                     |
+| ------------------- | --------------------------------------------------------------------------- |
+| `SANITY_AUTH_TOKEN` | CI fallback when there's no `sanity login` session (editor role for writes) |
+| `SANITY_API_HOST`   | Optional API host override (defaults to the prod API)                       |
+
+Run through the `dev` / `cli` scripts and the CLI itself and your
+`sanity.workflow.ts` load straight from TypeScript source: the scripts set
+`NODE_OPTIONS='--conditions=development'` under `tsx`, and the config file is
+transpiled on the fly by `jiti`. Definitions you author **inline** in the
+config, or import by **relative path**, transpile the same way — no build step.
+
+One caveat: a definition imported from a _separate workspace package_ (e.g.
+`@sanity/workflow-examples`) resolves to that package's built `dist/`. `jiti`
+applies its own module resolution and does **not** honour
+`--conditions=development`, so it never picks up a package's `src/` export
+condition — rebuild that package after editing it, or the config loads its
+stale compiled output.
 
 > [!NOTE]
 > pnpm intercepts a handful of its own flag names (`--check`,
@@ -75,25 +110,25 @@ built or standalone CLI instead resolves the package's compiled `dist`.
 
 ## 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-activity <instance-id> <activity-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`)  |
+| Command                                | Status                                                                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                       |
+| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                     |
+| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                             |
+| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                   |
+| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                            |
+| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields, `--as` for attribution)                                 |
+| `list`                                 | wired — `client.fetch` over `workflow.instance` documents (`--definition <name>` to filter)                                 |
+| `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)                                   |
+| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run) |
+| `fire-action <instance-id>`            | wired — `workflow.evaluate` lists actions; `workflow.fireAction` fires one                                                  |
+| `definition list`                      | wired — `client.fetch` over `workflow.definition` documents                                                                 |
+| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                   |
+| `definition diff <name>`               | 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
 
@@ -101,15 +136,18 @@ built or standalone CLI instead resolves the package's compiled `dist`.
   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.
+- **No true bypass.** `set-stage` is the engine's `setStage` admin
+  override: it skips the definition's declared transitions and filters, but
+  the target stage's enter lifecycle and the post-move cascade still run. A
+  command that also bypasses guards + enter effects (`force-stage`) needs
+  engine work that hasn't landed.
 - **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.
+  user via `/users/me` (which a token-only CLI can't reach). `start` and
+  `fire-action` take `--as <userId>` / `--as-role <role>` to attribute the
+  write to a real user, so assignee- and role-gated filters pass. Once we
+  host inside the Sanity CLI's auth flow, the real user can flow through
+  everywhere.
 
 ## Tech stack
 

package/dist/commands/abort.d.ts

@@ -1,4 +1,5 @@
 import { Command } from '@oclif/core';
+import { type WorkflowInstance } from '@sanity/workflow-engine';
 export default class Abort extends Command {
     static description: string;
     static examples: string[];
@@ -12,19 +13,16 @@ export default class Abort extends Command {
     run(): Promise<void>;
 }
 interface AbortOutcome {
-    fired: boolean;
-    instance: {
-        currentStage: string;
-        completedAt?: string | undefined;
-    };
+    changed: boolean;
+    instance: Pick<WorkflowInstance, 'currentStage' | 'completedAt'>;
 }
 /**
  * Turn an `abortInstance` result into the spinner message. Pure so the
- * fired / already-terminal permutations can be asserted without driving
+ * aborted / already-terminal permutations can be asserted without driving
  * a real abort.
  */
 export declare function abortReport(result: AbortOutcome): {
-    fired: boolean;
+    changed: boolean;
     message: string;
 };
 export {};

package/dist/commands/abort.js

@@ -2,9 +2,8 @@ import { styleText } from 'node:util';
 import { Args, Command, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
 import ora from 'ora';
-import { loadClient } from "../lib/client.js";
-import { loadWorkflowConfig } from "../lib/config.js";
-import { fail } from "../lib/fail.js";
+import { resolveInstanceContext } from "../lib/context.js";
+import { errorMessage, fail } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { buildOperationArgs } from "../lib/operation-args.js";
 export default class Abort extends Command {
@@ -22,16 +21,19 @@ export default class Abort extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Abort);
-        const config = loadWorkflowConfig(flags.tag);
-        const client = loadClient();
+        const { client, scope } = await resolveInstanceContext(flags, args.instanceId);
         const spinner = ora(`Aborting ${args.instanceId}…`).start();
         try {
             const result = await workflow.abortInstance({
                 client,
-                ...buildOperationArgs(config, args.instanceId, flags.reason),
+                ...buildOperationArgs({
+                    scope,
+                    instanceId: args.instanceId,
+                    reason: flags.reason,
+                }),
             });
             const report = abortReport(result);
-            if (!report.fired) {
+            if (!report.changed) {
                 spinner.warn(report.message);
                 return;
             }
@@ -39,24 +41,23 @@ export default class Abort extends Command {
         }
         catch (error) {
             spinner.fail('Abort rejected');
-            const message = error instanceof Error ? error.message : String(error);
-            fail('abortInstance error:', message);
+            fail('abort error:', errorMessage(error));
         }
     }
 }
 /**
  * Turn an `abortInstance` result into the spinner message. Pure so the
- * fired / already-terminal permutations can be asserted without driving
+ * aborted / already-terminal permutations can be asserted without driving
  * a real abort.
  */
 export function abortReport(result) {
     const stage = styleText('bold', result.instance.currentStage);
-    if (!result.fired) {
+    if (!result.changed) {
         const at = result.instance.completedAt ?? 'unknown';
         return {
-            fired: false,
-            message: `abortInstance returned without firing — instance is already terminal (at ${stage} since ${at})`,
+            changed: false,
+            message: `abortInstance changed nothing — instance is already terminal (at ${stage} since ${at})`,
         };
     }
-    return { fired: true, message: `Aborted — instance hard-stopped at ${stage}` };
+    return { changed: true, message: `Aborted — instance hard-stopped at ${stage}` };
 }

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

@@ -1,6 +1,6 @@
 import { Command } from '@oclif/core';
 import { type DeleteDefinitionArgs, type DeleteDefinitionResult } from '@sanity/workflow-engine';
-import { type WorkflowConfig } from '../../lib/config.ts';
+import { type EngineScope } from '../../lib/operation-args.ts';
 export default class DefinitionDelete extends Command {
     static description: string;
     static examples: string[];
@@ -21,11 +21,15 @@ export default class DefinitionDelete extends Command {
  * 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'>;
+export declare function buildDeleteArgs({ scope, name, flags, }: {
+    scope: EngineScope;
+    name: string;
+    flags: {
+        version?: number | undefined;
+        cascade: boolean;
+        reason?: string | undefined;
+    };
+}): DeleteDefinitionArgs & EngineScope;
 /** What the spinner names: the workflow, or one pinned version of it. */
 export declare function deleteTargetLabel(args: Pick<DeleteDefinitionArgs, 'definition' | 'version'>): string;
 /**

package/dist/commands/definition/delete.js

@@ -2,11 +2,10 @@ import { styleText } from 'node:util';
 import { Args, Command, Flags } from '@oclif/core';
 import { workflow, } from '@sanity/workflow-engine';
 import ora from 'ora';
-import { loadClient } from "../../lib/client.js";
-import { loadWorkflowConfig } from "../../lib/config.js";
-import { fail } from "../../lib/fail.js";
+import { resolveContext } from "../../lib/context.js";
+import { errorMessage, fail } from "../../lib/fail.js";
 import { tagFlags } from "../../lib/flags.js";
-import { baseEngineArgs } from "../../lib/operation-args.js";
+import { SYSTEM_ACTOR, 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 — ' +
@@ -34,9 +33,8 @@ export default class DefinitionDelete extends Command {
     };
     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 { deployment, client } = await resolveContext(flags);
+        const deleteArgs = buildDeleteArgs({ scope: deployment, name: args.name, flags });
         const spinner = ora(`Deleting definition ${deleteTargetLabel(deleteArgs)}…`).start();
         try {
             const result = await workflow.deleteDefinition({ client, ...deleteArgs });
@@ -44,8 +42,7 @@ export default class DefinitionDelete extends Command {
         }
         catch (error) {
             spinner.fail('Delete rejected');
-            const message = error instanceof Error ? error.message : String(error);
-            fail('deleteDefinition error:', message);
+            fail('definition delete error:', errorMessage(error));
         }
     }
 }
@@ -55,9 +52,9 @@ export default class DefinitionDelete extends Command {
  * engine's optionals reject an explicit `undefined` under
  * `exactOptionalPropertyTypes`.
  */
-export function buildDeleteArgs(config, name, flags) {
+export function buildDeleteArgs({ scope, name, flags, }) {
     return {
-        ...baseEngineArgs(config),
+        ...baseEngineArgs(scope, SYSTEM_ACTOR),
         definition: name,
         cascade: flags.cascade,
         ...(flags.version !== undefined ? { version: flags.version } : {}),

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

@@ -1,9 +1,10 @@
 import { Command } from '@oclif/core';
+import { type WorkflowDefinition } from '@sanity/workflow-engine';
 export default class DefinitionDiff extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        definition: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        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>;
@@ -11,3 +12,9 @@ export default class DefinitionDiff extends Command {
     };
     run(): Promise<void>;
 }
+/**
+ * Pick the single definition to diff by name and validate it, failing cleanly
+ * when it's missing from the deployment or doesn't pass validation. Extracted
+ * from `run` so the command's orchestration stays thin and this stays testable.
+ */
+export declare function selectDefinitionToDiff(definitions: WorkflowDefinition[], name: string): WorkflowDefinition;

package/dist/commands/definition/diff.js

@@ -1,13 +1,11 @@
 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 { resolveContext } from "../../lib/context.js";
+import { fetchDeployedDefinition, selectDefinitions, validateOrFail } 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";
+import { deploymentToTarget } from "../../lib/select-deployment.js";
 export default class DefinitionDiff extends Command {
     static description = 'Diff an in-code definition against the deployed version (latest by default).';
     static examples = [
@@ -15,7 +13,7 @@ export default class DefinitionDiff extends Command {
         '<%= config.bin %> definition diff productLaunch --version 2',
     ];
     static args = {
-        definition: Args.string({ required: true, description: 'Workflow definition name.' }),
+        name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
         ...tagFlags,
@@ -23,35 +21,43 @@ export default class DefinitionDiff extends Command {
     };
     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();
+        const { deployment, client } = await resolveContext(flags);
+        const def = selectDefinitionToDiff(deployment.definitions, args.name);
+        const target = deploymentToTarget(deployment);
+        const spinner = ora(`Diffing ${args.name} against deployed…`).start();
         let deployed;
         try {
-            deployed = await fetchDeployedDefinition(client, args.definition, config, flags.version);
-            spinner.succeed(`Diffed ${args.definition}`);
+            // An absent latest is a legitimate "create" diff, so `undefined`
+            // flows straight into the diff entry.
+            deployed = await fetchDeployedDefinition({
+                client,
+                name: args.name,
+                tag: target.tag,
+                version: flags.version,
+            });
+            spinner.succeed(`Diffed ${args.name}`);
         }
         catch (error) {
             spinner.fail('Diff failed');
             throw error;
         }
-        for (const line of diffReport([diffEntry(def, deployed, config)]))
+        for (const line of diffReport([diffEntry({ def, latestRaw: deployed, target })]))
             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.
+ * Pick the single definition to diff by name and validate it, failing cleanly
+ * when it's missing from the deployment or doesn't pass validation. Extracted
+ * from `run` so the command's orchestration stays thin and this stays testable.
  */
-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}.`);
+export function selectDefinitionToDiff(definitions, name) {
+    const [def] = selectDefinitions(definitions, { only: name });
+    // selectDefinitions already fails on no-match (naming the available defs), so
+    // a named lookup always yields at least one — this narrows the type, it is
+    // not a reachable failure.
+    if (def === undefined) {
+        throw new Error(`selectDefinitions returned no match for "${name}"`);
     }
-    return deployed ?? undefined;
+    validateOrFail([def]);
+    return def;
 }

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

@@ -1,8 +1,8 @@
 import { Command } from '@oclif/core';
-import { type WorkflowRole } from '@sanity/workflow-engine';
+import { type WorkflowLifecycle } from '@sanity/workflow-engine';
 interface DefinitionListFlags {
     tag?: string | undefined;
-    'workflow-name'?: string | undefined;
+    name?: string | undefined;
     limit: number;
 }
 export interface DefinitionListRow {
@@ -10,7 +10,7 @@ export interface DefinitionListRow {
     version: number;
     title: string;
     tag: string;
-    role?: WorkflowRole;
+    lifecycle?: WorkflowLifecycle;
     stageCount: number;
     inFlightCount: number;
     totalInstances: number;
@@ -24,7 +24,7 @@ export default class DefinitionList extends Command {
     static examples: string[];
     static flags: {
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
-        'workflow-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        name: 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>;

package/dist/commands/definition/list.js

@@ -2,7 +2,7 @@ import { Command, Flags } from '@oclif/core';
 import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, isStartableDefinition, tagScopeFilter, } from '@sanity/workflow-engine';
 import { Table } from 'console-table-printer';
 import logSymbols from 'log-symbols';
-import { loadClient } from "../../lib/client.js";
+import { resolveReadContext } from "../../lib/context.js";
 import { tagFlags } from "../../lib/flags.js";
 export function buildDefinitionListQuery(flags) {
     const params = { limit: flags.limit };
@@ -21,8 +21,8 @@ export function buildDefinitionListQuery(flags) {
         params.tag = flags.tag;
         filters.push(tagScopeFilter());
     }
-    if (flags['workflow-name']) {
-        params.name = flags['workflow-name'];
+    if (flags.name) {
+        params.name = flags.name;
         filters.push('name == $name');
     }
     const instanceMatch = instanceFilters.join(' && ');
@@ -31,7 +31,7 @@ export function buildDefinitionListQuery(flags) {
       version,
       title,
       tag,
-      role,
+      lifecycle,
       "stageCount": count(stages),
       "inFlightCount": count(*[${instanceMatch} && !defined(completedAt)]),
       "totalInstances": count(*[${instanceMatch}])
@@ -50,14 +50,14 @@ export default class DefinitionList extends Command {
             description: 'The maximum number of definitions to return.',
             default: 100,
         }),
-        'workflow-name': Flags.string({
-            description: 'Filter to a single workflow definition name (e.g. product-launch)',
+        name: Flags.string({
+            description: 'Filter to a single workflow definition name (e.g. product-launch).',
         }),
     };
     async run() {
         const { flags } = await this.parse(DefinitionList);
+        const { client } = await resolveReadContext(flags);
         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`);
@@ -81,7 +81,7 @@ export default class DefinitionList extends Command {
             // `definition show` title). Only declared keys are passed — console-table-
             // printer renders any extra key as a stray column.
             //
-            // `child`-role defs are spawn-only; the Startable column tells an admin
+            // `lifecycle: 'child'` defs are spawn-only; the Startable column tells an admin
             // which definitions a human can actually start standalone.
             table.addRow({
                 workflow: `${r.name} v${r.version}`,

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

@@ -1,14 +1,5 @@
 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: {
@@ -32,4 +23,3 @@ export declare function definitionHeader(def: WorkflowDefinition & {
  * activity's actions. Pure so it can be asserted without driving the oclif command.
  */
 export declare function describeDefinition(def: WorkflowDefinition): string[];
-export {};