bd dep

Usage

bd dep [issue-id] [flags]
bd dep add <issue-id> <depends-on-id>
bd dep remove <issue-id> <depends-on-id>
bd dep list <issue-id>
bd dep tree <issue-id>
bd dep cycles

Description

Manage dependencies between issues. Dependencies define blocking relationships, parent-child hierarchies, and other issue connections.

Subcommands

add

Add a dependency between two issues.

bd dep add <issue-id> <depends-on-id> [flags]

issue-id

string

required

The dependent issue (the one that is blocked)

depends-on-id

string

required

The dependency (the blocker). Can be:

Local issue ID (e.g., bd-xyz)
External reference: external:<project>:<capability> Can also be specified via --blocked-by or --depends-on flag.

--type

string

default:"blocks"

Dependency type: blocks, tracks, related, parent-child, discovered-from, until, caused-by, validates, relates-to, supersedes

--blocked-by

string

Alternative to positional arg (same as depends-on-id)

--depends-on

string

Alias for --blocked-by

remove (rm)

Remove a dependency.

bd dep remove <issue-id> <depends-on-id>

list

List dependencies or dependents of an issue.

bd dep list <issue-id> [flags]

--direction

string

default:"down"

Direction: down (dependencies), up (dependents)

--type

string

Filter by dependency type

tree

Show dependency tree.

bd dep tree <issue-id> [flags]

--direction

string

default:"down"

Direction: down (dependencies), up (dependents), both (full graph)

--max-depth

integer

default:"50"

Maximum tree depth to display

--status

string

Filter to only show issues with this status

--format

string

Output format: mermaid for Mermaid.js flowchart

--show-all-paths

boolean

Show all paths to nodes (no deduplication for diamond dependencies)

cycles

Detect dependency cycles.

bd dep cycles

Examples

Add Dependencies

bd dep add bd-123 bd-124 --json
# bd-123 depends on (is blocked by) bd-124

External Dependencies

bd dep add gt-xyz external:beads:mol-run-assignee --json
# gt-xyz depends on beads project shipping mol-run-assignee capability

List Dependencies

bd dep list bd-123 --json
# Default: down direction (dependencies)

Dependency Tree

bd dep tree bd-123 --json

Cycle Detection

bd dep cycles --json

JSON Output

dep add

{
  "status": "added",
  "issue_id": "bd-123",
  "depends_on_id": "bd-124",
  "type": "blocks"
}

dep list

[
  {
    "id": "bd-124",
    "title": "Implement API endpoint",
    "status": "in_progress",
    "priority": 1,
    "dependency_type": "blocks"
  }
]

dep tree

[
  {
    "id": "bd-123",
    "title": "Deploy feature",
    "status": "open",
    "priority": 1,
    "depth": 0,
    "parent_id": "",
    "truncated": false
  },
  {
    "id": "bd-124",
    "title": "Run tests",
    "status": "in_progress",
    "priority": 1,
    "depth": 1,
    "parent_id": "bd-123",
    "truncated": false
  }
]

dep cycles

[
  [
    {
      "id": "bd-123",
      "title": "Issue A"
    },
    {
      "id": "bd-124",
      "title": "Issue B"
    }
  ]
]

Dependency Types

blocks

Blocking relationship: Issue A depends on (is blocked by) Issue B. Issue A cannot be closed until B is closed.Default type when not specified.

parent-child

Hierarchical relationship: Used for epics and subtasks. Child issues inherit the parent’s completion dependency.Created automatically with --parent flag in bd create.

discovered-from

Discovery tracking: Links newly discovered issues to their source investigation.Example: Bug found during feature development.

tracks

Tracking relationship: Issue A tracks progress of Issue B (used in convoy patterns).

relates-to

Alias for related

until

Temporal dependency: Issue A depends on B until a condition is met.

caused-by

Causation tracking: Issue A was caused by Issue B (e.g., bug caused by feature).

validates

Validation relationship: Issue A validates Issue B (e.g., test validates feature).

supersedes

Replacement relationship: Issue A replaces Issue B.

External References

External references allow cross-project dependencies:

Format

external:<project>:<capability>

Examples

# gastown depends on beads shipping a capability
bd dep add gt-xyz external:beads:mol-run-assignee

# beads depends on gastown feature
bd dep add bd-abc external:gastown:agent-dispatch

Resolution

External refs are resolved at query time using routes.jsonl configuration:

Check if capability is “shipped” in target project
Block if not shipped
Unblock when shipped

External refs are stored as-is in the database. The external_projects config maps project names to their database locations.

Tree Visualization

Terminal Output

🌲 Dependency tree for bd-123:

bd-123: Deploy feature [P1] (open) [BLOCKED]
├── bd-124: Run tests [P1] (in_progress)
│   └── bd-125: Fix test data [P2] (open)
└── bd-126: Update docs [P3] (closed) ✓

Mermaid Diagram

Cycle Detection

Cycles hide issues from ready work and cause confusion:

bd dep cycles

Output:

⚠ Found 1 dependency cycles:

1. Cycle involving:
   - bd-123: Issue A
   - bd-124: Issue B
   - bd-125: Issue C

Run 'bd dep tree bd-123' to visualize.

Cycles prevent issues from appearing in bd ready even if they should be unblocked. Fix by removing one dependency in the cycle.

Anti-Patterns

Child→Parent Dependency

bd dep add bd-abc.1 bd-abc
# Error: bd-abc.1 is already a child of bd-abc
# Adding explicit dependency creates deadlock

Children inherit parent completion dependency via hierarchy. Explicit dependency creates:

Child can’t start (parent open)
Parent can’t close (children not done)
Deadlock!

Best Practices

For Agents

Use discovered-from to link bugs found during work
Check cycles after adding dependencies
Use external refs for cross-project dependencies
Verify dependencies exist before adding

For Humans

Keep dependency types semantic (blocks for blocking, tracks for tracking)
Use parent-child for true hierarchies
Avoid deep trees (>5 levels) - flatten if possible
Document external refs in issue description

Dependency Hygiene

# Before closing an issue, check what it blocks
bd dep list bd-123 --direction up --json

# After closing, verify nothing is wrongly blocked
bd blocked --json

bd ready - Find unblocked work
bd blocked - Show blocked issues
bd create --deps - Create with dependencies
bd update --parent - Reparent issues

Commands

Advanced Commands

Memory Commands

Molecule Commands

Usage

Description

Subcommands

add

remove (rm)

list

tree

cycles

Examples

Add Dependencies

External Dependencies

List Dependencies

Dependency Tree

Cycle Detection

JSON Output

dep add

dep list

dep tree

dep cycles

Dependency Types

External References

Format

Examples

Resolution

Tree Visualization

Terminal Output

Mermaid Diagram

Cycle Detection

Anti-Patterns

Child→Parent Dependency

Best Practices

For Agents

For Humans

Dependency Hygiene

Build docs developers (and LLMs) love

Commands

Advanced Commands

Memory Commands

Molecule Commands

​Usage

​Description

​Subcommands

​add

​remove (rm)

​list

​tree

​cycles

​Examples

​Add Dependencies

​External Dependencies

​List Dependencies

​Dependency Tree

​Cycle Detection

​JSON Output

​dep add

​dep list

​dep tree

​dep cycles

​Dependency Types

​External References

​Format

​Examples

​Resolution

​Tree Visualization

​Terminal Output

​Mermaid Diagram

​Cycle Detection

​Anti-Patterns

​Child→Parent Dependency

​Best Practices

​For Agents

​For Humans

​Dependency Hygiene

​Related Commands

Build docs developers (and LLMs) love

Usage

Description

Subcommands

add

remove (rm)

list

tree

cycles

Examples

Add Dependencies

External Dependencies

List Dependencies

Dependency Tree

Cycle Detection

JSON Output

dep add

dep list

dep tree

dep cycles

Dependency Types

External References

Format

Examples

Resolution

Tree Visualization

Terminal Output

Mermaid Diagram

Cycle Detection

Anti-Patterns

Child→Parent Dependency

Best Practices

For Agents

For Humans

Dependency Hygiene

Related Commands