Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt

Use this file to discover all available pages before exploring further.

​
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

bd show bd-123 --json

​
Display Modes

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

​
Special Views

bd show bd-epic --children --json

​
Time Travel

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

​
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:
  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: 
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

  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

Build docs developers (and LLMs) love

Get started for freeTalk to us