bd update

Update issue fields and claim work atomically

Usage

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

id · string[]

Issue IDs to update. If omitted, uses the last touched issue from recent create/update/show/close.

Field Updates

--title · string

Update issue title

--status · string

Update status: open, in_progress, blocked, deferred, closed, pinned, hooked

--priority · string

Update priority: 0-4 or P0-P4

--type · string

Update issue type: bug, feature, task, epic, chore, decision

--assignee · string

Update assignee. Use empty string to unassign.

--description · string

Update description. Use - to read from stdin.

--design · string

Update design notes

--acceptance · string

Update acceptance criteria

--notes · string

Replace notes field

--append-notes · string

Append to notes field (cannot be used with --notes)

--estimate · integer

Update time estimate in minutes

Labels

--add-label · string[]

Add labels (repeatable). Preserves existing labels.

--remove-label · string[]

Remove labels (repeatable)

--set-labels · string[]

Replace all labels (repeatable)

Scheduling

--due · string

Update due date. Use empty string to clear. Formats: +6h, tomorrow, 2025-01-15

--defer · string

Update defer_until. Use empty string to clear. Same formats as --due

Metadata

--metadata · string

Replace entire metadata (JSON string or @file.json)

--set-metadata · string[]

Set individual metadata fields (format: key=value, repeatable)

--unset-metadata · string[]

Remove metadata fields (repeatable)

Atomic Operations

--claim · boolean

Atomically claim the issue (sets assignee to you, status to in_progress). Fails if already claimed.

--parent · string

Reparent the issue. Use empty string to remove parent.

--ephemeral · boolean

Mark issue as ephemeral (wisp)

--persistent · boolean

Mark issue as persistent (promote wisp to regular issue)

Output

--json · boolean

Output JSON for agent use

Examples

Basic Updates

Change Status

bd update bd-123 --status in_progress --json

Atomic Claim

Claim Work

# Atomically sets assignee=you and status=in_progress
bd update bd-123 --claim --json

Label Management

Add Labels

bd update bd-123 \
  --add-label bug \
  --add-label p1 \
  --json

Metadata Operations

Set Metadata Fields

bd update bd-123 \
  --set-metadata team=platform \
  --set-metadata sprint=42 \
  --json

Time Management

Set Due Date

bd update bd-123 --due "next friday" --json

Append Notes

Add to Notes

bd update bd-123 \
  --append-notes "Additional context from investigation" \
  --json

Reparenting

Change Parent

bd update bd-123 --parent bd-abc --json

Bulk Updates

Update Multiple Issues

bd update bd-123 bd-124 bd-125 \
  --status open \
  --priority 2 \
  --json

JSON Output

With --json flag:

[
  {
    "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:

# 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:

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:

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:

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 - Create new issues
• bd show - View current state
• bd close - Complete work
• bd ready - Find claimable work