clawhub

Tandoor Recipe CLI

Item: Tandoor Recipe CLI
Rating: 8.2
Author: Implexa

Manage recipes, meal plans, and shopping lists on a Tandoor Recipe Manager instance via CLI.

copies: implexa run clawhub/tandoor-cli

view source

installs

stars

karma

SkillRank score ↗

8.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

tandoor-cli exposes recipe, meal plan, shopping list, and household management operations on a tandoor instance via command-line, with explicit approval gates for mutations and destructive actions.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: tandoor-recipe-cli
description: Manage recipes, meal plans, and shopping lists on a Tandoor Recipe Manager instance via CLI.
version: 1.5.0
compatibility: ">=18"
license: MIT
metadata:
  author: dcenatiempo
  repository: https://github.com/dcenatiempo/tandoor-cli
---

## Tandoor CLI Skill

This skill provides AI agents with the ability to interact with a Tandoor Recipe Manager instance using the `tandoor-cli` command-line tool.

### Prerequisites

The `tandoor-cli` tool must be installed and configured.

**Version Compatibility:** This skill documentation corresponds to the version specified in the metadata above. Before using this skill:
1. Verify your installed CLI version: `tandoor -V`
2. Ensure the installed version matches the skill version to avoid unexpected behavior or missing commands
3. If versions don't match, reinstall the CLI tool following the setup instructions in `references/SETUP.md`

If `tandoor -V` produces no valid version, see the setup instructions in `references/SETUP.md`.

### Security & Permission Model

**⚠️ IMPORTANT: This skill provides mutation authority over your Tandoor instance.**

- **Read operations** (list, search, get, random) are safe and require no confirmation
- **Write operations** (add, update, import) modify data but are typically reversible
- **Destructive operations** (delete, clear, household management) require explicit user approval before execution
- **Bulk operations** (shopping check --all, clear) affect multiple items and require confirmation
- **Administrative operations** (household management, user assignment, invite creation) require privileged credentials and explicit approval

**Token Security:**
- Use the **least-privileged token** possible for your use case
- Prefer read-only tokens if you only need to query recipes
- Avoid using space-owner or admin tokens unless household management is required
- Consider short-lived tokens (days/weeks) instead of long-lived tokens (years)
- Store tokens securely and rotate them regularly
- Revoke tokens immediately if compromised or no longer needed

**Supply Chain:**
- This skill uses the `tandoor-cli` npm package
- Verify the package source before first use: https://www.npmjs.com/package/tandoor-cli
- Review the package repository: https://github.com/dcenatiempo/tandoor-cli
- **Recommended:** Pin to the specific version matching this skill (see version in metadata above) to avoid unexpected updates
- Install pinned version: `npm install -g tandoor-cli@<version>` (replace `<version>` with the skill version)

### Invocation

```bash
tandoor <command> [options]
```

### Output formats and deprecated flags

Commands that print data accept **`--format text|json|api`** (default: `text`):

| `--format` | Use for |
|------------|---------|
| `text` | Human-readable output (default) |
| `json` | Slim JSON where supported (recipe add/update shape + `id` on `get`, `list`, `search`, `random`) |
| `api` | Raw Tandoor API JSON |

**Deprecated (output):** `--json` with no file path — alias for **`--format api`**; stderr warning. Do not use in new agent workflows.

**Recommended (input):** `tandoor add --file recipe.json`, `tandoor update <id> --file patch.json`

**Deprecated (input):** `tandoor add --json <file>`, `tandoor update <id> --json <file>` — still work with stderr warning.

| Deprecated | Use instead |
|------------|-------------|
| `tandoor get 1 --json` | `--format api` (full) or `--format json` (slim, for edit round-trips) |
| `tandoor list --json` | `--format api` |
| `tandoor add --json recipe.json` | `--file recipe.json` |
| `tandoor update 42 --json patch.json` | `--file patch.json` |

### Commands

#### Read Operations (Safe)

**Recipes:**
| Command | Description |
|---|---|
| `list [--limit N] [--page N] [--all]` | List recipes (default 20 per page, max 100) |
| `search <query>` | Search recipes by keyword |
| `get <id>` | Get full recipe details |
| `random` | Get a random recipe |

**Meal Plans:**
| Command | Description |
|---|---|
| `mealplan list [--startdate DATE] [--enddate DATE]` | List meal plan entries (optionally filtered by date range) |

**Shopping List:**
| Command | Description |
|---|---|
| `shopping list` | List shopping list entries |

**Food Ingredients:**
| Command | Description |
|---|---|
| `food list [--limit N] [--page N] [--all] [--search TERM] [--ignored] [--onhand]` | List food ingredients |

**Grocery Categories:**
| Command | Description |
|---|---|
| `category list` | List all supermarket categories (sorted A-Z) |
| `category uncategorised [--search TERM]` | List food items with no category assigned |

**Cook Logs:**
| Command | Description |
|---|---|
| `cooklog list [--recipe ID] [--limit N] [--page N] [--all] [--startdate YYYY-MM-DD] [--enddate YYYY-MM-DD] [--min-rating 1-5] [--max-rating 1-5]` | List cook log entries (sorted by most recent first) |
| `cooklog ingredient <name> [--limit N] [--startdate YYYY-MM-DD] [--enddate YYYY-MM-DD] [--min-rating 1-5] [--max-rating 1-5]` | Find cook logs by ingredient name (e.g., "when did we last have eggs?") |

**Households & Users:**
| Command | Description |
|---|---|
| `household list` | List all households |
| `household get <id>` | Get household details by ID |
| `household users list` | List all users in the space |
| `household users memberships` | List user-space memberships |
| `household invite list` | List all invite links |

#### Write Operations (Require Confirmation)

| Command | Description | Approval Required |
|---|---|---|
| `add [--file file] [--interactive]` | Create a recipe (`--json <file>` deprecated) | ✓ Before execution |
| `update <id> --file file` | Patch an existing recipe (`--json <file>` deprecated) | ✓ Before execution |
| `import <url> [--dry-run]` | Import a recipe from a URL | ✓ Before execution |
| `image <recipeId> <imagePath>` | Upload an image to a recipe | ✓ Before execution |
| `mealplan add --recipe ID --date YYYY-MM-DD --meal-type N` | Add a meal plan entry | ✓ Before execution |
| `shopping add --food NAME --amount N --unit UNIT` | Add a shopping list item | ✓ Before execution |
| `shopping check <id>` | Mark a shopping item as checked | ✓ Before execution |
| `food edit <id\|name> --ignore-shopping <true\|false>` | Edit a food's ignore_shopping flag | ✓ Before execution |
| `food ignore <id\|name> [--unset]` | Set or clear ignore_shopping by ID or name | ✓ Before execution |
| `food onhand <id\|name> [--unset]` | Set or clear the on-hand flag by ID or name | ✓ Before execution |
| `category set <food-id\|name> --category <name\|id>` | Assign a grocery category to a food item | ✓ Before execution |
| `category set <food-id\|name> --unset` | Remove the category from a food item | ✓ Before execution |
| `cooklog add --recipe ID --servings N [--rating 1-5] [--comment TEXT] [--date ISO8601]` | Add a cook log entry | ✓ Before execution |
| `cooklog update <id> [--recipe ID] [--servings N] [--rating 1-5] [--comment TEXT] [--date ISO8601]` | Update a cook log entry | ✓ Before execution |

#### Destructive Operations (Require Explicit Confirmation)

| Command | Description | Approval Required |
|---|---|---|
| `delete <id> [--force]` | Delete a recipe | ✓✓ Explicit confirmation required |
| `mealplan delete <id>` | Delete a meal plan entry | ✓✓ Explicit confirmation required |
| `shopping clear [--force]` | Clear all checked items | ✓✓ Explicit confirmation (bulk operation) |
| `shopping check --all` | Mark all items as checked | ✓✓ Explicit confirmation (bulk operation) |
| `cooklog delete <id>` | Delete a cook log entry | ✓✓ Explicit confirmation required |

#### Administrative Operations (Require Privileged Token + Explicit Confirmation)

**Important:** Tandoor uses **households** to organize users and recipes. Users are added to households via **invite links** — you cannot create users directly via the API.

> **Permission Requirements:** Household management commands require special permissions in Tandoor. Most operations need admin/staff privileges. The `household invite create` command specifically requires **space owner** authentication — even superusers or staff members will receive a 403 Permission Denied error if they're not the space owner. If you encounter permission errors, you must use the space owner's API token or contact your Tandoor administrator.

| Command | Description | Approval Required |
|---|---|---|
| `household add <name>` | Create a new household | ✓✓ Admin token + explicit confirmation |
| `household edit <id> --name <name>` | Rename a household | ✓✓ Admin token + explicit confirmation |
| `household delete <id> [--force]` | Delete a household | ✓✓ Admin token + explicit confirmation |
| `household users assign <user-space-id> <household-id>` | Assign user to household | ✓✓ Admin token + explicit confirmation |
| `household invite create <household-id> [--email EMAIL] [--expires DATE] [--group-id ID]` | Create invite link | ✓✓ Space-owner token + explicit confirmation |
| `household invite delete <id> [--force]` | Delete invite link | ✓✓ Admin token + explicit confirmation |

Read commands accept **`--format json`** (slim, where supported) or **`--format api`** (raw). Deprecated: `--json` (same as `--format api`).

### Agent Behavior Rules

**Before executing any command, the agent MUST:**

1. **For read operations:** Proceed without confirmation
2. **For write operations:** Describe the action and wait for user approval
3. **For destructive operations:** 
   - Clearly explain what will be deleted/modified
   - Warn that the action cannot be easily reversed
   - Wait for explicit user confirmation (e.g., "yes, delete recipe 42")
4. **For bulk operations:**
   - State how many items will be affected
   - Wait for explicit confirmation
5. **For administrative operations:**
   - Verify the user has provided an admin/space-owner token
   - Explain the scope of the change (e.g., "this will move user X to household Y")
   - Wait for explicit confirmation

**The agent MUST NOT:**
- Execute delete, force, bulk, household, invite, or user-assignment commands without explicit user approval
- Assume the user wants destructive actions even if implied by context
- Use `--force` flags without explicit user instruction
- Log or display the `TANDOOR_API_TOKEN` value in any output

### Configuration

The CLI supports three configuration methods (in precedence order):

1. **Environment variables** — `TANDOOR_URL` and `TANDOOR_API_TOKEN` in the current shell
2. **Config file** — `~/.config/tandoor-cli/config.json` (created by `tandoor configure`)
3. **`.env` file** — a `.env` file in the current working directory

Run `tandoor configure` once to save credentials interactively.

### Examples

**Configure credentials:**
```bash
tandoor configure
```

**Read example — list recipes as JSON:**
```bash
tandoor list --limit 5 --format api
```

**Read example — get recipe for editing:**
```bash
tandoor get 42 --format json
```

**Write example — create a recipe from a JSON file:**
```bash
# Agent should first ask: "I will create a new recipe from recipe.json. Proceed?"
# Only after user confirms:
tandoor add --file recipe.json
```

### Recipe JSON Schema

When creating recipes with `tandoor add --file <file>` (or deprecated `--json <file>`), the JSON file must conform to the following structure:

**TypeScript Definition:**
```typescript
interface RecipeCreatePayload {
  name: string;                    // Required: Recipe name
  description?: string;            // Optional: Recipe description
  servings?: number;               // Optional: Number of servings
  working_time?: number;           // Optional: Active cooking time in minutes
  waiting_time?: number;           // Optional: Passive time (baking, marinating) in minutes
  steps: StepCreatePayload[];      // Required: At least one step
}

interface StepCreatePayload {
  instruction: string;             // Required: Step instructions
  order: number;                   // Required: Step order (1, 2, 3, ...)
  ingredients: IngredientCreatePayload[];  // Required: Can be empty array
}

interface IngredientCreatePayload {
  food: { name: string };          // Required: Ingredient name
  unit: { name: string } | null;   // Optional: Unit of measurement (null if not applicable)
  amount: number;                  // Required: Quantity
  note?: string;                   // Optional: Additional notes (e.g., "finely chopped")
  order?: number | null;           // Optional: Order within the step
}
```

**Example Recipe JSON:**
```json
{
  "name": "Scrambled Eggs",
  "description": "Quick and easy scrambled eggs",
  "servings": 2,
  "working_time": 5,
  "steps": [
    {
      "instruction": "Crack eggs into a bowl, add milk and salt. Whisk until well combined.",
      "order": 1,
      "ingredients": [
        {
          "food": { "name": "eggs" },
          "unit": { "name": "whole" },
          "amount": 4
        },
        {
          "food": { "name": "milk" },
          "unit": { "name": "tbsp" },
          "amount": 2
        },
        {
          "food": { "name": "salt" },
          "unit": null,
          "amount": 1,
          "note": "to taste"
        }
      ]
    },
    {
      "instruction": "Heat butter in a pan over medium heat. Pour in egg mixture and stir gently until cooked to desired consistency.",
      "order": 2,
      "ingredients": [
        {
          "food": { "name": "butter" },
          "unit": { "name": "tbsp" },
          "amount": 1
        }
      ]
    }
  ]
}
```

**Key Points for Agents:**
- `name` and `steps` are required fields
- Each step must have `instruction`, `order`, and `ingredients` (can be empty array)
- Each ingredient must have `food.name` and `amount`
- Use `null` for `unit` when no unit applies (e.g., "to taste", "pinch")
- Common units: `g`, `kg`, `ml`, `l`, `cup`, `tbsp`, `tsp`, `whole`, `pinch`
- Times are in minutes
- Steps should be ordered sequentially (1, 2, 3, ...)

**Destructive example — delete a recipe:**
```bash
# Agent should first ask: "This will permanently delete recipe 42. This cannot be undone. Confirm deletion?"
# Only after explicit user confirmation:
tandoor delete 42 --force
```

**Image example — upload an image to a recipe:**
```bash
# Agent should first ask: "I will upload my-recipe-photo.jpg to recipe 42. Proceed?"
# Only after user confirms:
tandoor image 42 ./my-recipe-photo.jpg
```

**Household example — create a household and generate an invite link:**
```bash
# Agent should first ask: "I will create a new household named 'My Family'. This requires admin privileges. Proceed?"
# Only after user confirms:
tandoor household add "My Family"

# Agent should first ask: "I will create an invite link for household 1. This requires space-owner token. Proceed?"
# Only after user confirms:
tandoor household invite create 1 --email user@example.com --expires 2026-12-31
```

**Shopping list example — add items and check them off:**
```bash
# Agent should first ask: "I will add flour (500g) to the shopping list. Proceed?"
# Only after user confirms:
tandoor shopping add --food flour --amount 500 --unit g

# Agent should first ask: "This will mark ALL shopping items as checked. Confirm?"
# Only after explicit confirmation:
tandoor shopping check --all
```

**Grocery category example — organise foods for a better shopping list:**
```bash
# Read example — see what categories exist:
tandoor category list

# Read example — find foods with no category yet:
tandoor category uncategorised
tandoor category uncategorised --search pasta

# Agent should first ask: "I will assign 'milk' to the Dairy category. Proceed?"
# Only after user confirms:
tandoor category set milk --category Dairy
tandoor category set "olive oil" --category Oils
tandoor category set 42 --category "Canned Goods"   # by food ID

# Agent should first ask: "I will remove the category from 'milk'. Proceed?"
# Only after user confirms:
tandoor category set milk --unset
```

**Cook log example — track when you cook a recipe:**
```bash
# Agent should first ask: "I will add a cook log entry for recipe 42 (4 servings, rating 5). Proceed?"
# Only after user confirms:
tandoor cooklog add --recipe 42 --servings 4 --rating 5
tandoor cooklog add --recipe 42 --servings 4 --rating 5 --comment "Kids loved it"

# Read example — list cook logs for a specific recipe:
tandoor cooklog list --recipe 42 --format api

# Read example — find when you last had eggs:
tandoor cooklog ingredient eggs

# Read example — count how many times you had chicken last month:
tandoor cooklog ingredient chicken --startdate 2026-04-01 --enddate 2026-04-30

# Read example — find highly-rated egg recipes (4-5 stars):
tandoor cooklog ingredient eggs --min-rating 4

# Read example — find poorly-rated recipes from last month (1-2 stars):
tandoor cooklog list --startdate 2026-04-01 --enddate 2026-04-30 --max-rating 2

# Agent should first ask: "I will update cook log 2 with a new comment. Proceed?"
# Only after user confirms:
tandoor cooklog update 2 --comment "Next time add more garlic"

# Agent should first ask: "This will delete cook log entry 2. Confirm?"
# Only after explicit confirmation:
tandoor cooklog delete 2
```

### Installation & Setup

**Before first use:**
1. Verify the npm package: https://www.npmjs.com/package/tandoor-cli
2. Review the source code: https://github.com/dcenatiempo/tandoor-cli
3. **Recommended:** Install the pinned version matching this skill: `npm install -g tandoor-cli@<version>` (see version in metadata above)
4. Generate a token with minimal required permissions (see SECURITY.md)
5. Consider using a test Tandoor instance first

### Reference

- See `references/SETUP.md` for detailed setup documentation including authentication configuration
- See `SECURITY.md` for comprehensive security guidelines and token management best practices

related skills

semantically similar in the cross-vendor index

clawhub

68% match

Plan2meal

Manage recipes and grocery lists from your Plan2Meal React Native app. Add recipes from URLs, search, view, and manage your grocery lists.

by @clawhub

don't have the plugin yet? install it then click "run inline in claude" again.

added explicit decision tree for approval workflows, edge cases for network/auth/rate limits, recipe json schema as contract, household management permission requirements, and deprecated flag handling to convert original reference doc into implexa-compliant procedural skill.

intent

this skill gives ai agents cli access to a tandoor recipe manager instance for querying and modifying recipes, meal plans, shopping lists, food inventories, cook logs, and household management. use it when you need to create, retrieve, update, or delete recipe data; track meal planning; manage household grocery shopping; or record cooking history. read operations are safe and fast. write operations are reversible. destructive operations (delete, bulk clear) require explicit user sign-off.

inputs

external connection: tandoor recipe manager api

base url: TANDOOR_URL env var or config file ~/.config/tandoor-cli/config.json
authentication: TANDOOR_API_TOKEN env var or config file
token scope: use least-privileged token for your use case. read-only tokens suffice for queries. write tokens needed for recipe/meal plan mutations. admin/space-owner tokens required for household and invite management only.
edge case: token expiry or revocation will fail silently; check TANDOOR_URL connectivity first if commands hang.

local cli tool

binary: tandoor command must be in $PATH
version: verify with tandoor -V and match to this skill version (1.5.0) to avoid command drift
installation: npm install -g tandoor-cli@1.5.0 (pinned, not @latest)
edge case: old cli versions may lack --format or --file flags; reinstall if commands fail with "unknown option"

optional configuration file

location: ~/.config/tandoor-cli/config.json (created by tandoor configure)
fallback precedence: env vars > config file > .env in current directory
if unconfigured: agent must request TANDOOR_URL and TANDOOR_API_TOKEN from user before proceeding

network assumptions

tandoor instance is reachable at the configured url
rate limits: tandoor api typically allows ~100 req/sec; bulk operations (list --all, shopping check --all) may hit limits on large datasets
timeouts: network requests may stall; use --limit instead of --all for large lists to avoid timeouts

procedure

setup (one-time)

verify tandoor cli is installed
- input: user has npm or system package manager
- run: tandoor -V
- output: version string (e.g., "1.5.0") or "command not found"
- decision: if not found, proceed to step 2. if version < 1.5.0, reinstall.
install tandoor-cli to global path
- input: npm is available
- run: npm install -g tandoor-cli@1.5.0
- output: success message or error (e.g., "permission denied")
- decision: if permission error, may need sudo or --prefix flag. document and ask user to resolve.
configure credentials
- input: user has tandoor instance url and api token
- run: tandoor configure (interactive) or set env vars directly
- output: config file written to ~/.config/tandoor-cli/config.json or env vars set
- decision: verify with tandoor list --limit 1 to confirm auth works.

read operations (queries, no approval needed)

step 1: list recipes

input: optional --limit N (default 20, max 100), --page N (default 1), --all (fetch all, watch for timeouts), --format json|api (default text)
run: tandoor list [--limit N] [--page N] [--all] [--format FORMAT]
output: recipe summaries in requested format (text, json, or api)
edge case: --all on >10k recipes may timeout; recommend --limit 100 --page 1 then page through

step 2: search recipes

input: query string (required)
run: tandoor search "<query>"
output: matching recipes
edge case: empty query returns no results; special chars may need escaping

step 3: get full recipe details

input: recipe id (required), --format json|api (default text)
run: tandoor get <id> [--format FORMAT]
output: full recipe data including steps, ingredients, times, metadata
edge case: nonexistent id returns 404; agent should handle gracefully

step 4: get random recipe

input: none
run: tandoor random [--format FORMAT]
output: one random recipe in requested format
edge case: empty recipe database returns error; harmless

step 5: list meal plan entries

input: optional --startdate YYYY-MM-DD, --enddate YYYY-MM-DD to filter by date range
run: tandoor mealplan list [--startdate DATE] [--enddate DATE]
output: meal plan entries sorted by date
edge case: if no entries in range, returns empty list

step 6: list shopping list

input: none
run: tandoor shopping list [--format FORMAT]
output: shopping items with food name, amount, unit, checked status
edge case: empty shopping list returns success with zero items

step 7: list food ingredients

input: optional --limit N (default 20, max 100), --page N, --all, --search TERM (substring match), --ignored (filter), --onhand (filter)
run: tandoor food list [--limit N] [--page N] [--all] [--search TERM] [--ignored] [--onhand] [--format FORMAT]
output: food inventory with names, ids, flags
edge case: combining --ignored and --onhand may return zero results; filters are AND not OR

step 8: list grocery categories

input: none
run: tandoor category list
output: all supermarket categories sorted a-z
edge case: custom tandoor instances may have empty or domain-specific categories

step 9: list uncategorised foods

input: optional --search TERM to filter by food name
run: tandoor category uncategorised [--search TERM]
output: foods with no category assigned
edge case: large instances may return 100+ items

step 10: list cook logs

input: optional --recipe ID (filter by recipe), --limit N (default 20), --page N, --all, --startdate YYYY-MM-DD, --enddate YYYY-MM-DD, --min-rating 1-5, --max-rating 1-5
run: tandoor cooklog list [--recipe ID] [--limit N] [--page N] [--all] [--startdate DATE] [--enddate DATE] [--min-rating N] [--max-rating N]
output: cook log entries sorted by most recent first, with recipe id, servings, rating, comment, date
edge case: no entries matching filters returns empty list

step 11: search cook logs by ingredient

input: ingredient name (required), optional --limit N, --startdate, --enddate, --min-rating, --max-rating
run: tandoor cooklog ingredient "<name>" [--limit N] [--startdate DATE] [--enddate DATE] [--min-rating N] [--max-rating N]
output: cook logs that used the ingredient (matches recipes in logs), useful for "when did we last eat eggs?"
edge case: ingredient name is substring matched; misspelling may return zero results

step 12: list households

input: none
run: tandoor household list
output: all households in the tandoor instance
edge case: single-household instances return one result

step 13: get household details

input: household id (required)
run: tandoor household get <id>
output: household name, id, member count, recipe count
edge case: nonexistent id returns 404

step 14: list users

input: none
run: tandoor household users list
output: all users in the tandoor instance across all households
edge case: no users returns empty list

step 15: list user memberships

input: none
run: tandoor household users memberships
output: user-household membership mappings
edge case: user with no household assignment shows null or skipped

step 16: list invite links

input: none
run: tandoor household invite list
output: all active invite links with expiry dates and email targets
edge case: expired invites remain in list; filter by expiry date if needed

write operations (mutations, require approval before execution)

step 1: create recipe from json

input: user approval (required), recipe json file path (required), see recipe json schema below
run: tandoor add --file <path> after approval
output: new recipe id and confirmation message
edge case: duplicate recipe name does not error; tandoor allows duplicates

step 2: update recipe

input: user approval (required), recipe id (required), json file with patch (required, must conform to recipe schema), only fields to change needed
run: tandoor update <id> --file <path> after approval
output: updated recipe confirmation and id
edge case: nonexistent id returns 404; partial updates allowed

step 3: import recipe from url

input: user approval (required), source url (required), optional --dry-run to preview without persisting
run: tandoor import <url> [--dry-run] after approval
output: new recipe id or dry-run preview
edge case: invalid url, timeout, or unsupported recipe format returns error; common sources: allrecipes.com, foodnetwork.com, etc.

step 4: upload recipe image

input: user approval (required), recipe id (required), image file path (required)
run: tandoor image <recipe-id> <path> after approval
output: success confirmation
edge case: unsupported image format, file not found, or file too large (>10mb) returns error

step 5: add meal plan entry

input: user approval (required), recipe id (required), date in yyyy-mm-dd (required), meal type 1-4 (1=breakfast, 2=lunch, 3=dinner, 4=snack)
run: tandoor mealplan add --recipe <id> --date <date> --meal-type <n> after approval
output: new meal plan entry id
edge case: duplicate recipe on same date is allowed; conflicts are user's responsibility

step 6: add shopping list item

input: user approval (required), food name (required), amount as number (required), unit (required, e.g. "g", "ml", "whole", null for unitless)
run: tandoor shopping add --food "<name>" --amount <n> --unit "<unit>" after approval
output: new shopping item id
edge case: food name created if not found; units are flexible but consistency helps

step 7: mark shopping item checked

input: user approval (required), shopping item id (required)
run: tandoor shopping check <id> after approval
output: confirmation (item marked checked but not deleted)
edge case: already checked items can be checked again (idempotent)

step 8: edit food ignore-shopping flag

input: user approval (required), food id or name (required), true or false (required)
run: tandoor food edit <id|name> --ignore-shopping <true|false> after approval
output: confirmation
edge case: setting to current value is harmless

step 9: toggle food ignore-shopping flag

input: user approval (required), food id or name (required), optional --unset to clear
run: tandoor food ignore <id|name> [--unset] after approval
output: flag set or cleared
edge case: --unset clears the flag; without it, sets to true

step 10: toggle food on-hand flag

input: user approval (required), food id or name (required), optional --unset to clear
run: tandoor food onhand <id|name> [--unset] after approval
output: flag set or cleared
edge case: tracks inventory of items you have available

step 11: assign grocery category to food

input: user approval (required), food id or name (required), category name or id (required)
run: tandoor category set <id|name> --category <name|id> after approval
output: confirmation
edge case: overrides existing category if present; use --unset to remove

step 12: remove food category assignment

input: user approval (required), food id or name (required)
run: tandoor category set <id|name> --unset after approval
output: confirmation
edge case: harmless if no category was assigned

step 13: add cook log entry

input: user approval (required), recipe id (required), servings as number (required), optional rating 1-5, optional comment string, optional date in iso8601
run: tandoor cooklog add --recipe <id> --servings <n> [--rating <n>] [--comment "<text>"] [--date <iso8601>] after approval
output: new cook log entry id
edge case: missing date defaults to today; rating and comment are optional

step 14: update cook log entry

input: user approval (required), cook log entry id (required), optional recipe id, servings, rating, comment, or date (only changed fields needed)
run: tandoor cooklog update <id> [--recipe ID] [--servings N] [--rating N] [--comment "<text>"] [--date <iso8601>] after approval
output: confirmation
edge case: partial updates allowed; omitted fields unchanged

destructive operations (require explicit confirmation)

step 1: delete recipe

input: explicit user confirmation (required, e.g. "yes, delete recipe 42"), recipe id (required), optional --force (suppresses prompt)
run: tandoor delete <id> --force after explicit confirmation
output: success message or error
edge case: recipe with meals in future meal plans can still be deleted; orphans remain in meal plan. this is permanent.

step 2: delete meal plan entry

input: explicit user confirmation (required), meal plan entry id (required), optional --force
run: tandoor mealplan delete <id> --force after explicit confirmation
output: confirmation
edge case: meals on past dates can be deleted; deletes user's history record

step 3: clear checked shopping items (bulk)

input: explicit user confirmation (required, "yes, clear all checked items"), optional --force
run: tandoor shopping clear --force after explicit confirmation
output: count of cleared items
edge case: clears only items marked checked; unchecked items remain. count output helps user verify scope.

step 4: mark all shopping items checked (bulk)

input: explicit user confirmation (required, "yes, check all items"), optional --force
run: tandoor shopping check --all --force after explicit confirmation
output: count of checked items
edge case: this does not delete items, only marks them checked. reversible by unchecking (no uncheck command exists yet; user must do via web ui or individual check/uncheck if available).

step 5: delete cook log entry

input: explicit user confirmation (required), cook log entry id (required), optional --force
run: tandoor cooklog delete <id> --force after explicit confirmation
output: confirmation
edge case: removes history record; permanent.

administrative operations (require admin/space-owner token + explicit confirmation)

step 1: create household

input: explicit user confirmation (required), household name (required), admin or space-owner api token in TANDOOR_API_TOKEN
run: tandoor household add "<name>" after explicit confirmation
output: new household id
edge case: requires admin privileges; verify token has is_staff or is_superuser before attempting. permission error returns 403.

step 2: rename household

input: explicit user confirmation (required), household id (required), new name (required), admin token
run: tandoor household edit <id> --name "<name>" after explicit confirmation
output: confirmation
edge case: requires admin token; 403 if insufficient privileges

step 3: delete household

input: explicit user confirmation (required, "yes, delete household X and all its recipes"), household id (required), optional --force, admin token
run: tandoor household delete <id> --force after explicit confirmation
output: confirmation
edge case: deletes household and all recipes within it; permanent and affects all users in that household. extremely destructive.

step 4: assign user to household

input: explicit user confirmation (required), user-space id (required), target household id (required), admin token
run: tandoor household users assign <user-space-id> <household-id> after explicit confirmation
output: confirmation
edge case: requires admin token; user must exist in tandoor already (created via invite link, not api). 403 if insufficient privileges.

step 5: create invite link

input: explicit user confirmation (required), household id (required), optional email target, optional expiry date, optional group id, space-owner api token (required)
run: tandoor household invite create <household-id> [--email <email>] [--expires <date>] [--group-id <id>] after explicit confirmation
output: invite link (url and/or token)
edge case: requires space-owner token, not admin. staff and superusers without space ownership will get 403. expiry date format varies; iso8601 recommended.

step 6: delete invite link

input: explicit user confirmation (required), invite link id (required), optional --force, admin token
run: tandoor household invite delete <id> --force after explicit confirmation
output: confirmation
edge case: revokes the invite; active users from that invite are unaffected

decision points

is user requesting a read operation (list, search, get, random, mealplan list, shopping list, food list, category list, cooklog list)?

if yes: execute immediately without asking for approval. read operations do not modify data.
if no: proceed to next decision.

is user requesting a write operation (add, update, import, image, mealplan add, shopping add, shopping check, food edit, food ignore, food onhand, category set, cooklog add, cooklog update)?

if yes: describe the action in plain language, state the record(s) affected, and wait for user approval (e.g. "i will create a recipe from my-recipe.json. proceed?"). do not use --force. only execute after user says "yes" or similar affirmative.
if no: proceed to next decision.

is user requesting a destructive operation (delete, mealplan delete, shopping clear, shopping check --all, cooklog delete)?

if yes: explicitly state what will be deleted, warn that it is permanent and cannot be easily reversed, and demand explicit confirmation from user (e.g. "this will permanently delete recipe 42. this cannot be undone. confirm deletion?"). do not execute without a clear "yes" or equivalent. use --force flag to suppress prompts.
if no: proceed to next decision.

is user requesting a bulk operation (shopping clear, shopping check --all)?

if yes: state how many items will be affected (if known) and wait for explicit confirmation. (if count unknown, estimate based on last shopping list output.) these affect multiple records at once.
if no: proceed to next decision.

is user requesting an administrative operation (household add, household edit, household delete, household users assign, household invite create, household invite delete)?

if yes: verify that user has provided an admin or space-owner api token (check $TANDOOR_API_TOKEN env var or config file). if token scope is unclear, ask user to confirm. describe the scope of change (e.g. "this will move user alice to household family-recipes"). wait for explicit confirmation. execute after approval.
if no: operation is valid. proceed to execution.

has user provided an api token and is it accessible?

if yes: proceed with command execution.
if no: ask user to set TANDOOR_URL and TANDOOR_API_TOKEN env vars or run tandoor configure before retry.

did the command return a 401 or 403 error?

if 401: token is invalid or expired. ask user to regenerate token and reconfigure.
if 403: user lacks permission for this operation (common on household invite create without space-owner token). ask user to check token privileges and retry with appropriate token.
if neither: other errors may be transient (network, rate limit) or indicate user input error (invalid id, malformed json). report error to user and suggest retry or input correction.

is user trying to use deprecated flags like --json without --file or --format?

if yes: output a deprecation warning to stderr (as tandoor-cli does) and execute the command (still works). inform user to migrate to --format json|api or --file for future compatibility.
if no: proceed.

output contract

read operations output:

default format: human-readable text table or list
--format json: slim json (recipe id, name, servings; minimal fields for edit round-trips)
--format api: raw tandoor api json (complete, verbose)
location: stdout, one record per line or json object(s)
edge case: empty result sets return valid output (empty table, empty array [], empty object {}) and exit code 0

write operations output:

success: stdout prints new record id and confirmation message (e.g. "recipe 42 created")
error: stderr prints error message with http status if applicable; exit code nonzero
location: stdout for success, stderr for errors

destructive operations output:

success: stdout prints confirmation and count of deleted records (e.g. "3 shopping items cleared")
error: stderr prints error and exits with nonzero code
no partial deletes: either all succeed or operation fails; tandoor api is transactional per-record

administrative operations output:

success: stdout prints new resource id or confirmation (e.g. "household 5 created")
permission error: stderr prints "403 permission denied" or similar; may mention required token scope
other errors: follow standard error reporting

json schema for recipe create/update (input):

interface RecipeCreatePayload {
  name: string;                    // required
  description?: string;            // optional
  servings?: number;               // optional, integer
  working_time?: number;           // optional, minutes
  waiting_time?: number;           // optional, minutes
  steps: StepCreatePayload[];      // required, array of at least 1
}

interface StepCreatePayload {
  instruction: string;             // required, step text
  order: number;                   // required, integer (1, 2, 3...)
  ingredients: IngredientCreatePayload[]; // required, can be empty
}

interface IngredientCreatePayload {
  food: { name: string };          // required, ingredient name string
  unit: { name: string } | null;   // optional, null if unitless (e.g. "to taste")
  amount: number;                  // required, quantity
  note?: string;                   // optional, "finely chopped" etc.
  order?: number | null;           // optional, sequence within step
}

common units (case-sensitive): g, kg, mg, ml, l, dl, cl, cup, tbsp, tsp, whole, pinch, dash, oz, lb, fl oz

file location for json input: user provides path, agent reads and validates before sending to cli. agent should verify file exists and is valid json before invoking tandoor command.

outcome signal

user knows skill worked when:

read operations succeed: agent returns data in requested format (table, json, or api dump). agent confirms "found N recipes", "shopping list has M items", etc. if no data, agent reports "no results matching your query" (not an error).
write operations succeed: agent outputs new record id (e.g. "recipe 42 created", "meal plan entry 7 added") and user can verify via a follow-up read (e.g. tandoor get 42).
destructive operations succeed: agent outputs count of deleted records and summarizes what was removed (e.g. "deleted recipe 42 permanently"). user should verify via read operation (e.g. tandoor get 42 returns 404).
administrative operations succeed: new household/invite created, user assigned, etc. agent confirms resource id. user can verify via tandoor household list or tandoor household invite list.
approval workflow respected: before any write or destructive operation, agent describes the action and waits for user's explicit "yes" or affirmative. agent never auto-executes mutations.
error handling transparent: if a command fails, agent reports the error message (http status, validation failure, permission denial, etc.) to user and suggests remediation (retry, check credentials, fix json format, etc.).
token security maintained: agent never logs, prints, or echoes the TANDOOR_API_TOKEN value. agent only outputs errors/ids/data, not secrets.
version consistency: if cli version differs from skill version (1.5.0), agent warns user to reinstall (npm install -g tandoor-cli@1.5.0) before proceeding, avoiding command drift.