Beads Compatibility

Seamlessly interact with legacy Beads JSONL data without migrating.

←Back to Beads Compatibility feature page

Kanbus provides built-in compatibility with the older Beads format (which stores issues as a single .beads/issues.jsonl file). You do not need to migrate your data to use the Kanbus CLI or the Kanban board interface.

Enabling Beads Mode

Option 1: One-Time CLI Flag

You can use the --beads flag on any command to temporarily run in compatibility mode.

Terminal
kanbus --beads list
kanbus --beads show bdx-epic
kanbus --beads create "New issue" --parent bdx-epic

Option 2: Persistent Configuration

To avoid typing the flag constantly, enable it in your configuration files (.kanbus.yml or project/config.yaml):

Terminal
beads_compatibility: true

Once enabled, standard commands like kanbus list and kanbus console automatically read and write to .beads/issues.jsonl.

Supported Commands

When operating in beads mode, the following core features work as expected:

  • kanbus --beads list
  • kanbus --beads ready
  • kanbus --beads show <id>
  • kanbus --beads create <title> [--parent <id>]
  • kanbus --beads update <id> [--status <status>]
  • kanbus --beads delete <id>
  • kanbus --beads dep <id> [add|remove] <type> <target>

Migration (Optional)

If you decide you want to permanently move away from the JSONL format to the modern project/issues/ directory structure, Kanbus provides a one-way migration tool:

Terminal
kanbus migrate

Note: You can stay in Beads format indefinitely. However, certain new features like Local filtering (--no-local) are not supported while in beads mode.