How to generate a weekly shopping list

If you use Gram for meal prepping or batch cooking, you likely have multiple .gram files scattered in a directory.

Generating a single, consolidated shopping list across multiple recipes is one of Gram’s most powerful features. The @gram-lang/kitchen compiler aggregates ingredients intelligently, fusing quantities when possible.

The gram shop command

Use the CLI gram shop command and pass a glob pattern targeting your recipes.

# Target a specific folder
gram shop "menus/week-1/*.gram"

What happens during aggregation?

1. ID Matching: The compiler groups all ingredients that share the same base ID (e.g., all instances of @butter).
2. Alias Resolution: If your database defines unsalted butter as an alias for butter, Gram will seamlessly merge @unsalted butter{50g} and @butter{50g} into a single 100g entry, grouped internally under the canonical id butter. The displayed name isn’t forced to butter though — it comes from whichever recipe’s own wording was processed first, enriched with the database’s nicer name only when that recipe already used the exact canonical word itself. See Shopping List Aggregation for the full rule.
3. Unit Normalization: If one recipe uses @milk{200ml} and another uses @milk{1 cup}, the analyzer uses the database to normalize them (usually into grams, or whichever display unit you configured).
4. Categorization: The final list is sorted by culinary categories (e.g., Dairy, Produce, Pantry) based on your ingredients.yaml data, making it easy to navigate a supermarket.

Batch scaling

You can scale your entire meal plan at once. If your recipes are written for 2 portions, but you have 4 guests this week, you can pass a global scale multiplier:

gram shop "menus/week-1/*.gram" --scale 2

Note

When scaling multiple files at once, you must use a numeric multiplier (--scale 2). You cannot scale by a specific ingredient reference (--scale flour=500g), as the compiler wouldn’t know which recipe’s flour to target.

Output formats

By default, gram shop outputs a beautifully formatted ASCII list directly in your terminal.

However, you can export it to different formats to share it with your family or integrate it with other tools:

# Export to Markdown
gram shop "menus/*.gram" --format md --output shopping-list.md

# Export to JSON
gram shop "menus/*.gram" --format json --output shopping-list.json