npm package: @lumly/cli
Description: Lumly CLI - personal finance management from the terminal
Latest version: 0.0.1

# @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

```bash
# 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:

```bash
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.

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

# Login against a custom API URL
lumly login --api-url https://api.lumly.app

# Check current user
lumly whoami

# Clear session
lumly logout
```

## Configuration

Config is stored in `~/.lumly/config.json`. Environment variables take precedence:

| Variable              | Description            |
| --------------------- | ---------------------- |
| `LUMLY_API_URL`       | API base URL           |
| `LUMLY_SESSION_TOKEN` | Session token override |

```bash
# Show current config
lumly config
```

## Commands

### Accounts

```bash
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`

```bash
# 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

```bash
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

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

### Imports

```bash
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

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

### Billing

```bash
lumly billing status [--json]
lumly billing cancel
```

### Preferences

Alias: `lumly prefs`

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

### Onboarding

```bash
lumly onboarding status [--json]
lumly onboarding complete
```

### Feedback

```bash
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.