pp-splitwise

What this skill does

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

# Splitwise — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `splitwise-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 splitwise --cli-only
   ```
2. Verify: `splitwise-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/splitwise/cmd/splitwise-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

Reach for splitwise-pp-cli when a task involves shared expenses, group trips, roommate bills, or settling up — logging an expense, checking who owes whom, rolling up spend by category, finding a past expense, or computing a settle-up plan. It is the right tool when you want offline analytics over a Splitwise account or scriptable expense automation, not a one-off live lookup.

## Unique Capabilities

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

### Balances at a glance
- **`balances`** — See everything you owe and are owed across every friend and group in one net-position view.

  _Reach for this instead of N get_groups + get_friends calls when an agent needs the user's overall money position._

  ```bash
  splitwise-pp-cli balances --agent
  ```

  Add `--by-group` to break your net position out **per group** (one row per group per currency, biggest absolute balance first) instead of per friend — answers "what's my outstanding balance by group?" directly from the synced store:

  ```bash
  splitwise-pp-cli balances --by-group --agent
  ```
- **`debts`** — List who owes you (and whom you owe) sorted by how long the balance has gone unsettled.

  _Use when the task is 'who never pays me back' or chasing stale IOUs._

  ```bash
  splitwise-pp-cli debts --aged --agent
  ```
- **`ledger`** — Every expense in a group, in date order, with a cumulative running balance per member.

  _Use to audit how a group's balances got to where they are, not just the snapshot._

  ```bash
  splitwise-pp-cli ledger "Tahoe Trip" --agent
  ```

### Offline spend intelligence
- **`spend`** — Total shared spend broken down by category, group, or month from your synced history.

  _Use for any 'how much did we spend on X' question instead of paging the whole expense list._

  ```bash
  splitwise-pp-cli spend --group-by category --agent
  ```
- **`search`** — Full-text search across your entire expense history, comments, and group/friend names — offline.

  _Use to find a specific past expense by keyword without paging the API._

  ```bash
  splitwise-pp-cli search "ramen" --agent
  ```
- **`recurring`** — Surface repeating charges (rent, utilities, subscriptions) from your synced history and flag a month missing an expected entry.

  _Use to catch a shared monthly bill nobody remembered to log this cycle._

  ```bash
  splitwise-pp-cli recurring --agent
  ```

### Upcoming-obligations forecast
- **`forecast`** — Project your next shared obligations from recurring spending patterns over your synced history. Clusters expenses by normalized description, finds the ones with a regular cadence (>= 3 dated occurrences, mean cadence 2-400 days, largest gap <= 3x the smallest), and projects the next expected date and amount. Returns charges whose next occurrence falls inside the window (default 35 days) or is already overdue, sorted by expected date.
  Reads from your synced local store; on large accounts, results can be incomplete until a full sync.

  _Use to answer "what shared bills are coming up?" or "what should I budget for next month?" — and to catch a regular charge that's overdue and hasn't been logged yet._

  ```bash
  splitwise-pp-cli forecast --agent
  splitwise-pp-cli forecast --days 60 --limit 20 --json
  ```

  Output shape (`--agent` / `--json`):

  ```json
  {
    "as_of": "2026-05-30",
    "window_days": 35,
    "upcoming": [
      {
        "description": "Rent",
        "group": "Roommates",
        "last_date": "2026-05-01",
        "expected_date": "2026-06-01",
        "expected_amount": 1850.00,
        "cadence_days": 30,
        "occurrences": 6,
        "overdue": false
      }
    ]
  }
  ```

  Payments and settlement rows (`settle all balances`, `settle up`, `payment`, `paid via …`) are excluded. Read-only; never posts.

### Multi-currency normalization
- **`normalize`** — Normalize multi-currency net position and spend into one base currency using user-supplied offline FX rates (`--rate` / `--rates-file`); historical/automatic FX lookup is intentionally out of scope.

  _Use to compare or total spend across trips in different currencies — supply the rates and get one base-currency number; a currency with no rate is surfaced as unconverted, never silently dropped._

  ```bash
  splitwise-pp-cli normalize --base USD --rate EUR=1.08 --agent
  ```

### Trip & period reports
- **`report`** — Export an offline trip/period spend report as Markdown, CSV, or JSON. Single-currency only: defaults to the most common filtered currency, excludes other currencies with an explicit excluded count, and supports `--currency` to pin one. PDF is intentionally out of scope in v1.

  Output shape (`--agent` / `--json`):

  ```json
  {
    "scope": "group:Tahoe Trip",
    "currency": "USD",
    "period_start": "2025-01-10",
    "period_end": "2025-02-01",
    "expense_count": 12,
    "excluded_other_currency": 0,
    "total_cost": 1840.00,
    "your_paid": 920.00,
    "your_owed": 613.33,
    "your_net": 306.67,
    "people": [
      { "user_id": 1, "name": "You", "paid": 920.00, "owed": 613.33, "net": 306.67 }
    ],
    "categories": [
      { "name": "Lodging", "total": 1200.00, "count": 2 }
    ],
    "expenses": [
      { "id": 9001, "date": "2025-01-10", "description": "Cabin", "cost": 1200.00, "currency_code": "USD", "payer": "You" }
    ],
    "truncated": false
  }
  ```

  Payment and deleted rows are excluded. Single-currency: other-currency expenses are excluded and counted in `excluded_other_currency`. Read-only; never posts.

### Fairness & collection risk
- **`fairness`** — Score who carries the group, who's a collection risk, and who to chase or write off — offline, from your synced history.

  _Turns "who still owes me, and will I ever see it" into an action list: nudge, chase, or write off (debt that is old **and** gone quiet). `--by contribution` shows who fronts cash vs. free-rides; `--by collectability` ranks by debt age and settle latency. New group members with no history are surfaced separately, never flagged as risks._

  ```bash
  splitwise-pp-cli fairness --by risk --agent
  ```

### Reconcile and settle
- **`settle-up`** — Compute the minimum set of transfers that zeroes out balances in a group, then optionally record the payments.

  _Use when a group wants the fewest Venmo transfers to get everyone to zero._

  ```bash
  splitwise-pp-cli settle-up "Tahoe Trip" --agent
  ```
- **`activity`** — Show what changed since your last sync — new, edited, and deleted expenses to review.

  _Use to reconcile