> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bd cook

> Compile a formula into a proto (ephemeral by default)

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
```