Skip to main content

​
Overview

The bd mol distill command is the reverse of bd mol pour: instead of formula → molecule, it’s molecule → formula. It extracts a reusable formula from an existing epic, converting concrete values to variable placeholders for future reuse.

​
Usage

# Extract formula from epic
bd mol distill <epic-id> [formula-name]

# With variable substitution
bd mol distill bd-o5xe release-workflow --var branch_name=release-v2.0

# Preview without creating file
bd mol distill bd-abc123 --dry-run

# Specify output directory
bd mol distill bd-xyz789 my-workflow --output ~/.beads/formulas/

​
Arguments

  • <epic-id> - ID of the epic to distill into a formula
  • [formula-name] - Optional formula name. If omitted, derived from epic title.

​
Options

  • --var key=value - Replace value with {{variable}} placeholder (can be specified multiple times)
  • --dry-run - Preview what would be created without writing files
  • --output <dir> - Output directory for formula file (default: auto-detect)
  • --json - Output results in JSON format

​
Variable Syntax

Both formats are supported (smart detection): 
# Spawn-style: variable=value (recommended)
bd mol distill bd-epic workflow --var branch=feature-auth

# Substitution-style: value=variable
bd mol distill bd-epic workflow --var feature-auth=branch
The command detects which side is the concrete value by searching the epic text.

​
Output Locations

Formulas are written to the first writable directory (in order):
  1. .beads/formulas/ (project-level, default)
  2. ~/.beads/formulas/ (user-level, if project not writable)
Use --output to specify a different directory.

​
Examples

​
Extract Simple Workflow

Capture a successful workflow for reuse: 
# Team completed feature bd-auth-feature
bd mol distill bd-auth-feature feature-workflow
Output: 
✓ Distilled formula: 6 steps
  Formula: feature-workflow
  Path: .beads/formulas/feature-workflow.formula.json

To instantiate:
  bd mol pour feature-workflow

​
Extract with Variables

Replace specific values with variables: 
bd mol distill bd-auth-feature feature-workflow \
  --var component=auth \
  --var environment=staging
Output: 
✓ Distilled formula: 6 steps
  Formula: feature-workflow
  Path: .beads/formulas/feature-workflow.formula.json
  Variables: component, environment

To instantiate:
  bd mol pour feature-workflow --var component=<value> --var environment=<value>

​
Preview Before Creating

Use --dry-run to see the structure: 
bd mol distill bd-deploy-prod deploy-workflow --dry-run
Output: 
Dry run: would distill 8 steps from bd-deploy-prod into formula

Formula: deploy-workflow
Output: .beads/formulas/deploy-workflow.formula.json

Variables:
  environment: "production" → {{environment}}
  version: "v2.0.0" → {{version}}

Structure:
  ├── pre-deploy-checks
  ├── backup-database
  ├── deploy-application
  ├── run-migrations
  ├── smoke-tests
  ├── rollback-if-failed
  └── post-deploy-verification

​
Custom Output Location

Save formula to specific directory: 
bd mol distill bd-epic custom-workflow \
  --output ~/shared/formulas/

​
Variable Substitution

​
How It Works

The --var flag replaces concrete values in the epic text with {{variable}} placeholders: Before: 
Title: Deploy auth service to staging
Description: Deploy the auth component to the staging environment
After (with —var component=auth —var environment=staging): 
Title: Deploy {{component}} service to {{environment}}
Description: Deploy the {{component}} component to the {{environment}} environment

​
Smart Detection

The command automatically detects which format you used: 
# If epic contains "feature-auth" but not "branch"
bd mol distill bd-epic --var branch=feature-auth
# Detects: replace "feature-auth" with {{branch}}

# If epic contains "feature-auth" but not "branch"
bd mol distill bd-epic --var feature-auth=branch
# Detects: replace "feature-auth" with {{branch}}
Both produce the same result. Use whichever feels more natural.

​
Multiple Variables

Replace multiple values: 
bd mol distill bd-release release-workflow \
  --var version=v2.0.0 \
  --var region=us-west \
  --var tier=production

​
Formula Structure

The generated formula includes:
  • Title and description (from epic root)
  • Steps (from epic children)
  • Dependencies (from issue relationships)
  • Variables (from —var flags)
  • Labels (excluding internal ones)
  • Priority levels

​
Example Output File

.beads/formulas/feature-workflow.formula.json: 
{
  "formula": "feature-workflow",
  "description": "Standard feature development workflow",
  "version": 1,
  "type": "workflow",
  "vars": {
    "component": {
      "description": "Value for component",
      "required": true
    },
    "environment": {
      "description": "Value for environment",
      "required": true
    }
  },
  "steps": [
    {
      "id": "design",
      "title": "Design {{component}} architecture",
      "description": "Create design for the {{component}} component",
      "type": "task"
    },
    {
      "id": "implement",
      "title": "Implement {{component}}",
      "depends_on": ["design"],
      "type": "task"
    },
    {
      "id": "test",
      "title": "Test {{component}} in {{environment}}",
      "depends_on": ["implement"],
      "type": "task"
    }
  ]
}

​
Use Cases

​
Capture Tribal Knowledge

Team develops a successful workflow organically: 
# Team completes feature work
bd close bd-feature-auth

# Capture the process
bd mol distill bd-feature-auth auth-workflow

# Reuse for next feature
bd mol pour auth-workflow --var component=profile

​
Create Organization Standards

Standardize processes across teams: 
# Senior engineer completes exemplary work
bd mol distill bd-best-practice standard-feature \
  --output ~/shared/formulas/

# Share with team
# Others can now use: bd mol pour standard-feature

​
Incremental Refinement

Start with basic formula, refine over iterations: 
# First iteration
bd mol pour basic-feature --var name=v1
bd close bd-v1  # complete the work

# Extract and improve
bd mol distill bd-v1 improved-feature --var name=v1

# Edit .beads/formulas/improved-feature.formula.json
# Add better descriptions, more steps, etc.

# Use improved version
bd mol pour improved-feature --var name=v2

​
Document Successful Releases

Capture release processes that worked well: 
# After successful release
bd mol distill bd-release-v2.0 prod-release \
  --var version=v2.0.0 \
  --var date=2024-03-15

# Use for next release
bd mol pour prod-release \
  --var version=v2.1.0 \
  --var date=2024-04-15

​
Emergency Response Templates

Create templates from incident responses: 
# After resolving incident
bd mol distill bd-incident-response incident-template \
  --var service=api \
  --var severity=critical

# Use during next incident
bd mol pour incident-template \
  --var service=database \
  --var severity=high

​
JSON Output

{
  "formula_name": "feature-workflow",
  "formula_path": ".beads/formulas/feature-workflow.formula.json",
  "steps": 6,
  "variables": ["component", "environment"]
}

​
Workflow: Distill → Refine → Pour

​
1. Distill

Extract the raw formula: 
bd mol distill bd-successful-epic my-workflow

​
2. Refine

Edit the generated formula file: 
# Edit .beads/formulas/my-workflow.formula.json
# - Improve descriptions
# - Add default values
# - Adjust dependencies
# - Add validation patterns

​
3. Verify

Test the formula: 
bd mol seed my-workflow

​
4. Pour

Use the refined formula: 
bd mol pour my-workflow --var name=test

​
Common Patterns

​
No Variables (Direct Copy)

Just capture the structure: 
bd mol distill bd-epic simple-workflow
# No --var flags = no variables, literal copy

​
Auto-Named Formula

Let formula name derive from epic title: 
bd mol distill bd-epic
# Formula name = sanitized epic title
# "Deploy Auth Service" → "deploy-auth-service"

​
Multiple Epics, Same Formula

Distill similar epics to compare: 
bd mol distill bd-feature-1 approach-1
bd mol distill bd-feature-2 approach-2

# Compare .beads/formulas/approach-*.formula.json
# Merge best practices into unified formula

​
Error Handling

​
Variable Not Found

bd mol distill bd-epic workflow --var nonexistent=value
# Error: neither 'nonexistent' nor 'value' found in epic text
Solution: Check epic content and use actual values.

​
Epic Not Found

bd mol distill bd-missing workflow
# Error: 'bd-missing' not found
Solution: Verify epic ID with bd list --type epic.

​
Write Permission Denied

bd mol distill bd-epic workflow
# Error: no writable formula directory found
# Try: mkdir -p .beads/formulas
Solution: Create .beads/formulas/ directory or use --output.

Build docs developers (and LLMs) love

Get started for freeTalk to us