mymacros-cli

Unofficial CLI client for GetMyMacros, optimized for AI agent use.

Unofficial software: this project is not affiliated with, endorsed by, or supported by GetMyMacros. It relies on undocumented web endpoints that may change or stop working at any time. Review GetMyMacros' terms before use and use only with your own account.

The client is based on observed web-app behavior. See docs/ for implementation notes; no GetMyMacros source code is included.

Features

• Food and meal tracking — search foods, log meals, update servings, copy meals, and manage notes and favorites
• Agent-friendly output — JSON automatically when piped, stable IDs for command chaining, and machine-safe stdout
• Secure session storage — OS keyring by default, with an explicit 0600 config-file fallback for headless environments
• Scriptable defaults — date shortcuts, input validation, result limits, and plain or table output when needed

Installation

npm install -g mymacros-cli

Or run it without installing:

npx mymacros-cli --help

For development:

git clone https://github.com/crcatala/mymacros-cli.git
cd mymacros-cli
npm ci

Quick Start

# 1. Authenticate
mymacros auth login

# 2. See today's meals
mymacros daily

# 3. Find and add a food
mymacros search "chicken breast"
mymacros add 164298 --meal Lunch --serving 2

Authentication

Set credentials as environment variables (never stored to disk):

export MYMACROS_USER="your_username"
export MYMACROS_PASSWORD="your_password"

Or authenticate interactively:

mymacros auth login

Sessions are cached in your operating system keyring by default (macOS Keychain, Windows Credential Manager, or Linux Secret Service) and auto-refresh on expiry (~1 hour). In headless environments without a keyring, the CLI falls back to ~/.config/mymacros-cli/session.json, protected with 0600 permissions. Use mymacros auth login --use-config to choose that fallback explicitly. Never commit credentials or session files.

Web access and account eligibility

This CLI interoperates with the undocumented endpoints used by the GetMyMacros web app. GetMyMacros currently states that web access is limited to Pro and Macro Coach subscribers. A mobile-only account may still authenticate and use some endpoints, but food-log writes can be rejected by the server (observed response: { "success": false, "paid": false }).

For reliable food logging through this CLI, use an account entitled to access the web app. Endpoint availability and entitlement rules are controlled by GetMyMacros and may change without notice.

Running

# During development (no build step needed)
npx tsx src/cli.ts <command>

# Or build and run from dist
npm run build
node dist/cli.js <command>

# Check or clear locally stored credentials
mymacros auth status
mymacros auth clear

# JSON status distinguishes whether credentials exist from whether the cached session is fresh
mymacros auth status --json

Commands

Viewing Data

# Daily meals (default: today)
mymacros daily
mymacros daily yesterday
mymacros daily 2026-01-15

# Search the food database
mymacros search "chicken breast"
mymacros search "eggs" --limit 5

# Food details
mymacros food 164298
mymacros food -- -2288          # negative IDs need -- separator

# Browse by category
mymacros browse custom          # your custom foods & favorites
mymacros browse recent          # recently used
mymacros browse types           # list categories
mymacros browse types Chicken   # foods in a category
mymacros browse brands          # list brands
mymacros browse brands Costco   # foods from a brand

# Dates with logged data
mymacros dates --limit 10

Tracking Food

# Add a food (fetches food details automatically for required params)
mymacros add 164298 --meal Breakfast --serving 2

# Quick-add by macros (logs a fast-track food to a meal)
mymacros add-quick --name "Protein shake" --cal 200 --protein 30 --carbs 10 --fat 3

# Create a persistent custom food (paid web access required)
mymacros create-food --name "Too Good Zero Sugar Strawberry Yogurt" \
  --serving-size 1 --serving-name cup --brand "Too Good" \
  --cal 70 --fat 1.5 --sat-fat 1 --cholesterol 10 --sodium 40 \
  --carbs 6 --fiber 1 --sugar 0 --protein 13 --type Dairy

# Update serving size or move between meals
mymacros update 668 --serving 3
mymacros update 668 --meal Lunch

# Remove a food entry
mymacros remove 668

# Copy a meal to another date
mymacros copy-meal Breakfast --to-date tomorrow
mymacros copy-meal Lunch --to-date 2026-02-20 --to-meal Dinner

# Delete all entries from a meal
mymacros delete-meal Lunch --date yesterday

Notes & Favorites

# Day note
mymacros note "Felt great today"

# Meal note
mymacros note "Light meal" --meal Breakfast

# Clear a note
mymacros note ""

# Star / unstar a food
mymacros star 164298
mymacros unstar 164298

# Delete a custom food definition
mymacros delete-food -2288

Output Modes

| Flag | Behavior | |------|----------| | (default) | JSON when piped (non-TTY), plain text in terminal | | --json | Force structured JSON output | | --plain | Force human-readable text | | --table | Force aligned table output for list commands | | --quiet | Minimal output | | --debug | Show HTTP request/response details |

Command data is always written to stdout; progress, status, warnings, and errors go to stderr, so piping output stays machine-safe.

Manual Custom-Food Verification

Custom-food creation and deletion require a paid account with web access. These commands mutate the account; use a dedicated test account and a disposable food name:

mymacros auth status --json
mymacros create-food --name "CLI Verification Food" --serving-name cup \
  --brand "CLI Test" --cal 70 --fat 1.5 --sat-fat 1 \
  --cholesterol 10 --sodium 40 --carbs 6 --fiber 1 --sugar 0 \
  --protein 13 --type Dairy --json
mymacros browse custom --limit 0 --json | jq '.foods[] | select(.foodName == "CLI Verification Food")'
mymacros search "CLI Verification Food" --json
# Use the returned negative foodId after confirming it is the test food:
mymacros delete-food <food_id> --json

Fast-track verification (logs a meal entry and may not create a reusable custom-food definition):

mymacros add-quick --name "CLI Fast Track Verification" \
  --cal 70 --protein 13 --carbs 6 --fat 1.5 --meal Breakfast --debug

Do not add paid-account mutations to the default live test suite unless the suite is explicitly configured with a dedicated paid test account. Keep MYMACROS_LIVE_TESTS disabled for personal accounts.

JSON Output (Agent Use)

When piped or with --json, all commands return structured JSON with IDs included for chaining:

# Agent workflow: find food → add it → check totals
FOOD_ID=$(mymacros search "chicken breast" | jq -r '.sections[0].foods[0].foodId')
mymacros add "$FOOD_ID" --meal Lunch --serving 6
mymacros daily | jq '.dailyTotals'

Plain Output

Plain text includes [foodId/uniqueId] prefixes so IDs are accessible even in human-readable mode:

2026-02-17

Breakfast (301.79 kcal | 2.78P 38.18C 15.01F)
  [-28204/1583]    Double Espresso                1 Serving      200 kcal  2.1P 28C 8.9F
  [164298/2797]    Pringles                       19 Gr          101.79 kcal  0.68P 10.18C 6.11F

Daily Totals: 301.79 kcal | 2.78P 38.18C 15.01F

Agent Integration Notes

Designed for AI agents that help track food/nutrition. Key behaviors:

• JSON by default when piped — agents get structured data automatically without --json
• IDs always visible — foodId and uniqueId in every response for command chaining
• Pre-computed values — nutrition values are pre-multiplied by serving size (no math needed)
• Input validation — commands validate inputs before hitting the API to avoid bad data
• Helpful errors — invalid meal names show valid options, missing entries list available ones
• Result limits — search/browse default to 25 items (override with --limit N, use --limit 0 for all)

Important: uniqueId is Volatile

The uniqueId for a food entry changes on every update (the API does delete + re-insert). After any mutation (add, update, remove, copy-meal, delete-meal), re-read daily to get current IDs.

Write commands return the updated daily data in their JSON response, so agents can read the new IDs directly from the response.

Typical Agent Workflow

1. mymacros daily                          → see what's logged today
2. mymacros search "greek yogurt"          → find a food
3. mymacros food -1660                     → check nutrition details
4. mymacros add -1660 --meal Breakfast     → add it (response includes updated daily)
5. mymacros daily                          → verify the result

Date Formats

Commands accept these date formats:

| Input | Meaning | |-------|---------| | today | Current date (default) | | yesterday | Previous day | | tomorrow | Next day | | 2026-02-17 | Specific date (YYYY-MM-DD) |

Dates are converted to the API's internal MM-DD-YYYY format automatically.

Project Structure

src/
  cli.ts              # Entrypoint
  cli-main.ts         # Testable main (DI pattern)
  run.ts              # Commander setup
  client.ts           # HTTP client — auth, secure session cache, API methods, normalization
  credentials.ts      # Keyring and protected-config session storage
  types.ts            # API + normalized output types
  cli/
    context.ts        # Output config, colors, TTY detection
    client.ts         # Client factory with progress/debug wiring
    output.ts         # stdout/stderr helpers
    prompt.ts         # Interactive and masked-password prompts
    spinner.ts        # Delayed TTY-only progress indicator
    table.ts          # ANSI-safe terminal table renderer
    help.ts           # Shared Commander help formatting
    options.ts        # Shared output option registration
    errors.ts         # Typed errors
  commands/           # One file per command
    login.ts, daily.ts, search.ts, food.ts, browse.ts, dates.ts,
    add.ts, remove.ts, update.ts, copy-meal.ts, delete-meal.ts,
    note.ts, star.ts
  lib/
    date.ts           # Date parsing/formatting
tests/
  date.test.ts        # Date utility tests
docs/                 # Observed API behavior and schema notes
captures/             # Deterministic synthetic fixtures (generated by scripts/generate-fixtures.mjs)

Development

npm run dev -- daily                 # Run via tsx (no build)
npm run build                        # Compile TypeScript
npm test                             # Run tests
npm run lint                         # Check with Biome
npm run lint:fix                     # Auto-fix lint issues
npm run fixtures:check               # Verify committed fixtures are generated
npm run test:package                 # Smoke-test the npm tarball
npm run verify                       # Run all public-release checks

Live tests (maintainers only)

The live suite is deliberately opt-in and makes read-only requests with a dedicated GetMyMacros test account. It never uses the normal MYMACROS_USER credentials or persists a session locally. Do not point it at a personal account.

MYMACROS_LIVE_TESTS=1 \
MYMACROS_TEST_USER=dedicated-test-user \
MYMACROS_TEST_PASSWORD=dedicated-test-password \
npm run test:live

Live requests are serialized and paced at 500 ms by default (including login). Set MYMACROS_LIVE_DELAY_MS to a larger value when troubleshooting rate limits; do not lower it unless the API's current limits are known.

On a same-repository pull request, the repository owner can comment /run-live-tests to run the Live Tests workflow against that PR's head commit. The workflow rejects fork PRs and reports its result as both a check and a PR comment. As a manual alternative, run Live Tests from the Actions tab and type RUN (optionally supplying a PR number and head SHA for a status update). Create a protected live-tests environment containing the MYMACROS_TEST_USER and MYMACROS_TEST_PASSWORD secrets before enabling it.

Releases (maintainers only)

See RELEASING.md for prerequisites, initial and subsequent release procedures, recovery options, and post-publish verification.

Not Implemented

These features are out of scope for this CLI:

• Weight tracking (Weight.php)
• Settings / profile / goals (Settings.php)
• Recipe management
• Custom food creation (CreateCustomFood.php) via mymacros create-food (requires paid web access)

Contributing and security

See CONTRIBUTING.md. This project is available under the MIT License.