Pp Nutrition

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/food-and-dining/nutrition/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Nutrition (USDA FoodData Central + NutritionValue.org) — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the nutrition-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install nutrition --cli-only

2. Verify: nutrition-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/food-and-dining/nutrition/cmd/nutrition-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Look up any food's nutrition from USDA's ~600K-food database, then enrich it with NutritionValue.org's derived analytics (net carbs, omega-6/omega-3 ratio) that the USDA API never exposes. Compare foods on a per-100kcal protein-density basis, rank foods by any nutrient, filter by compound thresholds, and log a daily diary against targets - all offline-cached, cited, and agent-native.

When to Use This CLI

Use this CLI when an agent or user needs trustworthy, citable food nutrition data: looking up macros and micros for a food, comparing foods by protein density or on a common basis, ranking foods by a nutrient, finding foods that meet compound dietary thresholds, enriching a USDA record with NutritionValue.org's derived analytics, or logging a daily food diary against targets. It is offline-cached and agent-native, so repeated lookups and aggregations are cheap and the numbers always trace to a real USDA fdcId.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI for restaurant chain menu items - USDA and NutritionValue.org do not carry curated restaurant menus (use Nutritionix or CalorieKing).
• Do not use this CLI for glycemic index - neither source provides it.
• Do not use this CLI to place grocery orders or track weight/biometrics - it is a nutrition-facts and diary tool, not a fitness app.
• Do not use this CLI as a medical or clinical nutrition authority - it reports database values, not personalized dietary advice.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Cross-source intelligence

• enrich — Merge NutritionValue.org's derived analytics (net carbs and omega-6/omega-3 ratio) onto a USDA food record by its shared FDC id.

  Reach for this when a user wants net carbs or the omega-6/omega-3 ratio - numbers no USDA API call returns.

  nutrition-pp-cli enrich 173414 --agent

• rank — Top or bottom foods by any single nutrient, filterable by category and dataset, ingested from NutritionValue.org's precomputed ranking pages.

  Reach for this to answer 'which foods are highest/lowest in nutrient X' without paging the whole database yourself.

  nutrition-pp-cli rank potassium --order lowest --agent

Local math no API does

• compare — Compare 2-5 foods side by side on a common basis: per 100 g, per serving, or per 100 kcal (protein density).

  Reach for this to rank foods by protein density or compare macros fairly across different serving sizes.

  nutrition-pp-cli compare 2646170 173414 747447 --basis 100kcal --agent

• find — Find foods that satisfy multiple nutrient thresholds at once (e.g. protein >= 20 g AND kcal <= 165 per 100 g).

  Reach for this for diet-constrained discovery like high-protein low-calorie foods in one query.

  nutrition-pp-cli find --min protein=20 --max-kcal 165 --agent

• meal — Total nutrition across several foods at given quantities in one stateless call (id:quantity pairs).

  Reach for this to get the nutrition of a recipe or plate without recording it in the diary.

  nutrition-pp-cli meal 173414:50g 1105314:120g --agent

Local state that compounds

• log — A persistent daily food diary with macro/micro targets, backed by local SQLite, with today/summary/progress reports.

  Reach for this to record what a user ate and report progress against daily targets - a Claude-loggable tracker.

  nutrition-pp-cli log progress --agent

• cite — Emit an APA or MLA citation for a USDA food record so agent output is verifiable and traceable to a real fdcId.

  Reach for this when a user needs a citable source for a nutrition figure in a report or agent answer.

  nutrition-pp-cli cite 173414 --style apa

Command Reference

food — Manage food

• nutrition-pp-cli food <fdcId> — Retrieves a single food item by an FDC ID. Optional format and nutrients can be specified.

foods — Manage foods

• nutrition-pp-cli foods get — Retrieves a list of food items by a list of up to 20 FDC IDs. Optional format and nutrients can be specified.
• nutrition-pp-cli foods get-list — Retrieves a paged list of foods. Use the pageNumber parameter to page through the entire result set.
• nutrition-pp-cli foods get-search — Search for foods using keywords.
• nutrition-pp-cli foods post — Retrieves a list of food items by a list of up to 20 FDC IDs. Optional format and nutrients can be specified.
• nutrition-pp-cli foods post-list — Retrieves a paged list of foods. Use the pageNumber parameter to page through the entire result set.
• nutrition-pp-cli foods post-search — Search for foods using keywords.

json-spec — Manage json spec

• nutrition-pp-cli json-spec — The OpenAPI 3.0 specification for the FDC API rendered as JSON (JavaScript Object Notation)

yaml-spec — Manage yaml spec

• nutrition-pp-cli yaml-spec — The OpenAPI 3.0 specification for the FDC API rendered as YAML (YAML Ain't Markup Language)

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

nutrition-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Protein density leaderboard

nutrition-pp-cli compare 2646170 173414 747447 --basis 100kcal --agent --select foods.description,foods.protein_per_100kcal

Compare foods by grams of protein per 100 kcal and pull only the name and density fields.

Low-carb shopping list

nutrition-pp-cli rank carbs --order lowest --limit 15 --agent

Get the 15 lowest-carbohydrate foods from NutritionValue.org's ranking pages.

Enrich a food with derived analytics

nutrition-pp-cli enrich 173414 --agent --select net_carbs_g_per_100g,omega_6_3_ratio

Merge NutritionValue.org's net carbs and omega-6/omega-3 ratio onto a USDA record.

Total a meal

nutrition-pp-cli meal 173414:50g 1105314:120g --agent

Sum nutrition across cheddar and a banana at given gram quantities in one call.

Daily progress against targets

nutrition-pp-cli log progress --agent

Report today's logged intake versus configured macro targets.

Auth Setup

USDA FoodData Central needs a free api.data.gov key. Set FDC_API_KEY (or USDA_API_KEY). Without a key the CLI falls back to USDA's public DEMO_KEY (rate-limited to ~30 requests/hour). NutritionValue.org commands need no key.

Run nutrition-pp-cli doctor to verify setup.