@fire-zu/billclaw-cli

Standalone command-line interface for BillClaw financial data management.

Overview

The CLI package provides a command-line tool for managing financial data without requiring any AI framework. It includes:

• Interactive setup wizard for connecting accounts
• Manual transaction sync from Plaid and Gmail
• Account status monitoring
• Configuration management
• Export to Beancount and Ledger formats
• Import from CSV, OFX, and QFX files

Installation

Global Installation

npm install -g @fire-zu/billclaw-cli

Local Installation

npm install @fire-zu/billclaw-cli
npx billclaw

Quick Start

# Interactive setup wizard
billclaw setup

# Sync all accounts
billclaw sync

# Sync specific account
billclaw sync --account plaid-123

# Show account status
billclaw status

# Export transactions
billclaw export --format beancount --output transactions.beancount

Commands

setup

Interactive setup wizard for connecting accounts.

billclaw setup

Supports:

• Plaid (bank accounts via Plaid Link)
• Gmail (email bills)
• GoCardless (European open banking)

sync

Manually trigger transaction sync.

# Sync all accounts
billclaw sync

# Sync specific account
billclaw sync --account <id>

# Sync all (explicit)
billclaw sync --all

status

Show connection status and recent sync results.

billclaw status

Displays:

• Account ID and type
• Connection status
• Last sync time

config

Manage plugin configuration.

# List all configuration
billclaw config --list

# Get specific value
billclaw config --key storage.path

# Set value
billclaw config --key storage.format --value json

export

Export transactions to Beancount or Ledger format.

# Export to Beancount
billclaw export --format beancount --output transactions.beancount

# Export specific account
billclaw export --account plaid-123 --format ledger

# Export specific period
billclaw export --year 2024 --month 1

import

Import transactions from external files.

# Import from CSV
billclaw import transactions.csv

# Import from OFX
billclaw import statement.ofx --account checking-123

Configuration

Configuration is stored in ~/.billclaw/config.json:

{
  "accounts": [],
  "webhooks": [],
  "storage": {
    "path": "~/.billclaw",
    "format": "json",
    "encryption": { "enabled": false }
  },
  "sync": {
    "defaultFrequency": "daily",
    "maxRetries": 3,
    "retryOnFailure": true
  },
  "plaid": {
    "environment": "sandbox"
  }
}

Data Storage

By default, data is stored in ~/.billclaw/:

~/.billclaw/
├── config.json           # Configuration
├── data/                 # Transaction storage
│   ├── transactions/     # Per-account transactions
│   └── accounts/         # Account metadata
└── exports/              # Exported files

Exit Codes

• 0 - Success
• 1 - Error occurred

Examples

Complete Workflow

# 1. Setup accounts
billclaw setup

# 2. Sync transactions
billclaw sync

# 3. Check status
billclaw status

# 4. Export to Beancount
billclaw export --format beancount -o main.beancount

Monthly Accounting Export

# Export last month's transactions
billclaw export   --format beancount   --year 2024   --month 1   --output january.beancount

License

MIT