Usage Description Show detailed information about one or more issues, including description, design notes, dependencies, comments, and full audit trail.
Parameters Issue IDs to display. If omitted with --current, shows the active issue. Supports multiple IDs to view several issues at once.
Display Options Show compact one-line output per issue
Show all available fields (extended metadata, agent identity, gate fields, etc.)
Show the currently active issue (in-progress, hooked, or last touched)
Special Views Show full conversation thread (for message issues)
Show issues that reference this issue (reverse lookup)
Show only the children of this issue
Time Travel Show issue as it existed at a specific commit hash or branch (requires Dolt)
Advanced Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz)
Show timestamps in local time instead of UTC
Watch for changes and auto-refresh display
Output Output JSON for agent use
Examples Basic Display Single Issue
Multiple Issues
Current Issue
Display Modes Compact
Full Details
Watch Mode
bd show bd-123 --short # bd-123: Fix login bug [P1] (open) @alice
Special Views Children
References
Message Thread
bd show bd-epic --children --json
Time Travel Historical View
Branch View
bd show bd-123 --as-of abc123def --json # Show issue at commit abc123def
Flag-Like IDs ID Starting with Dash
Multiple Flag-Like IDs
bd show --id=gt--xyz --json
JSON Output With --json flag:
[ { "issue" : { "id" : "bd-123" , "title" : "Fix login bug" , "description" : "Users cannot log in after password reset" , "status" : "open" , "priority" : 1 , "issue_type" : "bug" , "assignee" : "alice" , "created_at" : "2025-01-15T10:00:00Z" , "updated_at" : "2025-01-15T12:30:00Z" , "created_by" : "bob" , "owner" : "beads" }, "labels" : [ "backend" , "security" ], "dependencies" : [ { "id" : "bd-124" , "title" : "Update auth library" , "status" : "in_progress" , "priority" : 1 , "dependency_type" : "blocks" } ], "dependents" : [ { "id" : "bd-125" , "title" : "Deploy hotfix" , "status" : "open" , "priority" : 0 , "dependency_type" : "blocks" } ], "comments" : [ { "id" : "cmt-1" , "author" : "alice" , "text" : "Root cause identified" , "created_at" : "2025-01-15T11:00:00Z" } ], "parent" : "bd-epic-auth" } ]
Terminal Output Default View bd-123: Fix login bug [P1] (open) Owner: beads · Type: bug | Created: 2025-01-15 10:00 · Updated: 2025-01-15 12:30 DESCRIPTION Users cannot log in after password reset. The session token is not invalidated properly, causing authentication failures. DESIGN Update the auth middleware to invalidate old tokens before issuing new ones. Add validation in the login endpoint. ACCEPTANCE CRITERIA - Users can log in after password reset - Old tokens are invalidated - New tokens are issued correctly LABELS: backend, security DEPENDS ON → bd-124: Update auth library [P1] (in_progress) BLOCKS ← bd-125: Deploy hotfix [P0] (open) COMMENTS 2025-01-15 11:00 alice Root cause identified in auth middleware
Short View bd-123: Fix login bug [P1] (open) @alice bd-124: Update auth library [P1] (in_progress) @bob bd-125: Deploy hotfix [P0] (open) @unassigned
Long View Includes additional fields:
EXTENDED METADATA External Ref: JIRA-123 Spec ID: spec-auth-v2 Estimated: 120 minutes Due: 2025-01-20 17:00 Defer Until: (none) Ephemeral: false Metadata: {"team":"platform","sprint":42} AGENT IDENTITY Rig: gastown Role Type: polecat Mol Type: work GATE FIELDS Await Type: gh:pr Await ID: 123 Await Gate: all-children
Current Issue Resolution With --current flag, resolves the active issue using this priority:
In-progress issues assigned to current actorHooked issues assigned to current actorLast touched issue from recent create/update/show/close
# Agent workflow bd update bd-123 --claim bd show --current --json # Shows bd-123 (in-progress and assigned to you)
Watch Mode Continuously monitor an issue for changes:
Uses polling (not filesystem watching) because Dolt stores data server-side. Refreshes every 2 seconds.
Press Ctrl+C to exit.
Time Travel with Dolt View historical versions of issues:
Specific Commit
Branch View
Compare Versions
bd show bd-123 --as-of abc123def --json
Time travel requires Dolt backend. Not available with SQLite.
Dependency Display Dependencies are grouped by type:
PARENT Parent-child relationships (issue is child)
DEPENDS ON Blocking dependencies (issue depends on these)
DISCOVERED FROM Discovery tracking (issue was found during these)
CHILDREN Hierarchical children (issue is parent)
BLOCKS Reverse blocking (issue blocks these)
DISCOVERED Reverse discovery (issue led to discovery of these)
Bidirectional informational links (deduplicated)
Best Practices For Agents
Use --json for parsingUse --current to check active workUse --short for bulk scanningParse dependencies to understand blocking state
For Humans
Use default view for detailed contextUse --long when debuggingUse --watch during active developmentCheck dependencies before starting work
Agent Workflow # Before starting work bd show bd-123 --json | jq '.dependencies' # Check if blockers are all closed # During work bd show --current --json # Verify you're working on the right issue # After work bd show bd-123 --json | jq '.dependents' # See what you just unblocked