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. Sync: Find new ingredients in your recipes.
2. Lint: Deduplicate plurals and synonyms.
3. Enrich: Use AI to fill in the missing data.

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 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.

3. Enriching Data

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 do it for you in batches:

gram db enrich

The CLI will fetch standard nutritional data and densities for all incomplete entries in your database.

It is completely idempotent—it will only fill in missing fields and will never overwrite data you have manually entered.

Validating Your Database

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.