beads/commands/search.md at c765e6562d67fa00a75e7da339673795c2b2735a

Files

Steve Yegge 1806183d5f feat: Add bd search command for efficient text queries (#347 )

Adds a new `bd search` command optimized for quick text searches,
addressing the issue where Claude using MCP bd list consumes 30k tokens.

Features:
- Searches across title, description, and ID with OR logic
- Default limit of 50 results (vs unlimited for bd list)
- Supports key filters: --status, --assignee, --type, --label
- Works in both daemon and direct modes
- Provides --json and --long output formats

Examples:
  bd search "performance" --status open
  bd search "database" --label backend --limit 10
  bd search "bd-5q"  # Search by partial ID

This provides a more efficient alternative to bd list when users
just want to find issues quickly without loading all results.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-20 22:44:19 -05:00

2.7 KiB

Raw Blame History

description, argument-hint

description	argument-hint
Search issues by text query	<query> [--status] [--label] [--assignee]

Search issues across title, description, and ID with a simple text query.

Note: The search command is optimized for quick text searches and uses less context than list when accessed via MCP. For advanced filtering options, use bd list.

Basic Usage

bd search "authentication bug"
bd search login --status open
bd search database --label backend
bd search "bd-5q"  # Search by partial issue ID

How It Works

The search command finds issues where your query appears in any of:

Issue title
Issue description
Issue ID (supports partial matching)

Unlike bd list, which requires you to specify which field to search, bd search automatically searches all text fields, making it faster and more intuitive for exploratory searches.

Filters

--status, -s: Filter by status (open, in_progress, blocked, closed)
--assignee, -a: Filter by assignee
--type, -t: Filter by type (bug, feature, task, epic, chore)
--label, -l: Filter by labels (must have ALL specified labels)
--label-any: Filter by labels (must have AT LEAST ONE)
--limit, -n: Limit number of results (default: 50)
--long: Show detailed multi-line output for each issue
--json: Output results in JSON format

Examples

Basic Search

# Find all issues mentioning "auth" or "authentication"
bd search auth

# Search for performance issues
bd search performance --status open

# Find database-related bugs
bd search database --type bug

Filtered Search

# Find open backend issues about login
bd search login --status open --label backend

# Search Alice's tasks for "refactor"
bd search refactor --assignee alice --type task

# Find recent bugs (limited to 10 results)
bd search bug --status open --limit 10

JSON Output

# Get JSON results for programmatic use
bd search "api error" --json

# Use with jq for advanced filtering
bd search memory --json | jq '.[] | select(.priority <= 1)'

Comparison with bd list

Command	Best For	Default Limit	Context Usage
`bd search`	Quick text searches, exploratory queries	50	Low (efficient for LLMs)
`bd list`	Advanced filtering, precise queries	None	High (all results)

When to use bd search:

You want to find issues quickly by keyword
You're exploring the issue database
You're using an LLM/MCP and want to minimize context usage

When to use bd list:

You need advanced filters (date ranges, priority ranges, etc.)
You want all results without a limit
You need special output formats (digraph, dot)

2.7 KiB Raw Blame History