cooklang-recipes

Cooklang Recipe Writing

Cook CLI

The cook command-line tool manages recipes. Key commands:

Command	Purpose
cook recipe "<path>"	Parse and display a recipe
cook recipe "<path>:2"	Scale recipe by factor
cook shopping-list <files>	Generate shopping list
cook doctor validate	Check all recipes for errors
cook doctor aisle	Find ingredients missing from aisle.conf
cook server	Browse recipes in web interface
cook search "<term>"	Search recipes

Recipe Display

cook recipe "Dinner/Pasta.cook"           # display recipe
cook recipe "Dinner/Pasta.cook:2"         # double the quantities
cook recipe "Dinner/Pasta.cook" -f json   # output as JSON
cook recipe "Dinner/Pasta.cook" -f markdown  # output as Markdown

Shopping Lists

cook shopping-list "Dinner/Pasta.cook"                    # single recipe
cook shopping-list "Dinner/Pasta.cook" "Dinner/Soup.cook" # multiple
cook shopping-list "Dinner/Pasta.cook:2"                  # scaled
cook shopping-list */*.cook                               # all recipes

Validation

cook doctor validate   # syntax errors and warnings
cook doctor aisle      # missing aisle.conf entries

Core Syntax

Markers

Marker	Purpose	Examples
@	Ingredient	@salt, @butter{2%tbsp}, @eggs{3}
#	Cookware	#pot, #frying pan{}, #bowl{large}
~	Timer	~{15%minutes}, ~resting{30%minutes}

Ingredient Format

@ingredient                    -- name only
@ingredient{quantity}          -- with quantity (no unit)
@ingredient{quantity%unit}     -- with quantity and unit
@multi-word ingredient{}       -- multi-word names need braces

Examples:

• @butter - name only
• @eggs{3} - quantity without unit
• @flour{250%g} - quantity with unit
• @ground black pepper{} - multi-word ingredient
• @olive oil{2%tbsp} - multi-word with quantity

Preparations

Add prep instructions in parentheses:

@onion{1}(diced)
@garlic{3%cloves}(minced)
@chicken{500%g}(cut into cubes)

Modifiers

Modifier	Purpose	Example
-	Hidden from shopping list	-@salt{to taste}
?	Optional ingredient	?@nuts{1%cup}
&	Reference earlier ingredient	&flour

Timer Formats

~{15%minutes}           -- exact time
~{2%minutes} to ~{3%minutes}  -- time range (preferred)
~{30%seconds}           -- short durations
~resting{10%minutes}    -- named timer

Recipe Structure

Metadata (YAML Frontmatter)

---
servings: 4
source: https://example.com/recipe
prep time: 15 minutes
cook time: 30 minutes
tags: dinner, quick, vegetarian
cuisine: Italian
difficulty: easy
---

Required: servings (must be a number, not "4 servings")

Optional: source, author, prep time, cook time, tags, cuisine, difficulty

Steps

Blank lines separate steps. Each paragraph becomes a numbered step:

Preheat #oven{} to 375°F.

Mix @flour{2%cups} and @sugar{1%cup} in a #bowl{large}.

Bake for ~{25%minutes} until golden.

Sections

For complex recipes with multiple parts, use =:

= Sauce

Mix @soy sauce{3%tbsp} with @honey{1%tbsp}.

= Stir Fry

Cook @chicken{1%lb} in -@oil{2%tbsp}.

Notes

Personal tips with >:

> Don't overmix the batter
> Works best with room temperature butter

Comments

-- Single line comment (not shown in output)

[- Multi-line
   comment block -]

Conversion Guidelines

Original	Cooklang
1 cup flour	@flour{1%cup}
2 large eggs	@eggs{2%large}
salt to taste	-@salt{to taste}
1/2 cup butter, softened	@butter{1/2%cup}(softened)
medium saucepan	#saucepan{medium}
cook for 20 minutes	cook for ~{20%minutes}
cook 2-3 minutes	cook ~{2%minutes} to ~{3%minutes}

Quality Checklist

• All ingredients marked with @
• Multi-word ingredients have {}
• Quantities include units where applicable
• Cookware marked with #
• Timers added for cooking steps
• Servings is a number (not "4 servings")
• Steps separated by blank lines
• Section headers use = not >>
• Pantry staples use -@
• Source credited if adapted

File Organization

• Filename becomes recipe title in apps
• Use Title Case: Chocolate Chip Cookies.cook
• Place in category folder: Desserts/Chocolate Chip Cookies.cook
• Categories: Breakfast, Lunch, Dinner, Sides, Sauces, Desserts, Drinks, Basics

Aisle Configuration

config/aisle.conf organizes shopping lists by store section:

[produce]
garlic|garlic clove|garlic cloves
onion|onions|yellow onion|red onion
bell pepper|peppers|green bell pepper|red bell pepper

[dairy]
butter|unsalted butter|salted butter
eggs|egg|large eggs|egg whites

[pantry]
flour|all-purpose flour|bread flour

Use | for synonyms that map to the same item.

Run cook doctor aisle after adding recipes to find missing entries.

Resources

• Cooklang Spec
• CLI Documentation