# Actual Budget

`@finopsbricks/fob-actual` connects to your [Actual Budget](https://actualbudget.org/) 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](/docs/actual/cli/install) |
| Read or change your budget from your own scripts and workers | **The library**, `import { fobActual }` | [Use the library](/docs/actual/integration/library) |

Both need the same thing first: your sync server's address and a way to sign in. [Connect your budget](/docs/actual/connect) takes a couple of minutes.

<Callout type="info" title="Beta">
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](#beta-limits).
</Callout>

<Video title="fob-actual in 90 seconds" />

## 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-run` and 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](/docs/actual/cli/reference/setup) 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.** `--limit` trims results after they're read.
- **Tables show amounts with two decimals** and no currency symbol. `--json` uses 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](https://github.com/finopsbricks/fob-actual/issues).

<Callout type="info">
Actual Budget is open source under the MIT license. fob-actual is not affiliated with or endorsed by the Actual Budget project.
</Callout>