* 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>
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):
- <resolved-beads-dir>/formulas/ (active project)
- ~/.beads/formulas/ (user)
- $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):
- <resolved-beads-dir>/formulas/ (active project - highest priority)
- ~/.beads/formulas/ (user)
- $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>