beads CLI (bd)

beads (invoked as bd) is the godotz.ai task-graph tracker. It models work as a directed acyclic graph of epics and tasks, persisted in a local SQLite store at ~/.beads/db.sqlite. Every agent and human uses the same bd CLI to track progress.

Installation

beads ships with the godotz.ai harness. Verify installation:

bd --version
# beads 0.9.4

Global Flags

Commands

bd init

Initialize a beads workspace in the current directory.

bd init
# Created .beads/config.yml
# Initialized database at ~/.beads/db.sqlite

Creates .beads/config.yml with defaults. Safe to re-run — existing data is preserved.

Options:

bd init --project "fleet-upgrade" --owner "ops-team"

bd epic

Create or list epics. An epic is a top-level grouping of related tasks.

Create:

bd epic "Upgrade all nodes to NixOS 25.05"
# ✓ epic #7 created: Upgrade all nodes to NixOS 25.05

List:

bd epic list
# ID  Title                               Status    Tasks
# 7   Upgrade all nodes to NixOS 25.05   open      0/0
# 6   Deploy LiteLLM v1.42               closed    8/8

Options:

bd epic "Security hardening" --priority high --tags security,infra

bd task

Create a task, optionally attached to an epic.

bd task "Update NixOS flake inputs on pi-04" --epic 7
# ✓ task #42 created (epic #7)

With metadata:

bd task "Run nixos-rebuild on pi-04" \
  --epic 7 \
  --assign glm-5.1 \
  --depends 42 \
  --estimate 30m
# ✓ task #43 created (epic #7, depends on #42)

Fields:

bd show

Display details for a task, epic, or the full graph.

Single task:

bd show 42
# task #42: Update NixOS flake inputs on pi-04
# status:   in_progress
# assigned: glm-5.1
# epic:     #7
# depends:  —
# created:  2026-06-07 09:14

Epic with task tree:

bd show epic 7
# epic #7: Upgrade all nodes to NixOS 25.05
# ├── #42 [done]    Update NixOS flake inputs on pi-04
# ├── #43 [open]    Run nixos-rebuild on pi-04         (depends: #42)
# └── #44 [open]    Verify boot on pi-04

Full graph (current sprint):

bd show --all

bd done

Mark a task or epic complete.

bd done 42
# ✓ task #42 marked done

bd done epic 7
# ✓ epic #7 closed (8/8 tasks done)

Closing an epic with open tasks requires --force:

bd done epic 7 --force
# ⚠ 2 tasks still open — closing anyway

bd hooks

Manage lifecycle hooks that fire on task events. Hooks are shell scripts or omp-notify calls.

List registered hooks:

bd hooks list
# Event          Hook
# task.done      /opt/omp/hooks/notify-done.sh
# epic.closed    /opt/omp/hooks/ntfy-epic.sh

Register a hook:

bd hooks add task.done "/opt/omp/hooks/notify-done.sh"
# ✓ hook registered for task.done

Remove a hook:

bd hooks remove task.done

Available events:

Hook scripts receive the event payload as a JSON string in $BD_EVENT.

#!/usr/bin/env bash
# /opt/omp/hooks/notify-done.sh
echo "$BD_EVENT" | jq -r '.task.title' | xargs -I{} \
  curl -s -d "Task done: {}" https://ntfy.sh/omp-fleet

Related

• Task Graph concept
• Webhooks & Events
• Fleet Setup guide