Ledgr CLI & MCP Server

Terminal and AI-agent client for Ledgr — a privacy-first, end-to-end encrypted family finance tracker.

Current package: [email protected]

npx -y ledgr-cli@latest --help

Product model

| Step | Where | |------|--------| | Sign up, set PIN, create/join group | Web app only | | Repair cloud keys for CLI | Web → Developer Settings | | Unlock vault, add/list/update/delete txs, accounts | CLI / MCP |

The CLI does not onboard users. Complete setup in the web app first, then connect with ledgr doctor → ledgr unlock.

Security

Ledgr uses zero-knowledge, client-side encryption:

1. PIN → personal key (PBKDF2)
2. Personal key → decrypt RSA private key
3. Private key → open group key envelope
4. Group key → AES-256-GCM for transactions/accounts

The CLI decrypts only on your machine. Session file: ~/.ledgr/session.json (0600).

Install

# One-shot
npx -y ledgr-cli@latest <command>

# Global
npm install -g ledgr-cli
ledgr --help

Quick start

# 1) After web onboarding — verify cloud handoff
ledgr doctor

# 2) Unlock (prompts email, password, PIN)
ledgr unlock
# ledgr unlock --permanent    # 1-year session (agents)
# ledgr unlock --expiry 7     # N days

# 3) Work
ledgr accounts --summary
ledgr list --limit 20
ledgr add --amount 150 --category food --note "Coffee"

Auth options

A. Session (recommended)
ledgr unlock → session reused by later commands and MCP.

B. Environment variables (scripts / CI):

export LEDGR_EMAIL="[email protected]"
export LEDGR_PASSWORD="…"
export LEDGR_PIN="123456"

ledgr lock      # clear session
ledgr status    # session state

Commands

| Command | Purpose | |---------|---------| | doctor | Check cloud vault ready for CLI (after web onboard) | | unlock | Authenticate + save session | | lock / status | Clear / inspect session | | list | Recent transactions (ids, times, NO_ACCOUNT flag) | | add | Create transaction | | update | Change amount, category, note, type, account, date | | delete / rm | Delete one or many (--yes required) | | move | Reassign txs to another account | | accounts | List / create accounts; --summary for group wealth | | export | Full decrypted JSON dump | | mcp | MCP server for AI agents | | help | Global or per-command help |

ledgr help
ledgr help add
ledgr accounts --help

Transactions

Add

ledgr add --amount 15.50 --category food --note "Coffee" --type expense

| Flag | Description | |------|-------------| | --amount | Rupees (required) | | --category | e.g. food, bills, salary | | --note | Memo | | --type | expense (default) or income | | --accountId | Optional; omit = no account (still counts in wealth) | | --date / --time | ISO, YYYY-MM-DD HH:mm, or epoch (default: now) | | --external-id / --utr / --ref | Idempotency key (skip if already exists) | | --source | Prefix for UTR (e.g. hdfc) | | --fingerprint | Idempotent fingerprint when no UTR |

Exact time (agents / bank statements):

ledgr add --amount 320 --category food --note "Lunch" \
  --date "2026-07-15T13:45:00+05:30" \
  --utr UTR123456789 --source hdfc

Re-running the same --utr / --external-id skips create (no duplicate).

Update / delete / move

ledgr list --limit 20
ledgr update --id <txId> --amount 200 --note "Corrected"
ledgr update --id <txId> --date "2026-07-10T18:00:00+05:30"
ledgr update --id <txId> --accountId <accId>   # or none to unassign
ledgr delete --id <txId> --yes
ledgr delete --ids id1,id2 --yes
ledgr move --ids id1,id2 --to <accountId> --yes

Accounts

ledgr accounts
ledgr accounts --summary
ledgr accounts --add --name "IDFC" --type bank --balance 1643

| Flag | Description | |------|-------------| | --add | Create account | | --name | Required with --add | | --type | bank | cash | credit | investment | | --balance | Opening balance (₹); stored as an Opening balance income txn | | --icon | Optional icon name |

Totals (same rules as the web app)

Total wealth = sum(account balances) + (unassigned income − unassigned expense)
Total income / expense = all transactions (including no-account)
Per-account balance = only txs linked to that account

Unassigned txs show as NO_ACCOUNT in list and still affect total wealth.

Doctor (cloud handoff)

ledgr doctor

Checks Firestore for PIN salt, encrypted private key, groupId, and group envelope.

If not ready:

1. Web: finish PIN + group
2. Web: Developer Settings → Repair cloud vault
3. ledgr doctor again → ledgr unlock

MCP (Claude Desktop, etc.)

Session-based (recommended): unlock once, then:

{
  "mcpServers": {
    "ledgr": {
      "command": "npx",
      "args": ["-y", "ledgr-cli", "mcp"]
    }
  }
}

Env-based: set LEDGR_EMAIL, LEDGR_PASSWORD, LEDGR_PIN in the MCP env block.

Tools

| Tool | Purpose | |------|---------| | unlock_vault | Authenticate | | add_transaction | Add (supports date, externalId / utr, optional accountId) | | update_transaction | Update fields | | delete_transactions | Bulk delete by ids | | move_transactions | Bulk move to account | | list_accounts | Accounts + group wealth (web-aligned) | | list_categories | Categories | | get_group_info | Group metadata | | export_data | Full dump |

Config path (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json

Also copyable from the web app: Profile → Developer Settings.

Agent tips

1. Always use --date from the statement (not “now”).
2. Always pass --utr / --external-id when the bank provides a ref.
3. Prefer ledgr unlock --permanent for long-lived agents.
4. accountId is optional; no-account txs still count in wealth.
5. After web setup changes: ledgr doctor before unlock.

Categories (standard)

Expense: food, rent, transport, groceries, health, bills, fun, emi
Income: salary, freelance, business, investment

Known limitations (v1)

• Onboarding is web-only (by design).
• Cloud keys can be incomplete until Repair cloud vault.
• Fingerprint idempotency (no UTR) can collide for two identical rows same day.
• CLI bulk delete has no undo (web bulk delete has Undo toast).
• Encrypted cloud store: server cannot run SQL-style aggregates; clients compute totals after decrypt.

Links

• Web app: https://ledgr-f4eb3.web.app
• npm: https://www.npmjs.com/package/ledgr-cli

ledgr help <command>