@lumly/cli

Command-line interface for the Lumly personal finance API. Authenticate via Google OAuth and manage accounts, transactions, categories, imports, and more from the terminal.

Setup

# From the monorepo root
pnpm install

# Build the CLI
pnpm --filter @lumly/cli build

# Or run in dev mode
pnpm --filter @lumly/cli dev -- <command>

After building, the lumly binary is available at packages/cli/dist/index.js. You can link it globally:

cd packages/cli && pnpm link --global

Authentication

The CLI authenticates via Google OAuth. A local server is started on port 18920 to receive the callback.

# Login (opens browser for Google sign-in)
lumly login

# Check current user
lumly whoami

# Clear session
lumly logout

Commands

Accounts

lumly accounts list [--json]
lumly accounts create -n "Checking"
lumly accounts update --id <id> -n "Savings" --active true
lumly accounts delete --id <id>

Transactions

Alias: lumly tx

# List with filters
lumly tx list [--from 2025-01-01] [--to 2025-01-31] [--account <id>] \
              [--category <id>] [--uncategorized] [--search <query>] \
              [--merchant <key>] [--type expense|income] \
              [--limit 20] [--cursor <cursor>] [--json]

# Inbox (uncategorized transactions)
lumly tx inbox [--limit 20] [--json]
lumly tx inbox-count

# Search descriptions
lumly tx search -q "grocery" [--limit 10] [--json]

# Create a manual transaction
lumly tx create -a -42.50 -d 2025-03-01 --desc "Coffee" --account <id> \
                [--category <id>] [--note "Morning coffee"] [--kind <kind>]

# Update
lumly tx update --id <id> [-a <amount>] [-d <date>] [--desc <text>] \
                [--category <id>] [--note <text>] [--kind <kind>] [--account <id>]

# Delete / restore
lumly tx delete --id <id>
lumly tx restore --id <id>

# Categorize
lumly tx categorize --id <id> --category <id>
lumly tx bulk-categorize --merchant <key> --category <id>

Categories

lumly categories list [--json]
lumly categories usage -m 2025-03 [--json]
lumly categories create -n "Subscriptions"
lumly categories update --id <id> -n "New Name"
lumly categories delete --id <id>

Dashboard

lumly dashboard stats -m 2025-03 [--json]

Imports

lumly imports list --account <id> [--json]
lumly imports status --id <id> [--json]
lumly imports upload -f transactions.csv --account <id> --mapping '{"date":"Date","amount":"Amount"}' [--json]
lumly imports delete --id <id>

Exports

lumly exports transactions [--from 2025-01-01] [--to 2025-03-31] \
                           [--account <id>] [--category <id>] \
                           [-o transactions.csv]

Billing

lumly billing status [--json]
lumly billing cancel

Preferences

Alias: lumly prefs

lumly prefs get [--json]
lumly prefs set-currency -c EUR
lumly prefs set-account --id <id>
lumly prefs set-locale -l pt-BR

Onboarding

lumly onboarding status [--json]
lumly onboarding complete

Feedback

lumly feedback -m "Love the CLI!"

Output Formats

Most list commands support --json for machine-readable output. By default, results are displayed as formatted tables.