Pantry | Cooklang: recipe markup language

The pantry command helps you manage and analyze your pantry inventory, tracking what items are low on stock, expiring soon, or available for cooking.

Overview

cook pantry [OPTIONS] &lt;SUBCOMMAND&gt;

Options

-b, --base-path <PATH> - Base path for recipes and configuration files
-f, --format <FORMAT> - Output format: human (default), json, or yaml
-v, --verbose - Increase verbosity (can be used multiple times)
-h, --help - Print help information

Subcommands

`depleted` (alias: `d`)

Shows items that are out of stock or have low quantities.

cook pantry depleted [OPTIONS]

Options:

--all - Show all items including those without quantities

How it works:

Shows items where current quantity is at or below the defined low threshold
If no low threshold is defined, uses heuristics (≤100g/ml, ≤1 item)
Displays the low threshold for each item when available

Example:

$ cook pantry depleted
Depleted or Low Stock Items:
============================

PANTRY:
  • flour (400%g) [low when &lt; 500%g]
  • garlic (5) [low when &lt; 10]
  • onion (3) [low when &lt; 5]

`expiring` (alias: `e`)

Shows items that are expiring soon.

cook pantry expiring [OPTIONS]

Options:

-d, --days <DAYS> - Number of days to look ahead (default: 7)
--include-unknown - Include items without expiry dates

Example:

$ cook pantry expiring --days 14
Items Expiring Within 14 Days:
================================

Expiring Soon:
  • yogurt - 2025-09-17 (expires tomorrow) [fridge]
  • eggs - 2025-09-18 (expires in 2 days) [fridge]
  • milk - 2025-09-20 (expires in 4 days) [fridge]

`recipes` (alias: `r`)

Lists recipes that can be made with items currently in pantry.

cook pantry recipes [OPTIONS]

Options:

-p, --partial - Include partial matches (recipes where most ingredients are available)
--threshold <PERCENT> - Minimum percentage of ingredients that must be available for partial matches (default: 75)

Example:

$ cook pantry recipes --partial --threshold 50
Recipes You Can Make with Pantry Items:
========================================

✓ Complete Matches (all ingredients available):
  • Pasta Carbonara
  • Simple Salad

⚠ Partial Matches (50%+ ingredients available):
  • Pizza Margherita (80% available)
    Missing: fresh basil, mozzarella

Pantry Configuration

The pantry inventory is defined in pantry.conf (TOML format), which is searched for in:

./config/pantry.conf - Local to recipe directory
~/.config/cook/pantry.conf - Global configuration (Linux/macOS)

Configuration Format

[fridge]
milk = { quantity = &#34;500%ml&#34;, low = &#34;200%ml&#34;, expire = &#34;2025-09-20&#34; }
eggs = { quantity = &#34;12&#34;, low = &#34;6&#34;, bought = &#34;2025-09-10&#34;, expire = &#34;2025-09-25&#34; }
butter = &#34;250%g&#34;  # Simple format with just quantity

[pantry]
flour = { quantity = &#34;2%kg&#34;, low = &#34;500%g&#34; }
sugar = { quantity = &#34;1%kg&#34;, low = &#34;200%g&#34; }
olive oil = { quantity = &#34;750%ml&#34;, low = &#34;250%ml&#34; }

[spices]
oregano = { quantity = &#34;20%g&#34; }
basil = { quantity = &#34;15%g&#34;, low = &#34;5%g&#34; }

Item Attributes

Each pantry item can have the following optional attributes:

quantity - Current amount (e.g., "500%ml", "2%kg", "5")
low - Threshold for low stock warning (same format as quantity)
bought - Purchase date (e.g., "2025-09-10")
expire - Expiry date (e.g., "2025-09-25")

Low Stock Threshold

The low attribute defines when an item should be considered low on stock:

flour = { quantity = &#34;400%g&#34;, low = &#34;500%g&#34; }  # Low: 400 &lt; 500
sugar = { quantity = &#34;2%kg&#34;, low = &#34;1%kg&#34; }    # OK: 2 &gt; 1

Important: Comparisons only work when units match:

✅ 400%g vs 500%g (both grams)
✅ 2%kg vs 1%kg (both kilograms)
❌ 1%kg vs 500%g (different units - no comparison)

For items without units (counts), use plain numbers:

eggs = { quantity = &#34;6&#34;, low = &#34;12&#34; }

Integration with Other Commands

Shopping List

The pantry configuration works with the shopping list command to:

Filter out items already in stock
Show what needs restocking based on low thresholds

Recipe Command

Recipes can reference pantry items and the system will:

Check availability before cooking
Warn about low stock items used in recipes

Examples

Check Low Stock Items

# Show items that are low or out
cook pantry depleted

# Show all items including those with sufficient stock
cook pantry depleted --all

Monitor Expiring Items

# Check items expiring in the next week
cook pantry expiring

# Check items expiring in the next month
cook pantry expiring --days 30

# Include items without expiry dates
cook pantry expiring --include-unknown

Find Available Recipes

# Show only recipes with all ingredients available
cook pantry recipes

# Include recipes where you have most ingredients
cook pantry recipes --partial

# Show recipes with at least 60% of ingredients
cook pantry recipes --partial --threshold 60

Different Recipe Collections

# Check pantry for a different recipe collection
cook pantry -b ~/recipes depleted

# Use pantry in another directory
cook pantry --base-path ../other-recipes recipes

Output Formats

The pantry command supports multiple output formats for easy integration with other tools:

# Default human-readable format
cook pantry depleted

# JSON output for programmatic use
cook pantry -f json depleted

# YAML output
cook pantry -f yaml expiring --days 30

# Combine with other options
cook pantry -f json recipes --partial --threshold 60

JSON Output Example:

{
  &#34;items&#34;: [
    {
      &#34;name&#34;: &#34;flour&#34;,
      &#34;section&#34;: &#34;pantry&#34;,
      &#34;quantity&#34;: &#34;400%g&#34;,
      &#34;low_threshold&#34;: &#34;500%g&#34;,
      &#34;is_low&#34;: true
    },
    {
      &#34;name&#34;: &#34;eggs&#34;,
      &#34;section&#34;: &#34;fridge&#34;,
      &#34;quantity&#34;: &#34;6&#34;,
      &#34;low_threshold&#34;: &#34;12&#34;,
      &#34;is_low&#34;: true
    }
  ]
}

YAML Output Example:

items:
- name: milk
  section: fridge
  expire_date: &#34;2025-09-20&#34;
  days_until_expiry: 4
  status: &#34;expires in 4 days&#34;
- name: eggs
  section: fridge
  expire_date: &#34;2025-09-18&#34;
  days_until_expiry: 2
  status: &#34;expires in 2 days&#34;

Tips

Regular Updates: Keep your pantry.conf updated as you shop and use items
Set Realistic Thresholds: Set low values based on your shopping patterns
Use Sections: Organize items by storage location (fridge, freezer, pantry, etc.)
Track Expiry: Add expiry dates to perishables to reduce waste
Combine with Shopping: Use pantry depleted output to create shopping lists
Automate with JSON/YAML: Use -f json or -f yaml for scripting and automation
Integration: Parse JSON output in scripts to send notifications, generate reports, or update other systems

Overview

Options

Subcommands

depleted (alias: d)

expiring (alias: e)

recipes (alias: r)

Pantry Configuration

Configuration Format

Item Attributes

Low Stock Threshold

Integration with Other Commands

Shopping List

Recipe Command

Examples

Check Low Stock Items

Monitor Expiring Items

Find Available Recipes

Different Recipe Collections

Output Formats

Tips

`depleted` (alias: `d`)

`expiring` (alias: `e`)

`recipes` (alias: `r`)