pp-lunch-money

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/payments/lunch-money/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/". -->

# Lunch Money — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `lunch-money-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:
   ```bash
   npx -y @mvanhorn/printing-press-library install lunch-money --cli-only
   ```
2. Verify: `lunch-money-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.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/payments/lunch-money/cmd/lunch-money-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.

## When to Use This CLI

Use this CLI when you need to bulk-fix transactions, audit subscriptions or recurring items, reconcile net worth across Plaid + manual + crypto accounts, or expose Lunch Money to agent workflows. Especially valuable for Sunday-morning budgeting rituals (triage, retag, budget burn-down), end-of-month asset snapshots (manual account updates, balance history upserts), and expense-report assembly (transactions list --tag, attachment exports). Avoid it for one-off web-UI exploration — that's what lunchmoney.app is for.

## Unique Capabilities

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

### Local-join transcendence
- **`transactions subscriptions`** — Find regular-cadence merchant charges that are not yet linked to a recurring item, so you can promote them before subscription creep sneaks past you.

  _When a user asks 'what subscriptions are draining my account?', this surfaces unlabeled recurring charges in one local SQL pass._

  ```bash
  lunch-money-pp-cli transactions subscriptions --suspected-only --json --select 'payee,suggested_cadence,avg_amount,occurrences'
  ```
- **`recurring missing`** — List recurring items whose next expected date falls in the requested month but have no matching transaction yet, so you can catch missed bills.

  _Answers 'which subscriptions haven't hit my account yet?' which is a top-three Maya question with no API equivalent._

  ```bash
  lunch-money-pp-cli recurring missing --month 2026-05 --json
  ```
- **`transactions duplicates`** — Detect near-duplicate transactions in a window (same merchant, amount within tolerance, date within range) so you can group or delete them in bulk.

  _Use after a trip or when reviewing imports to catch the same Uber ride processed twice._

  ```bash
  lunch-money-pp-cli transactions duplicates --window 3 --tolerance 1.00 --json --select 'cluster_id,payee,amount,date,id'
  ```

### Net-worth tools
- **`accounts stale`** — Surface manual accounts and manual crypto whose balance has not been updated in N days, so net worth stays honest.

  _Answers 'what manual balances do I owe an update?' before quarterly NAV updates or Sunday reconciliation._

  ```bash
  lunch-money-pp-cli accounts stale --over 30d --json --select 'account_type,account_name,last_updated,days_stale'
  ```
- **`net-worth on`** — Reconstruct net worth at any historical date by walking balance_history across every account type, with last-known-balance carry-forward where needed.

  _Use for quarterly snapshots, retirement-plan inputs, or 'what was my net worth before I bought the car?' questions._

  ```bash
  lunch-money-pp-cli net-worth on 2026-03-31 --json --select 'as_of_date,total,by_account_type'
  ```

### Bulk transaction tools
- **`transactions retag`** — Match transactions by regex on payee/notes via local FTS, preview the affected set, then bulk-apply tag/category changes via the API.

  _Answers 'fix every Amazon transaction since January' in one command instead of pagination clicks._

  ```bash
  lunch-money-pp-cli transactions retag --match '^AMZN' --category-id 73 --dry-run --json
  ```
- **`triage`** — Pull all unreviewed transactions, compute a suggested category from prior categorizations of the same merchant, and optionally mass-apply the suggestion.

  _Sunday-morning ritual for power-user budgeters; agent-friendly suggested categories let an LLM bulk-approve high-confidence rows._

  ```bash
  lunch-money-pp-cli triage --limit 20 --json --select 'id,payee,amount,suggested_category,confidence'
  ```

### Budget intelligence
- **`budgets burn`** — For the current budget period, project end-of-month spend per category at the current linear rate and flag categories projected to overshoot.

  _Mid-month answer to 'am I on track?' that flows into agent workflows and dashboards._

  ```bash
  lunch-money-pp-cli budgets burn --period 2026-05 --json --select 'category_name,target,spent,projected_end_spend,over_under'
  ```

### Session orientation
- **`changed`** — List everything created or edited in the local store since a cutoff (e.g. --since 8h, --since 2026-05-01). Use at session start to orient before taking action.

  _Agents starting a fresh session can ask 'what changed overnight?' in one call instead of paginating multiple list endpoints._

  ```bash
  lunch-money-pp-cli changed --since 8h --json
  ```

## Command Reference

**balance-history** — View and update historical account balances. Balance history is what drives the [Net Worth](https://my.lunchmoney.app/net-worth) views in the Lunch Money app. Balance history is generated for each account's balance on the first day of each month and can be edited in the Lunch Money app or via the API.

- `lunch-money-pp-cli balance-history delete-entry` — Delete a single monthly balance history entry by its id.
- `lunch-money-pp-cli balance-history delete-for-account` — Delete all historical balance entries for a single manual, Plaid, manual crypto, or deleted account. Crypto synced...
- `lunch-money-pp-cli balance-history delete-for-crypto-synced` — Delete all historical balance entries for a single synced crypto symbol stream.<br><br> The path identifies both the...
- `lunch-money-pp-cli balance-history get` — Retrieve historical balance entries.<br><br> Balance history is monthly. When `start_date` and `end_date` are both...
- `lunch-money-pp-cli balance-history get-for-account` — Retrieve historical balance entries for one manual, Plaid, manual crypto, or deleted account. Crypto synced accounts...
- `lunch-money-pp-cli balance-history get-for-crypto-synced` — Retrieve historical balance entries for a single synced crypto symbol stream.<br><br> Use the `crypto_synced`...
- `lunch-money-pp-cli balance-history update-details` — Update archived metadata for a deleted balance history source.<br><br> Pass the `deleted` source id returned on...
- `lunch-money-pp-cli balance-history upsert-for-account` — Upsert one or more historical balance entries for a single manual, Plaid, manual crypto, or deleted acount. Crypto...
- `lunch-money-pp-cli balance-history upsert-for-crypto-synced` — Upsert one or more historical balance entries for a single synced crypto symbol stream.<br><br> The path identifies...

**budgets** — View settings and modify budget amounts.<p> Use the [/summary](#tag/summary) endpoint to view the budget details performance.

- `lunch-money-pp-cli budgets delete` — Removes the budget for the given category and period. If there already is no budget set for that period, the request...