- Blog
- Guides and Tutorials
- The Complete CookCLI Guide: From Install to Daily Use
The Complete CookCLI Guide: From Install to Daily Use
If you keep your recipes as .cook files, CookCLI is the tool that makes them useful. Parse a recipe, generate a combined shopping list from a week's worth of dinners, serve your whole collection on your local network, scale any dish to any number of servings — all from the terminal.
This guide covers every major command with real examples. You should be able to go from zero to productive in one sitting.
Installation
macOS via Homebrew is the easiest path:
Linux and macOS binary — download the latest release directly from GitHub:
Archives are named cook-<version>-<os>-<arch>[-<libc>]: check the releases page for the right one for your system (linux-aarch64-musl, macos-aarch64, …).
Docker — useful for trying it out without installing anything permanently:
Verify the install worked:
Your First Recipe
If you don't have any .cook files yet, the seed command creates a set of example recipes to explore:
You'll see a handful of recipes. Open one in your editor to see the format, then parse it with cook recipe:
The output shows the recipe broken into structured sections — metadata, ingredients with quantities, cookware, and the method steps. This is the parsed representation CookCLI works from.
Let's write a recipe from scratch. In a new, empty folder, save this as risotto.cook:
Parse it:
The parser pulls every ingredient out of prose and into a clean list. That's the foundation everything else builds on.
Shopping Lists
This is the feature that makes keeping recipes in Cooklang format worth it.
Say you're planning Monday through Wednesday: risotto, a pasta sauce, and a roast chicken. Generate one combined shopping list:
CookCLI merges ingredients across all three recipes, combining identical items. If risotto and pasta sauce both call for garlic, you get one line (garlic 4 cloves) — not two separate entries.
Scaling per recipe — if you're making a double batch of the pasta sauce but half the risotto, add a :N multiplier per recipe:
Each recipe scales independently. The quantities on the shopping list reflect the scaled amounts.
Organizing by aisle — create an aisle.conf file to group ingredients by where they live in your store:
The output groups ingredients under [produce], [dairy] and so on; anything not in the file lands under [other]. If you save the file as config/aisle.conf in your recipe folder, CookCLI finds it without -a. Practical when you're actually walking the store.
Excluding pantry staples — if you always have olive oil, salt, and stock on hand, list them in config/pantry.conf (TOML):
CookCLI finds config/pantry.conf automatically and leaves those items off the list. To use a file kept elsewhere, pass --pantry path/to/pantry.conf.
The Recipe Server
cook server starts a local web interface for browsing your recipes from any device on your network:
By default it runs on port 9080. Open http://localhost:9080 in a browser. You'll see your recipe collection as a browseable library — search by name, ingredient or tag, click through to formatted recipe views.
Access from your phone or tablet — this is the practical use case. Start the server with --host, find your computer's local IP address, and open http://192.168.x.x:9080 on whatever device is propped up in the kitchen. The interface is mobile-friendly.
By default the server only accepts connections from the same machine. To allow other devices:
Change the port with --port if something else is already running on 9080. The server reads .cook files directly from disk, so any changes you make to recipes are reflected immediately on reload.
Scaling Recipes
Any cook recipe call accepts a :N suffix that multiplies the recipe by N:
This halves the 4-serving recipe to 2 servings. All ingredient quantities adjust proportionally. 320 g arborio rice becomes 160 g. 1 litre of stock becomes 0.5 litre.
Double it to 8 servings and the quantities double.
Fixed ingredients — sometimes a quantity shouldn't scale. Salt, spices, or seasoning additions that you'd adjust by taste rather than math. Mark them fixed with =:
Fixed ingredients stay at their stated quantity regardless of the :N multiplier.
Scaling works identically in shopping lists:
A double batch of risotto plus one and a half of the chicken, combined and totalled.
Search and Discovery
Once you have more than a handful of recipes, finding what you can make from what you have becomes useful. cook search queries your recipe collection:
Returns every recipe that contains garlic as an ingredient.
Search by multiple terms to find recipes that match all of them. Useful when you have specific ingredients you want to use up.
Search also matches recipe names and metadata:
If you've tagged recipes consistently in frontmatter, these queries surface the right results fast.
Pantry Management
The cook pantry subcommands handle tracking what you have on hand. They read config/pantry.conf in your recipe folder. This pairs well with shopping lists — you know what you have, CookCLI knows what you need.
Check what's running low:
See what's expiring soon:
Find out which recipes you can make from current pantry stock:
This cross-references your pantry against your recipe collection and returns what you can cook right now without a trip to the store.
See which ingredients are worth keeping in stock to cover the most recipes:
The pantry subcommands are more useful the more consistently you maintain your pantry data, but even partial tracking helps — especially for staples and things you buy in bulk.
Importing Recipes
Found a recipe online you want to add to your collection? cook import fetches a URL and converts it to .cook format:
This requires an OpenAI API key set as an environment variable:
The import command fetches the page, extracts the recipe content, and uses the language model to convert it into valid Cooklang syntax. Review the output before saving — it's good but not always perfect, especially for recipes with unusual formats or vague ingredient quantities.
Redirect the output to a file:
Validating Recipes
cook doctor validate checks every .cook file in the current directory (and subfolders) for syntax errors and warnings:
Point it at another directory with -b:
Without flags the command always exits 0. The --strict flag makes it exit non-zero when any error or warning is found, which is what you want in CI:
Add this to a pre-commit hook or CI pipeline if you want to catch broken recipes before they land in your main collection. Malformed ingredient syntax, invalid quantities, references to recipes that don't exist — doctor surfaces these before they cause problems downstream.
Editor Integration
If you use a code editor with LSP support, cook lsp starts the Cooklang Language Server:
Configure your editor to use it for .cook files and you get syntax highlighting, error underlining, and autocomplete as you write recipes. The setup varies by editor — the LSP command page has editor-specific instructions for VS Code, Neovim, and others.
Quick Reference
| Command | What it does |
|---|---|
cook recipe file.cook | Parse and display a recipe |
cook recipe file.cook:2 | Display the recipe doubled |
cook shopping-list *.cook | Combined shopping list |
cook shopping-list a.cook:2 b.cook:0.5 | Shopping list with per-recipe multipliers |
cook shopping-list -a aisle.conf *.cook | Shopping list grouped by aisle |
cook shopping-list --pantry pantry.conf *.cook | Shopping list excluding pantry items |
cook server my-recipes/ | Start recipe browser on port 9080 |
cook server my-recipes/ --port 8080 | Use a different port |
cook search garlic | Find recipes by ingredient or name |
cook search chicken lemon | Find recipes matching multiple terms |
cook import <URL> | Import recipe from website (needs OPENAI_API_KEY) |
cook pantry depleted | Show low-stock pantry items |
cook pantry expiring | Show expiring pantry items |
cook pantry recipes | Show what you can cook now |
cook pantry plan | Rank ingredients to stock by recipes covered |
cook doctor validate | Check all recipes in the current folder |
cook doctor validate --strict | Exit non-zero on any issue (CI-friendly) |
cook seed my-recipes | Create example recipes to explore |
cook lsp | Start the Language Server |
Getting Productive
The workflow that works best day-to-day: recipes live as .cook files in a folder, the recipe server runs when you're in the kitchen, and shopping lists get generated before each grocery run.
Start with cook seed to see real examples, write a few of your own recipes, then run cook server to see how it looks as a browseable collection. From there, cook shopping-list for the week's meal plan becomes a natural habit.
The CookCLI documentation at /cli/ covers every flag and option in detail. The spec at /docs/spec/ has the full Cooklang syntax reference if you want to go deeper on the recipe format itself.
-Alex