splitwise-cli

A terminal-first CLI for Splitwise with readable tables, structured JSON/YAML output, and built-in skill files for coding assistants.

Links

• npm package: splitwise-cli on npm
• Code repository: michaelschnyder/splitwise-cli
• Splitwise library: keriwarr/splitwise
• Splitwise API docs: dev.splitwise.com

Installation

npm install -g splitwise-cli
# or
npx splitwise-cli --help

Quick Start

# save login credentials (named entries are supported)
splitwise-cli login token YOUR_TOKEN --name personal
# splitwise-cli login oauth YOUR_KEY YOUR_SECRET --name work

# verify current login
splitwise-cli login whoami

# common commands
splitwise-cli friends list
splitwise-cli groups list
splitwise-cli expenses list --from -30d --all

Configuration is stored under ~/.splitwise-cli/.

Supported Areas

Area	Summary	Commands	Jump
Login	Manage multiple login credentials and inspect current user	token, oauth, list, status, select, default, remove, validate, whoami	Login
Friends	List friends and balances	list	Friends
Groups	List groups and fetch group details	list, get	Groups
Expenses	Query expenses with date/person/group filters	list, get	Expenses
Profiles	Manage profile restrictions, active profile, and lock state	list, show, create, edit, select, remove, validate, lock	Profiles
Skills	List/install/create assistant skill files	list, path, install, create	Skills

For global log flags, output streams, and debug behavior, see Console Logging.

Global profile selection:

• -p, --profile <name> selects a profile for the current command.
• If the active profile is locked, switching profiles is blocked until the profile file is edited manually.

Global credential selection:

• -c, --credential <name> selects a credential for the current command.
• Resolution order: explicit --credential -> profile credential -> active login credential -> default login credential.

Output Formats

Use -o / --output when available.

Format	Use case
table	default terminal view
json	scripts, pipes, automation
yaml	readable structured output

When --output is omitted, commands run in TUI mode by default (readable table layout with an intro line, title-cased headers, and a single summary footer line with items/time/source).

splitwise-cli friends list -o yaml
splitwise-cli expenses list --from -7d -o json

Login

Create login credentials at splitwise.com/apps/register.

Commands

splitwise-cli login token YOUR_TOKEN --name personal
splitwise-cli login oauth YOUR_KEY YOUR_SECRET --name work
splitwise-cli login list
splitwise-cli login status
splitwise-cli login select work
splitwise-cli login default personal
splitwise-cli login validate work
splitwise-cli login whoami
splitwise-cli login whoami -o json

Example Response (login whoami -o json)

{
  "id": 12345678,
  "name": "Alex Example",
  "email": "alex@example.com"
}

Friends

Commands

splitwise-cli friends list
splitwise-cli friends list -o json

Example Response (friends list)

Showing friends and balances

Id         Name            Balance
────────   ─────────────   ─────────────
11111111   Alice Example   -12.40 USD
22222222   Bob Example     settled up

• 2 item(s) | 43 ms | source: Splitwise API

Example Response (friends list -o json)

[
  {
    "id": 11111111,
    "name": "Alice Example",
    "balance": "-12.40 USD"
  },
  {
    "id": 22222222,
    "name": "Bob Example",
    "balance": "settled up"
  }
]

Groups

Commands

splitwise-cli groups list
splitwise-cli groups get <groupId>

Expenses

Commands

splitwise-cli expenses list [options]
splitwise-cli expenses get <expenseId>

Core Options (expenses list)

Flag	Short	Description
`--group <id	name>`	-g
`--friend <id	name>`	-u
--from <date>	-f	include expenses on or after date
--to <date>		include expenses on or before date
--max <n>	-m	max rows unless --all is used
--all		walk all API pages
--mine		shorthand for --payer @me
`--involved <@me	id	name>`
`--payer <@me	id	name>`
--query <string>		shorthand key:value query
--output <format>	-o	table, json, or yaml

Date values support ISO (2026-01-01) and relative values (-10d, -2w, -1month, -1y).

Example Commands

splitwise-cli expenses list --from -30d --all -o json
splitwise-cli expenses list --group Flatmates --mine --from -1month
splitwise-cli expenses list --involved Alice --from -14d
splitwise-cli expenses get 99999 -o yaml

Example Response (expenses list)

Showing expenses from 2026-06-01 to 2026-06-13

ID         Date         Group/Friend   Paid By       Description              Costs      Category   Share
────────   ──────────   ────────────   ───────────   ───────────────────────  ─────────  ────────   ───────────
99999      6/10/2026    Flatmates      Alex Example  Groceries                48.90 USD  Food       24.45 USD
99998      6/09/2026    Flatmates      Alex Example  Rent transfer -> Jo      650.00 USD Payment    325.00 USD

• 2 item(s) | 71 ms | source: Splitwise API

Example Response (expenses list -o json)

[
  {
    "id": 99999,
    "date": "2026-06-10T10:25:00Z",
    "description": "Groceries",
    "cost": "48.90",
    "currency": "USD",
    "category": "Food",
    "isPayment": false,
    "paidBy": "Alex Example",
    "group": "Flatmates",
    "splits": [
      { "userId": 12345678, "name": "Alex Example", "paid": "48.90", "owes": "24.45" },
      { "userId": 87654321, "name": "Jo Example", "paid": "0.00", "owes": "24.45" }
    ],
    "createdAt": "2026-06-10T10:25:10Z",
    "createdByName": "Alex Example",
    "updatedByName": "Alex Example",
    "deletedByName": ""
  }
]

Profiles

Profiles control what the CLI is allowed to do and can optionally bind a credential name.

Restriction semantics:

• limitExpensesToGroupIds / limitExpensesToFriendIds omitted or null: unrestricted
• []: nobody allowed
• [id1, id2, ...]: only listed ids are allowed

Lock behavior:

• profiles lock is one-way from the CLI (no unlock command)
• lock confirmation is interactive in default TUI mode
• in explicit output mode, pass --yes to confirm lock
• when locked, login updates and profile/credential switching are blocked

Commands

splitwise-cli profiles list
splitwise-cli profiles show default
splitwise-cli profiles create work --create-expenses no --profile-credential personal
splitwise-cli profiles edit work --limit-expenses-to-groups Flatmates,12345 --profile-credential work
splitwise-cli profiles select work
splitwise-cli profiles validate work
splitwise-cli profiles lock work

Core Options (profiles create|edit)

Flag	Description
`--create-expenses <yes	no>`
`--update-expenses <yes	no>`
`--delete-expenses <yes	no>`
--limit-expenses-to-groups <items>	comma-separated ids/names, none for empty list, null for unrestricted
--limit-expenses-to-friends <items>	comma-separated ids/names, none for empty list, null for unrestricted
--clear-expense-group-limit	set expense group limit to unrestricted (null)
--clear-expense-friend-limit	set expense friend limit to unrestricted (null)
--profile-credential <name>	bind a profile to a credential
--clear-profile-credential	remove profile credential binding

Lock Recovery

When a profile is locked and an operation is blocked, the CLI prints the exact profile file path. To recover, edit that file and set "locked": false, or remove the file manually.

Skills

Built-in skills are copied into the package and can be installed for supported assistants.

Built-in Skill Names

• splitwise-cli
• splitwise-login
• splitwise-expenses
• splitwise-groups
• splitwise-friends
• splitwise-profiles

Commands

splitwise-cli skills list
splitwise-cli skills path [platform]
splitwise-cli skills install [platform]
splitwise-cli skills create

Supported platform values: claude, cursor, codex, opencode, windsurf, gemini, pi, all.

Example Response (skills list -o yaml)

- name: splitwise-cli
  type: skill
  description: Top-level splitwise-cli command reference and workflow.
- name: splitwise-expenses
  type: skill
  description: Expense listing filters, date parsing, and output behavior.

Console Logging

Logging and progress output are powered by consola.

Global logging controls:

Flag	Description
--log <level>	explicit level: error, warn, info, debug, trace
-v	increase verbosity (-v, -vv, -vvv, -vvvv)

Environment override:

• SW_DEBUG=1|yes|true forces trace-level logging in all modes.

Stream contract:

• Structured payloads (-o json, -o yaml) are printed to stdout.
• Logs, warnings, errors, and progress/status text are printed to stderr.

HTTP client logging:

• Request/response lifecycle logs include method, URL, status code, duration, and attempt.
• Error logs include method, URL, duration, and error message.
• Headers and response/request content are intentionally not logged.

Color behavior:

• Colored logs are shown only in table/TUI mode.
• JSON and YAML modes keep logs uncolored to stay script-friendly.

Icons and progress indicators:

• In TUI/table mode, status lines are icon-first (for example info/success) without the INFO text label.
• TUI progress uses an animated spinner on supported terminals.
• Progress completion uses a success icon when done and an error icon when failed.
• On minimal terminals, icon/spinner output falls back to ASCII-safe symbols.

Examples:

splitwise-cli friends list --log info
splitwise-cli expenses list -vv --from -30d
SW_DEBUG=true splitwise-cli groups get 12345 -o json

Development

npm install
npm run build
npm run dev -- expenses list --from -7d