Bill Ballou
b2735d24fa
Read-only Actual Budget API integration with shell helpers for querying accounts, transactions, budgets, categories, and spending.
116 lines
3.9 KiB
Markdown
116 lines
3.9 KiB
Markdown
---
|
|
name: actual-budget
|
|
description: Use when the user asks about finances, budget, spending, account balances, transactions, categories, or money. Triggers on questions like "how much did I spend", "what's my balance", "budget status", "spending breakdown", "net worth", or any financial query against the Actual Budget server.
|
|
---
|
|
|
|
# Actual Budget Finance Skill
|
|
|
|
Query your Actual Budget instance for financial data — accounts, transactions, budgets, categories, and spending analysis. Read-only access.
|
|
|
|
## Setup
|
|
|
|
Run the setup wizard (one-time):
|
|
|
|
```bash
|
|
SKILL_DIR=$(dirname "$(find ~/.claude -path '*/actual-budget/scripts/setup.sh' 2>/dev/null | head -1)")
|
|
bash "${SKILL_DIR}/setup.sh"
|
|
```
|
|
|
|
The wizard prompts for:
|
|
- **Server URL** — Your Actual Budget instance (default: `https://budget.prettyhefty.com`)
|
|
- **Password** — Server authentication password
|
|
- **Budget sync ID** — Selected from the list of available budgets
|
|
|
|
Configuration is stored in:
|
|
- `~/.config/actual-budget/config` — Server URL, sync ID
|
|
- `~/.config/actual-budget/password` — Server password (chmod 600)
|
|
|
|
## Using the Helper Functions
|
|
|
|
Source the helper script:
|
|
|
|
```bash
|
|
source "$(find ~/.claude -path '*/actual-budget/scripts/actual-helper.sh' 2>/dev/null | head -1)"
|
|
```
|
|
|
|
### Available Functions
|
|
|
|
**Configuration:**
|
|
- `actual_config` — Show current configuration
|
|
- `actual_check_config` — Verify configuration is complete
|
|
|
|
**Accounts:**
|
|
- `actual_accounts` — List all accounts with current balances
|
|
- `actual_balance [name]` — Get balance for specific account (fuzzy match by name)
|
|
|
|
**Budget:**
|
|
- `actual_budget_months` — List all months with budget data
|
|
- `actual_budget_month [YYYY-MM]` — Budget summary for a month (defaults to current)
|
|
|
|
**Transactions:**
|
|
- `actual_transactions [account] [start_date] [end_date]` — List transactions (all accounts if none specified)
|
|
- `actual_spending_by_category [start_date] [end_date]` — Spending breakdown by category
|
|
|
|
**Reference Data:**
|
|
- `actual_categories` — List all categories
|
|
- `actual_category_groups` — List category groups
|
|
- `actual_payees` — List all payees
|
|
- `actual_budgets` — List budgets available on server
|
|
|
|
**Advanced:**
|
|
- `actual_query '<json>'` — Run an arbitrary ActualQL query
|
|
|
|
### Output Format
|
|
|
|
All functions output JSON. Amounts are in decimal format (e.g., `123.45`), not Actual's internal integer format.
|
|
|
|
## Common Query Patterns
|
|
|
|
### "How much did I spend this month?"
|
|
```bash
|
|
actual_spending_by_category "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)"
|
|
```
|
|
|
|
### "What's my balance across all accounts?"
|
|
```bash
|
|
actual_accounts
|
|
```
|
|
|
|
### "Show me transactions for Groceries this month"
|
|
First get categories to find the ID, then query transactions and filter:
|
|
```bash
|
|
actual_categories # find the category ID
|
|
actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)" # then filter by category in the JSON output
|
|
```
|
|
|
|
### "Am I over budget this month?"
|
|
```bash
|
|
actual_budget_month "$(date +%Y-%m)"
|
|
```
|
|
The result includes `budgeted`, `spent`, and `balance` per category.
|
|
|
|
### "What did I spend at [payee] recently?"
|
|
```bash
|
|
actual_transactions "" "2026-01-01" "$(date +%Y-%m-%d)"
|
|
```
|
|
Then filter the JSON output by payee name.
|
|
|
|
## ActualQL Quick Reference
|
|
|
|
For complex queries, use `actual_query` with a JSON query object:
|
|
|
|
```bash
|
|
actual_query '{"table":"transactions","filter":{"date":{"$gte":"2026-03-01"}},"select":["date","amount","payee","category"]}'
|
|
```
|
|
|
|
**Operators:** `$eq`, `$lt`, `$lte`, `$gt`, `$gte`, `$ne`, `$regex`, `$like`, `$oneof`, `$and`, `$or`
|
|
|
|
**Tables:** `transactions` (primary), plus accounts, categories, payees accessible via the helper functions.
|
|
|
|
## Troubleshooting
|
|
|
|
- **"Config not found"** — Run `setup.sh`
|
|
- **"@actual-app/api not installed"** — Run `cd <skill-scripts-dir> && npm install @actual-app/api`
|
|
- **Connection errors** — Check server URL and password in `~/.config/actual-budget/config`
|
|
- **Empty results** — Verify the sync ID matches an active budget (`actual_budgets`)
|