From 8eae8f1e699d89514339f4700deddcd45bcf6f3c Mon Sep 17 00:00:00 2001
From: Peter Schilling <code@schpet.com>
Date: Wed, 5 Aug 2026 14:29:48 -0700
Subject: [PATCH] Add --add-label and --remove-label to issue update
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The reporter asked for a way to detach a label from one issue without
deleting it team-wide, believing --label was additive. It actually
replaces the issue's entire label set (IssueUpdateInput.labelIds), so
the gap was wider than reported: adding one label clobbered the rest.
Rather than only the suggested --remove-label, this maps both
--add-label and --remove-label onto the API's addedLabelIds/
removedLabelIds (one atomic mutation, no read-modify-write). --label
keeps its documented replace semantics for existing scripts, with help
text that now says so. Flag names match gh issue edit, the surface
users and agents reach for first.

A --clear-labels flag was considered (an empty label set is currently
inexpressible in one command) and deliberately deferred: adding a flag
later is backwards compatible, removing one is breaking, and nothing
has asked for clear-all yet.

Invalid combinations error before any network call: --label with
incremental flags, the same resolved label ID in both add and remove,
and --team moves combined with incremental flags (label names resolve
against the destination team, which would make source-team labels
silently unresolvable). Live QA confirmed removing an unattached label
is rejected by Linear's API ("Label <id> is not on issue <id>"), not a
silent no-op — surfaced as-is, consistent with the repo's
explicit-input-errors philosophy.

The reporter's alternative ask (label rename) is deferred: it is
team-wide and would not solve the per-issue detach workflow.

Github-Issue: Fixes #258
Github-Issue-Url: https://github.com/schpet/linear-cli/issues/258
---
 docs/usage.md                                 |  16 +
 skills/linear-cli/SKILL.md                    |   5 +-
 skills/linear-cli/SKILL.template.md           |   5 +-
 skills/linear-cli/references/issue.md         |   6 +-
 .../references/organization-features.md       |  14 +-
 src/commands/issue/issue-update.ts            |  82 ++-
 .../__snapshots__/issue-update.test.ts.snap   | 124 ++++-
 test/commands/issue/issue-update.test.ts      | 490 ++++++++++++++++++
 8 files changed, 726 insertions(+), 16 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index 7a19e60d..307905ff 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -159,6 +159,22 @@ update a specific issue:
 linear issue update TEAM-123
 ```
 
+change labels:
+
+```bash
+# Add a label, keeping existing labels
+linear issue update TEAM-123 --add-label bug
+
+# Remove a label from this issue (does not delete it from the team)
+linear issue update TEAM-123 --remove-label sprint-42
+
+# Swap labels atomically in one update
+linear issue update TEAM-123 --remove-label sprint-42 --add-label sprint-43
+
+# Replace the entire label set
+linear issue update TEAM-123 --label bug --label frontend
+```
+
 #### other issue commands
 
 get issue id from current git branch:
diff --git a/skills/linear-cli/SKILL.md b/skills/linear-cli/SKILL.md
index 024a2fff..eadf0ee9 100644
--- a/skills/linear-cli/SKILL.md
+++ b/skills/linear-cli/SKILL.md
@@ -61,7 +61,10 @@ Write multi-line markdown to a file and pass `--description-file` (see the markd
 ```bash
 linear issue update ENG-123 --state "In Review" --assignee sam
 linear issue update ENG-123 --unassign
-linear issue update ENG-123 --label infra --label security  # replaces the label set
+linear issue update ENG-123 --add-label security             # add, keep existing labels
+linear issue update ENG-123 --remove-label sprint-42         # detach; does not delete the label
+linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43  # atomic swap
+linear issue update ENG-123 --label infra --label security   # replaces the label set
 ```
 
 ### Add a comment
diff --git a/skills/linear-cli/SKILL.template.md b/skills/linear-cli/SKILL.template.md
index d65a2de1..dc69dc4d 100644
--- a/skills/linear-cli/SKILL.template.md
+++ b/skills/linear-cli/SKILL.template.md
@@ -61,7 +61,10 @@ Write multi-line markdown to a file and pass `--description-file` (see the markd
 ```bash
 linear issue update ENG-123 --state "In Review" --assignee sam
 linear issue update ENG-123 --unassign
-linear issue update ENG-123 --label infra --label security  # replaces the label set
+linear issue update ENG-123 --add-label security             # add, keep existing labels
+linear issue update ENG-123 --remove-label sprint-42         # detach; does not delete the label
+linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43  # atomic swap
+linear issue update ENG-123 --label infra --label security   # replaces the label set
 ```
 
 ### Add a comment
diff --git a/skills/linear-cli/references/issue.md b/skills/linear-cli/references/issue.md
index 1131c17f..44591254 100644
--- a/skills/linear-cli/references/issue.md
+++ b/skills/linear-cli/references/issue.md
@@ -581,7 +581,11 @@ Options:
   --estimate          <estimate>     - Points estimate of the issue                                                     
   -d, --description   <description>  - Description of the issue                                                         
   --description-file  <path>         - Read description from a file (preferred for markdown content)                    
-  -l, --label         <label>        - Issue label associated with the issue. May be repeated.                          
+  -l, --label         <label>        - Issue label associated with the issue; replaces the issue's entire label set.    
+                                       May be repeated. Use --add-label/--remove-label to change labels incrementally.  
+  --add-label         <label>        - Add a label to the issue, keeping its existing labels. May be repeated.          
+  --remove-label      <label>        - Remove a label from the issue, keeping its other labels (does not delete the     
+                                       label from the team). May be repeated.                                           
   --team              <team>         - Team associated with the issue (if not your default team)                        
   --project           <project>      - Project to assign the issue to (UUID, slug ID, or name)                          
   -s, --state         <state>        - Workflow state for the issue (by name or type)                                   
diff --git a/skills/linear-cli/references/organization-features.md b/skills/linear-cli/references/organization-features.md
index 71cb39d6..318c6c3a 100644
--- a/skills/linear-cli/references/organization-features.md
+++ b/skills/linear-cli/references/organization-features.md
@@ -74,12 +74,18 @@ echo -e "DEV-123\nDEV-124" | linear issue delete --bulk-stdin
 linear initiative archive --bulk <id1> <id2>
 ```
 
-## Adding Labels to Issues
+## Updating Labels on Issues
 
 ```bash
-# Add label to issue
-linear issue update DEV-123 --label "Bug"
+# Add a label, keeping the issue's existing labels
+linear issue update DEV-123 --add-label "Bug"
 
-# Add multiple labels
+# Remove a label from this issue only (label delete removes it team-wide)
+linear issue update DEV-123 --remove-label "sprint-42"
+
+# Swap labels atomically in one update
+linear issue update DEV-123 --remove-label "sprint-42" --add-label "sprint-43"
+
+# Replace the entire label set with exactly these labels
 linear issue update DEV-123 --label "Bug" --label "High Priority"
 ```
diff --git a/src/commands/issue/issue-update.ts b/src/commands/issue/issue-update.ts
index 52de1384..e1760e82 100644
--- a/src/commands/issue/issue-update.ts
+++ b/src/commands/issue/issue-update.ts
@@ -63,7 +63,17 @@ export const updateCommand = new Command()
   )
   .option(
     "-l, --label <label:string>",
-    "Issue label associated with the issue. May be repeated.",
+    "Issue label associated with the issue; replaces the issue's entire label set. May be repeated. Use --add-label/--remove-label to change labels incrementally.",
+    { collect: true },
+  )
+  .option(
+    "--add-label <label:string>",
+    "Add a label to the issue, keeping its existing labels. May be repeated.",
+    { collect: true },
+  )
+  .option(
+    "--remove-label <label:string>",
+    "Remove a label from the issue, keeping its other labels (does not delete the label from the team). May be repeated.",
     { collect: true },
   )
   .option(
@@ -104,6 +114,8 @@ export const updateCommand = new Command()
         description,
         descriptionFile,
         label: labels,
+        addLabel,
+        removeLabel,
         team,
         project,
         state,
@@ -134,6 +146,29 @@ export const updateCommand = new Command()
           )
         }
 
+        if (labels != null && (addLabel != null || removeLabel != null)) {
+          throw new ValidationError(
+            "Cannot combine --label with --add-label or --remove-label",
+            {
+              suggestion:
+                "--label replaces the issue's entire label set. Use it alone to set the exact set, or use --add-label/--remove-label alone to change it incrementally.",
+            },
+          )
+        }
+
+        // Label names resolve against the issue's (destination) team, so a
+        // team move combined with incremental label changes would silently
+        // make source-team labels unresolvable.
+        if (team != null && (addLabel != null || removeLabel != null)) {
+          throw new ValidationError(
+            "Cannot combine --team with --add-label or --remove-label",
+            {
+              suggestion:
+                "Move the issue with --team first, then change labels in a second update.",
+            },
+          )
+        }
+
         // Validate that description and descriptionFile are not both provided
         if (description && descriptionFile) {
           throw new ValidationError(
@@ -211,15 +246,41 @@ export const updateCommand = new Command()
           }
         }
 
-        const labelIds: string[] = []
-        if (labels != null && labels.length > 0) {
-          for (const label of labels) {
-            const labelId = await getIssueLabelIdByNameForTeam(label, teamKey)
+        // Resolves label names to IDs, deduped by resolved ID so case
+        // variants of the same label collapse to one entry.
+        const resolveLabelIds = async (names: string[]): Promise<string[]> => {
+          const ids: string[] = []
+          for (const name of names) {
+            const labelId = await getIssueLabelIdByNameForTeam(name, teamKey)
             if (!labelId) {
-              throw new NotFoundError("Issue label", label)
+              throw new NotFoundError("Issue label", name, {
+                suggestion:
+                  `Run \`linear label list --team ${teamKey}\` to see available labels.`,
+              })
+            }
+            if (!ids.includes(labelId)) {
+              ids.push(labelId)
             }
-            labelIds.push(labelId)
           }
+          return ids
+        }
+
+        const labelIds = labels != null ? await resolveLabelIds(labels) : []
+        const addedLabelIds = addLabel != null
+          ? await resolveLabelIds(addLabel)
+          : []
+        const removedLabelIds = removeLabel != null
+          ? await resolveLabelIds(removeLabel)
+          : []
+
+        if (addedLabelIds.some((id) => removedLabelIds.includes(id))) {
+          throw new ValidationError(
+            "Cannot add and remove the same label in one update",
+            {
+              suggestion:
+                "Remove the duplicate label from either --add-label or --remove-label.",
+            },
+          )
         }
 
         let projectId: string | undefined = undefined
@@ -289,7 +350,12 @@ export const updateCommand = new Command()
         if (priority !== undefined) input.priority = priority
         if (estimate !== undefined) input.estimate = estimate
         if (finalDescription !== undefined) input.description = finalDescription
-        if (labelIds.length > 0) input.labelIds = labelIds
+        if (labels != null) {
+          input.labelIds = labelIds
+        } else {
+          if (addLabel != null) input.addedLabelIds = addedLabelIds
+          if (removeLabel != null) input.removedLabelIds = removedLabelIds
+        }
         if (teamId !== undefined) input.teamId = teamId
         if (projectId !== undefined) input.projectId = projectId
         if (projectMilestoneId !== undefined) {
diff --git a/test/commands/issue/__snapshots__/issue-update.test.ts.snap b/test/commands/issue/__snapshots__/issue-update.test.ts.snap
index 1633eda8..c30d6d16 100644
--- a/test/commands/issue/__snapshots__/issue-update.test.ts.snap
+++ b/test/commands/issue/__snapshots__/issue-update.test.ts.snap
@@ -20,7 +20,11 @@ Options:
   --estimate          <estimate>     - Points estimate of the issue                                                     
   -d, --description   <description>  - Description of the issue                                                         
   --description-file  <path>         - Read description from a file (preferred for markdown content)                    
-  -l, --label         <label>        - Issue label associated with the issue. May be repeated.                          
+  -l, --label         <label>        - Issue label associated with the issue; replaces the issue's entire label set.    
+                                       May be repeated. Use --add-label/--remove-label to change labels incrementally.  
+  --add-label         <label>        - Add a label to the issue, keeping its existing labels. May be repeated.          
+  --remove-label      <label>        - Remove a label from the issue, keeping its other labels (does not delete the     
+                                       label from the team). May be repeated.                                           
   --team              <team>         - Team associated with the issue (if not your default team)                        
   --project           <project>      - Project to assign the issue to (UUID, slug ID, or name)                          
   -s, --state         <state>        - Workflow state for the issue (by name or type)                                   
@@ -219,3 +223,121 @@ https://linear.app/test-team/issue/ENG-123/some-issue
 stderr:
 ""
 `;
+
+snapshot[`Issue Update Command - Add Label Sends addedLabelIds 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue ENG-123: Some issue
+https://linear.app/test-team/issue/ENG-123/some-issue
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Update Command - Add Label Dedupes Case Variants 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue ENG-123: Some issue
+https://linear.app/test-team/issue/ENG-123/some-issue
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Update Command - Remove Label Sends removedLabelIds 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue ENG-123: Some issue
+https://linear.app/test-team/issue/ENG-123/some-issue
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Update Command - Add And Remove Label In One Update 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue ENG-123: Some issue
+https://linear.app/test-team/issue/ENG-123/some-issue
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Update Command - Label Replace Sends Exact labelIds 1`] = `
+stdout:
+"Updating issue ENG-123
+
+✓ Updated issue ENG-123: Some issue
+https://linear.app/test-team/issue/ENG-123/some-issue
+"
+stderr:
+""
+`;
+
+snapshot[`Issue Update Command - Label And Add Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Cannot combine --label with --add-label or --remove-label
+  --label replaces the issue's entire label set. Use it alone to set the exact set, or use --add-label/--remove-label alone to change it incrementally.
+"
+`;
+
+snapshot[`Issue Update Command - Label And Remove Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Cannot combine --label with --add-label or --remove-label
+  --label replaces the issue's entire label set. Use it alone to set the exact set, or use --add-label/--remove-label alone to change it incrementally.
+"
+`;
+
+snapshot[`Issue Update Command - Team Move And Add Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Cannot combine --team with --add-label or --remove-label
+  Move the issue with --team first, then change labels in a second update.
+"
+`;
+
+snapshot[`Issue Update Command - Team Move And Remove Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Cannot combine --team with --add-label or --remove-label
+  Move the issue with --team first, then change labels in a second update.
+"
+`;
+
+snapshot[`Issue Update Command - Add And Remove Same Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Cannot add and remove the same label in one update
+  Remove the duplicate label from either --add-label or --remove-label.
+"
+`;
+
+snapshot[`Issue Update Command - Unknown Add Label 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Issue label not found: nosuch
+  Run \`linear label list --team ENG\` to see available labels.
+"
+`;
+
+snapshot[`Issue Update Command - Unknown Remove Label 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update issue: Issue label not found: nosuch
+  Run \`linear label list --team ENG\` to see available labels.
+"
+`;
diff --git a/test/commands/issue/issue-update.test.ts b/test/commands/issue/issue-update.test.ts
index a7c1d5b5..2f56f64c 100644
--- a/test/commands/issue/issue-update.test.ts
+++ b/test/commands/issue/issue-update.test.ts
@@ -1268,3 +1268,493 @@ Deno.test("Issue Update Command - --cycle now errors helpfully when no cycle is
     true,
   )
 })
+
+// --add-label must send `addedLabelIds` and must NOT send `labelIds` — the
+// exact-variables mock proves the incremental field is used and the replace
+// field is absent (a wrong payload falls through to "no mock configured").
+await snapshotTest({
+  name: "Issue Update Command - Add Label Sends addedLabelIds",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--add-label", "frontend"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "frontend", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-frontend-456", name: "frontend" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: {
+            addedLabelIds: ["label-frontend-456"],
+            teamId: "team-eng-id",
+          },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "ENG-123",
+                url: "https://linear.app/test-team/issue/ENG-123/some-issue",
+                title: "Some issue",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// Case variants resolving to the same label collapse to a single ID.
+await snapshotTest({
+  name: "Issue Update Command - Add Label Dedupes Case Variants",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--add-label", "Bug", "--add-label", "BUG"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "Bug", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: { nodes: [{ id: "label-bug-123", name: "bug" }] },
+          },
+        },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "BUG", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: { nodes: [{ id: "label-bug-123", name: "bug" }] },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: { addedLabelIds: ["label-bug-123"], teamId: "team-eng-id" },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "ENG-123",
+                url: "https://linear.app/test-team/issue/ENG-123/some-issue",
+                title: "Some issue",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// The issue #258 workflow: detach a stale sprint label from one issue without
+// deleting it team-wide. No issue-read mock exists, so an accidental pre-read
+// of the issue's current labels would fail this test.
+await snapshotTest({
+  name: "Issue Update Command - Remove Label Sends removedLabelIds",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--remove-label", "sprint-42"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "sprint-42", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-sprint-42", name: "sprint-42" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: {
+            removedLabelIds: ["label-sprint-42"],
+            teamId: "team-eng-id",
+          },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "ENG-123",
+                url: "https://linear.app/test-team/issue/ENG-123/some-issue",
+                title: "Some issue",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// Add and remove compose into ONE atomic mutation carrying both arrays.
+await snapshotTest({
+  name: "Issue Update Command - Add And Remove Label In One Update",
+  meta: import.meta,
+  colors: false,
+  args: [
+    "ENG-123",
+    "--add-label",
+    "sprint-43",
+    "--remove-label",
+    "sprint-42",
+  ],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "sprint-43", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-sprint-43", name: "sprint-43" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "sprint-42", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-sprint-42", name: "sprint-42" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: {
+            addedLabelIds: ["label-sprint-43"],
+            removedLabelIds: ["label-sprint-42"],
+            teamId: "team-eng-id",
+          },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "ENG-123",
+                url: "https://linear.app/test-team/issue/ENG-123/some-issue",
+                title: "Some issue",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// The legacy replace path: --label must still send labelIds (deduped) and no
+// incremental fields. The older --label tests don't pin UpdateIssue variables,
+// so this is the test that actually proves replace semantics on the wire.
+await snapshotTest({
+  name: "Issue Update Command - Label Replace Sends Exact labelIds",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--label", "Frontend", "--label", "FRONTEND"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "Frontend", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-frontend-456", name: "frontend" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "FRONTEND", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: {
+              nodes: [{ id: "label-frontend-456", name: "frontend" }],
+            },
+          },
+        },
+      },
+      {
+        queryName: "UpdateIssue",
+        variables: {
+          id: "ENG-123",
+          input: { labelIds: ["label-frontend-456"], teamId: "team-eng-id" },
+        },
+        response: {
+          data: {
+            issueUpdate: {
+              success: true,
+              issue: {
+                id: "issue-existing-123",
+                identifier: "ENG-123",
+                url: "https://linear.app/test-team/issue/ENG-123/some-issue",
+                title: "Some issue",
+              },
+            },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// Conflict matrix: every invalid label-flag combination errors before any
+// network call (dead endpoint, like the --assignee/--unassign conflict test).
+await snapshotTest({
+  name: "Issue Update Command - Label And Add Label Conflict",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--label", "bug", "--add-label", "infra"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", "http://127.0.0.1:1")
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse()
+  },
+})
+
+await snapshotTest({
+  name: "Issue Update Command - Label And Remove Label Conflict",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--label", "bug", "--remove-label", "infra"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", "http://127.0.0.1:1")
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse()
+  },
+})
+
+// Label names resolve against the destination team, so a team move plus
+// incremental label changes is ambiguous — rejected until designed.
+await snapshotTest({
+  name: "Issue Update Command - Team Move And Add Label Conflict",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--team", "OPS", "--add-label", "bug"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", "http://127.0.0.1:1")
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse()
+  },
+})
+
+await snapshotTest({
+  name: "Issue Update Command - Team Move And Remove Label Conflict",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--team", "OPS", "--remove-label", "bug"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", "http://127.0.0.1:1")
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse()
+  },
+})
+
+// Same label (via case variants resolving to one ID) in both --add-label and
+// --remove-label is ambiguous. No UpdateIssue mock: the error must fire
+// before the mutation.
+await snapshotTest({
+  name: "Issue Update Command - Add And Remove Same Label Conflict",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--add-label", "Bug", "--remove-label", "BUG"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "Bug", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: { nodes: [{ id: "label-bug-123", name: "bug" }] },
+          },
+        },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "BUG", teamKey: "ENG" },
+        response: {
+          data: {
+            issueLabels: { nodes: [{ id: "label-bug-123", name: "bug" }] },
+          },
+        },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+// Unknown label names error with a lookup hint, in both directions.
+await snapshotTest({
+  name: "Issue Update Command - Unknown Add Label",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--add-label", "nosuch"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "nosuch", teamKey: "ENG" },
+        response: { data: { issueLabels: { nodes: [] } } },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})
+
+await snapshotTest({
+  name: "Issue Update Command - Unknown Remove Label",
+  meta: import.meta,
+  colors: false,
+  args: ["ENG-123", "--remove-label", "nosuch"],
+  denoArgs: commonDenoArgs,
+  canFail: true,
+  async fn() {
+    const { cleanup } = await setupMockLinearServer([
+      {
+        queryName: "GetTeamIdByKey",
+        variables: { team: "ENG" },
+        response: { data: { teams: { nodes: [{ id: "team-eng-id" }] } } },
+      },
+      {
+        queryName: "GetIssueLabelIdByNameForTeam",
+        variables: { name: "nosuch", teamKey: "ENG" },
+        response: { data: { issueLabels: { nodes: [] } } },
+      },
+    ], { LINEAR_TEAM_ID: "ENG" })
+
+    try {
+      await updateCommand.parse()
+    } finally {
+      await cleanup()
+    }
+  },
+})