Skip to main content
Generated from bd help --doc cook. Cook transforms a .formula.json file into a proto. By default, cook outputs the resolved formula as JSON to stdout for ephemeral use. The output can be inspected, piped, or saved to a file. Two cooking modes are available: COMPILE-TIME (default, —mode=compile): Produces a proto with {{variable}} placeholders intact. Use for: modeling, estimation, contractor handoff, planning. Variables are NOT substituted - the output shows the template structure. RUNTIME (—mode=runtime or when —var flags provided): Produces a fully-resolved proto with variables substituted. Use for: final validation before pour, seeing exact output. Requires all variables to have values (via —var or defaults). Formulas are high-level workflow templates that support:
  • Variable definitions with defaults and validation
  • Step definitions that become issue hierarchies
  • Composition rules for bonding formulas together
  • Inheritance via extends
The —persist flag enables the legacy behavior of writing the proto to the database. This is useful when you want to reuse the same proto multiple times without re-cooking. For most workflows, prefer ephemeral protos: pour and wisp commands accept formula names directly and cook inline. Examples: bd cook mol-feature.formula.json # Compile-time: keep {{vars}} bd cook mol-feature —var name=auth # Runtime: substitute vars bd cook mol-feature —mode=runtime —var name=auth # Explicit runtime mode bd cook mol-feature —dry-run # Preview steps bd cook mol-release.formula.json —persist # Write to database bd cook mol-release.formula.json —persist —force # Replace existing Output (default): JSON representation of the resolved formula with all steps. Output (—persist): Creates a proto bead in the database with:
  • ID matching the formula name (e.g., mol-feature)
  • The “template” label for proto identification
  • Child issues for each step
  • Dependencies matching depends_on relationships
bd cook <formula-file> [flags]
Flags: 
      --dry-run               Preview what would be created
      --force                 Replace existing proto if it exists (requires --persist)
      --mode string           Cooking mode: compile (keep placeholders) or runtime (substitute vars)
      --persist               Persist proto to database (legacy behavior)
      --prefix string         Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature')
      --search-path strings   Additional paths to search for formula inheritance
      --var stringArray       Variable substitution (key=value), enables runtime mode