bd close

Close completed issues with reason

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

With Reason

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

Reason Aliases

Git Style

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

Force Close

Override Blocker Check

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

Continue Workflow

Auto-Advance

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

Suggest Next

See Unblocked Work

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

Session Tracking

With Session ID

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.)

Related Commands

• bd update --status closed - Alternative way to close
• bd show - Check dependencies before closing
• bd dep list --direction up - See what this issue blocks
• bd ready - Find next work after closing