spense CLI

A token-efficient, agent-friendly command-line client for $pense.

Install

npm i -g spense-cli
spense --help

Requires Node 18+. Updating later: npm i -g spense-cli@latest.

Auth

Create a token in the app (Settings → tokens), then:

spense auth login --token spn_xxxxxxxx      # saved to ~/.spense/config.json (0600)
spense auth status

Or set SPENSE_TOKEN / SPENSE_API_URL in the environment. The base URL defaults to the $pense app, so you normally don't need to set it.

Read commands

spense summary   --month 2026-08
spense digest    --month 2026-08              # one-call "where did my money go"
spense breakdown --by category|account|merchant --month 2026-08
spense trend     --months 12
spense tx list   [--month --account --category --tag --direction --min --max --q --uncategorized --limit --cursor]
spense tx get    <id>
spense account list · category list · tag list
spense loan list · loan get <id>

Write commands

spense tx add        --account HDFC --amount 1200.50 --direction debit --desc "Swiggy" [--date --merchant --category --note --tag]
spense tx update     <id> [--amount --direction --desc --date --merchant --category --note]
spense tx categorize <id,id,…> --category EMIs         # or --uncategorize to clear
spense tx delete     <id>
spense category add|update|delete   [--name --color --icon]
spense tag add|update|delete        [--name --color]
spense loan add      --contact "Nishank" --direction lent|borrowed --amount 5000 [--date --note]
spense loan entry add <loanId> --amount 1000 --type principal|repayment [--date --note --txn]
spense contact add   --name "Nishank" [--phone --note]

Rules & import

spense rule list
spense rule add    --pattern SWIGGY --category Food [--field merchant|description --match contains|equals|starts_with|regex --priority 100]
spense rule update <id> [--pattern --category --field --match --priority --active true|false]
spense rule delete <id>
spense rule apply                       # backfill: categorize existing uncategorized txns

spense import <file> --account HDFC [--password ****]   # .xls/.xlsx/.csv (or .pdf if the parser is deployed)
spense tx list   --status pending        # imports stage as pending — review them
spense tx confirm <id,id,…>              # confirm so they leave the review queue

Imports run your active rules automatically; rule apply re-runs them over already-imported uncategorized transactions. PDF import needs the parser sidecar deployed (PARSER_SERVICE_URL); Excel/CSV parse in-process.

Names resolve to ids inside the CLI (--category EMIs, --account HDFC). Dates default to today (IST). Writes print ✓ <id> (or the JSON result with --json).

Token-efficient output (for agents)

• --json — compact JSON. --format tsv|csv|table — TSV/CSV state the header once (cheap for lists).
• --fields date,amount,category — keep only these columns.
• --limit N + --cursor — bounded pages; a # more rows hint prints to stderr.
• Names, not UUIDs — --category EMIs, --account HDFC resolve inside the CLI.
• spense schema --json — the entire command spec in one call (agent discovery).

Errors print error: CODE — message (or {"error":{…}} with --json) and set an exit code: 2 auth · 3 not found · 4 validation · 5 network · 1 other.