Actual Budget Assistant

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

Prerequisites

Install the Actual Budget API package:

npm install -g @actual-app/api

Set your server credentials:

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

Self-signed certificates (if needed):

export ACTUAL_ALLOW_SELF_SIGNED_CERTS=true

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 )