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

Commands

bd todo (or bd todo list)

List all open task-type issues.
Output:

bd todo add <title>

Create a new TODO item (task-type issue).
Flags:
  • -p, --priority <0-4>: Priority (default: 2)
  • -d, --description <text>: Description

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

Mark one or more TODOs as complete.
Flags:
  • --reason <text>: Reason for closing (default: “Completed”)

Converting TODOs

TODOs are regular task issues, so you can convert them:

Viewing TODO Details

Use regular bd commands:

Examples

Daily TODO workflow

Converting TODO to full issue

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