Actual Budget CLI
Your Actual Budget, from the terminal.
Import transactions, check balances, budget the month and query anything with ActualQL. CSV and JSON for your scripts, a dry run before every write, and a CLI your AI agent can drive.
$ npm install -g @finopsbricks/fob-actual$ fob actual transactions list --account Checking \ --from 2026-09-01 --fields date,payee,category,amount DATE PAYEE CATEGORY AMOUNT ------------------------------------------------ 2026-09-15 Employer Inc — 3,500.00 2026-09-05 Corner Grocery Groceries -84.23 2026-09-01 Landlord Rent -1,800.00
Two ways to drive it
The same commands work for you and for your agent.
You, in the terminal
Tables for reading, CSV and JSON for piping, and ActualQL when a list isn't enough. Every write has --dry-run, and deletes ask for --yes.
$ fob actual transactions import --account Checking --file sept.json --dry-runOutput and scripting →Your AI agent
Claude Code, Cursor and Codex already run commands. Point them at fob-actual and ask in plain English: "what did we spend on groceries each month this year?"
$ fob actual auth status # the agent's first commandUse with AI agents →What it covers
Talks to your own Actual sync server through Actual's official engine. Tested with Actual 26.9.
| Area | Resources | Writes |
|---|---|---|
| Transactions List by account and dates, add, import with Actual's duplicate detection and rules, edit, delete | List by account and dates, add, import with Actual's duplicate detection and rules, edit, delete | |
| Monthly budget Show a month by category, set amounts, carry over, hold funds for next month | Show a month by category, set amounts, carry over, hold funds for next month | |
| Accounts Balances (also on a past date), create, edit, close, reopen | Balances (also on a past date), create, edit, close, reopen | |
| Categories and payees Categories, groups, payees (including merge) and tags | Categories, groups, payees (including merge) and tags | |
| Rules and schedules List and show, create and edit as JSON | List and show, create and edit as JSON | |
| Query Any ActualQL query across accounts, with payee and category names | Any ActualQL query across accounts, with payee and category names | Read only |
Every command and option: command reference →
Set up in four steps
About five minutes, if you know your server's address and password.
- 1
Install
npm install -g @finopsbricks/fob-actual - 2
Have your server URL
The address you open Actual at, such as https://budget.example.com.
- 3
Sign in
fob-actual auth login --profile home --server-url … --password … - 4
List your accounts
fob-actual accounts list
Questions
Does my budget go through FinOpsBricks?
No. fob-actual runs on your machine and talks only to your own Actual sync server. Credentials stay in ~/.fob/fob-actual/config.yml (mode 0600) and are never sent to us.
Do I need a sync server?
Yes. fob-actual works with budgets on an Actual sync server, self-hosted or hosted (for example on PikaPods). A budget that lives only in one browser can't be reached.
My server signs in with Google or another OpenID provider. Does that work?
Yes. You copy a session token from a browser that's signed in to Actual, once. auth login walks you through it. Sign in with OpenID →
Is it safe to let it change my budget?
Every write has --dry-run to preview it, and every destructive action needs --yes. Writes sync into your live budget, so preview first, and practise on a copy of your budget. Changing your budget →
What does it cost?
Nothing. fob-actual is open source under Apache-2.0, and so is Actual itself.
Is it production-ready?
It's in Beta. The commands cover accounts, transactions, the budget, rules, schedules and queries. Bank sync isn't available, OpenID needs a copied token, and it's tested with Actual 26.9. Beta limits →
Actual Budget is open source under the MIT license. fob-actual is not affiliated with or endorsed by the Actual Budget project.