braatzledger user guide¶

Enough to go from nothing to a derived close. Short on purpose, and true today: where a feature is not built yet this page says so in a sentence rather than describing it.

🚀 Getting Started¶

What is braatzledger?¶

Your books, computed. You connect a bank, the feed lands your transactions, and every page is derived from the raw feed plus your own judgements — recomputed on every read. Nothing to key in, nothing to reconcile.

High-Level Overview¶

Create your ledger. Pick a tenant id and a passphrase at Create your ledger. A private vault is provisioned for you — usually under a minute; the page waits with you. Your books live in their own database with their own credentials, not a row-filter over a shared table.
Connect your bank. Sign in and open Connect a bank. The secure flow runs on Plaid's own site — your credentials go to your bank, never to us. When you finish there, the page notices by itself.
Watch the close derive. The first sync lands your lines; the Overview is computed from them on every load.
Categorise. Uncategorised lines carry a chip picker offering your own most-used labels, plus a box for a label your ledger hasn't seen yet. There is no imposed chart of accounts. A chip click files the line and returns you to the same filtered view.
Teach it a rule. The Rules room shows your rulebook and the queue of unexplained lines. Make a rule from a real line: name it, say how it matches (exact description, a pattern, or the amount's sign), and which category it assigns. Run all rules applies the whole book; running it twice decides nothing the second time. Retired rules stay visible, labelled.

What "derived" means¶

Your books are a computation: the raw feed plus your judgements, recomputed on every read. Corrections are new judgements appended to the record — history is never edited, so every number can answer "who decided this, and when".

Quickstart with Claude or ChatGPT¶

braatzledger ships an MCP server, so an assistant can read your books and file your judgements with your permission. See MCP / AI quickstart below.

🏦 Bank Connections¶

Connecting Your Bank (Plaid)¶

Connect a bank in the sidebar opens Plaid's hosted flow. Your bank credentials go to Plaid and your bank; this surface holds only a scoped token. The Connect page shows the state the connection is actually in and re-checks itself while you watch, so you never have to guess whether the handshake finished.

Sync Start Date¶

The first sync pulls the history your institution makes available through Plaid; there is no separate start-date control on this surface today. When you need a narrower window, ask for it at read time — every list and every export takes from and to bounds.

Disabling an account¶

Disconnecting is a two-click form in the Accounts room. It is one-way at the provider on purpose: disconnecting purges the bank credential we hold. Your lines stay yours, and your data leaves whole.

How and When to Run a Sync¶

Daily. A scheduled, cursor-sealed sync runs each day. "Cursor-sealed" means each run starts exactly where the last one stopped, so a run can never skip or double-count a line.
Sync now. The Accounts room's Sync now button — and POST /api/v1/sync-now — file a request. The watcher consumes it. One request per ledger at a time, and 409 when nothing is connected.
Sync history. The Accounts room and GET /api/v1/sync-history list the runs, newest first. The trace rows are the only thing allowed to say a sync happened: a request that was filed is not a sync that ran.

Re-Authenticating¶

When a bank invalidates a token, the connection's state says so on the Connect page and the fix is to run the Plaid flow again for that institution. Nothing about your existing lines changes when you do — the new token resumes the same cursor.

MFA¶

Multi-factor prompts from your bank are handled inside Plaid's hosted flow, on Plaid's own site. This surface never sees an MFA code. (For your braatzledger sign-in, two-step is in Settings and is a separate thing.)

💰 Data Fields (Columns)¶

Raw Data¶

Every line keeps the provider's verbatim record. GET /api/v1/transactions/A/{id} returns it under raw, alongside the line's lineage in words — what decided its category, and when.

Default Fields¶

The spreadsheet exports write a fixed set of columns, and the asterisks in the header are part of the name, not decoration:

*field — written once, and never overwritten if you edit it in the sheet.
**field — overwritten on a Force Re-Sync (and on the first write).
Any custom columns you add are never touched.

Transactions (6): *Name · **Date · **USD · **Account · **Category · **Plaid TX ID

Accounts (5): **Account Name · **USD Balance · **Institution · **Last Update · **Account ID

Two account cells are deliberately blank: this tier does not call Plaid's /accounts/get, so it holds no institution-given account name and no live balance. The columns are there because the header is a contract; the values stay empty rather than become invented.

Optional Fields¶

Add any of these column headers to your sheet and they are filled if we have the value: **Auth Date · **Category Header · *Vendor · *Sub-Account · **Check Number · *Notes · **USD Available.

Pending Transactions¶

A pending line is listed and in no total. It appears in the transactions list with state pending, it is excluded from every sum, and it is never written to any destination — not the CSV, not a connected sheet. When it posts, it lands as a booked line and the totals move then.

📊 Spreadsheet Integrations¶

CSV¶

Two files, from the same reads the pages already serve: transactions.csv and accounts.csv. A signed-in session or a read-only personal access token opens both. Booked lines only — the file's row count is the books' booked count.

Google Sheets¶

Settings → Integrations → Spreadsheets connects a Google account; the spreadsheet is created in your Drive, or you can bring your own. Sync is one-way, destination-ward: a normal sync never rewrites a row it already wrote.

Force Re-Sync¶

The one verb with teeth. It rewrites every ** column and restores rows you deleted in the sheet. Anything you typed into a * column survives it; anything you typed into a ** column does not.

Other destinations¶

Airtable, Notion and an OAuth app registry are not built. The Integrations list draws them greyed and labelled rather than as buttons that do nothing.

👥 Workspaces¶

Not built yet, and this is the honest version: today it is one ledger per sign-in. There are no shared workspaces, no invited members and no per-member roles. What exists instead is capability: every page that shows money passes an entitlement check on every request, and an entitlement is a row that can be revoked — taking effect on the next page load, with no deploy and no support ticket. Multi-member workspaces are a later project; until they ship, sharing a ledger means sharing a sign-in, and we would rather say so than draw a members table that does nothing.

🛠 Troubleshooting¶

Connection Problems¶

The Connect page renders the state the connection is actually in — not a spinner — and re-checks itself while you watch. If a handshake sticks, the state it names is the thing to act on.

Refusals¶

Every refusal on this surface names what to do next, and refusals are deliberate rather than accidental:

Sign-in refuses forgery. A tampered session cookie is refused outright, never quietly downgraded to a fresh anonymous session.
A refused read says so. If a ledger has withheld a read the page needs, the page says "this ledger has not granted the dashboard permission to read what this file is made of" rather than showing a zero. An unmeasured number and a measured one look identical on a page and mean opposite things.
A read-only token is refused on writes with 403, before the write runs.

Nothing appears after connecting¶

The first sync has to run. Check sync history: if there is no run, the request may still be queued; if there is a failed run, its row says why.

📈 Usage and Limits¶

Settings carries two meters, and they are the two a plan would bill on:

Bank connections in use, against the cap this surface enforces. The cap is read out of the feed's own source, never retyped — a number written down twice goes stale silently.
Transaction volume over a trailing window (30 days by default): the larger of money in and money out, never their sum and never the net, so a passthrough month doesn't double-bill you.

GET /api/v1/usage returns both. Pricing is on the pricing page. And whatever the prices become: leaving stays free.

🌐 Bank Coverage¶

Connections run through Plaid, so coverage is Plaid's: banks and credit unions in the United States and Canada, including most major institutions and many small ones.

Requesting New Banks¶

If your institution is not offered in the Plaid flow, tell us — the address is below. We can raise coverage requests with the provider, but the institution list is theirs, not ours, so we will not promise a date.

📞 Support and Contact¶

Support and security disclosures reach us fastest through the address on your welcome mail. Honest reports get honest answers.

Every question this guide doesn't answer is one we owe the docs — the docs grow with the product.

✨ MCP / AI quickstart¶

braatzledger ships an MCP server so Claude or ChatGPT can read your books and file judgements on your behalf.

Mint a personal access token at Settings — one year, read-only or read-write, revocable there.
Point your assistant's MCP configuration at braatzledger's MCP server and give it that token.
Ask it something: "what did I spend on software last month?", "file every Stripe payout as Revenue."

The tool list is generated from the API index at startup — there is no second list anywhere. A tool exists exactly when the endpoint does, which is the same reason the API Docs and /openapi.json cannot drift from the API.

Give an assistant a read-only token unless you want it filing judgements. A read-only token is refused on every write, and every judgement is appended with the actor recorded, so you can always see what the assistant decided and when.