bd list - Beads

Usage

bd list [flags]

Description

Search and filter issues using a wide range of criteria. Supports text search, date ranges, label filtering, metadata queries, and more.

Parameters

Core Filters

string

Filter by status: open, in_progress, blocked, deferred, closed, pinned, hooked. Default: non-closed, non-pinned.

string

Filter by priority: 0-4 or P0-P4

string

Filter by type: bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy. Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision

string

Filter by assignee

Label Filters

string[]

Filter by labels (AND: must have ALL). Can combine with --label-any.

string[]

Filter by labels (OR: must have AT LEAST ONE). Can combine with --label.

string

Filter by label glob pattern (e.g., tech-* matches tech-debt, tech-legacy)

string

Filter by label regex pattern (e.g., tech-(debt|legacy))

boolean

Filter issues with no labels

Text Search

string

Filter by title text (case-insensitive substring match)

string

Filter by title substring (case-insensitive)

string

Filter by description substring (case-insensitive)

string

Filter by notes substring (case-insensitive)

Date Ranges

string

Filter issues created after date (YYYY-MM-DD or RFC3339)

string

Filter issues created before date (YYYY-MM-DD or RFC3339)

string

Filter issues updated after date

string

Filter issues updated before date

string

Filter issues closed after date

string

Filter issues closed before date

Priority Ranges

string

Filter by minimum priority (inclusive, 0-4 or P0-P4)

string

Filter by maximum priority (inclusive, 0-4 or P0-P4)

Hierarchy

string

Filter by parent issue ID (shows children of specified issue)

boolean

Exclude child issues (show only top-level issues)

Scheduling

boolean

Show only issues with defer_until set

string

Filter issues deferred after date

string

Filter issues deferred before date

string

Filter issues due after date

string

Filter issues due before date

boolean

Show only issues with due_at in the past (not closed)

Metadata

string[]

Filter by metadata field (format: key=value, repeatable)

string

Filter issues that have this metadata key set

Special Filters

string

Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)

string

Filter by spec_id prefix

boolean

Filter issues with empty or missing description

boolean

Filter issues with no assignee

boolean

Show only pinned issues

boolean

Exclude pinned issues (default)

boolean

Show only ready issues (status=open, excludes hooked/in_progress/blocked/deferred)

string

Filter by molecule type: swarm, patrol, or work

string

Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation

Display

integer

default:"50"

Limit results (default 50, use 0 for unlimited)

boolean

Show all issues including closed (overrides default filter)

boolean

Show detailed multi-line output for each issue

string

Sort by field: priority, created, updated, closed, status, id, title, type, assignee

boolean

Reverse sort order

boolean

Display issues in a tree format with status/priority symbols

boolean

Alias for --pretty: hierarchical tree format

boolean

Watch for changes and auto-update display (implies --pretty)

Disable pager output

Advanced

string

Output format: digraph (for golang.org/x/tools/cmd/digraph), dot (Graphviz), or Go template

boolean

Include template molecules in output

boolean

Include gate issues in output (normally hidden)

boolean

Include infrastructure beads (agent/rig/role/message) in output

string

Query a different rig’s database (e.g., --rig gastown, --rig gt-, --rig gt)

Output

boolean

Output JSON for agent use

Examples

Basic Queries

bd list --json

bd list --status in_progress --json

bd list --priority 1 --json

bd list --type bug --json

bd list --assignee alice --json

Label Filtering

bd list --label backend --label api --json

bd list --label-any frontend,mobile --json

bd list --label backend --label-any urgent,p0 --json
# backend AND (urgent OR p0)

bd list --label-pattern "tech-*" --json
# Matches tech-debt, tech-legacy, etc.

bd list --label-regex "(bug|security)" --json

Text Search

bd list --title "login" --json

bd list --desc-contains "authentication" --json

bd list --notes-contains "TODO" --json

Date Filters

bd list --created-after 2025-01-13 --json

bd list --updated-after 2025-01-15 --json

bd list \
  --closed-after 2024-12-01 \
  --closed-before 2024-12-31 \
  --json

Priority Ranges

bd list --priority-min 0 --priority-max 1 --json

bd list --priority-min 3 --json

Hierarchy

bd list --parent bd-epic-123 --json

bd list --no-parent --json

bd list --parent bd-epic-123 --tree

Time-Based

bd list --deferred --json

bd list --overdue --json

bd list \
  --due-after 2025-01-15 \
  --due-before 2025-01-22 \
  --json

Metadata

bd list --metadata-field team=platform --json

bd list --has-metadata-key sprint --json

bd list \
  --metadata-field team=platform \
  --metadata-field priority=high \
  --json

Special Queries

bd list --id bd-1,bd-5,bd-10 --json

bd list --empty-description --json

bd list --no-assignee --json

bd list --ready --json

Sorting

bd list --sort priority --json

bd list --sort created --json

bd list --sort updated --reverse --json

Cross-Rig

bd list --rig gastown --json

bd list --rig beads --json
bd list --rig gastown --json

Watch Mode

bd list --status in_progress --watch
# Updates every 2 seconds, press Ctrl+C to exit

JSON Output

With --json flag:

[
  {
    "issue": {
      "id": "bd-123",
      "title": "Fix login bug",
      "status": "open",
      "priority": 1,
      "issue_type": "bug",
      "assignee": "alice",
      "labels": ["backend", "security"],
      "dependencies": [
        {
          "issue_id": "bd-123",
          "depends_on_id": "bd-124",
          "type": "blocks"
        }
      ]
    },
    "dependency_count": 1,
    "dependent_count": 3,
    "comment_count": 2,
    "parent": "bd-epic-auth"
  }
]

Complex Queries

Stale Issues

bd list \
  --status open \
  --updated-before 2024-12-01 \
  --no-assignee \
  --json

Sprint Planning

bd list \
  --metadata-field sprint=42 \
  --status open,in_progress \
  --sort priority \
  --json

Security Issues

bd list \
  --label-any security,cve \
  --priority-max 1 \
  --sort created \
  --json

Technical Debt

bd list \
  --label-pattern "tech-*" \
  --status open \
  --sort updated \
  --reverse \
  --json

Output Formats

Compact (Default)

bd-123 [P1] [bug] (open) @alice: Fix login bug [backend, security]
bd-124 [P2] [task] (in_progress) @bob: Add logging

Long Format

Found 2 issues:

bd-123
  Title: Fix login bug
  Status: open
  Priority: P1
  Type: bug
  Assignee: alice
  Labels: backend, security
  Created: 2025-01-15 10:00
  Updated: 2025-01-15 12:30

bd-124
  Title: Add logging
  Status: in_progress
  Priority: P2
  Type: task
  Assignee: bob
  Created: 2025-01-14 09:00
  Updated: 2025-01-15 11:00

Pretty/Tree Format

● P1 [bug] bd-123: Fix login bug @alice
  Labels: backend, security
  
○ P2 [task] bd-124: Add logging @bob
  Epic: Infrastructure

Default Filters

By default, bd list excludes:

Closed issues (use --all or --status closed to include)
Pinned issues (use --all or --pinned to include)
Template molecules (use --include-templates)
Gate issues (use --include-gates)
Infrastructure beads (use --include-infra)

Best Practices

For Agents

Always use --json for parsing
Use --limit to control result size
Use --sort for deterministic ordering
Filter by metadata for agent-specific queries
Use --ready instead of manual status filtering for claimable work

For Humans

Use --pretty for visual scanning
Combine filters for precise queries
Use --watch during active development
Save complex queries as shell aliases

Performance Tips

Add --limit for large result sets
Use specific filters instead of text search when possible
Avoid --all unless needed (excludes closed by default)
Use --rig for targeted cross-rig queries

bd ready - Find unblocked work (better than --ready)
bd show - View detailed issue info
bd update - Modify filtered issues
bd blocked - Show blocked issues

​Usage

​Description

​Parameters

​Core Filters

​Label Filters

​Text Search

​Date Ranges

​Priority Ranges

​Hierarchy

​Scheduling

​Metadata

​Special Filters

​Display

​Advanced

​Output

​Examples

​Basic Queries

​Label Filtering

​Text Search

​Date Filters

​Priority Ranges

​Hierarchy

​Time-Based

​Metadata

​Special Queries

​Sorting

​Cross-Rig

​Watch Mode

​JSON Output

​Complex Queries

​Stale Issues

​Sprint Planning

​Security Issues

​Technical Debt

​Output Formats

​Compact (Default)

​Long Format

​Pretty/Tree Format

​Default Filters

​Best Practices

​For Agents

​For Humans

​Performance Tips

​Related Commands

Usage

Description

Parameters

Core Filters

Label Filters

Text Search

Date Ranges

Priority Ranges

Hierarchy

Scheduling

Metadata

Special Filters

Display

Advanced

Output

Examples

Basic Queries

Label Filtering

Text Search

Date Filters

Priority Ranges

Hierarchy

Time-Based

Metadata

Special Queries

Sorting

Cross-Rig

Watch Mode

JSON Output

Complex Queries

Stale Issues

Sprint Planning

Security Issues

Technical Debt

Output Formats

Compact (Default)

Long Format

Pretty/Tree Format

Default Filters

Best Practices

For Agents

For Humans

Performance Tips

Related Commands