@sanity/workflow-cli 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @sanity/workflow-cli
 
+## 0.14.0
+
+### Minor Changes
+
+- 59b40fd: **BREAKING:** deployment selection now keys on the deployment `name`, selected with `--deployment`. Deployment-targeted commands (`start`, `definition diff`, `definition delete`, `nuke`) take `--deployment` as the precise selector; `--tag` still selects while it names exactly one deployment and errors listing the candidates when it spans several. `deploy --tag <tag>` now deploys every deployment carrying the tag (a tag is an environment group); `--deployment` deploys one, `--all-tags` deploys everything, and the three are mutually exclusive. `nuke` requires exactly one of `--deployment` / `--tag`, and refuses when another same-tag deployment sweeps an overlapping resource — guard document ids embed only the tag, so within a shared dataset the sweep cannot tell the deployments' guards apart and would delete the other's live locks. The interactive deploy prompt selects by name with the tag as its description. Read commands keep `--tag` as an optional filter — a repeated tag fans reads out across every resource it is deployed to.
+- de7ccfa: The instance-keyed commands (`diagnose`, `abort`, `set-stage`, `fire-action`) accept `--deployment <name>` to choose which resource to read the instance from — the precise selector consistent with the deployment-targeted commands. `--deployment` names one deployment and reads from the resource it targets; `--tag` stays the optional narrower it was, and the instance's own tag partition still comes from the loaded instance itself, never from the flag. This closes the dead end where a tag repeated across several resources left these commands unable to resolve a resource, and the "spans multiple resources" failures now point at `--deployment` as the remedy.
+
+### Patch Changes
+
+- Updated dependencies [24b11dd]
+- Updated dependencies [2005ab7]
+- Updated dependencies [24b11dd]
+- Updated dependencies [59b40fd]
+  - @sanity/workflow-engine@0.19.0
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -49,7 +49,8 @@ project will fail on cross-resource reads.
 
 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:
+`defineWorkflowConfig`, declaring your **deployments** (typically one per
+environment):
 
 ```ts
 import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
@@ -60,7 +61,7 @@ export default defineWorkflowConfig({
   deployments: [
     {
       expectedMinReaderModel: 2,
-      name: 'production',
+      name: 'production', // the deployment's unique identity (lowercase letters, digits, dashes)
       tag: 'prod', // the environment partition the engine's docs are scoped to
       workflowResource: {type: 'dataset', id: 'acme.workflows'}, // where those docs live
       resourceAliases: [
@@ -76,11 +77,20 @@ export default defineWorkflowConfig({
 })
 ```
 
-Pick a deployment with `--tag <tag>`; with a single deployment configured you
-can omit it. With several configured, a bare interactive `deploy` presents a
-keyboard-driven tag selector. In CI or another non-interactive shell, it fails
-asking for `--tag` or `--all-tags` instead of blocking for input. `--all-tags`
-deploys every deployment in the config in one run: a failure in one doesn't
+`name` is the deployment's identity: unique across the config and constrained
+to the same grammar as `tag`. Tags group deployments by environment and may
+repeat, as long as no two deployments share both a `workflowResource` and a
+`tag` — that pair is the storage partition, and the config rejects the
+collision naming both entries.
+
+Pick a deployment with `--deployment <name>`; with a single deployment configured you
+can omit it. `--tag <tag>` also works on single-deployment commands while the
+tag names exactly one deployment — on `deploy` it targets every deployment
+carrying the tag (a tag is an environment group). With several configured, a
+bare interactive `deploy` presents a keyboard-driven deployment selector (by
+name, tag alongside). In CI or another non-interactive shell, it fails asking
+for `--deployment`, `--tag`, or `--all-tags` instead of blocking for input.
+`--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>:`
@@ -143,26 +153,26 @@ stale compiled output.
 
 ## Command status
 
-| 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)                                                                                                                              |
-| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                               |
-| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                                                                                     |
-| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, 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, removes 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.availableActions` lists actions; `workflow.fireAction` fires one                                                                                                               |
-| `definition list`                      | wired — `client.fetch` over `sanity.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`)                                                                                                         |
-| `nuke --tag <tag>`                     | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the tag (instances, definitions, guards across resources); plan + typed confirm |
+| 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)                                                                                                                                                                                                                                                                                   |
+| `list`                                          | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                                                                                                                                                                                    |
+| `show <instance-id>`                            | wired — `client.getDocument`                                                                                                                                                                                                                                                                                                                          |
+| `diagnose <instance-id>`                        | wired — calls `workflow.diagnose`, 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, removes 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.availableActions` lists actions; `workflow.fireAction` fires one                                                                                                                                                                                                                                                                    |
+| `definition list`                               | wired — `client.fetch` over `sanity.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`)                                                                                                                                                                                                                                                              |
+| `nuke --deployment <name>` / `nuke --tag <tag>` | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the deployment's tag (instances, definitions, guards across resources); exactly one selector required; refuses while another same-tag deployment sweeps an overlapping resource (guard ids embed only the tag); plan + typed confirm |
 
 ## Telemetry
 

package/dist/commands/editorial-workflows/abort.d.ts

@@ -10,6 +10,7 @@ export default class Abort extends WorkflowCommand {
     };
     static flags: {
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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/editorial-workflows/abort.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
-import { tagFlags } from "../../lib/flags.js";
+import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 export default class Abort extends WorkflowCommand {
@@ -17,7 +17,7 @@ export default class Abort extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         reason: Flags.string({ description: 'Reason for aborting (recorded in history).' }),
     };
     async run() {

package/dist/commands/editorial-workflows/definition/delete.d.ts

@@ -12,6 +12,7 @@ export default class DefinitionDelete extends WorkflowCommand {
         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>;
+        deployment: 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/editorial-workflows/definition/delete.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow, } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../../lib/base-command.js";
 import { resolveContext } from "../../../lib/context.js";
-import { tagFlags } from "../../../lib/flags.js";
+import { deploymentFlags } from "../../../lib/flags.js";
 import { baseEngineArgs } from "../../../lib/operation-args.js";
 import { runWriteVerb } from "../../../lib/ops-report.js";
 export default class DefinitionDelete extends WorkflowCommand {
@@ -20,7 +20,7 @@ export default class DefinitionDelete extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({
             description: 'Delete only this deployed version (default: every version).',
         }),

package/dist/commands/editorial-workflows/definition/diff.d.ts

@@ -9,6 +9,7 @@ export default class DefinitionDiff extends WorkflowCommand {
     };
     static flags: {
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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/editorial-workflows/definition/diff.js

@@ -5,7 +5,7 @@ import { WorkflowCommand } from "../../../lib/base-command.js";
 import { resolveContext } from "../../../lib/context.js";
 import { fetchDeployedDefinition, selectDefinitions, validateOrFail, } from "../../../lib/definitions.js";
 import { diffReport } from "../../../lib/diff.js";
-import { tagFlags } from "../../../lib/flags.js";
+import { deploymentFlags } from "../../../lib/flags.js";
 import { deploymentToTarget } from "../../../lib/select-deployment.js";
 export default class DefinitionDiff extends WorkflowCommand {
     static aliases = ['definition:diff'];
@@ -18,7 +18,7 @@ export default class DefinitionDiff extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({ description: 'Deployed version to diff against (default: latest).' }),
     };
     async run() {

package/dist/commands/editorial-workflows/deploy.d.ts

@@ -15,12 +15,13 @@ export default class Deploy extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'all-tags': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         check: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         only: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'share-defs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     /** Deploy (or diff, for `--dry-run`) one deployment's definitions.

package/dist/commands/editorial-workflows/deploy.js

@@ -8,9 +8,9 @@ import { clientFor, resolveTokenOrFail } from "../../lib/client.js";
 import { selectDefinitions, validateOrFail } from "../../lib/definitions.js";
 import { diffReport } from "../../lib/diff.js";
 import { fail, isAuthRejection } from "../../lib/fail.js";
-import { tagFlags } from "../../lib/flags.js";
+import { deploymentFlags } from "../../lib/flags.js";
 import { loadWorkflowConfig } from "../../lib/load-config.js";
-import { deploymentToTarget, selectDeployments } from "../../lib/select-deployment.js";
+import { deploymentLabel, deploymentToTarget, selectDeployments, } from "../../lib/select-deployment.js";
 import { shareDefinitionsAfterDeploy } from "../../lib/share-definitions.js";
 import { cliTelemetry } from "../../lib/telemetry.js";
 import { groupBanner } from "../../lib/ui.js";
@@ -18,6 +18,7 @@ export default class Deploy extends WorkflowCommand {
     static aliases = ['deploy'];
     static description = 'Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.';
     static examples = [
+        '<%= config.bin %> deploy --deployment review-prod',
         '<%= config.bin %> deploy --tag prod',
         '<%= config.bin %> deploy --all-tags',
         '<%= config.bin %> deploy --check',
@@ -25,11 +26,15 @@ export default class Deploy extends WorkflowCommand {
         '<%= config.bin %> deploy --only productLaunch',
     ];
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
+        tag: Flags.string({
+            description: 'Workflow environment tag (e.g. prod, test) — deploys every deployment carrying the tag (a tag is an environment group).',
+            exclusive: ['deployment'],
+        }),
         'all-tags': Flags.boolean({
-            description: 'Deploy every deployment in the config, not just one tag.',
+            description: 'Deploy every deployment in the config, not just a selection.',
             default: false,
-            exclusive: ['tag'],
+            exclusive: ['tag', 'deployment'],
         }),
         'dry-run': Flags.boolean({
             description: 'Validate + diff against the deployed version; do not write.',
@@ -51,7 +56,11 @@ export default class Deploy extends WorkflowCommand {
         const { flags } = await this.parse(Deploy);
         validateModeFlags(flags.check, flags['dry-run']);
         const config = await loadWorkflowConfig();
-        const batches = buildBatches(await selectDeployments(config, { tag: flags.tag, allTags: flags['all-tags'] }), flags.only);
+        const batches = buildBatches(await selectDeployments(config, {
+            name: flags.deployment,
+            tag: flags.tag,
+            allTags: flags['all-tags'],
+        }), flags.only);
         const log = (line) => this.log(line);
         if (flags.check) {
             await reconcileBatches({
@@ -145,9 +154,6 @@ export function validateModeFlags(check, dryRun) {
         fail('Pass either --check or --dry-run, not both.');
     }
 }
-function deploymentLabel({ name, tag }) {
-    return `${name} (${tag})`;
-}
 export function buildBatches(deployments, only) {
     return deployments.map((deployment) => {
         const context = deployments.length > 1 ? `${deploymentLabel(deployment)} — ` : '';

package/dist/commands/editorial-workflows/diagnose.d.ts

@@ -40,6 +40,7 @@ export default class Diagnose extends WorkflowCommand {
     };
     static flags: {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        deployment: 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/editorial-workflows/diagnose.js

@@ -5,7 +5,7 @@ import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
 import { fail, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { instanceFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { formatTimestamp, sectionHeader, activityIcon } from "../../lib/ui.js";
 import { instanceHeader } from "./show.js";
@@ -223,7 +223,7 @@ export default class Diagnose extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         ...jsonFlags,
     };
     async run() {

package/dist/commands/editorial-workflows/fire-action.d.ts

@@ -41,6 +41,7 @@ export default class FireAction extends WorkflowCommand {
         activity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         action: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         param: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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/editorial-workflows/fire-action.js

@@ -5,7 +5,7 @@ import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
 import { fail, failOnThrow, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { instanceFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../../lib/ops-report.js";
 import { parseParams } from "../../lib/params.js";
@@ -93,7 +93,7 @@ export default class FireAction extends WorkflowCommand {
         instanceId: Args.string({ required: true, description: 'Workflow instance id.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         activity: Flags.string({
             description: 'Activity the action belongs to. Required to fire; omit --action to list.',
         }),

package/dist/commands/editorial-workflows/nuke.d.ts

@@ -5,7 +5,8 @@ export default class Nuke extends WorkflowCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        tag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/editorial-workflows/nuke.js

@@ -7,7 +7,7 @@ import { clientFor, resolveApiHost, resolveTokenOrFail } from "../../lib/client.
 import { dedupeResources } from "../../lib/context.js";
 import { fail } from "../../lib/fail.js";
 import { loadWorkflowConfig } from "../../lib/load-config.js";
-import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, renderNukePlan, resolveNukePlan, } from "../../lib/nuke.js";
+import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, refuseOverlappingNuke, renderNukePlan, resolveNukePlan, sweptResources, } from "../../lib/nuke.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 import { canPromptOnStderr } from "../../lib/prompt.js";
 import { selectDeployment } from "../../lib/select-deployment.js";
@@ -19,13 +19,17 @@ export default class Nuke extends WorkflowCommand {
         'resource). Content documents are never touched. Prints a dry-run plan, then requires you to ' +
         'type back every involved dataset (--force skips the prompt; the plan still prints).';
     static examples = [
-        '<%= config.bin %> nuke --tag plugin-dev',
+        '<%= config.bin %> nuke --deployment plugin-dev',
         '<%= config.bin %> nuke --tag plugin-dev --force',
     ];
     static flags = {
+        deployment: Flags.string({
+            description: 'The deployment name to reset.',
+            exactlyOne: ['deployment', 'tag'],
+        }),
         tag: Flags.string({
-            description: 'The deployment tag to reset. Required — a destructive reset never guesses the environment.',
-            required: true,
+            description: 'The deployment tag to reset (while it names exactly one deployment).',
+            exactlyOne: ['deployment', 'tag'],
         }),
         force: Flags.boolean({
             description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
@@ -35,7 +39,8 @@ export default class Nuke extends WorkflowCommand {
     async run() {
         const { flags } = await this.parse(Nuke);
         const config = await loadWorkflowConfig();
-        const deployment = selectDeployment(config, { tag: flags.tag });
+        const deployment = selectDeployment(config, { name: flags.deployment, tag: flags.tag });
+        refuseOverlappingNuke(config.deployments, deployment);
         const targets = buildTargets(deployment, await resolveTokenOrFail());
         const plan = await resolveNukePlan({ tag: deployment.tag, targets });
         const apiHost = resolveApiHost() ?? 'https://api.sanity.io (production default)';
@@ -58,12 +63,11 @@ export default class Nuke extends WorkflowCommand {
     }
 }
 function buildTargets(deployment, token) {
-    const engineResource = deployment.workflowResource;
-    const aliasResources = (deployment.resourceAliases ?? []).map((binding) => binding.resource);
-    return dedupeResources([engineResource, ...aliasResources]).map((resource) => ({
+    const engineGdr = resourceGdr(deployment.workflowResource);
+    return dedupeResources(sweptResources(deployment)).map((resource) => ({
         resource,
         client: clientFor(resource, token),
-        holdsEngineDocs: resourceGdr(resource) === resourceGdr(engineResource),
+        holdsEngineDocs: resourceGdr(resource) === engineGdr,
     }));
 }
 async function confirmOrFail(targets) {

package/dist/commands/editorial-workflows/set-stage.d.ts

@@ -12,6 +12,7 @@ export default class SetStage extends WorkflowCommand {
     static flags: {
         to: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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/editorial-workflows/set-stage.js

@@ -3,7 +3,7 @@ import { Args, Flags } from '@oclif/core';
 import { workflow } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveInstanceContext } from "../../lib/context.js";
-import { tagFlags } from "../../lib/flags.js";
+import { instanceFlags } from "../../lib/flags.js";
 import { buildOperationArgs } from "../../lib/operation-args.js";
 import { cascadeTail, opsAppliedLines, runWriteVerb, } from "../../lib/ops-report.js";
 export default class SetStage extends WorkflowCommand {
@@ -20,7 +20,7 @@ export default class SetStage extends WorkflowCommand {
         }),
     };
     static flags = {
-        ...tagFlags,
+        ...instanceFlags,
         to: Flags.string({
             required: true,
             description: 'Target stage name.',

package/dist/commands/editorial-workflows/start.d.ts

@@ -13,6 +13,7 @@ export default class Start extends WorkflowCommand {
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         field: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
         'instance-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        deployment: 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/editorial-workflows/start.js

@@ -5,7 +5,7 @@ import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveContext } from "../../lib/context.js";
 import { fetchDeployedDefinition } from "../../lib/definitions.js";
 import { fail, failOnThrow, failureDetail } from "../../lib/fail.js";
-import { jsonFlags, tagFlags } from "../../lib/flags.js";
+import { deploymentFlags, jsonFlags } from "../../lib/flags.js";
 import { baseEngineArgs } from "../../lib/operation-args.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
 import { parseParams } from "../../lib/params.js";
@@ -23,7 +23,7 @@ export default class Start extends WorkflowCommand {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
     };
     static flags = {
-        ...tagFlags,
+        ...deploymentFlags,
         version: Flags.integer({
             description: 'Definition version to start from (default: highest deployed).',
         }),

package/dist/lib/context.d.ts

@@ -13,11 +13,12 @@ export interface InstanceContext {
 }
 /**
  * The resolution a WRITE shares: discover the config, pick the deployment for
- * `--tag` (or the sole one), and build an authenticated client for that
- * deployment's resource. A write acts on one specific deployment, so a
- * single, definite target is exactly what it needs.
+ * `--deployment` or `--tag` (or the sole one), and build an authenticated
+ * client for that deployment's resource. A write acts on one specific
+ * deployment, so a single, definite target is exactly what it needs.
  */
 export declare function resolveContext(flags: {
+    deployment?: string | undefined;
     tag?: string | undefined;
 }): Promise<DeploymentContext>;
 /** One resource a read inspects, with its authenticated client. */
@@ -34,8 +35,9 @@ export interface ReadTarget {
  *
  * Untagged, this is every distinct resource the config mentions — a read is
  * harmless to fan out, so "show me what's deployed" spans the whole config.
- * `--tag` narrows to that deployment's resource. The token resolves once for
- * the run, however many targets it spans.
+ * `--tag` narrows to the resources deployed under that tag (tags may repeat
+ * across deployments). The token resolves once for the run, however many
+ * targets it spans.
  */
 export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
@@ -44,9 +46,9 @@ export declare function resolveReadTargets(flags: {
  *  The first occurrence wins its position, so a caller-ordered list (e.g. the
  *  engine resource first) keeps its lead entry. */
 export declare function dedupeResources(resources: WorkflowResource[]): WorkflowResource[];
-/** The distinct resources a read targets: the tagged deployment's sole
- *  resource, or — untagged — every distinct one the config's deployments
- *  mention ({@link dedupeResources}). */
+/** The distinct resources a read targets: every resource deployed under the
+ *  tag (tags may repeat across deployments), or — untagged — every distinct
+ *  one the config's deployments mention ({@link dedupeResources}). */
 export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
 /** The single resource a read should target, or fail asking which when the
  *  config spans more than one. For the paths that need one definite dataset
@@ -60,15 +62,28 @@ export declare function resolveReadResource(config: WorkflowConfig, tag: string
  * config's declared deployments. An instance id is globally unique and carries
  * its own `tag`, so a command that names one acts on that instance regardless
  * of which tags the config happens to deploy; the config only locates the
- * resource (via {@link resolveReadResource}, no tag filter).
+ * resource (via {@link resolveInstanceResource}, no tag filter).
  *
  * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
  * declared deployment because it acts on the authored definition set (or a
  * definition name, which — unlike an instance id — isn't unique across tags).
  */
 export declare function resolveInstanceContext(flags: {
+    deployment?: string | undefined;
     tag?: string | undefined;
 }, instanceId: string): Promise<InstanceContext>;
+/**
+ * Which resource an instance-keyed command reads from: the one `--deployment`
+ * names (resolved by its unique deployment name), else the sole or
+ * `--tag`-narrowed resource ({@link resolveReadResource}). The instance id is
+ * globally unique, so this only locates the resource to look in — never the
+ * instance's `tag` partition, which the caller takes from the loaded instance.
+ * The shared path behind all four instance-keyed commands.
+ */
+export declare function resolveInstanceResource(config: WorkflowConfig, { deployment, tag }: {
+    deployment?: string | undefined;
+    tag?: string | undefined;
+}): WorkflowResource;
 /** Fetch an instance by id, exiting cleanly when the resource has no such
  *  document — the diagnostic an operator sees on a mistyped id. Split out from
  *  {@link resolveInstanceContext} so the not-found path is unit-testable

package/dist/lib/context.js

@@ -2,11 +2,11 @@ import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
-import { selectDeployment } from "./select-deployment.js";
+import { availableDeployments, deploymentsForTag, selectDeployment } from "./select-deployment.js";
 import { resourceLabel } from "./ui.js";
 export async function resolveContext(flags) {
     const config = await loadWorkflowConfig();
-    const deployment = selectDeployment(config, { tag: flags.tag });
+    const deployment = selectDeployment(config, { name: flags.deployment, tag: flags.tag });
     return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
 }
 export async function resolveReadTargets(flags) {
@@ -20,7 +20,7 @@ export function dedupeResources(resources) {
 }
 export function resolveReadResources(config, tag) {
     if (tag !== undefined) {
-        return [selectDeployment(config, { tag }).workflowResource];
+        return dedupeResources(deploymentsForTag(config, tag).map((deployment) => deployment.workflowResource));
     }
     const resources = dedupeResources(config.deployments.map((d) => d.workflowResource));
     if (resources.length === 0) {
@@ -34,16 +34,25 @@ export function resolveReadResource(config, tag) {
     if (resources.length === 1 && sole !== undefined) {
         return sole;
     }
-    const tags = config.deployments.map((d) => d.tag).join(', ');
-    fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
+    if (tag === undefined) {
+        fail('Config spans multiple resources — pass --deployment or --tag to choose one.', availableDeployments(config));
+    }
+    const carriers = config.deployments.filter((d) => d.tag === tag);
+    fail(`Tag "${tag}" spans multiple resources — pass --deployment to choose one.`, availableDeployments(config, carriers));
 }
 export async function resolveInstanceContext(flags, instanceId) {
     const config = await loadWorkflowConfig();
-    const workflowResource = resolveReadResource(config, flags.tag);
+    const workflowResource = resolveInstanceResource(config, flags);
     const client = clientFor(workflowResource, await resolveTokenOrFail());
     const instance = await loadInstanceOrFail(client, instanceId);
     return { client, scope: { tag: instance.tag, workflowResource } };
 }
+export function resolveInstanceResource(config, { deployment, tag }) {
+    if (deployment !== undefined) {
+        return selectDeployment(config, { name: deployment, tag: undefined }).workflowResource;
+    }
+    return resolveReadResource(config, tag);
+}
 export async function loadInstanceOrFail(client, instanceId) {
     const instance = await client.getDocument(instanceId, {
         tag: 'instance.load',

package/dist/lib/flags.d.ts

@@ -1,11 +1,33 @@
-/** The environment tag (e.g. prod, test). For write commands it selects which
- *  deployment in the discovered `sanity.workflow` config to act on. A sole
- *  deployment needs no tag, and an interactive `deploy` asks when several are
- *  configured. For read commands it's an optional query filter — and the
- *  resource disambiguator when a config spans more than one. */
+/** The environment tag (e.g. prod, test). Tags group deployments by
+ *  environment and may repeat across a config. For the read commands that
+ *  consume this directly it's an optional query filter — and the resource
+ *  disambiguator when a config spans more than one. Write commands layer
+ *  selection semantics on top via {@link deploymentFlags}; instance-keyed
+ *  commands add `--deployment` alongside it via {@link instanceFlags}. */
 export declare const tagFlags: {
     tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
+/** The selectors an instance-keyed command (`diagnose`, `abort`, `set-stage`,
+ *  `fire-action`) takes. An instance id is globally unique and carries its own
+ *  `tag`, so these only pick WHICH resource to read it from — never the
+ *  instance's partition, which always comes from the loaded instance.
+ *  `--deployment` names one deployment and reads from the resource it targets;
+ *  `--tag` stays the optional narrower {@link tagFlags} describes. Mutually
+ *  exclusive; a sole-resource config needs neither. */
+export declare const instanceFlags: {
+    deployment: 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>;
+};
+/** The selectors a single-deployment (write) command takes: `--deployment` —
+ *  the deployment's unique name identity — or `--tag`, which resolves while the
+ *  tag names exactly one deployment and errors asking for `--deployment` when
+ *  it spans several. Mutually exclusive; a sole-deployment config needs neither.
+ *  `deploy` overrides the `tag` description with its group semantics (every
+ *  deployment carrying the tag). */
+export declare const deploymentFlags: {
+    deployment: 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>;
+};
 export declare const jsonFlags: {
     json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };

package/dist/lib/flags.js

@@ -1,7 +1,23 @@
 import { Flags } from '@oclif/core';
+const tagAsFilterDescription = 'Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.';
 export const tagFlags = {
+    tag: Flags.string({ description: tagAsFilterDescription }),
+};
+export const instanceFlags = {
+    deployment: Flags.string({
+        description: 'Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.',
+        exclusive: ['tag'],
+    }),
+    tag: Flags.string({ description: tagAsFilterDescription, exclusive: ['deployment'] }),
+};
+export const deploymentFlags = {
+    deployment: Flags.string({
+        description: 'Deployment name — the unique identity of one deployment in the config.',
+        exclusive: ['tag'],
+    }),
     tag: Flags.string({
-        description: 'Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.',
+        description: 'Workflow environment tag (e.g. prod, test) — selects the deployment to act on while the tag names exactly one; pass --deployment when it spans several.',
+        exclusive: ['deployment'],
     }),
 };
 export const jsonFlags = {

package/dist/lib/nuke.d.ts

@@ -1,4 +1,4 @@
-import { type WorkflowClient, type WorkflowResource } from '@sanity/workflow-engine';
+import { type WorkflowClient, type WorkflowDeployment, type WorkflowResource } from '@sanity/workflow-engine';
 /** A resource a nuke may delete from, with the client that reads/writes it and
  *  whether it is the engine's own resource — the only one that holds instances
  *  and definitions (guards can co-locate with subjects in any resource). */
@@ -32,6 +32,20 @@ export interface PlanCounts {
     datasets: number;
     total: number;
 }
+/** Every resource a deployment's nuke sweeps: its own workflow resource (which
+ *  holds instances + definitions + guards) plus each alias-bound resource
+ *  (guards co-locate with the subjects they lock). */
+export declare function sweptResources(deployment: WorkflowDeployment): WorkflowResource[];
+/**
+ * Fail before any nuke work when another same-tag deployment sweeps a resource
+ * the selected one does. Guard document ids embed only the tag
+ * (`temp.system.guard.<tag>.wf-instance.*`), so within a shared resource the
+ * sweep cannot tell such deployments' guards apart — nuking one would delete
+ * the others' live locks, invisibly to the plan. Config validation already
+ * forbids sharing tag + workflow resource, so an overlap can only arrive
+ * through alias bindings.
+ */
+export declare function refuseOverlappingNuke(deployments: WorkflowDeployment[], selected: WorkflowDeployment): void;
 /**
  * Resolve what a tag-scoped nuke would delete, per resource — the dry-run plan
  * printed before any deletion. Instances and definitions are read only from the

package/dist/lib/nuke.js

@@ -1,8 +1,29 @@
 import { styleText } from 'node:util';
-import { GUARD_DOC_TYPE, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { GUARD_DOC_TYPE, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, resourceGdr, tagScopeFilter, } from '@sanity/workflow-engine';
+import { fail } from "./fail.js";
+import { deploymentLabel } from "./select-deployment.js";
 import { formatTable, resourceLabel, sectionHeader } from "./ui.js";
 const CHUNK = 200;
 const REQUEST_TAG = 'nuke';
+export function sweptResources(deployment) {
+    return [
+        deployment.workflowResource,
+        ...(deployment.resourceAliases ?? []).map((binding) => binding.resource),
+    ];
+}
+export function refuseOverlappingNuke(deployments, selected) {
+    const swept = new Set(sweptResources(selected).map(resourceGdr));
+    const clashing = deployments.filter((candidate) => candidate.name !== selected.name &&
+        candidate.tag === selected.tag &&
+        sweptResources(candidate).some((resource) => swept.has(resourceGdr(resource))));
+    if (clashing.length === 0) {
+        return;
+    }
+    fail(`Refusing to nuke "${deploymentLabel(selected)}" — its guards are indistinguishable ` +
+        `from ${clashing.map(deploymentLabel).join(', ')}'s in the shared resource(s).`, `Guard ids embed only the tag, and these deployments share tag "${selected.tag}" plus ` +
+        "a swept resource — the sweep would delete the other deployments' live guards. " +
+        'Give them distinct tags first.');
+}
 export async function resolveNukePlan(args) {
     const { tag, targets } = args;
     const resources = await Promise.all(targets.map((target) => resolveResourcePlan({ tag, target })));

package/dist/lib/select-deployment.d.ts

@@ -1,32 +1,54 @@
 import { type DeployTarget, type WorkflowConfig, type WorkflowDeployment } from '@sanity/workflow-engine';
-type ChooseDeploymentTag = (deployments: WorkflowDeployment[]) => Promise<string>;
+type ChooseDeploymentName = (deployments: WorkflowDeployment[]) => Promise<string>;
 interface DeploymentSelectionOptions {
+    name: string | undefined;
     tag: string | undefined;
     allTags: boolean;
     interactive?: boolean;
-    chooseTag?: ChooseDeploymentTag;
+    chooseName?: ChooseDeploymentName;
 }
+/** The one identity format for a deployment in output — banners, failure
+ *  summaries, and "available deployments" listings all render it the same
+ *  way. */
+export declare function deploymentLabel({ name, tag }: Pick<WorkflowDeployment, 'name' | 'tag'>): string;
 /**
- * Pick the deployment for the requested `--tag`. Tags are unique across a
- * config (enforced by defineWorkflowConfig), so a tag names at most one
- * deployment.
+ * Pick the deployment for the requested `--deployment` or `--tag`. Names are
+ * unique across a config (enforced by defineWorkflowConfig), so a name resolves
+ * exactly one deployment. Tags are repeatable — a tag resolves only while it
+ * names exactly one deployment; when it spans several, the failure lists them
+ * so `--deployment` can disambiguate.
  *
- * With no tag: fall back to the sole deployment when there's exactly one
- * (the common single-environment case), otherwise fail asking for `--tag` —
- * a multi-deployment config is ambiguous without it. `orAlternative` extends
- * that ambiguity message for callers with another way out (deploy's `--all-tags`).
+ * With no selector: fall back to the sole deployment when there's exactly one
+ * (the common single-environment case), otherwise fail asking for
+ * `--deployment` or `--tag` — a multi-deployment config is ambiguous without
+ * one. `orAlternative`
+ * extends that ambiguity message for callers with another way out (deploy's
+ * `--all-tags`).
  */
-export declare function selectDeployment(config: WorkflowConfig, { tag, orAlternative }: {
+export declare function selectDeployment(config: WorkflowConfig, { name, tag, orAlternative, }: {
+    name: string | undefined;
     tag: string | undefined;
     orAlternative?: string;
 }): WorkflowDeployment;
 /**
- * The deployments a `deploy` run acts on: every one with `--all-tags`,
- * otherwise a single target via {@link selectDeployment}. An ambiguous bare
- * interactive run asks for a tag; a run that cannot prompt keeps the explicit
- * flag guidance. Deploying everything is an explicit opt-in — never a default.
+ * Every deployment carrying `tag`, failing when the tag matches none — the
+ * shared resolution for the callers that accept a whole tag group (deploy's
+ * tag-as-environment run, the read paths' resource narrowing).
  */
-export declare function selectDeployments(config: WorkflowConfig, { tag, allTags, interactive, chooseTag }: DeploymentSelectionOptions): Promise<WorkflowDeployment[]>;
+export declare function deploymentsForTag(config: WorkflowConfig, tag: string): WorkflowDeployment[];
+/**
+ * The deployments a `deploy` run acts on: every one with `--all-tags`, one
+ * definite deployment via `--deployment`, every deployment carrying the tag with
+ * `--tag` (a tag is an environment group), otherwise the sole deployment. An
+ * ambiguous bare interactive run asks which deployment; a run that cannot
+ * prompt keeps the explicit flag guidance. Deploying everything is an
+ * explicit opt-in — never a default.
+ */
+export declare function selectDeployments(config: WorkflowConfig, { name, tag, allTags, interactive, chooseName }: DeploymentSelectionOptions): Promise<WorkflowDeployment[]>;
+/** The "Available deployments: name (tag), …" hint every ambiguity failure
+ *  prints — one vocabulary across the write and instance-keyed paths, so a
+ *  reader always sees both the `--deployment` names and their `--tag`s. */
+export declare function availableDeployments(config: WorkflowConfig, deployments?: WorkflowDeployment[]): string;
 /**
  * Project a deployment into the engine's {@link DeployTarget} — the shape the
  * deploy/diff verbs (`deployDefinitions`, `computeDiffEntries`, `diffEntry`)

package/dist/lib/select-deployment.js

@@ -2,55 +2,81 @@ import { select } from '@sanity/cli-core/ux';
 import { resourceAliasesToMap, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
 import { canPromptOnStderr } from "./prompt.js";
-export function selectDeployment(config, { tag, orAlternative = '' }) {
-    if (tag === undefined) {
-        if (config.deployments.length > 1) {
-            fail(`Multiple deployments configured — pass --tag${orAlternative}.`, availableTags(config));
+export function deploymentLabel({ name, tag }) {
+    return `${name} (${tag})`;
+}
+export function selectDeployment(config, { name, tag, orAlternative = '', }) {
+    if (name !== undefined) {
+        const deployment = config.deployments.find((candidate) => candidate.name === name);
+        if (deployment === undefined) {
+            fail(`No deployment named "${name}".`, availableDeployments(config));
         }
-        const [sole] = config.deployments;
-        if (sole === undefined) {
-            fail('No deployments configured.');
+        return deployment;
+    }
+    if (tag !== undefined) {
+        const matches = deploymentsForTag(config, tag);
+        const [sole, ...rest] = matches;
+        if (sole === undefined || rest.length > 0) {
+            fail(`Multiple deployments tagged "${tag}" — pass --deployment to choose one.`, availableDeployments(config, matches));
         }
         return sole;
     }
-    const deployment = config.deployments.find((candidate) => candidate.tag === tag);
-    if (deployment === undefined) {
-        fail(`No deployment for tag "${tag}".`, availableTags(config));
+    if (config.deployments.length > 1) {
+        fail(`Multiple deployments configured — pass --deployment or --tag${orAlternative}.`, availableDeployments(config));
+    }
+    const [sole] = config.deployments;
+    if (sole === undefined) {
+        fail('No deployments configured.');
     }
-    return deployment;
+    return sole;
 }
-export async function selectDeployments(config, { tag, allTags, interactive, chooseTag = chooseDeploymentTag }) {
+export function deploymentsForTag(config, tag) {
+    const matches = config.deployments.filter((candidate) => candidate.tag === tag);
+    if (matches.length === 0) {
+        fail(`No deployment for tag "${tag}".`, availableDeployments(config));
+    }
+    return matches;
+}
+export async function selectDeployments(config, { name, tag, allTags, interactive, chooseName = chooseDeploymentName }) {
     if (allTags) {
         return config.deployments;
     }
-    if (tag === undefined && config.deployments.length > 1) {
+    if (tag !== undefined) {
+        return deploymentsForTag(config, tag);
+    }
+    if (name === undefined && config.deployments.length > 1) {
         if (!(interactive ?? canPromptOnStderr())) {
             return [
                 selectDeployment(config, {
+                    name,
                     tag,
                     orAlternative: ', or --all-tags to deploy every deployment',
                 }),
             ];
         }
-        const selectedTag = await chooseTag(config.deployments);
-        return [selectDeployment(config, { tag: selectedTag })];
+        const selectedName = await chooseName(config.deployments);
+        return [selectDeployment(config, { name: selectedName, tag: undefined })];
     }
     return [
-        selectDeployment(config, { tag, orAlternative: ', or --all-tags to deploy every deployment' }),
+        selectDeployment(config, {
+            name,
+            tag,
+            orAlternative: ', or --all-tags to deploy every deployment',
+        }),
     ];
 }
-async function chooseDeploymentTag(deployments) {
+async function chooseDeploymentName(deployments) {
     return select({
-        message: 'Select a deployment tag',
+        message: 'Select a deployment',
         choices: deployments.map(({ name, tag }) => ({
-            name: tag,
-            value: tag,
-            description: name,
+            name,
+            value: name,
+            description: `tag: ${tag}`,
         })),
     }, { output: process.stderr });
 }
-function availableTags(config) {
-    return `Available tags: ${config.deployments.map((candidate) => candidate.tag).join(', ')}`;
+export function availableDeployments(config, deployments = config.deployments) {
+    return `Available deployments: ${deployments.map(deploymentLabel).join(', ')}`;
 }
 export function deploymentToTarget(deployment) {
     return {

package/oclif.manifest.json

@@ -17,8 +17,21 @@
         "<%= config.bin %> abort wf-instance.abc123 --reason 'superseded by relaunch'"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -54,6 +67,7 @@
       "args": {},
       "description": "Validate, diff, and deploy workflow definitions to the resource bound by the selected deployment.",
       "examples": [
+        "<%= config.bin %> deploy --deployment review-prod",
         "<%= config.bin %> deploy --tag prod",
         "<%= config.bin %> deploy --all-tags",
         "<%= config.bin %> deploy --check",
@@ -61,17 +75,31 @@
         "<%= config.bin %> deploy --only productLaunch"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — the unique identity of one deployment in the config.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — deploys every deployment carrying the tag (a tag is an environment group).",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "all-tags": {
-          "description": "Deploy every deployment in the config, not just one tag.",
+          "description": "Deploy every deployment in the config, not just a selection.",
           "exclusive": [
-            "tag"
+            "tag",
+            "deployment"
           ],
           "name": "all-tags",
           "allowNo": false,
@@ -136,8 +164,21 @@
         "<%= config.bin %> diagnose wf-instance.abc123 --json"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -183,8 +224,21 @@
         "<%= config.bin %> fire-action wf-instance.abc123 --activity publish --action publish --param note=shipping"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -249,7 +303,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -312,14 +366,20 @@
       "args": {},
       "description": "The reset for a dataset holding engine documents the versioned upgrade framework cannot yet migrate: deletes the tag's instances, definitions, and guards (across every alias-bound resource). Content documents are never touched. Prints a dry-run plan, then requires you to type back every involved dataset (--force skips the prompt; the plan still prints).",
       "examples": [
-        "<%= config.bin %> nuke --tag plugin-dev",
+        "<%= config.bin %> nuke --deployment plugin-dev",
         "<%= config.bin %> nuke --tag plugin-dev --force"
       ],
       "flags": {
+        "deployment": {
+          "description": "The deployment name to reset.",
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "The deployment tag to reset. Required — a destructive reset never guesses the environment.",
+          "description": "The deployment tag to reset (while it names exactly one deployment).",
           "name": "tag",
-          "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -398,8 +458,21 @@
         "<%= config.bin %> set-stage wf-instance.abc123 --to ready --reason 'unblock for demo'"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — read the instance from the resource that deployment targets; the tag partition still comes from the loaded instance.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -454,7 +527,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -506,8 +579,21 @@
         "<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — the unique identity of one deployment in the config.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — selects the deployment to act on while the tag names exactly one; pass --deployment when it spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -574,7 +660,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -614,8 +700,21 @@
         "<%= config.bin %> definition delete my-workflow --cascade --reason 'workflow retired'"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — the unique identity of one deployment in the config.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — selects the deployment to act on while the tag names exactly one; pass --deployment when it spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -675,8 +774,21 @@
         "<%= config.bin %> definition diff productLaunch --version 2"
       ],
       "flags": {
+        "deployment": {
+          "description": "Deployment name — the unique identity of one deployment in the config.",
+          "exclusive": [
+            "tag"
+          ],
+          "name": "deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — selects the deployment to act on while the tag names exactly one; pass --deployment when it spans several.",
+          "exclusive": [
+            "deployment"
+          ],
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -718,7 +830,7 @@
       ],
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -770,7 +882,7 @@
       "description": "Show a deployed workflow definition.",
       "flags": {
         "tag": {
-          "description": "Workflow environment tag (e.g. prod, test) — the deployment to target for writes; an optional filter for reads.",
+          "description": "Workflow environment tag (e.g. prod, test) — an optional query filter, and the resource disambiguator when the config spans several.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -801,5 +913,5 @@
       ]
     }
   },
-  "version": "0.13.0"
+  "version": "0.14.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -56,15 +56,15 @@
     "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
     "ora": "^9.4.0",
-    "@sanity/workflow-engine": "0.18.0"
+    "@sanity/workflow-engine": "0.19.0"
   },
   "devDependencies": {
     "@types/diff": "^8.0.0",
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine-test": "0.13.0",
-    "@sanity/workflow-examples": "0.8.0"
+    "@sanity/workflow-engine-test": "0.13.1",
+    "@sanity/workflow-examples": "0.8.1"
   },
   "oclif": {
     "bin": "sanity-workflows",