bd update

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

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

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

Atomic Claim

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

Label Management

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

Metadata Operations

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

Time Management

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

Append Notes

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

Reparenting

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

Bulk Updates

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

Use --claim to atomically take ownership
Always use --json for parsing
Update status to reflect progress (in_progress → closed)
Append notes to document investigation findings

For Humans

Use incremental label operations (--add-label) to avoid data loss
Set due dates for time-sensitive work
Update priority as urgency changes
Add context via --append-notes for future reference

bd create - Create new issues
bd show - View current state
bd close - Complete work
bd ready - Find claimable work

Commands

Advanced Commands

Memory Commands

Molecule Commands

Usage

Description

Parameters

Field Updates

Labels

Scheduling

Metadata

Atomic Operations

Output

Examples

Basic Updates

Atomic Claim

Label Management

Metadata Operations

Time Management

Append Notes

Reparenting

Bulk Updates

JSON Output

Atomic Claim Semantics

Validation

Status Validation

Priority Validation

Metadata Key Validation

Best Practices

For Agents

For Humans

Build docs developers (and LLMs) love

Commands

Advanced Commands

Memory Commands

Molecule Commands

​Usage

​Description

​Parameters

​Field Updates

​Labels

​Scheduling

​Metadata

​Atomic Operations

​Output

​Examples

​Basic Updates

​Atomic Claim

​Label Management

​Metadata Operations

​Time Management

​Append Notes

​Reparenting

​Bulk Updates

​JSON Output

​Atomic Claim Semantics

​Validation

​Status Validation

​Priority Validation

​Metadata Key Validation

​Best Practices

​For Agents

​For Humans

​Related Commands

Build docs developers (and LLMs) love

Usage

Description

Parameters

Field Updates

Labels

Scheduling

Metadata

Atomic Operations

Output

Examples

Basic Updates

Atomic Claim

Label Management

Metadata Operations

Time Management

Append Notes

Reparenting

Bulk Updates

JSON Output

Atomic Claim Semantics

Validation

Status Validation

Priority Validation

Metadata Key Validation

Best Practices

For Agents

For Humans

Related Commands