bd show

View detailed issue information with full audit trail

Usage

bd show [id...] [flags]

Description

Show detailed information about one or more issues, including description, design notes, dependencies, comments, and full audit trail.

Parameters

id · string[]

Issue IDs to display. If omitted with --current, shows the active issue. Supports multiple IDs to view several issues at once.

Display Options

--short · boolean

Show compact one-line output per issue

--long · boolean

Show all available fields (extended metadata, agent identity, gate fields, etc.)

--current · boolean

Show the currently active issue (in-progress, hooked, or last touched)

Special Views

--thread · boolean

Show full conversation thread (for message issues)

--refs · boolean

Show issues that reference this issue (reverse lookup)

--children · boolean

Show only the children of this issue

Time Travel

--as-of · string

Show issue as it existed at a specific commit hash or branch (requires Dolt)

Advanced

--id · string[]

Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz)

--local-time · boolean

Show timestamps in local time instead of UTC

--watch · boolean

Watch for changes and auto-refresh display

Output

--json · boolean

Output JSON for agent use

Examples

Basic Display

Single Issue

bd show bd-123 --json

Display Modes

Compact

bd show bd-123 --short
# bd-123: Fix login bug [P1] (open) @alice

Special Views

Children

bd show bd-epic --children --json

Time Travel

Historical View

bd show bd-123 --as-of abc123def --json
# Show issue at commit abc123def

Flag-Like IDs

ID Starting with Dash

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:

1. In-progress issues assigned to current actor
2. Hooked issues assigned to current actor
3. Last 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:

bd show bd-123 --watch

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

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)

RELATED

Bidirectional informational links (deduplicated)

Best Practices

For Agents

1. Use --json for parsing
2. Use --current to check active work
3. Use --short for bulk scanning
4. Parse dependencies to understand blocking state

For Humans

1. Use default view for detailed context
2. Use --long when debugging
3. Use --watch during active development
4. Check 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

Related Commands

• bd list - Search for issues
• bd update - Modify issues
• bd dep list - List dependencies
• bd ready - Find claimable work