Pantry

Manage and analyze your pantry inventory. Supports full CRUD operations on pantry items as well as analysis commands for stock levels, expiry dates, and recipe planning.

Usage

cook pantry [OPTIONS] <COMMAND>

Options

OptionDescription
-b, --base-path <PATH>Base path for recipes and configuration files
-f, --format <FORMAT>Output format: human (default), json, yaml

Subcommands

list (alias: ls)

Display all pantry items organized by section.

cook pantry list [OPTIONS]
OptionDescription
--section <NAME>Only show items from this section
cook pantry list                     # All sections
cook pantry list --section dairy     # Only the dairy section
cook pantry -f json list             # JSON output

add (alias: a)

Add a new item to the pantry. Creates the pantry file and the section if they do not exist yet.

cook pantry add &lt;SECTION&gt; &lt;NAME&gt; [OPTIONS]
OptionDescription
--quantity <VALUE>Quantity on hand (e.g. 2%kg, 500%ml, 12)
--low <VALUE>Low-stock threshold (e.g. 200%g)
--expire <DATE>Expiry date (e.g. 2025-06-01)
--bought <DATE>Purchase date
cook pantry add pantry flour                                    # Simple item
cook pantry add dairy milk --quantity &#34;2%l&#34; --low &#34;500%ml&#34;      # With attributes
cook pantry add dairy yogurt --quantity &#34;500%g&#34; --expire 2025-06-01

remove (alias: rm)

Remove an item from a section. If the section becomes empty it is deleted from the file too.

cook pantry remove &lt;SECTION&gt; &lt;NAME&gt;
cook pantry remove dairy milk
cook pantry rm pantry flour

update (alias: up)

Update one or more attributes of an existing pantry item. Only the flags you provide are changed; everything else is kept as-is.

cook pantry update &lt;SECTION&gt; &lt;NAME&gt; [OPTIONS]
OptionDescription
--quantity <VALUE>New quantity
--low <VALUE>New low-stock threshold
--expire <DATE>New expiry date
--bought <DATE>New purchase date
cook pantry update dairy milk --quantity &#34;1%l&#34;
cook pantry update dairy milk --expire 2025-06-15 --low &#34;500%ml&#34;
cook pantry up pantry flour --quantity &#34;2%kg&#34;

depleted (alias: d)

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

cook pantry depleted [OPTIONS]
OptionDescription
--allShow all items including those without quantities

Items are flagged when current quantity is at or below the low threshold. Without a low threshold, heuristics are used.

expiring (alias: e)

Show items that are expiring soon.

cook pantry expiring [OPTIONS]
OptionDescription
-d, --days <DAYS>Number of days to look ahead (default: 7)
--include-unknownInclude items without expiry dates

recipes (alias: r)

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

cook pantry recipes [OPTIONS]
OptionDescription
-p, --partialInclude partial matches (most ingredients available)
--threshold <PERCENT>Minimum percentage of ingredients for partial matches (default: 75)

plan (alias: pl)

Analyze ingredient usage across recipes to help plan pantry items.

cook pantry plan [OPTIONS]
OptionDescription
-n, --max-ingredients <N>Maximum number of ingredients to show (default: all needed for 100% coverage)
-s, --skip <N>Skip the first N ingredients (default: 0)
-m, --allow-missing <N>Allow recipes to be considered cookable even if N ingredients are missing (default: 0)

Configuration

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

  1. ./config/pantry.conf — local to recipe directory
  2. ~/.config/cook/pantry.conf — global configuration

When you run cook pantry add and no pantry file exists, one is created at ./config/pantry.conf automatically.

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;

[pantry]
flour = { quantity = &#34;2%kg&#34;, low = &#34;500%g&#34; }
salt = &#34;1%kg&#34;

Item attributes: quantity, low (threshold), bought (date), expire (date). Simple format (item = "quantity") is also supported.

Examples

# List everything in the pantry
cook pantry list

# Add a new item
cook pantry add dairy milk --quantity &#34;2%l&#34; --low &#34;500%ml&#34;

# Update quantity after shopping
cook pantry update dairy milk --quantity &#34;3%l&#34;

# Remove an item
cook pantry remove dairy milk

# Show low/out-of-stock items
cook pantry depleted

# Items expiring in the next 14 days
cook pantry expiring --days 14

# Recipes you can fully make
cook pantry recipes

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

# Plan pantry stocking
cook pantry plan

# JSON output
cook pantry -f json list
cook pantry -f json depleted

Notes

  • Unit comparisons only work when units match (e.g., g vs g, not kg vs g)
  • For items without units, use plain numbers (e.g., eggs = { quantity = "6", low = "2" })
  • pantry update merges new values over existing attributes — omitted flags are left unchanged