⚡ CLI Documentation

# Install globally to use from anywhere
npm install -g avocavo

# Verify installation
avocavo --version

# Use without installing
npx avocavo --help

# Example usage
npx avocavo ingredient "1 cup rice"

# Login with Google OAuth (opens browser)
avocavo login

# Check login status
avocavo status

# Now analyze ingredients without API keys!
avocavo ingredient "1 cup chicken breast"

# Analyze a single ingredient
avocavo ingredient "2 tbsp olive oil"

# Analyze a complete recipe
avocavo recipe -i "2 cups flour" "1 cup milk" "2 eggs" -s 8

# Batch process multiple ingredients (Starter+ plans)
avocavo batch -i "1 cup rice" "4 oz salmon" "1 cup broccoli"

# Check API health
avocavo health

# Analyze a single ingredient
avocavo ingredient "1 cup chicken breast"

# Output:
✅ 1 cup chicken breast
  🔥 Calories: 231.0
  🥩 Protein: 43.5g
  🧈 Fat: 5.0g
  🌾 Carbs: 0.0g
  🌿 Fiber: 0.0g
  🧂 Sodium: 104.0mg
🔗 USDA: Chicken, broilers or fryers, breast, meat only, cooked, roasted (ID: 171077)

# Include USDA verification URL
avocavo ingredient "100g salmon" --verify

# Output includes verification link:
✅ 100g salmon
  🔥 Calories: 208.0
  🥩 Protein: 25.4g
  🧈 Fat: 12.4g
  🌾 Carbs: 0.0g
🔗 USDA: Salmon, Atlantic, farmed, cooked, dry heat (ID: 175167)
🔍 Verify: https://fdc.nal.usda.gov/fdc-app.html#/food-details/175167/nutrients

# Get JSON output for scripting
avocavo ingredient "1 cup rice" --json

# Output:
{
  "success": true,
  "ingredient": "1 cup rice",
  "nutrition": {
    "calories": 205,
    "protein": 4.3,
    "carbs": 44.5,
    "fat": 0.4,
    "fiber": 0.6,
    "sodium": 1.0
  },
  "usda_match": {
    "fdc_id": 168880,
    "description": "Rice, white, long-grain, regular, cooked",
    "data_type": "SR Legacy"
  },
  "verification_url": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/168880/nutrients",
  "from_cache": true,
  "processing_time_ms": 23.4,
}

# Natural language parsing handles complex descriptions!
avocavo ingredient "1 handful of baby spinach"
avocavo ingredient "a splash of vanilla extract"
avocavo ingredient "1 very small pinch of salt"
avocavo ingredient "2 medium bananas, ripe"
avocavo ingredient "a drizzle of extra virgin olive oil"
avocavo ingredient "1 generous dollop of Greek yogurt"

# All of these work with intelligent parsing:
✅ 1 handful of baby spinach: 7 calories, 0.9g protein
✅ a splash of vanilla extract: 6 calories, 0.0g protein
✅ 1 very small pinch of salt: 0 calories, 117mg sodium
✅ 2 medium bananas, ripe: 210 calories, 2.6g protein
✅ a drizzle of extra virgin olive oil: 40 calories, 4.5g fat
✅ 1 generous dollop of Greek yogurt: 30 calories, 5.5g protein

# Analyze recipe with ingredients and servings
avocavo recipe -i "2 cups flour" "1 cup milk" "2 eggs" -s 8

# Output:
🍳 Analyzing recipe with 3 ingredients (8 servings)...
✅ Recipe analysis complete!

📊 Total Nutrition:
  🔥 Calories: 1247.0
  🥩 Protein: 45.2g
  🧈 Fat: 18.4g
  🌾 Carbs: 220.8g
  🌿 Fiber: 7.2g
  🧂 Sodium: 287.0mg

🍽️  Per Serving (8 servings):
  🔥 Calories: 155.9
  🥩 Protein: 5.7g
  🧈 Fat: 2.3g
  🌾 Carbs: 27.6g
  🌿 Fiber: 0.9g
  🧂 Sodium: 35.9mg

📋 Ingredient Breakdown:
┌────────┬─────────────┬──────────┬─────────┬─────┬───────┐
│ Status │ Ingredient  │ Calories │ Protein │ Fat │ Carbs │
├────────┼─────────────┼──────────┼─────────┼─────┼───────┤
│ ✅     │ 2 cups flour│ 910      │ 25.4g   │ 2.4g│ 190g  │
│ ✅     │ 1 cup milk  │ 149      │ 7.7g    │ 8.0g│ 12g   │
│ ✅     │ 2 eggs      │ 155      │ 12.6g   │ 10.6g│ 1.1g  │
└────────┴─────────────┴──────────┴─────────┴─────┴───────┘
🎯 USDA matches: 3/3

# Start interactive recipe builder
avocavo recipe

# Interactive prompts:
? Enter recipe ingredients (one per line, press Enter twice when done):
1 cup brown rice
4 oz grilled chicken
1 tbsp olive oil
1 cup steamed broccoli

? Number of servings: 2

🍳 Analyzing recipe with 4 ingredients (2 servings)...
✅ Recipe analysis complete!

📊 Total Nutrition:
  🔥 Calories: 756.0
  🥩 Protein: 35.8g
  ...

# Create a recipe file (recipe.txt):
2 cups whole wheat flour
1 cup Greek yogurt
2 large eggs
1/4 cup honey
1 tsp vanilla extract
1 tsp baking soda

# Analyze from file
avocavo recipe -f recipe.txt -s 12

# Perfect for saved recipes or meal prep!

# Real-world recipe with complex mixed ingredient formats
avocavo recipe -i \
  "2 cups all-purpose flour" \
  "3 large eggs, room temperature" \
  "1 generous cup whole milk" \
  "a pinch of salt" \
  "2 tbsp melted butter" \
  "a splash of vanilla extract" \
  "1 handful of fresh blueberries" \
  -s 6

# Output shows perfect parsing of ALL ingredient types:
🍳 Analyzing recipe with 7 ingredients (6 servings)...
✅ Recipe analysis complete!

📊 Total Nutrition:
  🔥 Calories: 1,847.0
  🥩 Protein: 67.8g
  🧈 Fat: 45.2g
  🌾 Carbs: 278.4g

📋 Ingredient Breakdown:
┌────────┬─────────────────────────────┬──────────┬─────────┐
│ Status │ Ingredient                  │ Calories │ Protein │
├────────┼─────────────────────────────┼──────────┼─────────┤
│ ✅     │ 2 cups all-purpose flour    │ 910      │ 25.4g   │
│ ✅     │ 3 large eggs, room temp     │ 210      │ 18.0g   │
│ ✅     │ 1 generous cup whole milk   │ 160      │ 8.5g    │
│ ✅     │ a pinch of salt             │ 0        │ 0.0g    │
│ ✅     │ 2 tbsp melted butter        │ 204      │ 0.2g    │
│ ✅     │ a splash of vanilla extract │ 6        │ 0.0g    │
│ ✅     │ 1 handful fresh blueberries │ 21       │ 0.3g    │
└────────┴─────────────────────────────┴──────────┴─────────┘

🎯 USDA matches: 7/7 - Even complex natural language parsed perfectly!

# Get detailed JSON response with full parsing breakdown
avocavo ingredient "1 handful of baby spinach" --json

{
  "success": true,
  "ingredient": "1 handful of baby spinach",      // ← Original input
  "nutrition": {
    "calories": 7,
    "protein": 0.9,
    "total_fat": 0.1,
    "carbohydrates": 1.1,
    "fiber": 0.7,
    "sodium": 24
  },
  "parsing": {
    "quantity": 1,                               // ← Extracted number
    "unit": "handful",                           // ← Recognized unit type
    "ingredient_name": "baby spinach",           // ← Clean ingredient name
    "estimated_grams": 30                        // ← Converted to grams
  },
  "metadata": {
    "method_used": "gpt_normalized",             // ← How we found the answer
    "parsing_method": "gpt_processing",         // ← Which parsing method used
    "processing_time_ms": 23.4,                 // ← How fast we processed it
    "cached": false,                             // ← Was result cached?
    "usda_match": {
      "fdc_id": 168462,                          // ← USDA Food Database ID
      "description": "Spinach, baby, raw",       // ← Official USDA description
      "data_type": "sr_legacy_food",             // ← USDA data source type
      "verification_url": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/168462/nutrients"
    }
  }
}

# See exactly how different ingredients are parsed:

# TIER 1: Direct SQL Match (fastest)
avocavo ingredient "1 cup rice" --json
# → method_used: "sql_exact"
# → portion_source: "tier_1_exact"

# Fuzzy Match (spelling variations)
avocavo ingredient "1 cup ryce" --json
# → method_used: "fuzzy_match_90%"
# → confidence: "90%"

# GPT-Powered Ingredient Normalization
avocavo ingredient "1 large apple" --json  
# → method_used: "gpt_normalized"
# → parsing_method: "gpt_processing"

# Complex Ingredient Processing
avocavo ingredient "1 very small pinch of salt" --json
# → method_used: "gpt_normalized"
# → parsing_method: "gpt_processing"

# Cache-Based Processing
avocavo ingredient "a splash of vanilla extract" --json
# → method_used: "redis_cache"
# → portion_source: "tier_5_generic"

# TIER 6: Small Measurement Handling
avocavo ingredient "a dash of cinnamon" --json
# → method_used: "small_measurement"
# → portion_source: "tier_6_small_measurement"

# TIER 7: Smart USDA Matching
avocavo ingredient "about 2 heaping tablespoons of chunky peanut butter" --json
# → method_used: "llm_driven_search"
# → portion_source: "tier_7_semantic_match"

# Analyze multiple ingredients efficiently
avocavo batch -i "1 cup rice" "2 tbsp oil" "4 oz salmon"

# Output:
⚡ Batch analyzing 3 ingredients...
✅ Batch analysis complete!

📋 Results:
✅ 1 cup rice: 205 cal, 4.3g protein
✅ 2 tbsp oil: 240 cal, 0.0g protein  
✅ 4 oz salmon: 208 cal, 25.4g protein

📊 Totals:
  🔥 Total Calories: 653
  🥩 Total Protein: 29.7g
  🧈 Total Fat: 27.4g
  🌾 Total Carbs: 44.5g

🎯 Success rate: 100%
⏱️  Total time: 156ms

# Create shopping list (shopping-list.txt):
2 lbs ground beef
1 dozen eggs
1 gallon milk
2 lbs chicken breast
1 bag brown rice
2 lbs bananas
1 lb spinach
1 lb carrots

# Batch analyze from file
avocavo batch -f shopping-list.txt

# Perfect for meal prep planning!

# Get JSON output for further processing
avocavo batch -f ingredients.txt --json > nutrition-data.json

# Use with jq for filtering
avocavo batch -i "1 cup oats" "1 banana" "1 tbsp honey" --json | jq '.results[].nutrition.calories'

# Output:
307
105
64

# Create ingredients.txt
1 cup brown rice
2 tablespoons olive oil
4 oz grilled chicken breast
1 cup steamed broccoli
1/4 cup almonds

# Use with any command
avocavo recipe -f ingredients.txt -s 2
avocavo batch -f ingredients.txt

# meal-prep.txt - Comments are ignored
# Breakfast ingredients
1 cup oatmeal
1 medium banana
1 tbsp almond butter

# Lunch ingredients  
2 cups mixed salad
6 oz grilled chicken
2 tbsp olive oil dressing

# Empty lines are ignored

# Dinner ingredients
8 oz salmon fillet
1 cup steamed vegetables
1/2 cup quinoa

# Extract specific nutrition data
avocavo ingredient "1 cup rice" --json | jq '.nutrition.calories'
# Output: 205

# Get USDA description
avocavo ingredient "1 cup rice" --json | jq '.usda_match.description'
# Output: "Rice, white, long-grain, regular, cooked"

# Check if analysis was successful
avocavo ingredient "invalid food" --json | jq '.success'
# Output: false

# Extract multiple values
avocavo ingredient "1 cup quinoa" --json | jq '{calories: .nutrition.calories, protein: .nutrition.protein}'
# Output: {"calories": 222, "protein": 8.1}

#!/bin/bash
# analyze-shopping-list.sh

echo "Analyzing shopping list..."

# Check if API is healthy first
if avocavo health --json | jq -e '.status == "ok"' > /dev/null; then
    echo "✅ API is healthy"
else
    echo "❌ API is down. Exiting."
    exit 1
fi

# Analyze shopping list
RESULT=$(avocavo batch -f shopping-list.txt --json)

# Check if analysis was successful
if echo "$RESULT" | jq -e '.success_rate > 80' > /dev/null; then
    echo "✅ Analysis successful"
    
    # Extract total calories
    TOTAL_CALORIES=$(echo "$RESULT" | jq '[.results[] | select(.success) | .nutrition.calories] | add')
    echo "Total calories in shopping list: $TOTAL_CALORIES"
    
    # Save detailed results
    echo "$RESULT" > "nutrition-analysis-$(date +%Y%m%d).json"
    echo "📁 Detailed results saved to nutrition-analysis-$(date +%Y%m%d).json"
else
    echo "❌ Analysis failed or low success rate"
    exit 1
fi

#!/usr/bin/env python3
# nutrition-processor.py

import subprocess
import json
import sys

def analyze_ingredient(ingredient):
    """Analyze ingredient using CLI and return parsed JSON"""
    try:
        result = subprocess.run(
            ['avocavo', 'ingredient', ingredient, '--json'],
            capture_output=True,
            text=True,
            check=True
        )
        return json.loads(result.stdout)
    except subprocess.CalledProcessError as e:
        print(f"CLI error: {e}")
        return None
    except json.JSONDecodeError as e:
        print(f"JSON parse error: {e}")
        return None

def check_api_health():
    """Check if API is healthy"""
    try:
        result = subprocess.run(
            ['avocavo', 'health', '--json'],
            capture_output=True,
            text=True,
            check=True
        )
        health_data = json.loads(result.stdout)
        return health_data.get('status') == 'ok'
    except:
        return False

# Main script
if __name__ == "__main__":
    if not check_api_health():
        print("❌ API is not healthy. Exiting.")
        sys.exit(1)
    
    ingredients = [
        "1 cup brown rice",
        "4 oz grilled chicken",
        "1 tbsp olive oil",
        "1 cup steamed broccoli"
    ]
    
    total_calories = 0
    successful_analyses = 0
    
    for ingredient in ingredients:
        print(f"Analyzing: {ingredient}")
        result = analyze_ingredient(ingredient)
        
        if result and result.get('success'):
            calories = result['nutrition']['calories']
            total_calories += calories
            successful_analyses += 1
            print(f"  ✅ {calories} calories")
        else:
            print(f"  ❌ Analysis failed")
    
    print(f"\nSummary:")
    print(f"Successful analyses: {successful_analyses}/{len(ingredients)}")
    print(f"Total calories: {total_calories}")

# GitHub Actions example (.github/workflows/nutrition-analysis.yml)
name: Daily Nutrition Analysis

on:
  schedule:
    - cron: '0 8 * * *'  # Run daily at 8 AM UTC
  workflow_dispatch:

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Avocavo CLI
        run: npm install -g avocavo
      
      - name: Analyze Menu
        env:
          AVOCAVO_API_KEY: ${{ secrets.AVOCAVO_API_KEY }}
        run: |
          avocavo batch -f menu-items.txt --json > nutrition-analysis.json
          
      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: nutrition-analysis
          path: nutrition-analysis.json