cookcli

CookCLI

Command line tools for working with Cooklang recipes. Full reference: CookCLI documentation.

Quick Install

# macOS/Linux (Homebrew)
brew install cookcli

# Download binary (all platforms)
# Visit: https://github.com/cooklang/CookCLI/releases

Table of Contents

• What is CookCLI?
• Getting Started
• Installation
• Commands
• Documentation
• Configuration
• Tips
• Contributing
• Contributors
• License
• Support

What is CookCLI?

CookCLI provides a suite of commands to create shopping lists, reports and maintain recipes. We've built it to be simple and useful for automating your cooking and shopping routine with existing UNIX command line and scripting tools. It can also function as a webserver for your recipes, making them browsable on any device with a web browser.

Try the web interface live at demo.cooklang.org

✨ Features

• UNIX Philosophy - Integrate your Cooklang recipes with other tools
• Meal Planning - Script meal planning and shopping
• Reports - Evaluate your recipes or menus with custom reports
• Web Interface - Browse recipes from any device
• Smart Shopping - Generate organized shopping lists
• Recipe Search - Find recipes quickly
• Pantry Tracking - Manage inventory and expiration dates

Getting Started

First, install CookCLI using one of the methods below. CookCLI comes with a few sample recipes to play with. cook seed populates its target directory with recipe files and folders, so create a dedicated directory for them first:

$ mkdir my-recipes && cd my-recipes
$ cook seed ./
$ cook recipe "Neapolitan Pizza.cook"

This displays the recipe in a human-readable format:

…

Create a shopping list from multiple recipes:

$ cook -v shopping-list "Neapolitan Pizza.cook" "./Breakfast/Easy Pancakes.cook""

Plan your meals with a menu file (Weekly Plan.menu):

---
servings: 2
---

==Saturday==

Breakfast: \
- @oats{1%cup} with @milk{1/2%cup} and @honey{1%tbsp}

Lunch: \
- @./lamb-chops{}

Dinner: \
- @./Neapolitan Pizza{}

==Sunday==

Breakfast: \
- @./Breakfast/Easy Pancakes{} with @maple syrup{2%tbsp}

Lunch: \
- @./Salads/Caprese{}

Dinner: \
- @./Risotto{}

Menu files let you reference recipes and inline ingredients, plan by day and meal, and generate a combined shopping list for the whole plan.

Or start the web server to browse your recipes:

$ cook server --open
Listening on http://127.0.0.1:9080
Serving Web UI on http://localhost:9080
Serving recipe files from: "/Users/chefalexey/recipes"

Installation

Download Binary

Download the latest release for your platform from the releases page and add it to your PATH.

macOS/Linux

Using Homebrew:

brew install cookcli

Fedora / RPM-based Linux

Every release ships RPMs built in Fedora containers (x86_64 and aarch64). Download the one for your Fedora version and install it:

sudo dnf install ./cookcli-<version>-1.fcXX.x86_64.rpm

The package installs the cook binary and shell completions. To build the RPM yourself (or to set up a COPR repository), see packaging/fedora.

Install with Cargo

If you have Rust installed:

cargo install cookcli --locked

--locked builds against the dependency versions we tested and released with, rather than re-resolving to the newest compatible ones.

Note that this compiles CookCLI and all its dependencies from source, which needs a few GB of RAM and disk. If you are on a Raspberry Pi, an Armbian board, or anything else memory-constrained, prefer the prebuilt binaries — we publish aarch64 and armv7 Linux builds.

cargo install places its build directory under $TMPDIR. On Armbian, /tmp is mounted on zram — a RAM-backed device sized to half your RAM — so a multi-gigabyte build will exhaust memory and fail, sometimes with a confusing failed to load bitcode of module ... error.

Point the build somewhere on real storage:

CARGO_TARGET_DIR=~/.cache/cookcli-build cargo install cookcli --locked

If memory is still tight, disable link-time optimisation for the build:

CARGO_PROFILE_RELEASE_LTO=false \
CARGO_TARGET_DIR=~/.cache/cookcli-build \
  cargo install cookcli --locked

Build from Source

You'll need Rust and Node.js installed. Then:

# Clone the repository
git clone https://github.com/cooklang/CookCLI.git
cd CookCLI

# Install frontend dependencies
npm install

# Build CSS and JS (required for web UI; the build fails without them)
npm run build-css
npm run build-js

# Build the CLI with web UI
cargo build --release

# Binary will be at target/release/cook

Building without Node.js

static/css/output.css and static/js/editor.bundle.js are generated by Tailwind and esbuild and are not checked into git, so they are missing from clones and from GitHub's auto-generated tag archives — and cargo build refuses to start without them.

If Node.js is unavailable or its native toolchain has no build for your platform, use a source drop that ships those two files prebuilt:

# cook-<version>-source.tar.gz is attached to each GitHub release.
# Set VERSION to the one you want: https://github.com/cooklang/CookCLI/releases
VERSION=0.34.0

curl -LO "https://github.com/cooklang/CookCLI/releases/download/v$VERSION/cook-$VERSION-source.tar.gz"
tar xzf "cook-$VERSION-source.tar.gz"
cd "cookcli-$VERSION"
cargo build --release --locked

The crates.io package (cargo install cookcli --locked) includes them too.

Cargo features

The optional commands are behind Cargo features, all enabled by default. Turning them off cuts the dependency graph roughly in half (412 crates → 225) and the binary from ~23 MB to ~9 MB — useful for CI/CD, package managers, or small machines where you only want the core recipe tooling.

# Core CLI only: recipe, shopping-list, search, doctor, pantry, report, build, seed
cargo build --release --no-default-features

# Core plus the web server
cargo build --release --no-default-features --features server

Everything not listed above — parsing, scaling, shopping lists, search, pantry, reports and the static site builder — is always compiled in.

Development Setup

For development with hot-reload of CSS changes:

# Install dependencies
npm install

# In one terminal, watch CSS changes
npm run watch-css

# In another terminal, run the development server
cargo run -- server ./seed

# Or use the Makefile
make dev_server  # Builds CSS and starts server

Commands

CookCLI follows the UNIX philosophy: each command does one thing well.

cook recipe

Parse and display recipe files. You can view them in different formats and scale quantities.

# View a recipe
cook recipe "Pasta Carbonara.cook"

# Scale a recipe to 2x
cook recipe "Pizza.cook:2"

# Output as JSON
cook recipe "Soup.cook" -f json

# Save as Markdown
cook recipe "Cake.cook" -f markdown > cake.md

cook shopping-list

Generate shopping lists from one or more recipes. Ingredients are automatically combined and organized by store section.

# Single recipe
cook shopping-list "Dinner.cook"

# Multiple recipes with scaling
cook shopping-list "Pasta.cook:3" "Salad.cook"

# All recipes in a directory
cook shopping-list *.cook

cook server

Run a web server to browse your recipes from any device.

# Start on localhost
cook server

# Allow access from other devices on your network
cook server --host

# Use a different port
cook server --port 8080

# Open browser immideately
cook server --open

cook build web

Generate a self-contained static website from your recipes. Hostable anywhere or browsable via file://.

# Build into ./_site from the current directory
cook build web

# Build a specific collection into a custom output
cook build web dist --base-path ~/my-recipes

# Build for hosting under a subpath
cook build web --base-url /recipes/

# Link back to the recipe repository from the footer
cook build web --repo-url https://github.com/user/my-recipes

cook search

Find recipes by searching through ingredients, instructions, and metadata.

# Search for recipes with chicken
cook search chicken

# Find quick recipes
cook search "30 minutes"

# Search in specific directory
cook search -b ~/recipes pasta

cook import

Import recipes from websites and convert them to Cooklang format. Requires OPENAI_API_KEY environment variable set.

# Import a recipe
cook import https://www.example.com/recipe > recipe.cook

# Import without conversion
cook import https://www.example.com/recipe --skip-conversion

cook doctor

Check your recipe collection for issues and maintain consistency.

# Validate all recipes and display parsing errors
cook doctor validate

# Check aisle configuration for shopping lists
cook doctor aisle

# Check pantry configuration
cook doctor pantry

# Run all checks
cook doctor

cook seed

Add sample recipes to explore Cooklang features. This populates the target directory with recipe files and folders, so point it at an empty or dedicated directory.

# Add to current directory
cook seed ./

# Add to specific directory
cook seed ~/my-recipes

cook report

Generate custom outputs using templates (experimental feature).

# Generate a recipe card
cook report -t recipe-card.md.jinja recipe.cook

# Create nutrition label
cook report -t nutrition.html.jinja recipe.cook

cook pantry

Manage your pantry inventory, track low stock items, expiring ingredients, and find recipes you can make.

# Show items that are low or out of stock
cook pantry depleted

# Check expiring items in the next 7 days
cook pantry expiring

# Find recipes you can make with available ingredients
cook pantry recipes

# Include partial matches (recipes where most ingredients are available)
cook pantry recipes --partial --threshold 60

# Output in machine-readable formats
cook pantry -f json depleted
cook pantry -f yaml expiring --days 14

Documentation

Detailed documentation for each command is available in the docs/ directory:

• Recipe command - viewing and converting recipes
• Shopping lists - creating shopping lists
• Server - web interface
• Build - generate a static website
• Search - finding recipes
• Import - importing from websites
• Doctor - validation and maintenance
• Seed - example recipes
• Report - custom outputs
• Pantry - inventory management and tracking
• Completions - shell completion scripts

⚙️ Configuration

CookCLI looks for configuration files in:

• ./config/ - in your recipe directory (highest priority)
• ~/.config/cooklang/ - in your home directory (fallback)
• `~/Librar