Actual Budget
@finopsbricks/fob-actual connects to your Actual Budget sync server. One npm package gives you two ways in:
| You want to… | Use | Start here |
|---|---|---|
| Query and update your budget from a terminal, or let an AI agent do it | The CLI, fob-actual | Install the CLI |
| Read or change your budget from your own scripts and workers | The library, import { fobActual } | Use the library |
Both need the same thing first: your sync server's address and a way to sign in. Connect your budget takes a couple of minutes.
fob-actual covers accounts, transactions, the monthly budget, categories, payees, rules, schedules, tags and ActualQL queries, with --dry-run on every write. It needs an Actual sync server. See Beta limits.
How it works#
Actual has no web API you can call. Instead, the official Actual engine (@actual-app/api) downloads your budget from the sync server into a local database, works on that copy, and syncs changes back. fob-actual runs that engine for you.
- It runs on your machine, or in your worker, and talks only to your own sync server. Your budget and credentials are never sent to FinOpsBricks.
- Each profile keeps a local copy of one budget in
~/.fob/fob-actual/data/<profile>/(owner-only). The first command downloads it; later commands sync only what changed. - Writes sync straight into your live budget, which other people may share. That's why every write has
--dry-runand every destructive action needs--yes.
What you can do#
| Area | Read | Change |
|---|---|---|
| Budgets | List budget files, show one, list months, show a month by category | Set budgeted amounts, carry over, hold and release funds, sync |
| Accounts | List with balances, show one, balance on a date | Create, edit, close, reopen, delete |
| Transactions | List by account and date range | Add, import with Actual's duplicate detection and rules, edit, delete |
| Categories, category groups, payees, tags | List, show | Create, edit, delete; merge payees |
| Rules, schedules | List, show | Create, edit, delete (as JSON) |
| Query | Any ActualQL query | — |
The command reference lists every command and option.
Beta limits#
- You need a sync server. Budgets kept only in one browser or desktop app, with no server, can't be reached.
- OpenID sign-in (Google, Authentik…) has no browser login in fob-actual: you copy a session token from a signed-in browser once. Password servers sign in directly.
- Bank sync isn't available from fob-actual.
- One budget session per process. Two fob-actual commands running at the same moment on the same profile aren't protected from each other.
- No paging.
--limittrims results after they're read. - Tables show amounts with two decimals and no currency symbol.
--jsonuses Actual's integer minor units. - Tested with Actual 26.9. fob-actual pins the Actual engine at 26.9.0.
Missing something? Open an issue on GitHub.
Actual Budget is open source under the MIT license. fob-actual is not affiliated with or endorsed by the Actual Budget project.