> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt > Use this file to discover all available pages before exploring further. # bd update > Update issue fields and claim work atomically ## Usage ```bash theme={null} bd update [id...] [flags] ``` ## Description Update one or more issues. If no ID is provided, updates the last touched issue. The `--claim` flag provides atomic compare-and-swap semantics for claiming work. ## Parameters Issue IDs to update. If omitted, uses the last touched issue from recent create/update/show/close. ### Field Updates Update issue title Update status: `open`, `in_progress`, `blocked`, `deferred`, `closed`, `pinned`, `hooked` Update priority: 0-4 or P0-P4 Update issue type: `bug`, `feature`, `task`, `epic`, `chore`, `decision` Update assignee. Use empty string to unassign. Update description. Use `-` to read from stdin. Update design notes Update acceptance criteria Replace notes field Append to notes field (cannot be used with `--notes`) Update time estimate in minutes ### Labels Add labels (repeatable). Preserves existing labels. Remove labels (repeatable) Replace all labels (repeatable) ### Scheduling Update due date. Use empty string to clear. Formats: `+6h`, `tomorrow`, `2025-01-15` Update defer\_until. Use empty string to clear. Same formats as `--due` ### Metadata Replace entire metadata (JSON string or `@file.json`) Set individual metadata fields (format: `key=value`, repeatable) Remove metadata fields (repeatable) ### Atomic Operations Atomically claim the issue (sets assignee to you, status to `in_progress`). Fails if already claimed. Reparent the issue. Use empty string to remove parent. Mark issue as ephemeral (wisp) Mark issue as persistent (promote wisp to regular issue) ### Output Output JSON for agent use ## Examples ### Basic Updates ```bash Change Status theme={null} bd update bd-123 --status in_progress --json ``` ```bash Update Priority theme={null} bd update bd-123 --priority 0 --json ``` ```bash Update Title theme={null} bd update bd-123 --title "New title" --json ``` ### Atomic Claim ```bash Claim Work theme={null} # Atomically sets assignee=you and status=in_progress bd update bd-123 --claim --json ``` ```bash Claim Multiple theme={null} # Fails if any issue is already claimed bd update bd-123 bd-124 --claim --json ``` ### Label Management ```bash Add Labels theme={null} bd update bd-123 \ --add-label bug \ --add-label p1 \ --json ``` ```bash Remove Labels theme={null} bd update bd-123 \ --remove-label wontfix \ --json ``` ```bash Replace All Labels theme={null} bd update bd-123 \ --set-labels bug,critical,security \ --json ``` ### Metadata Operations ```bash Set Metadata Fields theme={null} bd update bd-123 \ --set-metadata team=platform \ --set-metadata sprint=42 \ --json ``` ```bash Remove Metadata theme={null} bd update bd-123 \ --unset-metadata old_field \ --json ``` ```bash Replace All Metadata theme={null} bd update bd-123 \ --metadata '{"team":"platform","priority":"high"}' \ --json ``` ### Time Management ```bash Set Due Date theme={null} bd update bd-123 --due "next friday" --json ``` ```bash Clear Due Date theme={null} bd update bd-123 --due "" --json ``` ```bash Defer Task theme={null} bd update bd-123 --defer "+2w" --json ``` ### Append Notes ```bash Add to Notes theme={null} bd update bd-123 \ --append-notes "Additional context from investigation" \ --json ``` ```bash Notes from Stdin theme={null} echo "Investigation results" | \ bd update bd-123 --append-notes=- --json ``` ### Reparenting ```bash Change Parent theme={null} bd update bd-123 --parent bd-abc --json ``` ```bash Remove Parent theme={null} bd update bd-123 --parent "" --json ``` ### Bulk Updates ```bash Update Multiple Issues theme={null} bd update bd-123 bd-124 bd-125 \ --status open \ --priority 2 \ --json ``` ```bash Last Touched Issue theme={null} # No ID needed - uses last create/update/show/close bd update --status in_progress --json ``` ## JSON Output With `--json` flag: ```json theme={null} [ { "id": "bd-123", "title": "Fix login bug", "status": "in_progress", "priority": 1, "assignee": "agent-name", "updated_at": "2025-01-15T10:35:00Z" } ] ``` ## Atomic Claim Semantics The `--claim` flag uses compare-and-swap to prevent race conditions: ```bash theme={null} # Agent 1 tries to claim bd update bd-123 --claim --json # Success: {"id":"bd-123","assignee":"agent-1","status":"in_progress"} # Agent 2 tries to claim the same issue bd update bd-123 --claim --json # Error: issue already claimed by agent-1 ``` This ensures only one agent can work on an issue at a time. ## Validation ### Status Validation Only valid statuses are accepted: ```bash theme={null} bd update bd-123 --status invalid --json # Error: invalid status "invalid" (valid: open, in_progress, blocked, deferred, closed, pinned, hooked) ``` ### Priority Validation Priority must be 0-4 or P0-P4: ```bash theme={null} bd update bd-123 --priority 5 --json # Error: priority must be 0-4 or P0-P4 ``` ### Metadata Key Validation Metadata keys must be alphanumeric with underscores: ```bash theme={null} bd update bd-123 --set-metadata "invalid-key=value" --json # Error: metadata keys must match [a-zA-Z0-9_]+ ``` ## Best Practices ### For Agents 1. **Use `--claim`** to atomically take ownership 2. **Always use `--json`** for parsing 3. **Update status** to reflect progress (in\_progress → closed) 4. **Append notes** to document investigation findings ### For Humans 1. **Use incremental label operations** (`--add-label`) to avoid data loss 2. **Set due dates** for time-sensitive work 3. **Update priority** as urgency changes 4. **Add context** via `--append-notes` for future reference ## Related Commands * [`bd create`](/cli/create) - Create new issues * [`bd show`](/cli/show) - View current state * [`bd close`](/cli/close) - Complete work * [`bd ready`](/cli/ready) - Find claimable work