beads/website/docs/cli-reference/labels.md

id, title, sidebar_position

id	title	sidebar_position
labels	Labels & Comments	5

Labels & Comments

Commands for managing labels and comments.

Labels

Adding Labels

# During creation
bd create "Task" -l "backend,urgent"

# To existing issue
bd update bd-42 --add-label urgent
bd update bd-42 --add-label "backend,security"

Removing Labels

bd update bd-42 --remove-label urgent

Listing Labels

# All labels in use
bd label list
bd label list --json

# Issues with specific labels
bd list --label-any urgent,critical
bd list --label-all backend,security

Label Conventions

Suggested label categories:

Category	Examples	Purpose
Type	bug, feature, docs	Issue classification
Priority	urgent, critical	Urgency markers
Area	backend, frontend, api	Code area
Status	blocked, needs-review	Workflow state
Size	small, medium, large	Effort estimate

Comments

Adding Comments

bd comment add bd-42 "Working on this now"
bd comment add bd-42 --message "Found the bug in auth.go:45"

Listing Comments

bd comment list bd-42
bd comment list bd-42 --json

Viewing with Issue

bd show bd-42 --full  # Includes comments

Filtering by Labels

Any Match (OR)

# Issues with urgent OR critical
bd list --label-any urgent,critical

All Match (AND)

# Issues with BOTH backend AND security
bd list --label-all backend,security

Combined Filters

# Open bugs with urgent label
bd list --status open --type bug --label-any urgent --json

Bulk Operations

Add Label to Multiple Issues

# Using shell
for id in bd-42 bd-43 bd-44; do
  bd update $id --add-label "sprint-1"
done

Find and Label

# Label all open bugs as needs-triage
bd list --status open --type bug --json | \
  jq -r '.[].id' | \
  xargs -I {} bd update {} --add-label needs-triage

Best Practices

1. Keep labels lowercase - backend not Backend
2. Use hyphens for multi-word - needs-review not needs_review
3. Be consistent - Establish team conventions
4. Don't over-label - 2-4 labels per issue is typical
5. Review periodically - Remove unused labels