Actual Budget Assistant

Query your Actual Budget data using natural language. Fast, offline-capable, and clean output.

Prerequisites

1. Install the Actual Budget API package:

   npm install -g @actual-app/api
   

2. Set your server credentials:

   export ACTUAL_SERVER_URL=https://actual.example.com
   export ACTUAL_PASSWORD=yourpassword
   export ACTUAL_SYNC_ID=your-sync-id
   

3. Self-signed certificates (if needed):

   export ACTUAL_ALLOW_SELF_SIGNED_CERTS=true
   

4. Run initial setup to download your budget:

   node scripts/setup-budget.js
   

Quick Start

# All accounts balance
node scripts/actual-cli.js balance --offline

# Specific account (uses partial name matching)
node scripts/actual-cli.js balance --account=jago --offline

# Transactions for a date range
node scripts/actual-cli.js transactions --start=2026-01-01 --end=2026-01-31 --account=bca --offline

# Import transactions from JSON
node scripts/actual-cli.js import --data='[{"date":"2026-01-15","account":"uuid","payee":"Starbucks","amount":450}]'

# Full power (sync with server)
node scripts/actual-cli.js balance

Features

1. Offline Mode (--offline)

Works entirely from local cache. No server connection needed. Fast and reliable.

2. Account Name Resolution

Use partial names instead of UUIDs:

• --account=jago matches "Jago (Utama+GoPay)"
• --account=bca matches "BCA"

3. Clean Output

Filters API noise (TLS warnings, breadcrumbs, sync logs) automatically. Only shows the data you want.

4. Graceful Sync Failures

If server sync fails, automatically falls back to cached data.

CLI Reference

Usage: actual-cli.js <command> [options]

Commands:
  transactions --start=DATE --end=DATE [--account=NAME] [--limit=N]
  balance [--account=NAME]
  import --data='JSON_ARRAY'

Options:
  --offline    Work from cache only (no server sync)

Examples:
  actual-cli.js transactions --start=2026-01-01 --end=2026-01-31
  actual-cli.js transactions --start=2026-01-01 --end=2026-01-31 --account=jago
  actual-cli.js balance --account=bca
  actual-cli.js balance --offline
  actual-cli.js import --data='[{"date":"2026-01-15","account":"uuid","payee":"Starbucks","amount":4.50}]'

Import Command

Import transactions from inline JSON. Use shell quotes to pass the data.

JSON Format:

[
  {
    "date": "2026-01-15",
    "account": "account-uuid",
    "amount": 4.50,
    "payee": "Starbucks",
    "note": "Morning coffee"
  }
]

Required fields: date, account, amount

• date: YYYY-MM-DD format
• account: Account UUID (not name - must be actual ID)
• amount: Decimal number (positive = income, negative = expense)
• payee: Optional payee name
• note: Optional note/memo

The API handles deduplication automatically based on transaction data.

Natural Language Queries

User asks	What happens
"What's my BCA balance?"	Resolves "BCA" → account ID → runs balance
"List transactions in Jago last month"	Resolves dates + account → runs transactions
"Export my spending to CSV"	Runs transactions with CSV output

Pro Tips

• Always use --offline for instant reads (data is cached locally)
• Date formats: 2026-01-01, 2026-01 (full month)
• First run must download budget from server (or use setup-budget.js)