Skip to main content
The bd todo command provides a lightweight interface for managing TODO items as task-type issues.

​
Philosophy

TODOs in bd are not a separate tracking system - they are regular task-type issues with convenient shortcuts. This means:
  • No parallel systems: TODOs use the same storage and sync as all other issues
  • Promotable: Easy to convert a TODO to a bug/feature when needed
  • Full featured: TODOs support all bd features (dependencies, labels, routing)
  • Simple interface: Quick commands for common TODO workflows

​
Quick Start

# Add a TODO
bd todo add "Fix the login bug" -p 1

# List TODOs
bd todo

# Mark TODO as done
bd todo done <id>

​
Commands

​
bd todo (or bd todo list)

List all open task-type issues. 
bd todo                  # List open TODOs
bd todo list            # Same as above
bd todo list --all      # Show completed TODOs too
bd todo list --json     # JSON output
Output: 
  ○ test-yxg  Fix the login bug                         ● P1  open
  ○ test-ryl  Update documentation                      ● P3  open

Total: 2 TODOs

​
bd todo add <title>

Create a new TODO item (task-type issue). 
bd todo add "Fix the login bug"                                # Default P2
bd todo add "Update docs" -p 3 -d "Add examples"              # With priority and description
bd todo add "Critical fix" --priority 0 --description "ASAP"  # P0 task
Flags:
  • -p, --priority <0-4>: Priority (default: 2)
  • -d, --description <text>: Description

​
bd todo done <id> [<id>...]

Mark one or more TODOs as complete. 
bd todo done test-abc              # Close one TODO
bd todo done test-abc test-def     # Close multiple
bd todo done test-abc --reason "Fixed in PR #42"  # With reason
Flags:
  • --reason <text>: Reason for closing (default: “Completed”)

​
Converting TODOs

TODOs are regular task issues, so you can convert them: 
# Promote TODO to bug
bd update test-abc --type bug --priority 0

# Add dependencies
bd dep add test-abc test-def

# Add labels
bd update test-abc --set-labels "urgent,frontend"

​
Viewing TODO Details

Use regular bd commands: 
bd show test-abc        # View TODO details
bd list --type task     # List all tasks (including TODOs)
bd ready               # See ready TODOs in work queue

​
Examples

​
Daily TODO workflow

# Morning: add your tasks
bd todo add "Review PRs"
bd todo add "Fix CI pipeline" -p 1
bd todo add "Update changelog" -p 3

# Check what's on your plate
bd todo

# Complete work
bd todo done <id>
bd todo done <id>

# End of day: see what's left
bd todo

​
Converting TODO to full issue

# Start with a quick TODO
bd todo add "Login is broken"

# Later, realize it's more serious
bd update <id> --type bug --priority 0 --description "Users can't login, multiple reports"
bd update <id> --acceptance "Login works for all user types"

# Now it's a full-fledged bug with proper tracking
bd show <id>

​
FAQ

Q: Are TODOs different from tasks? A: No, TODOs are just task-type issues. The bd todo command provides shortcuts for common task operations. Q: Can TODOs have dependencies? A: Yes! Use bd dep add <todo-id> <blocks-id> like any other issue. Q: Do TODOs sync across machines? A: Yes, they’re stored in the Dolt database and synced via Dolt remotes like all other issues. Q: Can I use TODOs with bd ready? A: Yes! bd ready shows all unblocked issues, including task-type TODOs. Q: Should I use TODOs or regular tasks? A: Use bd todo for quick, informal tasks. Use bd create -t task for tasks that need more context or are part of larger planning.

​
Design Rationale

The TODO command follows beads’ philosophy of minimal surface area:
  1. No new types: TODOs are task-type issues
  2. No special storage: Same Dolt database as everything else
  3. Convenience layer: Just shortcuts for common operations
  4. Fully compatible: Works with all bd features and commands
This ensures:
  • No duplicate tracking systems
  • No migration needed between TODOs and tasks
  • Works with all existing bd tooling (federation, compaction, routing)
  • Simple to understand and maintain