Double-entry, made explicit
Every transaction records at least two postings. The postings balance each other, which makes missing destinations and accidental one-sided edits easier to catch.
A practical guide to BeanFlow
Understand the ledger. Use BeanFlow with confidence.
BeanFlow keeps everyday entry approachable while preserving a balanced double-entry ledger underneath. This guide explains what Beancount is, how BeanFlow relates to it, and the daily workflow.
Double-entry by design
Local-first
Import & export
01 · Beancount
What is Beancount?
Beancount is a plain-text, double-entry accounting language. Instead of storing a transaction as an isolated number, it records how value moves between accounts, so the ledger can be checked, searched, versioned, and moved between tools.
Plain text, portable by default
A ledger file can be read as text, reviewed in a diff, backed up, and migrated without locking the account history inside one database format.
How BeanFlow fits
BeanFlow does not use a .bean file as its runtime database. The app uses local SwiftData for the live ledger, while Beancount is the bridge for importing and exporting structured account history.
Account paths carry meaning
Paths such as Assets:Bank:Checking and Expenses:Food:Coffee make the account hierarchy visible. BeanFlow keeps the same structure available when you need detailed reports or migration.
A small example
One coffee purchase, two sides
The expense increases while the cash account decreases. The two postings describe one event from both sides.
2026-09-19 * "Coffee"
Expenses:Food:Coffee 28.00 CNY
Assets:Cash -28.00 CNYThe amounts balance to zero. In BeanFlow, the same relationship is created through the transaction editor; you do not need to type this syntax for everyday entry.
02 · Use BeanFlow
A simple daily workflow
Start with the simple interface, then add account detail, budgets, imports, and reports as your ledger grows.
1
Choose your mode
Use Simple Mode for fast everyday entries. Choose paid Beancount Mode when you want full account paths, ledger import/export, and stricter bookkeeping workflows.
2
Set up accounts and currency
Set the default currency in Settings, then create the accounts you actually use: bank, cash, cards, income sources, and expense categories.
3
Record the transaction
Choose Expense, Income, or Transfer. Select the source and destination accounts, enter a positive amount, choose the date, and add a useful description or tag.
4
Review overview and budgets
Use Overview to check assets, liabilities, income, expenses, equity, trends, and category charts. Use Budgets to set a limit for an expense category and follow its progress.
5
Import or export when needed
In Settings, import Beancount files, Bean packages, or CSV. Export a single file, package, or CSV only when you choose to save or share it.
6
Keep your devices in sync
The ledger stays local by default. If you enable iCloud sync, supported records use your private CloudKit database; Widgets and Apple Watch receive limited summary snapshots.
Transaction shortcuts
Three entries cover most days
The editor keeps the user-facing flow short while BeanFlow creates the corresponding balanced postings.
Expense
From an asset or liability account to an expense category. Example: cash or card → Food:Coffee.
Income
From an income category to the account that receives the money. Example: Salary → Bank:Checking.
Transfer
Between two asset or liability accounts. Example: Bank:Checking → Cash. The source and destination must be different.
03 · Complete feature tour
What BeanFlow does in detail
BeanFlow is more than a quick expense form. It connects a structured ledger, valuation, reports, budgets, migration, and private cross-device summaries into one workflow.
Ledger foundation
The app keeps the accounting model visible without forcing every user to start with accounting jargon.
- First-class account types include assets, liabilities, equity, income, expenses, trading, and off-balance accounts.
- Transactions are stored as postings connected to accounts, dates, descriptions, tags, and currencies.
- Refunded transactions can be marked without erasing history; overview and budgets exclude them from active totals.
Transactions
The editor turns common money movements into balanced entries with a short, repeatable form.
- Expense moves value from an asset or liability account to an expense category.
- Income moves value from an income category to the account that receives it; transfer connects two asset or liability accounts.
- Search, period filters, tags, refund/cancel-refund actions, edit, and delete keep the ledger usable over time.
Overview and reports
The Overview screen separates “what happened during the period” from “what the accounts are worth at the end”.
- Choose day, week, month, year, or a custom range and move between periods.
- Assets, liabilities, and equity use closing balances; income and expenses use interval totals.
- Interactive pie, bar, and line charts support slice selection, drag inspection, tooltips, and trend review.
Accounts and themes
Accounts can stay simple at first and become a meaningful hierarchy as the ledger grows.
- Build account paths level by level, for example Assets → Bank → Checking, with an optional English export name.
- Search by account path, display name, or currency; group accounts by type and inspect current balances.
- Give each account an SF Symbol, light/dark colors, and a theme; deletion is blocked when postings or budgets still reference it.
Budgets
Budgets turn expense categories into a forward-looking control instead of a number you only inspect afterward.
- Use monthly, quarterly, yearly, or custom periods and set a limit in the budget currency.
- Spent is computed from matching expense postings, with refunded transactions excluded.
- Progress changes from green to orange to red as the budget approaches or passes its limit; recurring periods can roll forward automatically.
Import and export
Beancount is the portability layer: the app stays database-driven at runtime, while files remain available for migration and sharing.
- Import .bean/.beancount files, Bean packages, ZIP packages, includes, open directives, price directives, tags, and multi-line descriptions.
- Import CSV grouped by TransactionKey; strict parsing requires complete values and balanced debit/credit rows.
- Invalid transactions are reported and skipped by default; auto-balance is an explicit import option, not a silent repair.
Money, currencies, and valuation
Amounts are entered in the user’s regional format, while file formats remain strict and portable.
- Transaction, split, budget, and manual-price fields share the same locale-aware amount parsing and display.
- Direct, reverse, and intermediate-currency rates can be used; transactions use the transaction-date rate and balances use period-end valuation.
- Manual prices, imported prices, and ECB reference rates are supported. Missing rates never fall back to 1:1; incomplete totals are marked instead.
Receipt and statement OCR
For supported bill and statement workflows, BeanFlow can turn on-device recognition into reviewable transaction candidates.
- Use photos or files as input; recognition runs on the device with bundled Core ML models.
- The review step exposes amount, currency, date, merchant, direction, confidence, and possible duplicates before import.
- You choose the account and category, resolve ambiguous candidates, and explicitly confirm what enters the ledger.
Privacy and protection
BeanFlow is designed to work without a developer-hosted account or ledger server.
- The live ledger uses local SwiftData; optional iCloud sync uses your private CloudKit database.
- Optional App Lock can use system authentication and BeanFlow PIN or pattern protection; biometric data is handled by the system.
- Import files are processed on-device, and exports are created only after you choose to save or share them.
Widgets and Apple Watch
The companion surfaces are summaries, not a second copy of the raw ledger.
- Widgets show overview and equity snapshots in small, medium, and large layouts, with freshness and incomplete-valuation notices.
- Apple Watch shows the selected range, assets, liabilities, income, expense, equity, sync status, and missing-currency warnings.
- The Watch can change presets and move the period on the iPhone through WatchConnectivity.
How the pieces connect
One entry, many useful views
A transaction is entered once. BeanFlow then keeps the same balanced source available to the ledger, reports, budgets, and cross-device snapshots.
Enter a transaction
Create balanced postings
Aggregate and value
Show reports, budgets, Widgets, and Watch
Simple Mode and Beancount Mode
| Area | Simple Mode | Beancount Mode |
|---|---|---|
| Best for | Fast daily expenses, income, transfers, and summaries. | People who want full account paths, migration, valuation, and stricter ledger workflows. |
| Entry experience | Short, approachable forms with balanced postings created behind the scenes. | The same transaction flow, with deeper account structure and ledger-oriented tools. |
| Data and files | Local-first app ledger for everyday use. | Beancount/Bean package/CSV import and export, account naming, prices, and compatibility preview. |
| Reports | Overview, budgets, and the core financial picture. | The same overview plus detailed account hierarchy, valuation, ledger health, and migration context. |
| Switching | Start free and move to Beancount Mode later when the extra structure becomes useful. | A compatibility preview lets you inspect a ledger before committing to the paid mode. |
04 · Questions
Before you start
Do I need to know Beancount to use BeanFlow?
No. Simple Mode is designed for normal daily entry. Beancount Mode adds the deeper account and migration tools when you want them.
Where is my data stored?
The live ledger is stored on your Apple device by default. BeanFlow does not run a developer-hosted ledger server. Optional iCloud sync uses your private CloudKit database.
Can I move an existing ledger?
Yes. You can import supported Beancount or CSV data, review the import report, and export the ledger later as Beancount, a Bean package, or CSV.
What happens if a transaction is not balanced?
Normal entry keeps the postings balanced. During import, invalid or unbalanced transactions are reported and skipped unless you explicitly enable the auto-balance option.
Start small. Keep the ledger honest.
Record one real transaction today, then use the overview to see how the two sides of that transaction affect your accounts.