beads/website/docs/cli-reference/formula.md
matt wilkie b2a4d1d04a
docs: generate CLI reference from live help (#3704)
* docs: generate CLI reference from live help

* docs(cli): move bd version stamp from per-command pages to index only

Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:

- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
  labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
  labelled with the explicit semver tag parsed from the directory name

This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.

Refs: mybd-afb, PR #3704

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 19:43:49 -07:00

2.8 KiB

id title slug sidebar_position
formula bd formula /cli-reference/formula 310

Generated from bd help --doc formula

bd formula

Manage workflow formulas - the source layer for molecule templates.

Formulas are YAML/JSON files that define workflows with composition rules. They are "cooked" into proto beads which can then be poured or wisped.

The Rig → Cook → Run lifecycle:

  • Rig: Compose formulas (extends, compose)
  • Cook: Transform to proto (bd cook expands macros, applies aspects)
  • Run: Agents execute poured mols or wisps

Search paths (in order):

  1. <resolved-beads-dir>/formulas/ (active project)
  2. ~/.beads/formulas/ (user)
  3. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)

Commands: list List available formulas from all search paths show Show formula details, steps, and composition rules

bd formula

bd formula convert

Convert formula files from JSON to TOML format.

TOML format provides better ergonomics:

  • Multi-line strings without \n escaping
  • Human-readable diffs
  • Comments allowed

The convert command reads a .formula.json file and outputs .formula.toml. The original JSON file is preserved (use --delete to remove it).

Examples: bd formula convert shiny # Convert shiny.formula.json to .toml bd formula convert ./my.formula.json # Convert specific file bd formula convert --all # Convert all JSON formulas bd formula convert shiny --delete # Convert and remove JSON file bd formula convert shiny --stdout # Print TOML to stdout

bd formula convert <formula-name|path> [--all] [flags]

Flags:

      --all      Convert all JSON formulas
      --delete   Delete JSON file after conversion
      --stdout   Print TOML to stdout instead of file

bd formula list

List all formulas from search paths.

Search paths (in order of priority):

  1. <resolved-beads-dir>/formulas/ (active project - highest priority)
  2. ~/.beads/formulas/ (user)
  3. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)

Formulas in earlier paths shadow those with the same name in later paths.

Examples: bd formula list bd formula list --json bd formula list --type workflow bd formula list --type convoy

bd formula list [flags]

Flags:

      --type string   Filter by type (workflow, expansion, aspect, convoy)

bd formula show

Show detailed information about a formula.

Displays:

  • Formula metadata (name, type, description)
  • Variables with defaults and constraints
  • Steps with dependencies
  • Composition rules (extends, aspects, expansions)
  • Bond points for external composition

Examples: bd formula show shiny bd formula show rule-of-five bd formula show security-audit --json

bd formula show <formula-name>