--- name: pp-splitwise description: "Every Splitwise feature, plus an offline SQLite ledger that powers balance, debt-aging, spend analytics, fairness, and full-text search no other Splitwise tool has. Trigger phrases: `what do I owe on splitwise`, `who owes me money`, `split this expense`, `settle up the trip`, `how much did we spend on food`, `use splitwise`, `run splitwise`." author: "Vinny Pasceri" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - splitwise-pp-cli --- # 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 before this CLI has a public-library category, install Node or use the category-specific Go fallback after publish. 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. splitwise-pp-cli wraps the full Splitwise API — expenses, groups, friends, comments, settle-ups — and keeps a local copy of your whole ledger. That local store powers a net `balances` view, `debts --aged` (who never pays you back), `spend` rollups by category or month, offline `search`, a group `ledger` with running balances, `fairness` and `net` for who's carrying cost and how balances collapse across groups, and a `settle-up` plan that minimizes transfers. `brief` gives an agent one bounded state digest, and `reconcile` verifies the local store still matches Splitwise before you trust any of it. Fuzzy name resolution means you never paste a numeric ID. ## 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, aging a stale debt, rolling up spend by category, finding a past expense, checking who's carrying more than their share, or computing a settle-up plan. It is the right tool when you want offline analytics or a verified local copy of a Splitwise account, not a one-off live lookup. Under --agent every command wraps its payload as {"meta": {...}, "results": ...}; --json returns the bare payload. ## Anti-triggers Do not use this CLI for: - do not use for live FX conversion — normalize takes user-supplied rates - do not use to pay anyone — it records settlements in Splitwise only - do not use for multi-user OAuth apps — the CLI authenticates as a single user with a personal API key - do not use for real-time push notifications — sync and reconcile are both pull-based, not a live feed ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Money state that compounds locally - **`balances`** — See everything you owe and are owed across every friend and group in one net-position view. _Reach for this instead of separate get-groups + get-friends calls when an agent needs the user's overall money position._ ```bash splitwise-pp-cli balances --by-currency --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, not just the current balance._ ```bash splitwise-pp-cli debts --aged --agent ``` - **`net`** — Collapse a person's balance across every group and non-group expense into the minimum set of real-world transfers. _Use when one person's balance is scattered across multiple groups and one-off expenses and you want the fewest real transfers, not a per-group snapshot._ ```bash splitwise-pp-cli net --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. Add --friend to replay one person across every group instead of one group's members._ ```bash splitwise-pp-cli ledger "Tahoe Trip" --agent ``` - **`balances`** — See one row per group per currency for every non-zero balance, without the noise of settled groups. _Use when the question is scoped to 'which groups do I still owe in', not the single net number._ ```bash splitwise-pp-cli balances --by-group --agent ``` ### Settle and record safely - **`settle-up`** — Compute the minimum set of transfers that zeroes out balances in a group, then optionally record the payments (print-only by default; --record writes real payment expenses to your Splitwise account). _Use when a group wants the fewest transfers to get everyone to zero, previewed before anything is recorded._ ```bash splitwise-pp-cli settle-up "Tahoe Trip" --agent ``` - **`audit`** — Catch duplicate settlement rows and abnormal expense amounts before you trust a settle-up plan. _Run this before settle-up or report so a duplicate settlement or an outlier expense doesn't get baked into a transfer plan._ ```bash splitwise-pp-cli audit --since 90d --agent ``` - **`split`** — Build and preview the exact expense split (equal, exact, percentage, or shares) before recording it. _Reach for this to turn 'I paid $84, split equally with the trip' into a ready-to-record expense without hand-building the share arrays. Add --record to submit it._ ```bash splitwise-pp-cli split "Tahoe Trip" --amount 84 --equal --agent ``` - **`fairness nudge`** — Post a payment reminder as a comment on the actual open expense thread, previewed before it sends (print-only by default; --send posts a real comment your friend will see). _Use to nudge one person about a specific unpaid expense instead of a generic message outside Splitwise._ ```bash splitwise-pp-cli fairness nudge "Jordan" ``` - **`reconcile`** — Verify the local store actually matches Splitwise before you trust a settle-up or report (calls the live Splitwise API; needs SPLITWISE_API_KEY and network). _Run this before a settle-up or report when a number looks wrong, or as a routine pre-settle check._ ```bash splitwise-pp-cli reconcile --since 30d --agent ``` ### Analytics no endpoint offers - **`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 --since 30d --agent ``` - **`fairness`** — See who's carrying more than their share of cost, and how likely a stale balance is to actually get paid. _Use when the question is who's owed the most relative to what they've paid, not just the raw balance._ ```bash splitwise-pp-cli fairness --by collectability --agent ``` - **`report`** — Turn synced trip or period spend into a shareable summary plus per-person and per-category export. _Use for an end-of-trip or end-of-month writeup, or as a generic JSON/CSV sink into an external workflow tool._ ```bash splitwise-pp-cli report --group "Tahoe Trip" --format md ``` - **`recurring`** — Surface repeating charges (rent, utilities, subscriptions) from your synced history and flag a cycle missing an expected entry. _Use to catch a shared monthly bill nobody remembered to log this cycle._ ```bash splitwise-pp-cli recurring --agent ``` - **`forecast`** — See what shared bills are expected next, projected from your recurring-expense history. _Use for 'what's coming up' instead of recurring, which only detects the pattern of bills already logged._ ```bash splitwise-pp-cli forecast --agent ``` - **`normalize`** — Express multi-currency spend in one base currency, using rates you supply, with anything unconverted called out honestly. _Use when spend spans more than one currency and you want one honest number, not a silently-dropped or auto-converted total._ ```bash splitwise-pp-cli normalize --base USD --rate EUR=1.08 --agent ``` ### Agent-native plumbing - **`brief`** — Get one compact digest of net position, the stalest debts, and what changed since last sync in a single call. _Reach for this first at the start of a session instead of three separate calls; use balances, debts --aged, or activity directly when you need the full detail behind one of these numbers._ ```bash splitwise-pp-cli brief --agent --compact ``` - **`activity`** — Show what changed since your last sync — new, edited, and deleted expenses to review. _Use to reconcile recent account activity before settling or reporting._ ```bash splitwise-pp-cli activity --agent ``` ## Command Reference **add-user-to-group** — Manage add user to group - `splitwise-pp-cli add-user-to-group` — **Note**: 200 OK does not indicate a successful response. You must check the `success` value of the response. **create-comment** — Manage create comment - `splitwise-pp-cli create-comment` — Create a comment **create-expense** — Manage create expense - `splitwise-pp-cli create-expense` — Creates an expense. You may either split an expense equally (only with `group_id` provided), or supply a list of shares. **create-friend** — Manage create friend - `splitwise-pp-cli create-friend` — Adds a friend. If the other user does not exist, you must supply `user_first_name`. **create-friends** — Manage create friends - `splitwise-pp-cli create-friends` — Add multiple friends at once. **create-group** — Manage create group - `splitwise-pp-cli create-group` — Creates a new group. Adds the current user to the group by default. **delete-comment** — Manage delete comment - `splitwise-pp-cli delete-comment ` — Deletes a comment. Returns the deleted comment. **delete-expense** — Manage delete expense - `splitwise-pp-cli delete-expense ` — **Note**: 200 OK does not indicate a successful response. The operation was successful only if `success` is true. **delete-friend** — Manage delete friend - `splitwise-pp-cli delete-friend ` — Given a friend ID, break off the friendship between the current user and the specified user. **delete-group** — Manage delete group - `splitwise-pp-cli delete-group ` — Delete an existing group. Destroys all associated records (expenses, etc.) **get-categories** — Manage get categories - `splitwise-pp-cli get-categories` — Returns a list of all categories Splitwise allows for expenses. **get-comments** — Manage get comments - `splitwise-pp-cli get-comments` — Get expense comments **get-currencies** — Manage get currencies - `splitwise-pp-cli get-currencies` — Returns a list of all currencies allowed by the system. **get-current-user** — Manage get current user - `splitwise-pp-cli get-current-user` — Get information about the current user **get-expense** — Manage get expense - `splitwise-pp-cli get-expense ` — Get expense information **get-expenses** — Manage get expenses - `splitwise-pp-cli get-expenses` — List the current user's expenses **get-friend** — Manage get friend - `splitwise-pp-cli get-friend ` — Get details about a friend **get-friends** — Manage get friends - `splitwise-pp-cli get-friends` — **Note**: `group` objects only include group balances with that friend. **get-group** — Manage get group - `splitwise-pp-cli get-group ` — Get information about a group **get-groups** — Manage get groups - `splitwise-pp-cli get-groups` — **Note**: Expenses that are not associated with a group are listed in a group with ID 0. **get-notifications** — Manage get notifications - `splitwise-pp-cli get-notifications` — Return a list of recent activity on the users account with the most recent items first. **get-user** — Manage get user - `splitwise-pp-cli get-user ` — Get information about another user **remove-user-from-group** — Manage remove user from group - `splitwise-pp-cli remove-user-from-group` — Remove a user from a group. Does not succeed if the user has a non-zero balance. **undelete-expense** — Manage undelete expense - `splitwise-pp-cli undelete-expense ` — **Note**: 200 OK does not indicate a successful response. The operation was successful only if `success` is true. **undelete-group** — Manage undelete group - `splitwise-pp-cli undelete-group ` — Restores a deleted group. **Note**: 200 OK does not indicate a successful response. **update-expense** — Manage update expense - `splitwise-pp-cli update-expense ` — Updates an expense. **update-user** — Manage update user - `splitwise-pp-cli update-user ` — Update a user ## Freshness Contract This printed CLI owns bounded freshness only for registered store-backed read command paths. In `--data-source auto` mode, those paths check `sync_state` and may run a bounded refresh before reading local data. `--data-source local` never refreshes. `--data-source live` reads the API and does not mutate the local store. Set `SPLITWISE_NO_AUTO_REFRESH=1` to skip the freshness hook without changing source selection. Covered paths: - `splitwise-pp-cli get-categories` - `splitwise-pp-cli get-categories get` - `splitwise-pp-cli get-categories list` - `splitwise-pp-cli get-categories search` - `splitwise-pp-cli get-comments` - `splitwise-pp-cli get-comments get` - `splitwise-pp-cli get-comments list` - `splitwise-pp-cli get-comments search` - `splitwise-pp-cli get-currencies` - `splitwise-pp-cli get-currencies get` - `splitwise-pp-cli get-currencies list` - `splitwise-pp-cli get-currencies search` - `splitwise-pp-cli get-current-user` - `splitwise-pp-cli get-current-user get` - `splitwise-pp-cli get-current-user list` - `splitwise-pp-cli get-current-user search` - `splitwise-pp-cli get-expenses` - `splitwise-pp-cli get-expenses get` - `splitwise-pp-cli get-expenses list` - `splitwise-pp-cli get-expenses search` - `splitwise-pp-cli get-friends` - `splitwise-pp-cli get-friends get` - `splitwise-pp-cli get-friends list` - `splitwise-pp-cli get-friends search` - `splitwise-pp-cli get-groups` - `splitwise-pp-cli get-groups get` - `splitwise-pp-cli get-groups list` - `splitwise-pp-cli get-groups search` - `splitwise-pp-cli get-notifications` - `splitwise-pp-cli get-notifications get` - `splitwise-pp-cli get-notifications list` - `splitwise-pp-cli get-notifications search` When JSON output uses the generated provenance envelope, freshness metadata appears at `meta.freshness`. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash splitwise-pp-cli which "" ``` `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. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Net position for an agent ```bash splitwise-pp-cli balances --agent --select by_currency ``` Returns just the headline numbers an agent needs to report the user's overall money position. ### Inspect a group's members and balances (narrow a verbose payload) ```bash splitwise-pp-cli get-groups --agent --select name,members.first_name,members.balance.amount ``` get-groups returns deeply nested members and balance arrays; --select with dotted paths keeps only the fields you need so an agent doesn't burn context on the full payload. ### Verify the local store before trusting it ```bash splitwise-pp-cli reconcile --since 30d --agent ``` Diffs the local store against live get_expenses and reports anything missing, stale, or deleted remotely before you build a settle-up or report on it. ### One-shot agent state check ```bash splitwise-pp-cli brief --agent --compact ``` Returns net position, the stalest debts, and recent activity in one bounded call instead of three separate fan-out calls. ### Plan the fewest transfers to settle a trip ```bash splitwise-pp-cli settle-up "Tahoe Trip" ``` Prints the minimum-transfer settle-up plan; add --record to create the payment expenses. ### Who is carrying the cost in a group ```bash splitwise-pp-cli fairness --by contribution --group "Tahoe Trip" --agent ``` Classifies each member as carrier or rider from paid vs owed shares; --by risk and --by collectability switch lenses. The --agent output is wrapped as {meta, results}. ### Turn a friend, group, or category name into its id ```bash splitwise-pp-cli resolve "Alex Kim" --type friend --agent ``` Use resolve whenever you need an id for a name: it matches the local store (no network) and returns the candidate records. Do not page through get-friends or get-groups and grep for a name; resolve is the id lookup. ## Auth Setup Splitwise authenticates with a personal API key used as an HTTP Bearer token. Register an app at https://secure.splitwise.com/apps to get your key, then set SPLITWISE_API_KEY. The Splitwise API also offers OAuth 2.0 (authorization-code) for multi-user apps, but this CLI authenticates as a single user with a personal API key only — there is no OAuth login flow in the binary. Run `splitwise-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash splitwise-pp-cli get-categories --agent ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv