linguini-cli

Companion CLI for Linguini, a collaborative family meal-planning app.

Manage recipes, meal plans, groceries, labels, and the capture inbox from your terminal. Follows Printing Press conventions: JSON output by default when piped, <noun> <verb> subcommand shape, stable exit codes.

Install

npm install -g linguini-cli

Requires Node.js >= 20.

Quick start

# First time on a new machine: create or join a household end-to-end
# (signs you in by emailing a 6-digit code, creates/joins the household,
# mints an API key, and saves it to your config).
linguini setup

linguini whoami
linguini recipes list --json
linguini recipes list --search "chicken"
echo '{"title":"Eggs","totalTimeMinutes":5}' | linguini recipes new --stdin --json

# Bookshelf: add a cookbook by ISBN, then attach a recipe to it
linguini sources new --isbn 9781476753836            # → looks up "Salt, Fat, Acid, Heat" and saves
linguini sources list
linguini recipes edit <recipe-id> --source-id <src-id> --page-ref "p. 217"

If you already have an API key (minted from the web app's Household → API keys page or another machine), use linguini login instead of setup.

Pointing at a self-hosted instance: pass --url https://your-app.example.com to linguini setup or linguini login.

Setup flow

linguini setup is fully terminal-driven — the only thing you need a web browser or mail client for is reading the magic-code email. It walks through:

1. Prompts for your email and sends a 6-digit code via Instant's built-in mailer.
2. Prompts for the code (check your inbox) and exchanges it for a short-lived session token.
3. Asks whether to create a new household or join an existing one with an invite code.
4. Creates or joins the household, mints an lng_… API key, and saves it to ~/.config/linguini/config.json.

All inputs can also be supplied as flags so the command works headless in CI:

# Step 1: kick off send-code only (so a human can fetch the magic code).
linguini setup --email [email protected] --mode create --display-name Sam \
  --household-name "The Carter House" --json
# …then re-run with the code from the email:
linguini setup --email [email protected] --code 123456 --skip-send \
  --mode create --display-name Sam --household-name "The Carter House" --json

Use --mode join --invite-code ABCD2345 to join an existing household instead.

Config is saved to ~/.config/linguini/config.json with mode 0600 (override location with LINGUINI_CONFIG_HOME or XDG_CONFIG_HOME).

Headless / CI use

Skip linguini login and set environment variables instead — env wins over the config file. LINGUINI_API_URL is optional and defaults to the hosted instance:

export LINGUINI_API_KEY=lng_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# export LINGUINI_API_URL=https://your-app.example.com  # only for self-hosted
linguini recipes list --json

Output

Output is JSON when any of these are true:

• --json is passed
• LINGUINI_AGENT=1 is set
• stdout is piped

Otherwise output is human-readable.

Exit codes

| code | meaning | | --- | --- | | 0 | ok | | 1 | other / internal error | | 2 | usage error | | 3 | auth (missing/invalid key) | | 4 | not found | | 5 | conflict |

Commands

Run linguini --help or linguini <noun> --help for the full list. Top-level nouns:

• setup — full account + household bootstrap from the terminal (magic-code email sign-in, create or join, mint API key, save config)
• login — save an existing API key (defaults to the hosted instance)
• whoami — show signed-in user + household
• recipes — list / get / new / edit / delete
• meals — list / get / new / edit / delete (all meal-option types)
• plan — view & manage the weekly meal plan
• grocery — view & manage the shared grocery list
• labels — list / new / delete
• capture — manage the capture inbox
• household — show household info & manage API keys
• sources — manage the Bookshelf (cookbooks / sites / magazines, with ISBN lookup)
• import — bulk import recipes from JSON
• upgrade — check npm for a newer linguini-cli release and install it (use --check to only report availability)

License

MIT © Zach Galant