From 10553fe632d83c1f30d02947f738429657bbc1b2 Mon Sep 17 00:00:00 2001
From: Peter Schilling <code@schpet.com>
Date: Sat, 5 Sep 2026 07:58:21 -0700
Subject: [PATCH] Add, remove, and set flags for project teams, labels, and
 initiatives

project update could only replace a project's teams and labels, and could
not change initiatives at all: project create accepts --initiative, but
after creation the only route was a hand-written mutation. Every
collection field an update command can change should offer the same three
operations, following the pattern issue update already has for labels:
--team/--label/--initiative replace the whole set, --add-* appends,
--remove-* detaches, all repeatable, and a replace flag cannot be combined
with its add/remove flags.

Linear's ProjectUpdateInput only takes a full teamIds/labelIds list, so
add and remove read the project's current connection, following every
page, compute the new set, and send it. Removing something the project
does not have is an error that lists what it does have, rather than a
silent no-op, and removing the last team errors up front because Linear
rejects an empty teamIds. Initiatives have no input field: membership is
an InitiativeToProject join row, so all three initiative flags diff the
desired set against the current rows and run initiativeToProjectDelete
then initiativeToProjectCreate. Deletes go first because a project may
appear only once in an initiative hierarchy, so moving it to a parent or
child initiative is rejected while the old link still exists; that is
also why a UUID-shaped initiative is confirmed to exist before any link
is touched, since the shared resolver passes UUIDs through unchecked.
Those mutations are not transactional, so a failure part-way reports what
was applied, including the already-committed project fields, and what is
still pending, with the remaining flags given by initiative ID because
names are not unique, instead of implying a rollback.

The survey of issue update and initiative update found no other
replace-only collection flag: IssueUpdateInput's releaseIds and
subscriberIds and InitiativeUpdateInput's labelIds are not exposed by
either command.

Claude-Session: https://claude.ai/code/session_01A9qEGri4p2HZMQSuYsBmub
---
 CHANGELOG.md                                  |   1 +
 README.md                                     |   2 +
 docs/usage.md                                 |   9 +
 .../references/organization-features.md       |   9 +
 skills/linear-cli/references/project.md       |  48 +-
 src/commands/project/project-update.ts        | 606 +++++++++++++++++-
 .../__snapshots__/project-update.test.ts.snap |  91 ++-
 test/commands/project/project-update.test.ts  | 549 ++++++++++++++++
 8 files changed, 1248 insertions(+), 67 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c2142bc..72e60cf8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 - `issue query --state` and `issue mine --state` accept a workflow state name or ID as well as the six state types, looked up within the queried team scope (all teams under `--all-teams`, where a name matches every team's same-named state). An unknown name errors and lists the scope's states, and types and names can be mixed
 - `project update --content <markdown>` and `--content-file <path>` replace a project's long-form overview body, matching the flags `project create` already had. Previously the only way to change the body after creation was a hand-written `projectUpdate` mutation through `linear api`
 - `issue update --clear-due-date`, `--clear-estimate`, `--clear-parent`, `--clear-project`, and `--clear-milestone`, plus `project update --clear-lead`, `--clear-start-date`, and `--clear-target-date`, to remove a value the way `--unassign` and `--clear-cycle` already do. Each sends an explicit `null` to Linear and errors when combined with its set flag; `--clear-project` also rejects `--milestone`, since a milestone belongs to the project being removed. Previously these fields could only be changed, never cleared: cliffy treats `--due-date ""` as a missing value
+- `project update` now changes teams, labels, and initiatives with the same three operations `issue update` has for labels: `--team`, `--label`, and `--initiative` replace the whole set, `--add-team`/`--add-label`/`--add-initiative` append, and `--remove-team`/`--remove-label`/`--remove-initiative` detach, all repeatable, with a replace flag rejected alongside its add/remove flags. Linear's project input only accepts a full `teamIds`/`labelIds` list, so add and remove read the project's current set (every page of it) and send the computed set; initiatives have no input field at all and go through the initiative-to-project link mutations, so `project update` previously could not change them after `project create --initiative`. Removing a team, label, or initiative the project does not have errors and lists what it does have, and a link change that fails part-way reports what was applied and what is still pending
 - `--json` (`-j`) on `team list`, `cycle list`, `cycle view`, `milestone list`, `milestone view`, and `project view`, the last read commands without machine-readable output. List commands emit the same `{ nodes, pageInfo }` connection shape as the other list commands, after the same filtering and ordering as the table; view commands emit the GraphQL object as fetched, including every issue rather than the ten-item preview, and `milestone view --all --json` includes every page. (A 2.0.0 entry claimed `cycle list --json`; that change never actually landed.) ([#276](https://github.com/schpet/linear-cli/issues/276); thanks @lakardion)
 
 ### Fixed
diff --git a/README.md b/README.md
index 6e62c1f0..e9c4e328 100644
--- a/README.md
+++ b/README.md
@@ -204,6 +204,8 @@ linear project create --name "API v2" --team ENG --content-file overview.md
 linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com
 linear project update <projectId> --content-file overview.md  # replace the project's overview body
 linear project update <projectId> --clear-lead --clear-target-date  # remove values (also --clear-start-date)
+linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets"  # change teams, labels, initiatives incrementally
+linear project update <projectId> --team ENG --team OPS   # replace the whole team set (--label and --initiative replace likewise)
 linear project comment list <project>                         # list the project's discussion thread (UUID, slug, or name)
 linear project comment add <project> --body "Kickoff Monday"  # comment on a project
 linear project comment add <project> --body "+1" --reply-to <commentId>  # reply in a thread
diff --git a/docs/usage.md b/docs/usage.md
index 2982021b..1356845c 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -317,6 +317,15 @@ linear project update PROJECT-ID --content-file overview.md
 
 # Remove the lead, start date, or target date (each conflicts with its set flag)
 linear project update PROJECT-ID --clear-lead --clear-start-date --clear-target-date
+
+# Teams, labels, and initiatives are sets. --team, --label, and --initiative
+# replace the whole set; --add-*/--remove-* change it incrementally. All are
+# repeatable, and a replace flag cannot be combined with its add/remove flags.
+linear project update PROJECT-ID --add-team OPS --remove-team APP
+linear project update PROJECT-ID --add-label Launch --remove-label Beta
+linear project update PROJECT-ID --add-initiative "Q4 Bets"     # ID, slug, or name
+linear project update PROJECT-ID --initiative "Q4 Bets" --initiative "Platform"  # exactly these
+# Removing a team, label, or initiative the project does not have is an error.
 ```
 
 #### list projects
diff --git a/skills/linear-cli/references/organization-features.md b/skills/linear-cli/references/organization-features.md
index 318c6c3a..2d2328f2 100644
--- a/skills/linear-cli/references/organization-features.md
+++ b/skills/linear-cli/references/organization-features.md
@@ -56,6 +56,15 @@ linear project view <id>
 linear project create --name "New Feature" --team DEV
 linear project create --name "Q1 Work" --team DEV --initiative "Q1 Goals"
 linear project create -i  # Interactive mode
+
+# Change a project's teams, labels, or initiatives incrementally
+linear project update <id> --add-team OPS --remove-team APP
+linear project update <id> --add-label "Launch" --remove-label "Beta"
+linear project update <id> --add-initiative "Q1 Goals"   # ID, slug, or name
+
+# Replace a whole set (cannot be combined with that set's --add-*/--remove-*)
+linear project update <id> --team DEV --team OPS
+linear project update <id> --initiative "Q1 Goals" --initiative "Platform"
 ```
 
 ## Bulk Operations
diff --git a/skills/linear-cli/references/project.md b/skills/linear-cli/references/project.md
index 78715273..1ec28cfb 100644
--- a/skills/linear-cli/references/project.md
+++ b/skills/linear-cli/references/project.md
@@ -191,23 +191,37 @@ Description:
 
 Options:
 
-  -h, --help                             - Show this help.                                                             
-  --workspace             <slug>         - Target workspace (uses credentials)                                         
-  -n, --name              <name>         - Project name                                                                
-  -d, --description       <description>  - Project description (max 255 characters, enforced by Linear's API)          
-  -f, --description-file  <path>         - Read project description from file (still subject to the 255-character API  
-                                           limit)                                                                      
-  --content               <markdown>     - Project overview markdown                                                   
-  --content-file          <path>         - Read project overview markdown from a file                                  
-  -s, --status            <status>       - Status (planned, started, paused, completed, canceled, backlog)             
-  -l, --lead              <lead>         - Project lead (username, email, or @me). Use --clear-lead to remove it       
-  --clear-lead                           - Remove the project's lead (cannot be combined with --lead)                  
-  --start-date            <startDate>    - Start date (YYYY-MM-DD). Use --clear-start-date to remove it                
-  --clear-start-date                     - Remove the project's start date (cannot be combined with --start-date)      
-  --target-date           <targetDate>   - Target date (YYYY-MM-DD). Use --clear-target-date to remove it              
-  --clear-target-date                    - Remove the project's target date (cannot be combined with --target-date)    
-  -t, --team              <team>         - Team key, name, or ID (can be repeated for multiple teams)                  
-  --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.
+  -h, --help                             - Show this help.                                                                  
+  --workspace             <slug>         - Target workspace (uses credentials)                                              
+  -n, --name              <name>         - Project name                                                                     
+  -d, --description       <description>  - Project description (max 255 characters, enforced by Linear's API)               
+  -f, --description-file  <path>         - Read project description from file (still subject to the 255-character API       
+                                           limit)                                                                           
+  --content               <markdown>     - Project overview markdown                                                        
+  --content-file          <path>         - Read project overview markdown from a file                                       
+  -s, --status            <status>       - Status (planned, started, paused, completed, canceled, backlog)                  
+  -l, --lead              <lead>         - Project lead (username, email, or @me). Use --clear-lead to remove it            
+  --clear-lead                           - Remove the project's lead (cannot be combined with --lead)                       
+  --start-date            <startDate>    - Start date (YYYY-MM-DD). Use --clear-start-date to remove it                     
+  --clear-start-date                     - Remove the project's start date (cannot be combined with --start-date)           
+  --target-date           <targetDate>   - Target date (YYYY-MM-DD). Use --clear-target-date to remove it                   
+  --clear-target-date                    - Remove the project's target date (cannot be combined with --target-date)         
+  -t, --team              <team>         - Team key, name, or ID; replaces the project's entire team set. May be repeated.  
+                                           Use --add-team/--remove-team to change teams incrementally.                      
+  --add-team              <team>         - Add a team to the project, keeping its existing teams. May be repeated.          
+  --remove-team           <team>         - Remove a team from the project, keeping its other teams. May be repeated.        
+  --label                 <label>        - Project label; replaces the project's entire label set. May be repeated. Use     
+                                           --add-label/--remove-label to change labels incrementally.                       
+  --add-label             <label>        - Add a label to the project, keeping its existing labels. May be repeated.        
+  --remove-label          <label>        - Remove a label from the project, keeping its other labels (does not delete the   
+                                           label). May be repeated.                                                         
+  --initiative            <initiative>   - Initiative ID, slug, or name; replaces the project's entire initiative set. May  
+                                           be repeated. Use --add-initiative/--remove-initiative to change initiatives      
+                                           incrementally.                                                                   
+  --add-initiative        <initiative>   - Add the project to an initiative, keeping its existing initiatives. May be       
+                                           repeated.                                                                        
+  --remove-initiative     <initiative>   - Remove the project from an initiative, keeping its other initiatives (does not   
+                                           delete the initiative). May be repeated.
 ```
 
 ### view
diff --git a/src/commands/project/project-update.ts b/src/commands/project/project-update.ts
index 3cfb7f49..a1f585c1 100644
--- a/src/commands/project/project-update.ts
+++ b/src/commands/project/project-update.ts
@@ -2,9 +2,12 @@ import { Command } from "@cliffy/command"
 import { gql } from "../../__codegen__/gql.ts"
 import type { ProjectUpdateInput } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
+import type { GraphQLClient } from "graphql-request"
 import {
   getProjectLabelIdByName,
+  isLinearUuid,
   lookupUserId,
+  resolveInitiativeId,
   resolveProjectId,
   resolveTeams,
 } from "../../utils/linear.ts"
@@ -50,6 +53,102 @@ const GetProjectStatuses = gql(`
   }
 `)
 
+// ProjectUpdateInput only has replace-style teamIds/labelIds, so --add-*/
+// --remove-* read the current set, compute the new one, and send the full
+// set. Each connection is paginated: a project with more than one page must
+// never have its later pages silently dropped from the replacement set.
+const GetProjectTeamsForUpdate = gql(`
+  query GetProjectTeamsForUpdate($id: String!, $after: String) {
+    project(id: $id) {
+      teams(first: 250, after: $after) {
+        nodes {
+          id
+          key
+          name
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`)
+
+const GetProjectLabelsForUpdate = gql(`
+  query GetProjectLabelsForUpdate($id: String!, $after: String) {
+    project(id: $id) {
+      labels(first: 250, after: $after) {
+        nodes {
+          id
+          name
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`)
+
+// Initiative membership is a join row (InitiativeToProject) with no field on
+// ProjectUpdateInput; the row id is what the delete mutation needs. name/url
+// are selected so an initiative-only update can print the success line
+// without sending an empty projectUpdate.
+const GetProjectInitiativeLinksForUpdate = gql(`
+  query GetProjectInitiativeLinksForUpdate($id: String!, $after: String) {
+    project(id: $id) {
+      id
+      name
+      url
+      initiativeToProjects(first: 250, after: $after) {
+        nodes {
+          id
+          initiative {
+            id
+            name
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`)
+
+// resolveInitiativeId passes a UUID through unchecked. Links are deleted
+// before new ones are created, so an unknown UUID must be caught here or a
+// replace would drop the old links and then fail to add the new one.
+const GetInitiativeByIdForUpdate = gql(`
+  query GetInitiativeByIdForUpdate($id: ID!) {
+    initiatives(filter: { id: { eq: $id } }) {
+      nodes {
+        id
+        name
+      }
+    }
+  }
+`)
+
+const AddProjectToInitiativeForUpdate = gql(`
+  mutation AddProjectToInitiativeForUpdate($input: InitiativeToProjectCreateInput!) {
+    initiativeToProjectCreate(input: $input) {
+      success
+    }
+  }
+`)
+
+const RemoveProjectFromInitiativeForUpdate = gql(`
+  mutation RemoveProjectFromInitiativeForUpdate($id: String!) {
+    initiativeToProjectDelete(id: $id) {
+      success
+    }
+  }
+`)
+
 const STATUS_TYPE_MAPPING: Record<string, string> = {
   "planned": "planned",
   "in progress": "started",
@@ -60,6 +159,247 @@ const STATUS_TYPE_MAPPING: Record<string, string> = {
   "backlog": "backlog",
 }
 
+type Page<T> = {
+  nodes: T[]
+  pageInfo: { hasNextPage: boolean; endCursor?: string | null }
+}
+
+/** Follow a connection's cursor until every page has been read. */
+async function fetchAllPages<T extends { id: string }>(
+  fetchPage: (after: string | null) => Promise<Page<T>>,
+): Promise<T[]> {
+  const nodes: T[] = []
+  const seen = new Set<string>()
+  let after: string | null = null
+  while (true) {
+    const page: Page<T> = await fetchPage(after)
+    for (const node of page.nodes) {
+      if (seen.has(node.id)) continue
+      seen.add(node.id)
+      nodes.push(node)
+    }
+    if (!page.pageInfo.hasNextPage) return nodes
+    if (page.pageInfo.endCursor == null) {
+      throw new CliError(
+        "Linear reported another page of results but returned no cursor to fetch it",
+      )
+    }
+    if (page.pageInfo.endCursor === after) {
+      throw new CliError(
+        "Linear reported another page of results but returned the same cursor again",
+      )
+    }
+    after = page.pageInfo.endCursor
+  }
+}
+
+/** A user-supplied reference resolved to an id, keeping the reference for messages. */
+type ResolvedRef = { id: string; label: string }
+
+/**
+ * Apply --add/--remove to a collection: current order is kept, removed ids
+ * are dropped, added ids not already present are appended in flag order. A
+ * removal that is not in the current set throws before anything is sent.
+ */
+function applyCollectionEdit(opts: {
+  current: readonly string[]
+  add: readonly ResolvedRef[]
+  remove: readonly ResolvedRef[]
+  onMissing: (ref: ResolvedRef) => Error
+}): string[] {
+  const currentSet = new Set(opts.current)
+  for (const ref of opts.remove) {
+    if (!currentSet.has(ref.id)) throw opts.onMissing(ref)
+  }
+  const removeIds = new Set(opts.remove.map((r) => r.id))
+  const result = opts.current.filter((id) => !removeIds.has(id))
+  for (const ref of opts.add) {
+    if (!result.includes(ref.id)) result.push(ref.id)
+  }
+  return result
+}
+
+function rejectAddRemoveOverlap(
+  kind: "team" | "label" | "initiative",
+  add: readonly ResolvedRef[],
+  remove: readonly ResolvedRef[],
+): void {
+  const removeIds = new Set(remove.map((r) => r.id))
+  if (add.some((r) => removeIds.has(r.id))) {
+    throw new ValidationError(
+      `Cannot add and remove the same ${kind} in one update`,
+      {
+        suggestion:
+          `Remove the duplicate ${kind} from either --add-${kind} or --remove-${kind}.`,
+      },
+    )
+  }
+}
+
+function rejectReplaceWithIncremental(
+  kind: "team" | "label" | "initiative",
+  replace: readonly string[] | undefined,
+  add: readonly string[] | undefined,
+  remove: readonly string[] | undefined,
+): void {
+  if (replace != null && (add != null || remove != null)) {
+    throw new ValidationError(
+      `Cannot combine --${kind} with --add-${kind} or --remove-${kind}`,
+      {
+        suggestion:
+          `--${kind} replaces the project's entire ${kind} set. Use it alone to set the exact set, or use --add-${kind}/--remove-${kind} alone to change it incrementally.`,
+      },
+    )
+  }
+}
+
+/** Resolve project label names to ids, deduped by id, erroring on unknown names. */
+async function resolveProjectLabels(
+  names: readonly string[],
+): Promise<ResolvedRef[]> {
+  const resolved: ResolvedRef[] = []
+  for (const name of names) {
+    const id = await getProjectLabelIdByName(name)
+    if (!id) {
+      throw new NotFoundError("Project label", name)
+    }
+    if (!resolved.some((r) => r.id === id)) {
+      resolved.push({ id, label: name })
+    }
+  }
+  return resolved
+}
+
+async function resolveInitiatives(
+  client: GraphQLClient,
+  references: readonly string[],
+): Promise<ResolvedRef[]> {
+  const resolved: ResolvedRef[] = []
+  for (const reference of references) {
+    let ref: ResolvedRef
+    if (isLinearUuid(reference)) {
+      const data = await client.request(GetInitiativeByIdForUpdate, {
+        id: reference,
+      })
+      const initiative = data.initiatives.nodes[0]
+      if (initiative == null) {
+        throw new NotFoundError("Initiative", reference, {
+          suggestion:
+            "Pass an initiative UUID, slug ID, or exact initiative name.",
+        })
+      }
+      ref = { id: initiative.id, label: initiative.name }
+    } else {
+      ref = { id: await resolveInitiativeId(reference), label: reference }
+    }
+    if (!resolved.some((r) => r.id === ref.id)) {
+      resolved.push(ref)
+    }
+  }
+  return resolved
+}
+
+type InitiativeChange =
+  | { kind: "add"; initiativeId: string; label: string }
+  | { kind: "remove"; linkId: string; initiativeId: string; label: string }
+
+function describeInitiativeChange(change: InitiativeChange): string {
+  return change.kind === "add"
+    ? `added "${change.label}"`
+    : `removed "${change.label}"`
+}
+
+// By UUID: initiative names are not unique and the resolver rejects an
+// ambiguous name, so a name here could make the suggested command unrunnable.
+function initiativeChangeFlag(change: InitiativeChange): string {
+  return change.kind === "add"
+    ? `--add-initiative ${change.initiativeId}`
+    : `--remove-initiative ${change.initiativeId}`
+}
+
+/**
+ * Apply initiative link changes one mutation at a time. Linear has no
+ * transaction across join-row mutations, so a failure part-way leaves earlier
+ * changes applied; the error says exactly which, and which are still pending,
+ * instead of implying a rollback or that the identical command is safe to
+ * re-run (a completed --remove-initiative would fail its presence check).
+ * A request that throws may have been committed before the reply was lost,
+ * so that change is reported as unknown rather than as not applied.
+ */
+async function applyInitiativeChanges(
+  client: GraphQLClient,
+  projectId: string,
+  changes: readonly InitiativeChange[],
+  // Work already committed before these changes started (the projectUpdate
+  // for the other fields), so the failure report never reads as "no effect".
+  priorApplied: string | undefined,
+): Promise<void> {
+  const fail = (
+    applied: number,
+    outcome: "rejected" | "unknown",
+    cause: unknown,
+  ): CliError => {
+    const done = [
+      ...priorApplied != null ? [priorApplied] : [],
+      ...changes.slice(0, applied).map(describeInitiativeChange),
+    ]
+    const current = changes[applied]
+    const rest = changes.slice(applied + 1)
+    const unknownText = outcome === "unknown"
+      ? ` Unknown (the request failed before Linear answered): ${
+        describeInitiativeChange(current)
+      }.`
+      : ""
+    const notApplied = outcome === "unknown" ? rest : [current, ...rest]
+    const notAppliedText = notApplied.length > 0
+      ? ` Not applied: ${notApplied.map(describeInitiativeChange).join(", ")}.`
+      : ""
+    const remaining = [current, ...rest].map(initiativeChangeFlag).join(" ")
+    return new CliError(
+      `Failed to update project initiatives after ${applied} of ${changes.length} changes; earlier changes were not rolled back. Applied: ${
+        done.length > 0 ? done.join(", ") : "none"
+      }.${unknownText}${notAppliedText}`,
+      {
+        suggestion: outcome === "unknown"
+          ? `Check the project's initiatives, then re-run with only the remaining changes (${remaining}), or use --initiative to set the exact set.`
+          : `Re-run with only the remaining changes (${remaining}), or use --initiative to set the exact set.`,
+        cause,
+      },
+    )
+  }
+
+  let applied = 0
+  for (const change of changes) {
+    let success: boolean
+    try {
+      if (change.kind === "add") {
+        const result = await client.request(AddProjectToInitiativeForUpdate, {
+          input: { initiativeId: change.initiativeId, projectId },
+        })
+        success = result.initiativeToProjectCreate.success
+      } else {
+        const result = await client.request(
+          RemoveProjectFromInitiativeForUpdate,
+          { id: change.linkId },
+        )
+        success = result.initiativeToProjectDelete.success
+      }
+    } catch (cause) {
+      throw fail(applied, "unknown", cause)
+    }
+    if (!success) {
+      throw fail(
+        applied,
+        "rejected",
+        new CliError(
+          `Linear reported failure for initiative "${change.label}"`,
+        ),
+      )
+    }
+    applied++
+  }
+}
+
 export const updateCommand = new Command()
   .name("update")
   .description(withMarkdownHint("Update a Linear project"))
@@ -108,12 +448,47 @@ export const updateCommand = new Command()
   )
   .option(
     "-t, --team <team:string>",
-    "Team key, name, or ID (can be repeated for multiple teams)",
+    "Team key, name, or ID; replaces the project's entire team set. May be repeated. Use --add-team/--remove-team to change teams incrementally.",
+    { collect: true },
+  )
+  .option(
+    "--add-team <team:string>",
+    "Add a team to the project, keeping its existing teams. May be repeated.",
+    { collect: true },
+  )
+  .option(
+    "--remove-team <team:string>",
+    "Remove a team from the project, keeping its other teams. May be repeated.",
     { collect: true },
   )
   .option(
     "--label <label:string>",
-    "Replace the project's labels. May be repeated to set multiple labels.",
+    "Project label; replaces the project'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 project, keeping its existing labels. May be repeated.",
+    { collect: true },
+  )
+  .option(
+    "--remove-label <label:string>",
+    "Remove a label from the project, keeping its other labels (does not delete the label). May be repeated.",
+    { collect: true },
+  )
+  .option(
+    "--initiative <initiative:string>",
+    "Initiative ID, slug, or name; replaces the project's entire initiative set. May be repeated. Use --add-initiative/--remove-initiative to change initiatives incrementally.",
+    { collect: true },
+  )
+  .option(
+    "--add-initiative <initiative:string>",
+    "Add the project to an initiative, keeping its existing initiatives. May be repeated.",
+    { collect: true },
+  )
+  .option(
+    "--remove-initiative <initiative:string>",
+    "Remove the project from an initiative, keeping its other initiatives (does not delete the initiative). May be repeated.",
     { collect: true },
   )
   .action(
@@ -132,7 +507,14 @@ export const updateCommand = new Command()
         targetDate,
         clearTargetDate,
         team: teams,
+        addTeam,
+        removeTeam,
         label: labels,
+        addLabel,
+        removeLabel,
+        initiative: initiatives,
+        addInitiative,
+        removeInitiative,
       },
       projectId,
     ) => {
@@ -148,13 +530,16 @@ export const updateCommand = new Command()
           content == null && contentFile == null && !status &&
           !lead && !clearLead && !startDate && !clearStartDate &&
           !targetDate && !clearTargetDate &&
-          (!teams || teams.length === 0) && (!labels || labels.length === 0)
+          teams == null && addTeam == null && removeTeam == null &&
+          labels == null && addLabel == null && removeLabel == null &&
+          initiatives == null && addInitiative == null &&
+          removeInitiative == null
         ) {
           throw new ValidationError(
             "At least one update option must be provided",
             {
               suggestion:
-                "Use --name, --description, --description-file, --content, --content-file, --status, --lead, --clear-lead, --start-date, --clear-start-date, --target-date, --clear-target-date, --team, or --label",
+                "Use --name, --description, --description-file, --content, --content-file, --status, --lead, --clear-lead, --start-date, --clear-start-date, --target-date, --clear-target-date, --team, --add-team, --remove-team, --label, --add-label, --remove-label, --initiative, --add-initiative, or --remove-initiative",
             },
           )
         }
@@ -189,13 +574,26 @@ export const updateCommand = new Command()
           )
         }
 
-        if (labels) {
-          for (const label of labels) {
-            if (label.trim() === "") {
-              throw new ValidationError("Project label cannot be empty", {
-                suggestion: 'Provide a label name, e.g. --label "My Label".',
-              })
-            }
+        rejectReplaceWithIncremental("team", teams, addTeam, removeTeam)
+        rejectReplaceWithIncremental("label", labels, addLabel, removeLabel)
+        rejectReplaceWithIncremental(
+          "initiative",
+          initiatives,
+          addInitiative,
+          removeInitiative,
+        )
+
+        for (
+          const label of [
+            ...labels ?? [],
+            ...addLabel ?? [],
+            ...removeLabel ?? [],
+          ]
+        ) {
+          if (label.trim() === "") {
+            throw new ValidationError("Project label cannot be empty", {
+              suggestion: 'Provide a label name, e.g. --label "My Label".',
+            })
           }
         }
 
@@ -271,40 +669,180 @@ export const updateCommand = new Command()
           input.leadId = leadId
         }
 
-        if (teams && teams.length > 0) {
+        if (teams != null) {
           input.teamIds = (await resolveTeams(teams)).map((t) => t.id)
+        } else if (addTeam != null || removeTeam != null) {
+          const toRef = (t: { id: string; key: string }): ResolvedRef => ({
+            id: t.id,
+            label: t.key,
+          })
+          const added = (await resolveTeams(addTeam ?? [])).map(toRef)
+          const removed = (await resolveTeams(removeTeam ?? [])).map(toRef)
+          rejectAddRemoveOverlap("team", added, removed)
+          const current = await fetchAllPages(async (after) => {
+            const data = await client.request(GetProjectTeamsForUpdate, {
+              id: resolvedId,
+              after,
+            })
+            return data.project.teams
+          })
+          const teamIds = applyCollectionEdit({
+            current: current.map((t) => t.id),
+            add: added,
+            remove: removed,
+            onMissing: (ref) =>
+              new ValidationError(
+                `Cannot remove team "${ref.label}": it is not on this project`,
+                {
+                  suggestion: `Current teams: ${
+                    current.map((t) => `${t.key} (${t.name})`).join(", ")
+                  }. Use --add-team to add one.`,
+                },
+              ),
+          })
+          // Verified against the API: projectUpdate rejects teamIds: [] with
+          // "teamIds must contain at least 1 elements".
+          if (teamIds.length === 0) {
+            throw new ValidationError(
+              "Removing these teams would leave the project with no teams; Linear requires at least one",
+              {
+                suggestion:
+                  "Keep at least one team, or use --team to replace the set.",
+              },
+            )
+          }
+          input.teamIds = teamIds
         }
 
-        if (labels && labels.length > 0) {
+        if (labels != null) {
           // Replace the project's labels with exactly the resolved set,
           // matching `project update --team` and `issue update --label`.
-          const labelIds: string[] = []
-          const seen = new Set<string>()
-          for (const label of labels) {
-            const labelId = await getProjectLabelIdByName(label)
-            if (!labelId) {
-              spinner?.stop()
-              throw new NotFoundError("Project label", label)
-            }
-            if (!seen.has(labelId)) {
-              seen.add(labelId)
-              labelIds.push(labelId)
+          input.labelIds = (await resolveProjectLabels(labels)).map((l) => l.id)
+        } else if (addLabel != null || removeLabel != null) {
+          const added = await resolveProjectLabels(addLabel ?? [])
+          const removed = await resolveProjectLabels(removeLabel ?? [])
+          rejectAddRemoveOverlap("label", added, removed)
+          const current = await fetchAllPages(async (after) => {
+            const data = await client.request(GetProjectLabelsForUpdate, {
+              id: resolvedId,
+              after,
+            })
+            return data.project.labels
+          })
+          input.labelIds = applyCollectionEdit({
+            current: current.map((l) => l.id),
+            add: added,
+            remove: removed,
+            onMissing: (ref) =>
+              new ValidationError(
+                `Cannot remove label "${ref.label}": it is not on this project`,
+                {
+                  suggestion: current.length > 0
+                    ? `Current labels: ${
+                      current.map((l) => l.name).join(", ")
+                    }. Use --add-label to add one.`
+                    : "The project has no labels. Use --add-label to add one.",
+                },
+              ),
+          })
+        }
+
+        let initiativeChanges: InitiativeChange[] = []
+        let projectFromLinks: { name: string; url: string } | undefined
+        if (
+          initiatives != null || addInitiative != null ||
+          removeInitiative != null
+        ) {
+          const replacement = initiatives != null
+            ? await resolveInitiatives(client, initiatives)
+            : undefined
+          const added = await resolveInitiatives(client, addInitiative ?? [])
+          const removed = await resolveInitiatives(
+            client,
+            removeInitiative ?? [],
+          )
+          rejectAddRemoveOverlap("initiative", added, removed)
+
+          const links = await fetchAllPages(async (after) => {
+            const data = await client.request(
+              GetProjectInitiativeLinksForUpdate,
+              { id: resolvedId, after },
+            )
+            projectFromLinks = {
+              name: data.project.name,
+              url: data.project.url,
             }
+            return data.project.initiativeToProjects
+          })
+          const currentIds = links.map((l) => l.initiative.id)
+          const desiredIds = replacement != null
+            ? replacement.map((r) => r.id)
+            : applyCollectionEdit({
+              current: currentIds,
+              add: added,
+              remove: removed,
+              onMissing: (ref) =>
+                new ValidationError(
+                  `Cannot remove initiative "${ref.label}": it is not linked to this project`,
+                  {
+                    suggestion: links.length > 0
+                      ? `Current initiatives: ${
+                        links.map((l) => l.initiative.name).join(", ")
+                      }. Use --add-initiative to link one.`
+                      : "The project is not linked to any initiative. Use --add-initiative to link one.",
+                  },
+                ),
+            })
+          const desired = new Set(desiredIds)
+          const current = new Set(currentIds)
+          const labelFor = (id: string): string =>
+            [...replacement ?? [], ...added].find((r) => r.id === id)?.label ??
+              id
+          // Deletes first: a project may appear only once in an initiative
+          // hierarchy, so moving it from an initiative to that initiative's
+          // parent or child is rejected while the old link still exists.
+          initiativeChanges = [
+            ...links.filter((l) => !desired.has(l.initiative.id)).map((l) => ({
+              kind: "remove" as const,
+              linkId: l.id,
+              initiativeId: l.initiative.id,
+              label: l.initiative.name,
+            })),
+            ...desiredIds.filter((id) => !current.has(id)).map((id) => ({
+              kind: "add" as const,
+              initiativeId: id,
+              label: labelFor(id),
+            })),
+          ]
+        }
+
+        // Everything above is resolution and validation; nothing has been
+        // sent yet. An initiative-only update has nothing for projectUpdate.
+        let project: { name: string; url: string } | undefined
+        if (Object.keys(input).length > 0) {
+          const result = await client.request(UpdateProject, {
+            id: resolvedId,
+            input,
+          })
+          if (!result.projectUpdate.success) {
+            throw new CliError("Failed to update project")
           }
-          input.labelIds = labelIds
+          const updated = result.projectUpdate.project
+          if (updated) project = { name: updated.name, url: updated.url }
+        } else {
+          project = projectFromLinks
         }
 
-        const result = await client.request(UpdateProject, {
-          id: resolvedId,
-          input,
-        })
+        await applyInitiativeChanges(
+          client,
+          resolvedId,
+          initiativeChanges,
+          Object.keys(input).length > 0
+            ? "updated the project's other fields"
+            : undefined,
+        )
         spinner?.stop()
 
-        if (!result.projectUpdate.success) {
-          throw new CliError("Failed to update project")
-        }
-
-        const project = result.projectUpdate.project
         if (project) {
           console.log(`✓ Updated project: ${project.name}`)
           if (project.url) {
diff --git a/test/commands/project/__snapshots__/project-update.test.ts.snap b/test/commands/project/__snapshots__/project-update.test.ts.snap
index 7080a982..4285bc3b 100644
--- a/test/commands/project/__snapshots__/project-update.test.ts.snap
+++ b/test/commands/project/__snapshots__/project-update.test.ts.snap
@@ -16,22 +16,36 @@ Description:
 
 Options:
 
-  -h, --help                             - Show this help.                                                             
-  -n, --name              <name>         - Project name                                                                
-  -d, --description       <description>  - Project description (max 255 characters, enforced by Linear's API)          
-  -f, --description-file  <path>         - Read project description from file (still subject to the 255-character API  
-                                           limit)                                                                      
-  --content               <markdown>     - Project overview markdown                                                   
-  --content-file          <path>         - Read project overview markdown from a file                                  
-  -s, --status            <status>       - Status (planned, started, paused, completed, canceled, backlog)             
-  -l, --lead              <lead>         - Project lead (username, email, or @me). Use --clear-lead to remove it       
-  --clear-lead                           - Remove the project's lead (cannot be combined with --lead)                  
-  --start-date            <startDate>    - Start date (YYYY-MM-DD). Use --clear-start-date to remove it                
-  --clear-start-date                     - Remove the project's start date (cannot be combined with --start-date)      
-  --target-date           <targetDate>   - Target date (YYYY-MM-DD). Use --clear-target-date to remove it              
-  --clear-target-date                    - Remove the project's target date (cannot be combined with --target-date)    
-  -t, --team              <team>         - Team key, name, or ID (can be repeated for multiple teams)                  
-  --label                 <label>        - Replace the project's labels. May be repeated to set multiple labels.       
+  -h, --help                             - Show this help.                                                                  
+  -n, --name              <name>         - Project name                                                                     
+  -d, --description       <description>  - Project description (max 255 characters, enforced by Linear's API)               
+  -f, --description-file  <path>         - Read project description from file (still subject to the 255-character API       
+                                           limit)                                                                           
+  --content               <markdown>     - Project overview markdown                                                        
+  --content-file          <path>         - Read project overview markdown from a file                                       
+  -s, --status            <status>       - Status (planned, started, paused, completed, canceled, backlog)                  
+  -l, --lead              <lead>         - Project lead (username, email, or @me). Use --clear-lead to remove it            
+  --clear-lead                           - Remove the project's lead (cannot be combined with --lead)                       
+  --start-date            <startDate>    - Start date (YYYY-MM-DD). Use --clear-start-date to remove it                     
+  --clear-start-date                     - Remove the project's start date (cannot be combined with --start-date)           
+  --target-date           <targetDate>   - Target date (YYYY-MM-DD). Use --clear-target-date to remove it                   
+  --clear-target-date                    - Remove the project's target date (cannot be combined with --target-date)         
+  -t, --team              <team>         - Team key, name, or ID; replaces the project's entire team set. May be repeated.  
+                                           Use --add-team/--remove-team to change teams incrementally.                      
+  --add-team              <team>         - Add a team to the project, keeping its existing teams. May be repeated.          
+  --remove-team           <team>         - Remove a team from the project, keeping its other teams. May be repeated.        
+  --label                 <label>        - Project label; replaces the project's entire label set. May be repeated. Use     
+                                           --add-label/--remove-label to change labels incrementally.                       
+  --add-label             <label>        - Add a label to the project, keeping its existing labels. May be repeated.        
+  --remove-label          <label>        - Remove a label from the project, keeping its other labels (does not delete the   
+                                           label). May be repeated.                                                         
+  --initiative            <initiative>   - Initiative ID, slug, or name; replaces the project's entire initiative set. May  
+                                           be repeated. Use --add-initiative/--remove-initiative to change initiatives      
+                                           incrementally.                                                                   
+  --add-initiative        <initiative>   - Add the project to an initiative, keeping its existing initiatives. May be       
+                                           repeated.                                                                        
+  --remove-initiative     <initiative>   - Remove the project from an initiative, keeping its other initiatives (does not   
+                                           delete the initiative). May be repeated.                                         
 
 "
 stderr:
@@ -109,3 +123,48 @@ https://linear.app/test/project/proj-content
 stderr:
 ""
 `;
+
+snapshot[`Project Update Command - Add Team Sends Full Team Set 1`] = `
+stdout:
+"✓ Updated project: Triad Project
+https://linear.app/test/project/triad
+"
+stderr:
+""
+`;
+
+snapshot[`Project Update Command - Replace Initiatives Creates And Deletes Links 1`] = `
+stdout:
+"✓ Updated project: Triad Project
+https://linear.app/test/project/triad
+"
+stderr:
+""
+`;
+
+snapshot[`Project Update Command - Team And Add Team Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update project: Cannot combine --team with --add-team or --remove-team
+  --team replaces the project's entire team set. Use it alone to set the exact set, or use --add-team/--remove-team alone to change it incrementally.
+"
+`;
+
+snapshot[`Project Update Command - Label And Remove Label Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update project: Cannot combine --label with --add-label or --remove-label
+  --label replaces the project's entire label set. Use it alone to set the exact set, or use --add-label/--remove-label alone to change it incrementally.
+"
+`;
+
+snapshot[`Project Update Command - Initiative And Add Initiative Conflict 1`] = `
+stdout:
+""
+stderr:
+"✗ Failed to update project: Cannot combine --initiative with --add-initiative or --remove-initiative
+  --initiative replaces the project's entire initiative set. Use it alone to set the exact set, or use --add-initiative/--remove-initiative alone to change it incrementally.
+"
+`;
diff --git a/test/commands/project/project-update.test.ts b/test/commands/project/project-update.test.ts
index 70edd22b..78229d23 100644
--- a/test/commands/project/project-update.test.ts
+++ b/test/commands/project/project-update.test.ts
@@ -832,3 +832,552 @@ Deno.test("Project Update Command - clear flags reject their set flags", async (
     })
   }
 })
+
+// --- collection triads: --team/--label/--initiative with --add-*/--remove-* --
+
+const TRIAD_PROJECT_ID = "550e8400-e29b-41d4-a716-446655440030"
+const INITIATIVE_A = "11111111-1111-4111-8111-111111111111"
+const INITIATIVE_B = "22222222-2222-4222-8222-222222222222"
+const INITIATIVE_C = "33333333-3333-4333-8333-333333333333"
+
+const TEAM_ENG = { id: "team-eng", key: "ENG", name: "Engineering" }
+const TEAM_OPS = { id: "team-ops", key: "OPS", name: "Operations" }
+const TEAM_APP = { id: "team-app", key: "APP", name: "App" }
+
+function resolveTeamMock(reference: string, team: typeof TEAM_ENG) {
+  return {
+    queryName: "ResolveTeam",
+    variables: { reference },
+    response: { data: { teams: { nodes: [team] } } },
+  }
+}
+
+function projectLabelMock(name: string, id: string) {
+  return {
+    queryName: "GetProjectLabelIdByName",
+    variables: { name },
+    response: { data: { projectLabels: { nodes: [{ id, name }] } } },
+  }
+}
+
+function pageInfo(endCursor?: string) {
+  return { hasNextPage: endCursor != null, endCursor: endCursor ?? null }
+}
+
+// Pinning `after` proves the cursor loop forwards the previous page's cursor.
+function projectTeamsPage(
+  after: string | null,
+  nodes: typeof TEAM_ENG[],
+  endCursor?: string,
+) {
+  return {
+    queryName: "GetProjectTeamsForUpdate",
+    variables: { id: TRIAD_PROJECT_ID, after },
+    response: {
+      data: { project: { teams: { nodes, pageInfo: pageInfo(endCursor) } } },
+    },
+  }
+}
+
+function projectLabelsPage(
+  after: string | null,
+  nodes: { id: string; name: string }[],
+  endCursor?: string,
+) {
+  return {
+    queryName: "GetProjectLabelsForUpdate",
+    variables: { id: TRIAD_PROJECT_ID, after },
+    response: {
+      data: { project: { labels: { nodes, pageInfo: pageInfo(endCursor) } } },
+    },
+  }
+}
+
+function initiativeLinksPage(
+  after: string | null,
+  nodes: { id: string; initiative: { id: string; name: string } }[],
+  endCursor?: string,
+) {
+  return {
+    queryName: "GetProjectInitiativeLinksForUpdate",
+    variables: { id: TRIAD_PROJECT_ID, after },
+    response: {
+      data: {
+        project: {
+          id: TRIAD_PROJECT_ID,
+          name: "Triad Project",
+          url: "https://linear.app/test/project/triad",
+          initiativeToProjects: { nodes, pageInfo: pageInfo(endCursor) },
+        },
+      },
+    },
+  }
+}
+
+// The exact `input` is pinned: an implementation that sends the wrong set (or
+// an additive field that does not exist on ProjectUpdateInput) cannot match.
+function updateTriadProjectMock(input: Record<string, unknown>) {
+  return {
+    queryName: "UpdateProject",
+    variables: { id: TRIAD_PROJECT_ID, input },
+    response: {
+      data: {
+        projectUpdate: {
+          success: true,
+          project: {
+            id: TRIAD_PROJECT_ID,
+            slugId: "triad",
+            name: "Triad Project",
+            description: null,
+            url: "https://linear.app/test/project/triad",
+            updatedAt: "2024-01-20T15:30:00Z",
+          },
+        },
+      },
+    },
+  }
+}
+
+function addInitiativeMock(initiativeId: string, success = true) {
+  return {
+    queryName: "AddProjectToInitiativeForUpdate",
+    variables: { input: { initiativeId, projectId: TRIAD_PROJECT_ID } },
+    response: { data: { initiativeToProjectCreate: { success } } },
+  }
+}
+
+function removeInitiativeMock(linkId: string) {
+  return {
+    queryName: "RemoveProjectFromInitiativeForUpdate",
+    variables: { id: linkId },
+    response: { data: { initiativeToProjectDelete: { success: true } } },
+  }
+}
+
+// A UUID-shaped initiative is confirmed to exist before any link is touched.
+function initiativeByIdMock(id: string, name: string | undefined) {
+  return {
+    queryName: "GetInitiativeByIdForUpdate",
+    variables: { id },
+    response: {
+      data: { initiatives: { nodes: name == null ? [] : [{ id, name }] } },
+    },
+  }
+}
+
+/** Run the command against a mock server, capturing stdout, stderr, and exit. */
+async function runTriad(
+  mocks: ConstructorParameters<typeof MockLinearServer>[0],
+  args: string[],
+): Promise<{ logs: string[]; errorLogs: string[]; exited: boolean }> {
+  const server = new MockLinearServer(mocks)
+  const logs: string[] = []
+  const errorLogs: string[] = []
+  const logStub = stub(console, "log", (...a: unknown[]) => {
+    logs.push(a.map(String).join(" "))
+  })
+  const errorStub = stub(console, "error", (...a: unknown[]) => {
+    errorLogs.push(a.map(String).join(" "))
+  })
+  const exitStub = stub(Deno, "exit", (_code?: number) => {
+    throw new Error("EXIT")
+  })
+  let exited = false
+  try {
+    await server.start()
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await updateCommand.parse([TRIAD_PROJECT_ID, ...args])
+  } catch (e) {
+    if (!(e instanceof Error) || e.message !== "EXIT") throw e
+    exited = true
+  } finally {
+    logStub.restore()
+    errorStub.restore()
+    exitStub.restore()
+    await server.stop()
+    Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+    Deno.env.delete("LINEAR_API_KEY")
+  }
+  return { logs, errorLogs, exited }
+}
+
+function assertUpdated(logs: string[]) {
+  assertEquals(logs.some((l) => l.includes("✓ Updated project")), true)
+}
+
+function assertErrored(
+  result: { logs: string[]; errorLogs: string[]; exited: boolean },
+  ...fragments: string[]
+) {
+  assertEquals(result.exited, true)
+  assertEquals(result.logs.some((l) => l.includes("✓ Updated project")), false)
+  for (const fragment of fragments) {
+    assertEquals(
+      result.errorLogs.some((l) => l.includes(fragment)),
+      true,
+      `expected stderr to include ${JSON.stringify(fragment)}, got:\n${
+        result.errorLogs.join("\n")
+      }`,
+    )
+  }
+}
+
+// --add-team reads the current teams and sends current + added as the full
+// teamIds set (ProjectUpdateInput has no addedTeamIds).
+await cliffySnapshotTest({
+  name: "Project Update Command - Add Team Sends Full Team Set",
+  meta: import.meta,
+  colors: false,
+  args: [TRIAD_PROJECT_ID, "--add-team", "OPS"],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    await runUpdateWithServer(
+      new MockLinearServer([
+        resolveTeamMock("OPS", TEAM_OPS),
+        projectTeamsPage(null, [TEAM_ENG]),
+        updateTriadProjectMock({ teamIds: ["team-eng", "team-ops"] }),
+      ]),
+    )
+  },
+})
+
+Deno.test("Project Update Command - remove team keeps the other teams", async () => {
+  const result = await runTriad([
+    resolveTeamMock("OPS", TEAM_OPS),
+    projectTeamsPage(null, [TEAM_ENG, TEAM_OPS]),
+    updateTriadProjectMock({ teamIds: ["team-eng"] }),
+  ], ["--remove-team", "OPS"])
+  assertUpdated(result.logs)
+})
+
+// A second page of teams must survive into the replacement set; the pinned
+// `after` cursor proves the loop asked for it.
+Deno.test("Project Update Command - add team reads every page of current teams", async () => {
+  const result = await runTriad([
+    resolveTeamMock("OPS", TEAM_OPS),
+    projectTeamsPage(null, [TEAM_ENG], "teams-cursor"),
+    projectTeamsPage("teams-cursor", [TEAM_APP]),
+    updateTriadProjectMock({ teamIds: ["team-eng", "team-app", "team-ops"] }),
+  ], ["--add-team", "OPS"])
+  assertUpdated(result.logs)
+})
+
+// A cursor that never advances would otherwise refetch the same page forever;
+// no UpdateProject mock, so the loop must exit through the error.
+Deno.test("Project Update Command - non-advancing page cursor errors instead of looping", async () => {
+  const result = await runTriad([
+    resolveTeamMock("OPS", TEAM_OPS),
+    projectTeamsPage(null, [TEAM_ENG], "stuck-cursor"),
+    projectTeamsPage("stuck-cursor", [TEAM_APP], "stuck-cursor"),
+  ], ["--add-team", "OPS"])
+  assertErrored(result, "returned the same cursor again")
+})
+
+// No UpdateProject mock: the error must fire before the mutation.
+Deno.test("Project Update Command - remove team not on the project errors", async () => {
+  const result = await runTriad([
+    resolveTeamMock("OPS", TEAM_OPS),
+    projectTeamsPage(null, [TEAM_ENG]),
+  ], ["--remove-team", "OPS"])
+  assertErrored(
+    result,
+    'Cannot remove team "OPS": it is not on this project',
+    "Current teams: ENG (Engineering)",
+  )
+})
+
+Deno.test("Project Update Command - removing the last team errors", async () => {
+  const result = await runTriad([
+    resolveTeamMock("ENG", TEAM_ENG),
+    projectTeamsPage(null, [TEAM_ENG]),
+  ], ["--remove-team", "ENG"])
+  assertErrored(
+    result,
+    "Removing these teams would leave the project with no teams",
+  )
+})
+
+// Two references resolving to one team (key and lowercase key) collapse to a
+// single id, so the overlap is detected on ids, not spelling.
+Deno.test("Project Update Command - same team in add and remove errors", async () => {
+  const result = await runTriad([
+    {
+      queryName: "ResolveTeam",
+      response: { data: { teams: { nodes: [TEAM_OPS] } } },
+    },
+  ], ["--add-team", "OPS", "--remove-team", "ops"])
+  assertErrored(result, "Cannot add and remove the same team in one update")
+})
+
+// Adding a label already on the project is a no-op (no duplicate id), and a
+// removal in the same update is applied to the same computed set.
+Deno.test("Project Update Command - add and remove labels together", async () => {
+  const result = await runTriad([
+    projectLabelMock("Frontend", "label-frontend"),
+    projectLabelMock("Backend", "label-backend"),
+    projectLabelsPage(null, [
+      { id: "label-frontend", name: "Frontend" },
+      { id: "label-backend", name: "Backend" },
+      { id: "label-launch", name: "Launch" },
+    ]),
+    updateTriadProjectMock({ labelIds: ["label-frontend", "label-launch"] }),
+  ], ["--add-label", "Frontend", "--remove-label", "Backend"])
+  assertUpdated(result.logs)
+})
+
+Deno.test("Project Update Command - add label reads every page of current labels", async () => {
+  const result = await runTriad([
+    projectLabelMock("Launch", "label-launch"),
+    projectLabelsPage(
+      null,
+      [{ id: "label-frontend", name: "Frontend" }],
+      "labels-cursor",
+    ),
+    projectLabelsPage("labels-cursor", [{
+      id: "label-backend",
+      name: "Backend",
+    }]),
+    updateTriadProjectMock({
+      labelIds: ["label-frontend", "label-backend", "label-launch"],
+    }),
+  ], ["--add-label", "Launch"])
+  assertUpdated(result.logs)
+})
+
+Deno.test("Project Update Command - remove label not on the project errors", async () => {
+  const result = await runTriad([
+    projectLabelMock("Launch", "label-launch"),
+    projectLabelsPage(null, [{ id: "label-frontend", name: "Frontend" }]),
+  ], ["--remove-label", "Launch"])
+  assertErrored(
+    result,
+    'Cannot remove label "Launch": it is not on this project',
+    "Current labels: Frontend",
+  )
+})
+
+// --initiative replaces the set through link mutations: the missing one is
+// created and the obsolete link row is deleted by its own id. There is no
+// UpdateProject mock, proving an initiative-only update skips projectUpdate.
+await cliffySnapshotTest({
+  name:
+    "Project Update Command - Replace Initiatives Creates And Deletes Links",
+  meta: import.meta,
+  colors: false,
+  args: [TRIAD_PROJECT_ID, "--initiative", INITIATIVE_B],
+  denoArgs: commonDenoArgs,
+  async fn() {
+    await runUpdateWithServer(
+      new MockLinearServer([
+        initiativeByIdMock(INITIATIVE_B, "Beta"),
+        initiativeLinksPage(null, [
+          { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+        ]),
+        addInitiativeMock(INITIATIVE_B),
+        removeInitiativeMock("link-a"),
+      ]),
+    )
+  },
+})
+
+Deno.test("Project Update Command - add initiative by name", async () => {
+  const result = await runTriad([
+    {
+      queryName: "ResolveInitiativeBySlug",
+      variables: { slugId: "Beta" },
+      response: { data: { initiatives: { nodes: [] } } },
+    },
+    {
+      queryName: "ResolveInitiativeByName",
+      variables: { name: "Beta" },
+      response: {
+        data: {
+          initiatives: {
+            nodes: [{ id: INITIATIVE_B, name: "Beta", slugId: "beta" }],
+          },
+        },
+      },
+    },
+    initiativeLinksPage(null, [
+      { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+    ]),
+    addInitiativeMock(INITIATIVE_B),
+  ], ["--add-initiative", "Beta"])
+  assertUpdated(result.logs)
+})
+
+// No mutation mocks at all: an already-linked initiative must not be re-added.
+Deno.test("Project Update Command - add already-linked initiative is a no-op", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_A, "Alpha"),
+    initiativeLinksPage(null, [
+      { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+    ]),
+  ], ["--add-initiative", INITIATIVE_A])
+  assertUpdated(result.logs)
+})
+
+Deno.test("Project Update Command - remove initiative not linked errors", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, "Beta"),
+    initiativeLinksPage(null, [
+      { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+    ]),
+  ], ["--remove-initiative", INITIATIVE_B])
+  assertErrored(
+    result,
+    'Cannot remove initiative "Beta": it is not linked to this project',
+    "Current initiatives: Alpha",
+  )
+})
+
+// Link mutations are not transactional. When the second of two reports
+// failure, the error names what was applied and what was not, and does not
+// claim success.
+Deno.test("Project Update Command - initiative failure after partial progress is reported", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, "Beta"),
+    initiativeByIdMock(INITIATIVE_C, "Gamma"),
+    initiativeLinksPage(null, []),
+    addInitiativeMock(INITIATIVE_B),
+    addInitiativeMock(INITIATIVE_C, false),
+  ], ["--initiative", INITIATIVE_B, "--initiative", INITIATIVE_C])
+  assertErrored(
+    result,
+    "Failed to update project initiatives after 1 of 2 changes; earlier changes were not rolled back",
+    'Applied: added "Beta"',
+    'Not applied: added "Gamma"',
+  )
+})
+
+// The thrown path: the create has no mock, so the request itself rejects
+// after the delete succeeded. A lost reply may follow a committed mutation,
+// so that change is reported as unknown, not as "not applied". "1 of 2"
+// with the removal applied also pins the ordering: deletes run before
+// creates, because a project may appear only once in an initiative
+// hierarchy and a move to a parent or child initiative is rejected while
+// the old link exists.
+Deno.test("Project Update Command - thrown initiative mutation after partial progress is reported", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, "Beta"),
+    initiativeLinksPage(null, [
+      { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+    ]),
+    removeInitiativeMock("link-a"),
+  ], ["--initiative", INITIATIVE_B])
+  assertErrored(
+    result,
+    "after 1 of 2 changes",
+    'Applied: removed "Alpha"',
+    'Unknown (the request failed before Linear answered): added "Beta"',
+    "Check the project's initiatives, then re-run",
+    `--add-initiative ${INITIATIVE_B}`,
+  )
+})
+
+// projectUpdate has already committed the other fields when a link mutation
+// fails, so the report must say so rather than "Applied: none".
+Deno.test("Project Update Command - initiative failure reports the already-applied project update", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, "Beta"),
+    initiativeLinksPage(null, []),
+    updateTriadProjectMock({ name: "Renamed" }),
+  ], ["--name", "Renamed", "--add-initiative", INITIATIVE_B])
+  assertErrored(
+    result,
+    "after 0 of 1 changes",
+    "Applied: updated the project's other fields.",
+    'Unknown (the request failed before Linear answered): added "Beta"',
+  )
+})
+
+// Retry flags name initiatives by UUID: names are not unique and the
+// resolver rejects an ambiguous one, so a name could make the suggested
+// command unrunnable.
+Deno.test("Project Update Command - suggested retry flags use initiative ids", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_A, "Alpha"),
+    initiativeLinksPage(null, [
+      { id: "link-a", initiative: { id: INITIATIVE_A, name: "Alpha" } },
+    ]),
+  ], ["--remove-initiative", INITIATIVE_A])
+  assertErrored(
+    result,
+    "after 0 of 1 changes",
+    "Applied: none.",
+    'Unknown (the request failed before Linear answered): removed "Alpha"',
+    `--remove-initiative ${INITIATIVE_A}`,
+  )
+})
+
+// Links are deleted before new ones are created, so an unknown UUID must be
+// rejected up front: no delete mock, so any deletion would surface as a
+// different error, and the read-back of current links never happens.
+Deno.test("Project Update Command - replace with an unknown initiative uuid errors before deleting links", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, undefined),
+  ], ["--initiative", INITIATIVE_B])
+  assertErrored(result, `Initiative not found: ${INITIATIVE_B}`)
+})
+
+// Scalar fields, a computed team set, and an initiative link in one call:
+// one pinned UpdateProject, then the link create, then one success line.
+Deno.test("Project Update Command - combined scalar, team, and initiative update", async () => {
+  const result = await runTriad([
+    initiativeByIdMock(INITIATIVE_B, "Beta"),
+    resolveTeamMock("OPS", TEAM_OPS),
+    projectTeamsPage(null, [TEAM_ENG]),
+    initiativeLinksPage(null, []),
+    updateTriadProjectMock({
+      name: "Renamed",
+      teamIds: ["team-eng", "team-ops"],
+    }),
+    addInitiativeMock(INITIATIVE_B),
+  ], [
+    "--name",
+    "Renamed",
+    "--add-team",
+    "OPS",
+    "--add-initiative",
+    INITIATIVE_B,
+  ])
+  assertEquals(
+    result.logs.filter((l) => l.includes("✓ Updated project")).length,
+    1,
+  )
+})
+
+// Replace cannot be combined with add/remove of the same kind. Dead endpoint:
+// the error must fire before any request.
+for (
+  const [name, args] of [
+    ["Team And Add Team Conflict", ["--team", "ENG", "--add-team", "OPS"]],
+    ["Label And Remove Label Conflict", [
+      "--label",
+      "Launch",
+      "--remove-label",
+      "Beta",
+    ]],
+    ["Initiative And Add Initiative Conflict", [
+      "--initiative",
+      INITIATIVE_A,
+      "--add-initiative",
+      INITIATIVE_B,
+    ]],
+  ] as const
+) {
+  await cliffySnapshotTest({
+    name: `Project Update Command - ${name}`,
+    meta: import.meta,
+    colors: false,
+    args: [TRIAD_PROJECT_ID, ...args],
+    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()
+    },
+  })
+}