Breww recipe files allow you to share recipes between Breww accounts or edit recipe definitions outside of Breww using any text editor. The files use the YAML format (.breww-recipe.yaml) and contain a complete description of a recipe's stages, actions, reporting tags, and calculated fields.
This is particularly useful for:
- Sharing recipes between different Breww accounts (e.g. between brewery locations or with contract brewing partners)
- Backing up recipes in a human-readable format
- Editing recipes in bulk using a text editor before importing them
- Creating recipes programmatically from external tools or spreadsheets
Exporting a recipe
You can export any recipe as a Breww recipe file from its detail page.
- Navigate to the recipe you want to export (via
Production->View->Recipes, then select the recipe) - Click the Actions & tools button in the page header
- Select Export as Breww recipe file
This will download a .breww-recipe.yaml file containing the recipe's current version. The file is named using the pattern Recipe Name - v1.breww-recipe.yaml.
You can also export a specific version of a recipe by navigating to that version's detail page (via Actions & tools -> View version history on the recipe, then selecting the version) and using the same Export as Breww recipe file option.
The exported file will contain:
- Recipe details (name, beer name, batch size, brewhouse efficiency, expected wastage)
- All stages with their type, category, duration, and settings
- All actions within each stage (ingredients, readings, temperature changes, checks, etc.)
- Any reporting tags referenced by actions in the recipe
- Any calculated fields referenced by actions in the recipe
Importing a recipe
To import a Breww recipe file, head to Production -> View -> Recipes and click either:
- New recipe -> Import from Breww recipe file, or
- The Import Breww recipe file button on the new recipe page
The import process uses a multi-step wizard to guide you through the process.
Step 1: Upload file
Select the .breww-recipe.yaml file you wish to import. Breww will validate the file structure and report any errors found in the file.
Note: Breww recipe files can be opened and edited with any text editor. For a better experience, we recommend Visual Studio Code (free, Windows/Mac/Linux) which provides syntax highlighting and formatting for YAML files.
Step 2: Recipe details
Confirm or adjust the basic recipe details parsed from the file:
- Recipe name - Pre-filled from the file. Must be unique within your account.
- Beer - If the file contains a
beer_nameand a beer with a matching name exists in your account, it will be pre-selected. You can change this or leave it blank (you can link the recipe to a beer later). - Batch size - Pre-filled from the file, converted to your account's production volume unit.
- Brewhouse efficiency - Pre-filled from the file if specified.
- Expected wastage - Pre-filled from the file if specified.
Step 3: Stock item mapping
For each ingredient referenced in the recipe file, you need to map it to a stock item in your Breww account. Breww will automatically attempt to match ingredients by name:
- Exact match found (green badge) - The ingredient name in the file exactly matches a stock item name in your account.
- Similar match found (amber badge) - A stock item with a very similar name was found. Check that this is the correct item.
- No match found (red badge) - No matching stock item could be found. You will need to manually select the correct stock item from the dropdown.
Breww will also validate that the unit type of the selected stock item is compatible with the unit used in the recipe file (e.g. you cannot map a recipe ingredient specified in kilograms to a stock item tracked in litres).
If the recipe does not contain any ingredient additions, this step will be skipped.
Step 4: Stage type mapping
For each stage type used in the recipe, you need to map it to a stage type in your Breww account. Breww will automatically match stage types by name within the same category (e.g. Brewing, Fermenting).
- Exact match found (green badge) - A stage type with the same name and category already exists in your account.
- New stage type will be created (blue badge) - No matching stage type was found. If you leave the field blank, a new stage type will be created automatically with the name and category from the file.
You can also select a different existing stage type from the dropdown if you prefer.
Step 5: Reporting tags and calculated fields
This step only appears if the recipe file includes reporting tags or calculated fields.
For each reporting tag and calculated field defined in the file:
- If a matching tag or field already exists in your account, it will show as Use existing and no action is needed.
- If no match exists, you can choose to Create it in your account or Ignore from recipe (which will skip any actions that reference it).
Step 6: Review
The final step shows a summary of the import, including:
- Recipe name, beer, and batch size
- Total number of stages and actions
- Stock item mappings
- Stage type mappings
- Reporting tag and calculated field actions
Review the summary and click Import recipe to create the recipe. The imported recipe will be created as a draft version, ready for you to review and tweak.
Breww recipe file format reference
A Breww recipe file is a YAML document with four top-level sections: recipe, stages, reporting_tags, and calculated_fields. Only recipe and stages are required.
Here is a minimal example:
recipe:
name: Simple Pale Ale
batch_size: 1000 l
stages:
- name: Mash
type:
name: Single Infusion Mash
category: brewing
actions:
- type: add_ingredient
trigger:
type: start_of_stage
stock_item_name: Pale Malt
quantity: 200 kg
The recipe section
The recipe section defines the top-level recipe details.
| Field | Required | Description |
|---|---|---|
name |
Yes | The recipe name. |
beer_name |
No | The name of the beer this recipe is for. Used to auto-match to a beer in your account during import. |
batch_size |
Yes | The batch size as a quantity with a unit (e.g. 1000 l, 30 bbl, 10 hl). See the units section for supported units. |
brewhouse_efficiency |
No | Brewhouse efficiency as a percentage value (e.g. 75 for 75%). |
expected_wastage |
No | Expected wastage as a quantity with a unit (e.g. 5 l, 0.5 bbl). |
The stages section
The stages section is a list of recipe stages in order. Each stage represents a phase of the brewing process (e.g. Mash, Boil, Fermentation).
| Field | Required | Default | Description |
|---|---|---|---|
name |
Yes | The display name for this stage. | |
type |
Yes | An object containing name (stage type name) and category (see below). |
|
duration |
No | The duration of this stage (e.g. 1 hour, 7 days, 1 hour 30 minutes). See durations. |
|
repeated_per_turn |
No | false |
Whether this stage is repeated for each turn in a multi-turn batch. |
auto_allocate_stock |
No | true |
Whether to auto-allocate stock for ingredient additions in this stage. |
include_in_pre_allocate_stock |
No | true |
Whether to include this stage's ingredients in pre-allocation when starting a batch. |
actions |
No | [] |
A list of actions to perform during this stage. |
Stage type categories
Each stage type must belong to one of these categories:
| Category value | Description |
|---|---|
preparation |
Preparation stages (e.g. water treatment, starter preparation). |
brewing |
Brewing stages (e.g. mash, boil, whirlpool). |
fermenting |
Fermentation stages (e.g. primary fermentation, secondary fermentation). |
post_fermentation |
Post-fermentation stages (e.g. conditioning, dry hopping). |
Actions
Each stage can contain a list of actions. Every action must have a type field and a trigger field. The type determines what kind of action it is, and the trigger determines when it should happen.
All action types support an optional notes field for additional free-text notes.
Action type: add_ingredient
Adds a stock item (ingredient) to the brew.
| Field | Required | Description |
|---|---|---|
stock_item_name |
Yes | The name of the ingredient (mapped to a stock item during import). |
quantity |
Yes | The quantity to add, with a unit (e.g. 200 kg, 500 g, 2 units). |
ingredient_attributes |
No | A dictionary of attribute names and their decimal values (e.g. {alpha_acid: 5.5}). |
adjust_quantity_by_attribute |
No | The name of an attribute to use for automatic quantity adjustment (e.g. alpha_acid for hop additions). |
notes |
No | Additional notes for this action. |
Action type: add_water
Adds water to the brew.
| Field | Required | Description |
|---|---|---|
quantity |
Yes | The volume of water to add, with a unit (e.g. 100 l, 750 ml). |
notes |
No | Additional notes for this action. |
Action type: reading
Records a reading (e.g. gravity, temperature, pH).
| Field | Required | Description |
|---|---|---|
reading_type |
Yes | The type of reading. Must be one of: temperature, ph, gravity, time, weight, volume, custom. |
reading_unit |
No | The unit for the reading (e.g. SG, plato, brix, c, f, ph, l, kg). Only needed when expected values do not include a unit suffix. See specifying units on reading values below. |
expected_value |
No | A single expected value for this reading (e.g. "1.050 SG", "65 °C"). Cannot be used together with expected_range_start/expected_range_end — use either a fixed value or a range, not both. |
expected_range_start |
No | The lower bound of the expected range. Cannot be used together with expected_value. |
expected_range_end |
No | The upper bound of the expected range. Cannot be used together with expected_value. |
copy_to_batch_readings |
No | Set to true to copy this reading to the batch's analysis tab. Defaults to false. |
reporting_tag_name |
No | The variable name of a reporting tag to associate with this reading. Must be defined in the reporting_tags section or already exist on your account. |
custom_reading_name |
No | A custom name for this reading (only used when reading_type is custom). |
notes |
No | Additional notes for this action. |
Specifying units on reading values
For reading types that use units (temperature, gravity, ph, volume, weight), the unit must be provided. There are two ways to do this:
Approach 1: Include the unit in the value string (recommended)
The simplest approach is to include the unit directly in the expected value, e.g. "1.050 SG", "65 °C", "5.2 pH", "2350 l", "50 kg". This is the recommended approach because the unit is clear and self-contained.
# Fixed value example:
- type: reading
trigger:
type: start_of_stage
reading_type: gravity
expected_value: "1.050 SG"
# Range example:
- type: reading
trigger:
type: start_of_stage
reading_type: gravity
expected_range_start: "1.045 SG"
expected_range_end: "1.055 SG"
Approach 2: Use the reading_unit field
Alternatively, you can specify the unit separately using the reading_unit field and provide plain numeric values:
- type: reading
trigger:
type: start_of_stage
reading_type: ph
reading_unit: ph
expected_range_start: "5.2"
expected_range_end: "5.4"
Note: If you include units in the value strings and specify
reading_unit, the two must agree. For example, usingreading_unit: Platowithexpected_value: "1.050 SG"will produce an error.
When all expected values include a unit suffix, reading_unit is not needed. When expected values are plain numbers, reading_unit is required for reading types that use units.
All expected values within a single reading action must use the same unit. For example, you cannot mix "1.045 SG" and "10.5 Plato" in the same action.
Supported reading units
The following units are supported in reading values and the reading_unit field:
Temperature:
| Unit | Aliases |
|---|---|
°C |
C, celsius |
°F |
F, fahrenheit |
Gravity:
| Unit | Aliases |
|---|---|
SG |
sg |
Plato |
plato |
Brix |
brix |
pH:
| Unit | Aliases |
|---|---|
pH |
ph |
Volume:
| Unit | Aliases |
|---|---|
l |
litre, litres, liter, liters |
gal |
gallon, gallons |
bbl |
barrel, barrels |
imp_gal |
Weight:
| Unit | Aliases |
|---|---|
kg |
kilogram, kilograms |
lb |
lbs, pound, pounds |
time and custom reading types do not require a unit.
Action type: change_temperature
Sets a target temperature.
| Field | Required | Description |
|---|---|---|
target |
Yes | The target temperature (e.g. 65 °C, 149 °F). The ° symbol is optional. |
notes |
No | Additional notes for this action. |
Action type: check
Adds a check (a yes/no verification step) to the brew sheet.
| Field | Required | Description |
|---|---|---|
check_to_make |
Yes | The description of what should be checked. |
reporting_tag_name |
No | The variable name of a reporting tag to associate with this check. |
notes |
No | Additional notes for this action. |
Action type: custom_instructions
Adds custom free-text instructions to the brew sheet.
| Field | Required | Description |
|---|---|---|
instructions |
Yes | The instruction text. |
notes |
No | Additional notes for this action. |
Action type: take_notes
Adds a note-taking prompt to the brew sheet.
| Field | Required | Description |
|---|---|---|
note_title |
Yes | The title/prompt for the notes. |
notes |
No | Additional notes for this action. |
Action type: calculation
Adds a calculated field result to the brew sheet.
| Field | Required | Description |
|---|---|---|
calculated_field_name |
Yes | The variable name of the calculated field. Must be defined in the calculated_fields section or already exist on your account. |
notes |
No | Additional notes for this action. |
Triggers
Every action requires a trigger that determines when the action should occur during the stage. The trigger is an object with a type field and, for some types, additional fields.
Trigger type: start_of_stage
The action occurs at the start of the stage. No additional fields required.
trigger:
type: start_of_stage
Trigger type: immediately_after_previous_action
The action occurs immediately after the previous action in the stage completes. No additional fields required.
trigger:
type: immediately_after_previous_action
Trigger type: time_after_previous_action
The action occurs a specified time after the previous action completes.
| Field | Required | Description |
|---|---|---|
duration |
Yes | The delay after the previous action (e.g. 30 minutes, 1 hour). |
trigger:
type: time_after_previous_action
duration: 30 minutes
Trigger type: time_before_end_of_stage
The action occurs a specified time before the end of the stage.
| Field | Required | Description |
|---|---|---|
duration |
Yes | The time before the end of stage (e.g. 15 minutes, 1 hour). |
trigger:
type: time_before_end_of_stage
duration: 15 minutes
Trigger type: time_after_start_of_stage
The action occurs a specified time after the stage starts.
| Field | Required | Description |
|---|---|---|
duration |
Yes | The time after the start of the stage (e.g. 2 hours, 30 minutes). |
trigger:
type: time_after_start_of_stage
duration: 2 hours
Trigger type: on_fermentation_gravity_reading
The action is triggered when a gravity reading falls below a specified value.
| Field | Required | Description |
|---|---|---|
gravity_below |
Yes | The gravity threshold value (e.g. 1.010). |
gravity_unit |
Yes | The gravity unit (e.g. SG, plato, brix). |
trigger:
type: on_fermentation_gravity_reading
gravity_below: 1.010
gravity_unit: SG
Trigger type: end_of_stage
The action occurs at the end of the stage. No additional fields required.
trigger:
type: end_of_stage
Units on quantities
Quantity fields (such as batch_size, quantity on ingredients, and expected_wastage) must include a numeric value followed by a unit, separated by a space.
The following units are supported:
Mass units:
| Unit | Aliases |
|---|---|
kg |
kilogram, kilograms |
g |
gram, grams |
lb |
lbs, pound, pounds |
oz |
ounce, ounces |
Volume units:
| Unit | Aliases |
|---|---|
l |
litre, litres, liter, liters |
hl |
hectolitre, hectolitres, hectoliter, hectoliters |
ml |
millilitre, millilitres |
gal |
gallon, gallons |
bbl |
barrel, barrels |
fl oz |
floz |
Dimensionless units:
| Unit | Aliases |
|---|---|
unit |
units |
Examples: 200 kg, 500 g, 30 bbl, 1000 l, 2 units, 3.5 lb
When exporting, Breww uses the display unit configured for each stock item (for ingredients) or your account's production volume unit (for batch size and water additions).
Durations
Duration fields (such as stage duration and trigger duration) use natural language time expressions. Supported tokens are:
days/dayhours/hour/hrs/hrminutes/minute/mins/minseconds/second/secs/sec
Tokens can be combined: 1 hour 30 minutes, 2 days 4 hours.
Examples: 1 hour, 7 days, 30 minutes, 1 hour 30 minutes, 2 days 12 hours
Temperatures
Temperature values (in change_temperature target and reading expected values for temperature readings) use the format:
<number> °C
<number> °F
The ° symbol is optional, and full words (celsius, fahrenheit) are also accepted. Examples: 65 °C, 149 °F, 65 C, 65 celsius.
The reporting_tags section
The reporting_tags section is an optional list of reporting tag definitions used by actions in the recipe. Each tag is referenced by its variable_name from reading or check actions.
| Field | Required | Description |
|---|---|---|
name |
Yes | The display name of the reporting tag. |
variable_name |
Yes | The unique variable name used to reference this tag in actions and formulas. |
action_type |
Yes | The type of action this tag applies to. Must be reading or check. |
reading_type |
No | Required when action_type is reading. Must be one of: temperature, ph, gravity, time, weight, volume, custom. |
Example:
reporting_tags:
- name: Original Gravity
variable_name: og_reading
action_type: reading
reading_type: gravity
- name: Clarity Check
variable_name: clarity_check
action_type: check
The calculated_fields section
The calculated_fields section is an optional list of calculated field definitions. These are formulas that compute values from reporting tag variables and are displayed on the brew sheet.
| Field | Required | Description |
|---|---|---|
name |
Yes | The display name of the calculated field. |
variable_name |
Yes | The unique variable name for this field (can be referenced in other formulas). |
formula |
Yes | The calculation formula, using reporting tag and calculated field variable names. |
Example:
calculated_fields:
- name: Total Extract
variable_name: total_extract
formula: og_reading * batch_volume
- name: ABV Estimate
variable_name: abv_estimate
formula: (og_reading - fg_reading) * 131.25
Complete example
Here is a complete example showing all sections, action types, and trigger types:
recipe:
name: Full Test Recipe
beer_name: My Test Beer
batch_size: 500 l
brewhouse_efficiency: 75
expected_wastage: 5 l
stages:
- name: Preparation Stage
type:
name: Starter Prep
category: preparation
duration: 1 hour
repeated_per_turn: false
auto_allocate_stock: true
include_in_pre_allocate_stock: true
actions:
- type: add_ingredient
trigger:
type: start_of_stage
stock_item_name: Water Treatment
quantity: 10 g
ingredient_attributes:
alpha_acid: 5.5
adjust_quantity_by_attribute: alpha_acid
notes: Add carefully
- type: add_water
trigger:
type: immediately_after_previous_action
quantity: 100 l
- type: reading
trigger:
type: time_after_previous_action
duration: 30 minutes
reading_type: gravity
expected_range_start: "1.045 SG"
expected_range_end: "1.055 SG"
copy_to_batch_readings: true
reporting_tag_name: og_reading
custom_reading_name: Original Gravity
- type: change_temperature
trigger:
type: time_before_end_of_stage
duration: 15 minutes
target: 65 °C
- type: check
trigger:
type: time_after_start_of_stage
duration: 45 minutes
check_to_make: Verify clarity
reporting_tag_name: clarity_check
- type: custom_instructions
trigger:
type: end_of_stage
instructions: Clean all equipment thoroughly
- type: take_notes
trigger:
type: time_after_start_of_stage
duration: 2 hours
note_title: Batch observations
- type: calculation
trigger:
type: start_of_stage
calculated_field_name: total_extract
- name: Fermentation
type:
name: Primary Fermentation
category: fermenting
duration: 7 days
repeated_per_turn: true
auto_allocate_stock: false
include_in_pre_allocate_stock: false
actions:
- type: reading
trigger:
type: start_of_stage
reading_type: temperature
reporting_tags:
- name: Original Gravity
variable_name: og_reading
action_type: reading
reading_type: gravity
- name: Clarity Check
variable_name: clarity_check
action_type: check
calculated_fields:
- name: Total Extract
variable_name: total_extract
formula: og_reading * batch_volume
