How to manage an ingredient database

Gram uses a local ingredients.yaml file to store physical and nutritional data about the ingredients you use in your recipes. Maintaining this database ensures that features like Mass Standardization, Yield Calculation, and Nutritional Estimation work perfectly.

This guide explains the standard workflow for maintaining your database using the Gram CLI.

The database workflow

The recommended workflow consists of three steps, to be run in this exact order:

1. Syncing new ingredients

   As you write new recipes, you will inevitably use ingredients that are not yet in your database. Instead of adding them manually, let the CLI find them.

   gram db sync

   This command scans all .gram files in your project. If it finds an ingredient (e.g., @coconut milk{200ml}) that doesn’t exist in ingredients.yaml, it will add a blank entry for it.

   Tip

   It uses fuzzy matching to suggest avoiding duplicates if it finds a typo!

2. Linting and deduplication

   Sometimes, you might write @egg in one recipe and @eggs in another. Or @sugar and @sucre if you write in multiple languages.

   gram db lint

   This command uses the configured AI (see Configure AI Provider) to detect semantic duplicates in your database. If it finds egg and eggs, it will ask you which one to keep as the primary key. It will then merge the other into the primary key’s aliases list.

   Tip

   The AI respects the default language defined in your config.yaml. If it merges English and French terms, it will intelligently propose the term in your preferred language as the primary key!

   From now on, writing @eggs will automatically point to the egg database entry.

   Not the same as the recipe’s : alias syntax

   This aliases list is what shopping-list aggregation uses to group ingredients across recipes. It’s unrelated to the recipe-level @Real Name:Display Name renaming syntax (see Ingredients syntax), which only changes how an ingredient is displayed inline in the recipe steps — it never affects grouping or the shopping list.

3. Enriching data

   v1.1.0

   Now that your database has clean, deduplicated entries, you need to fill in their physical (density, unit weight, yield) and nutritional (calories, macros) data.

   Doing this manually is tedious. Gram can use AI to propose values for you in batches (see Configure AI Provider):

   gram db enrich

   The CLI will fetch standard nutritional data and densities for all incomplete entries, then walk you through them one by one so you can accept, edit, or skip each proposal — density and nutrition values are product-specific (a French AOP butter isn’t the same as a US one), so only you can really validate them. category/tags are low-stakes and get written automatically.

   It only ever fills in missing fields, never overwrites data you’ve manually entered, and is safe to re-run. Values you accept as-is are tagged # [LLM] in ingredients.yaml, marking them as AI estimates not yet reviewed by a human.

   Tip

   In a hurry, or scripting this in CI? gram db enrich --yes skips the review and accepts every AI estimate automatically. Use gram db enrich --report to preview what needs review without writing anything.

Validating your database

v1.1.0

Before committing your ingredients.yaml to version control, it is good practice to validate it against the Gram schema to ensure there are no formatting errors (like overlapping aliases).

gram db validate --strict

Sharing and merging databases

If you are working on a team, or if you want to import a community-driven ingredient database, you can merge an external YAML file into your local one:

gram db merge ~/Downloads/community-db.yaml

If there are conflicts (e.g., the community database says butter has 717 kcal, but yours says 740 kcal), the CLI will ask you interactively how to resolve them.