Grocery Tracker

Always use --json flag for programmatic consumption.

Full command reference: See references/cli-commands.md for all options and response formats.

Receipt Processing Workflow

When user uploads a receipt image:

1. Extract data with vision - Parse store, date, items, prices
2. Format as JSON:

{
  "store_name": "Giant Food",
  "transaction_date": "2026-01-25",
  "line_items": [
    {"item_name": "Bananas", "quantity": 3, "unit_price": 0.49, "total_price": 1.47}
  ],
  "total": 1.47
}

3. Call CLI: grocery receipt process --data '<json>' --json
4. Present results:

Matched from your list: Bananas, Milk
Still need: Eggs, Bread

Extraction guidelines:

• Normalize item names (proper capitalization)
• Remove store-specific codes/SKUs
• Infer quantities when not explicit
• Use null for missing optional fields

Adding Items

Parse natural language like "Add 3 bananas from Giant" into:

grocery add "bananas" --quantity 3 --store Giant --json

Handle duplicates: If DUPLICATE_ITEM error, ask user:

1. Increase quantity
2. Add separate entry (use --force)
3. Keep existing

If store not specified, prompt user with store options.

Viewing Lists

grocery list --json

Format output for the chat platform:

Telegram (markdown):

# Grocery List

## Giant Food
### Produce
- **Bananas** (3)
- **Avocados** (2)

Signal (plain):

GROCERY LIST

GIANT FOOD
Produce:
- Bananas (3)
- Avocados (2)

Group by: Store > Category > Aisle (if available)

Analytics Workflows

Spending Summary

grocery stats --period monthly --json

Present: Total spent, budget remaining, category breakdown.

Purchase Frequency

grocery stats frequency "milk" --json

Present: "You buy milk every ~5 days. Last: 6 days ago. Consider adding to list."

Price Comparison

grocery stats compare "milk" --json

Present: Prices by store, cheapest option, potential savings.

Smart Suggestions

grocery stats suggest --json

Present proactively when appropriate:

• Restock reminders based on purchase patterns
• Price alerts for increases
• Out-of-stock warnings

Inventory Management

Track household inventory with expiration dates:

# Add to inventory
grocery inventory add "milk" --location fridge --expires 2026-01-28 --threshold 1 --json

# Check expiring items
grocery inventory expiring --days 3 --json

# Check low stock
grocery inventory low-stock --json

# Use items
grocery inventory use <id> --quantity 1 --json

Locations: pantry, fridge, freezer

Present expiring items as alerts: "Milk expires in 3 days (Jan 28)"

Waste Tracking

Log and analyze food waste:

grocery waste log "lettuce" --reason spoiled --cost 3.99 --json
grocery waste summary --period monthly --json

Reasons: spoiled, never_used, overripe, other

Present insights: "Lettuce spoils frequently - consider buying smaller quantities"

Budget Management

grocery budget set 500 --month 2026-01 --json
grocery budget status --json

Present: Budget, spent, remaining, percentage, on-track status.

User Preferences

Store brand preferences, dietary restrictions, and allergens:

grocery preferences view "Alice" --json
grocery preferences set "Alice" --brand "milk:Organic Valley" --dietary vegetarian --json

Incorporate in responses: "Note: Alice prefers Organic Valley milk"

Multi-User Context

Alice and Bob share the list:

• Different brand preferences (Alice: Organic Valley, Bob: Horizon)
• Dietary restrictions (Bob is vegetarian)
• Shopping patterns (Alice: Tue/Sat, Bob: Wed/Sun)

Output Best Practices

1. Always use --json for CLI calls
2. Parse JSON before presenting to user
3. Format naturally - no raw JSON shown to users
4. Use emoji sparingly - Only for success/warning indicators
5. Keep concise - users are on mobile
6. Group items - by store, category, or status

Error Handling

For low-confidence receipt extraction, present items with confidence and ask for corrections.