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

--status

string

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

--priority

string

Filter by priority: 0-4 or P0-P4

--type

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

--assignee

string

Filter by assignee

Label Filters

--label

string[]

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

--label-any

string[]

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

--label-pattern

string

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

--label-regex

string

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

--no-labels

boolean

Filter issues with no labels

Text Search

--title

string

Filter by title text (case-insensitive substring match)

--title-contains

string

Filter by title substring (case-insensitive)

--desc-contains

string

Filter by description substring (case-insensitive)

--notes-contains

string

Filter by notes substring (case-insensitive)

Date Ranges

--created-after

string

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

--created-before

string

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

--updated-after

string

Filter issues updated after date

--updated-before

string

Filter issues updated before date

--closed-after

string

Filter issues closed after date

--closed-before

string

Filter issues closed before date

Priority Ranges

--priority-min

string

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

--priority-max

string

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

Hierarchy

--parent

string

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

--no-parent

boolean

Exclude child issues (show only top-level issues)

Scheduling

--deferred

boolean

Show only issues with defer_until set

--defer-after

string

Filter issues deferred after date

--defer-before

string

Filter issues deferred before date

--due-after

string

Filter issues due after date

--due-before

string

Filter issues due before date

--overdue

boolean

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

Metadata

--metadata-field

string[]

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

--has-metadata-key

string

Filter issues that have this metadata key set

Special Filters

--id

string

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

--spec

string

Filter by spec_id prefix

--empty-description

boolean

Filter issues with empty or missing description

--no-assignee

boolean

Filter issues with no assignee

--pinned

boolean

Show only pinned issues

--no-pinned

boolean

Exclude pinned issues (default)

--ready

boolean

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

--mol-type

string

Filter by molecule type: swarm, patrol, or work

--wisp-type

string

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

Display

--limit

integer

default:"50"

Limit results (default 50, use 0 for unlimited)

--all

boolean

Show all issues including closed (overrides default filter)

--long

boolean

Show detailed multi-line output for each issue

--sort

string

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

--reverse

boolean

Reverse sort order

--pretty

boolean

Display issues in a tree format with status/priority symbols

--tree

boolean

Alias for --pretty: hierarchical tree format

--watch

boolean

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

Disable pager output

Advanced

--format

string

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

--include-templates

boolean

Include template molecules in output

--include-gates

boolean

Include gate issues in output (normally hidden)

--include-infra

boolean

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

--rig

string

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

Output

--json

boolean

Output JSON for agent use

Examples

Basic Queries

bd list --json

Label Filtering

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

Text Search

bd list --title "login" --json

Date Filters

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

Priority Ranges

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

Hierarchy

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

Time-Based

bd list --deferred --json

Metadata

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

Special Queries

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

Sorting

bd list --sort priority --json

Cross-Rig

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

Commands

Advanced Commands

Memory Commands

Molecule 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

Build docs developers (and LLMs) love

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