Skip to main content

​
Usage

bd close [id...] [flags]

​
Description

Close one or more issues. If no ID is provided, closes the last touched issue. Validates that gates are satisfied and no open blockers exist before closing.

​
Parameters

​
id
string[]
Issue IDs to close. If omitted, uses the last touched issue from recent create/update/show/close.

​
Reason

​
--reason
string
default:"Closed"
Reason for closing. Used in audit trail.
​
--resolution
string
Alias for --reason (Jira CLI convention)
​
--message
string
Alias for --reason (git commit convention)
​
--comment
string
Alias for --reason

​
Options

​
--force
boolean
Force close pinned issues or issues with unsatisfied gates
​
--continue
boolean
Auto-advance to next step in molecule after closing
​
--no-auto
boolean
With --continue, show next step but don’t claim it
​
--suggest-next
boolean
Show newly unblocked issues after closing
​
--session
string
Claude Code session ID (or set CLAUDE_SESSION_ID env var)

​
Output

​
--json
boolean
Output JSON for agent use

​
Examples

​
Basic Close

bd close bd-123 --reason "Fixed authentication bug" --json

​
Reason Aliases

bd close bd-123 -m "Fixed bug" --json

​
Force Close

bd close bd-123 --force --json
# Closes even if other issues depend on it

​
Continue Workflow

bd close bd-mol-abc.1 --continue --json
# Closes step 1, claims and shows step 2

​
Suggest Next

bd close bd-123 --suggest-next --json
# Shows issues that were blocked by bd-123

​
Session Tracking

bd close bd-123 --session "claude-session-abc" --json

​
JSON Output

With --json flag: 
[
  {
    "id": "bd-123",
    "title": "Fix login bug",
    "status": "closed",
    "priority": 1,
    "closed_at": "2025-01-15T14:30:00Z",
    "closed_by": "agent-name",
    "closed_by_session": "claude-session-abc"
  }
]
With --suggest-next: 
{
  "closed": [
    {
      "id": "bd-123",
      "title": "Fix login bug",
      "status": "closed"
    }
  ],
  "unblocked": [
    {
      "id": "bd-124",
      "title": "Deploy hotfix",
      "priority": 0,
      "status": "open"
    }
  ]
}
With --continue: 
{
  "closed": [
    {
      "id": "bd-mol-abc.1",
      "status": "closed"
    }
  ],
  "continue": {
    "next_step": {
      "id": "bd-mol-abc.2",
      "title": "Run tests",
      "status": "in_progress",
      "assignee": "agent-name"
    },
    "claimed": true
  }
}

​
Validation

​
Blocker Check

By default, issues with open dependents cannot be closed: 
bd close bd-123 --json
# Error: cannot close bd-123: blocked by open issues [bd-124, bd-125]
# Use --force to override
Use --force to override: 
bd close bd-123 --force --json
# Success: closed despite open blockers

​
Gate Satisfaction

Machine-checkable gates must be satisfied: 
bd close bd-gate-pr --json
# Checks if GitHub PR is merged
# Error: gate condition not satisfied: PR #123 not merged
Gate types:
  • gh:pr - GitHub pull request must be merged
  • gh:run - GitHub Actions run must succeed
  • timer - Time must have elapsed
  • bead - Dependent issue must be closed
Use --force to skip gate checks: 
bd close bd-gate-pr --force --json

​
Pinned Issues

Pinned issues require --force: 
bd close bd-pinned --json
# Error: cannot close pinned issue

bd close bd-pinned --force --json
# Success

​
Auto-Close Molecules

When closing a molecule step, the parent molecule is automatically closed if all steps are complete: 
bd close bd-mol-abc.3 --json
# If this was the last open step:
# ✓ Closed bd-mol-abc.3
# ✓ Auto-closed completed molecule bd-mol-abc

​
Continue Workflow

The --continue flag enables sequential molecule execution:
  1. Close current step
  2. Find next ready step in same molecule
  3. Optionally claim it (unless --no-auto)
  4. Return next step info
# Agent workflow for molecule
while true; do
  # Work on current step
  # ...
  
  # Close and advance
  result=$(bd close --current --continue --json)
  
  # Check if there's a next step
  next_id=$(echo $result | jq -r '.continue.next_step.id')
  if [ "$next_id" = "null" ]; then
    echo "Molecule complete!"
    break
  fi
  
  echo "Starting next step: $next_id"
done

​
Suggest Next

The --suggest-next flag shows work that was unblocked: 
bd close bd-123 --suggest-next --json
Returns:
  • Issues that were blocked by bd-123
  • Now have no open blockers
  • Sorted by priority
Useful for agents to immediately claim the next highest-priority work.

​
Session Tracking

Session IDs track which AI session closed an issue: 
# Set via environment
export CLAUDE_SESSION_ID="session-2025-01-15-abc"
bd close bd-123 --json

# Or via flag
bd close bd-123 --session "session-2025-01-15-abc" --json
Stored in closed_by_session field for analytics and debugging.

​
Best Practices

​
For Agents

  1. Always provide --reason with meaningful context
  2. Use --json for parsing
  3. Use --continue for molecule workflows
  4. Use --suggest-next to find next work
  5. Set CLAUDE_SESSION_ID for tracking

​
For Humans

  1. Write descriptive reasons for audit trail
  2. Check dependencies before closing (bd show)
  3. Use --force sparingly (indicates process issue)
  4. Close parent epics after all children are done

​
Agent Workflow

# Standard workflow
bd update bd-123 --claim --json
# ... do work ...
bd close bd-123 --reason "Implemented feature X" --json

# Molecule workflow
bd update bd-mol-abc.1 --claim --json
# ... do work ...
bd close bd-mol-abc.1 --continue --json
# Now working on bd-mol-abc.2

# With next work suggestion
bd close bd-123 --suggest-next --json | jq -r '.unblocked[0].id'
# Get next issue to work on

​
Exit Codes

  • 0 - All issues closed successfully
  • 1 - One or more issues failed to close (validation error, already closed, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us