fitvete-food-cli

Command-line interface for the FitVete Food & Nutrition API. Zero dependencies (Node 18+, built-in fetch). Prints clean JSON to stdout, so it pipes into jq and is trivial for AI agents to parse. Use --pretty for humans.

Install

# install globally from npm
npm install -g fitvete-food-cli
fitvete-food search-foods chicken

# or run without installing
npx fitvete-food-cli search-foods chicken

Authenticate

Get a free key at https://fitvete.com/api/, then:

export FITVETE_API_KEY=fv_live_your_key
# or pass --key on any command

Commands

| Command | Description | | --- | --- | | search-foods <query...> [--number N] | Search foods; calories, macros, confidence. | | compute <ingredient...> | Full nutrient breakdown for an ingredient list. | | recipes [query...] [filters] | Search recipes by name + filters (--diet --cuisine --type --intolerances --include-ingredients --exclude-ingredients --max-ready-time --min-calories --max-calories --min-protein --sort --offset --number). | | recipe-random [--number N] [--tags ...] | Random recipes. | | recipe-autocomplete <query...> [--number N] | Recipe title suggestions. | | recipes-by-nutrients [--min-protein N --max-calories N ...] | Recipes matching nutrient ranges. | | recipe-similar <id> [--number N] | Recipes similar to an id. | | recipe-diets, recipe-meal-types, recipe-cuisines | Supported filter values. | | recipe <id> [--servings N] | Full recipe detail (ingredients, steps, nutrition); optional servings scaler. | | drinks <query...> [--number N] | Search drinks/cocktails. | | score <name...>\|--barcode CODE\|--id UUID [--goals ... --diet ... --allergies ... --avoid ... --explain] | Personalized 0–100 health score + grade. | | analyze-ingredients <text...> | Additives, allergens, NOVA level, diet flags. | | parse <text...> | Free-text meal → structured items + nutrition (NLP). | | alternatives <name...>\|--barcode CODE\|--id UUID [--number N] | Healthier swaps, ranked. | | foods-autocomplete <query...> [--number N] | Food name typeahead. | | barcode <code> | Look up a packaged food by UPC/EAN barcode. | | photo <image-path> | Estimate meal nutrition from a JPEG, PNG, or WebP image. | | label <image-path> | Parse a Nutrition Facts label from a JPEG, PNG, or WebP image. | | identify '<json>' | Unified barcode, text, photo or label identification. | | foods-search <query...> | Alias for food search. | | food <uuid> | Read a reference food or one of your private foods. | | create-food '<json>' | Create a private food with explicit 100 g macros. | | log '<json>' | Log food_id + grams or amount/unit; server computes nutrition. | | scan <uuid> | Read your latest scan result (0 points). | | scan-feedback <uuid> '<json>' | Save a complete correction and expected revision (0 points). | | delete-scan <uuid> | Delete your scan memory (0 points). | | recipe-calculate '<json>' | Calculate from public food IDs, grams or amount/unit or explicit amount/unit (g, ml, serving), preparation, servings and measured yield. | | recipe-retention [query...] [--code CODE] | Search the 270 USDA cooking profiles; missing factors remain unknown. | | recipe-bulk <ids...> | Retrieve 1–25 owned recipes, 5 points; missing IDs remain explicit. | | recipes-by-ingredients "rice,chicken" | Pantry ranking and used/missing/unused ingredient breakdowns; supports --number, --ranking and --ignore-pantry true/false. | | recipe-ingredients <id> [--servings N] | Scale recorded ingredient amounts; missing quantities remain null. | | recipe-nutrition <id> | Recorded nutrients per serving. | | recipe-instructions <id> | Recorded instruction groups and steps. | | tools | Print a JSON tool manifest for AI agents (function-calling). | | help, version | Help / version. |

Options

• --key <key> — API key (overrides FITVETE_API_KEY).
• --number, -n <N> — result count for search commands (1–25).
• --base <url> — API base URL (overrides FITVETE_API_BASE).
• --timeout <ms> — request timeout in milliseconds (overrides FITVETE_API_TIMEOUT; default 60000, none disables it).
• --pretty — human-readable table instead of JSON.
• --json — force JSON (default).
• --version, -v — print the CLI version.

photo and label images must be JPEG, PNG, or WebP and at most 5 MB.

Exit codes

0 ok · 1 request/HTTP error · 2 usage error · 3 auth or rate-limit.

Examples

fitvete-food search-foods "greek yogurt" --number 3
fitvete-food compute "1 cup rice" "2 eggs" | jq '.calories'
fitvete-food recipe 715538 | jq '.title'
fitvete-food drinks margarita --pretty
fitvete-food barcode 012345678905
fitvete-food photo ./meal.jpg
fitvete-food label ./nutrition-label.jpg | jq '.nutrients[] | select(.name=="Sodium")'

Using it from an AI agent

The CLI is designed to be driven by autonomous agents:

• Output is pure JSON — no prompts, spinners, or colour codes.
• Failures return a non-zero exit code and a JSON error body.
• fitvete-food tools prints a function-calling manifest describing every command and its method/path and parameters, so a model can discover the available functions at runtime.

fitvete-food tools     # → { "tools": [ { "name": "fitvete_search_foods", "input_schema": {...} }, ... ] }

As an MCP tool

Expose the CLI to any MCP client (Claude Desktop, Cursor, …) by running it from a shell tool, or wrap each command as an MCP tool. Minimal stdio wrapper sketch:

// mcp-server.js (pseudocode) — map each manifest tool to a CLI call
import { execFile } from "node:child_process";
const run = (cmd, args) => new Promise((res, rej) =>
  execFile("fitvete-food", [cmd, ...args], (e, out) => (e ? rej(e) : res(JSON.parse(out)))));
// tool "fitvete_search_foods" -> run("search-foods", [query, "--number", String(n)])

The same key (FITVETE_API_KEY) and JSON contract apply.

Storage and charging

Private foods/logs require a direct developer key and belong only to its account. Scan memory expires after 30 days; management still uses burst limits at 0 points. Complete corrections stay private unless explicit contribution consent is supplied. Creating foods/logs is not idempotent; do not retry an uncertain creation automatically.

Successful authorization reserves the route's points, including cache hits and later handler errors. Invalid image format/size is checked before reservation; authentication, quota and burst rejection cost zero. X-RateLimit-Cost reports the actual reserved cost. See the current contract.

Text/photo identification supplies names and estimated portions; the database supplies nutrition. A partial text resolution returns null meal totals plus unresolved_items and resolved_totals. Missing measurements are never filled in. The CLI never uploads an image larger than 5 MB.

License

MIT

Semantic discovery

fitvete-food search-foods "soybean curd" --mode semantic --number 5
fitvete-food foods-search "fermented milk" --mode hybrid

Semantic retrieval covers generic reference foods; packaged products retain lexical and barcode lookup. Nutrient coverage explicitly distinguishes reported values from unknown values. No minimum number of measured nutrients is guaranteed.

Recipe independence: add --data owned to recipes, recipe, recipe-random, recipe-autocomplete, recipes-by-nutrients or recipe-similar. These requests use only complete stored recipes. Missing searches return an empty list and a missing detail returns 404; the default --data auto permits external fallback.

fitvete-food recipes chicken --data owned
fitvete-food recipes-by-nutrients --max-fat 0 --data owned

Ingredient tools (1 point each): ingredient-units, ingredient-convert '<JSON>' and ingredient-amount '<JSON>'. Conversions use explicit units such as g, lb, ml and us_cup; cross-dimension conversions require verified food evidence.

fitvete-food ingredient-convert '{"amount":1,"from_unit":"lb","to_unit":"g"}'
fitvete-food ingredient-amount '{"food_id":"PUBLIC_FOOD_UUID","nutrient_key":"protein","target_amount":25,"target_unit":"g"}'

Private developer user workspace (1.13)

Use the developer key only from your backend. Connect an opaque user ID with connect-user; the returned UUID is not an end-user authentication token.

• generate-plan '<JSON>' creates owned day/week suggestions; save its plan_days explicitly.
• user-recipes|user-plans|user-templates|user-shopping-lists|user-foods|user-logs USER_UUID lists/searches records.
• create-user-recipe USER_UUID '{"id":"UUID","data":{...}}' saves with a stable retry ID; the same pattern applies to plan, template, shopping-list, food and log.
• user-recipe USER_UUID UUID reads data/revision; update-user-recipe USER_UUID UUID '{"data":{...}}' --revision N replaces only that revision.
• delete-user-recipe USER_UUID UUID --revision N deletes it. Updates/deletes return conflict for stale revisions.
• plan-shopping-list USER_UUID PLAN_UUID '{"id":"LIST_UUID","name":"Shopping","plan_revision":1}' scales ingredients from the saved plan snapshot.
• disconnect-user USER_UUID erases this user's workspace.

Each operation costs one point. Private records never enter public search or training. Missing nutrients/quantities remain unknown; unsupported mass/volume conversions are rejected. Input fields, storage limits and every operation are in the workspace reference.

Recipe content (1.14)

recipe-extract '<JSON>' reads schema.org Recipe metadata from html or an allowlisted HTTPS url. recipe-import-sources lists hosts and limits. No redirects or automatic saving; extracted nutrition stays unverified.

recipe-analyze '{"instructions":["Bake at 180°C for 20 minutes."]}' returns explicit English timer, temperature and equipment mentions with UTF-16 spans. Negations remain in context; mentions are not required equipment.

recipe-summary <id>, recipe-equipment <id> and recipe-card <id> use only owned recipes. Cards return JSON with self-contained HTML/SVG. nutrition-widget '{"name":"Milk","basis":"per_100ml","nutrients":{"kcal":42,"sodium":null}}' renders submitted measurements, preserving unknowns and zeros. Renderers are not persisted and do not assert regulatory-label compliance. Each costs one point.