Explanation
Idea
You have your Assets accounts to be defined in accounts.bean or accounts.gen.bean (autogenerated from the YAML config). Note that definition date is not important, it just needs to be earlier than the account participates in any other directives. 1970-01-01 should surely do. An example of account definition is Assets:MyFavouriteBank:Cash.
For each asset account there will be a correspoinding Equity:OpeningBalances:* account (e.g. Equity:OpeningBalances:MyFavouriteBank:Cash). It will be used to offset starting values of the accounts at some date when you started tracking.
Finally, for each account you will need a corresponding account that will track changes in your accounts. For bank accounts, this will be Expenses:Unattributed:MyFavouriteBank. For cash it will be Expenses:Unattributed:Physical:Cash. For savings accounts, brokers and other institutions where the value will vary by time (opaque funds), we will define a PnL (profit and loss) account like Income:MyAutomaticBroker:PnL. The more advanced way to track this is described later in this section.
Liabilities are mostly the same as Assets. The only difference is that Assets is something that you own and Liabilities is something that you owe or that is owed to you. The primary difference is the conceptual one and how they will be displayed in the interface. Also, Assets have a positive balance, and Liabilities will have negative balance when you are owed something (and positive when you have some debt). Both will be considered as a part of your financial “net worth”. If unsure, start by tracking everyting in Assets.
The Beancount instructions you will need to become familiar with are balance and pad. The first will be used to assert values of the accounts, the second will create auxiliary transactions to keep everything balanced.
Tracking totals
The first generated file, initial.gen.bean starts with a block of pad operations:
2023-02-03 pad Assets:MyFavouriteBank:Cash Equity:OpeningBalances:MyFavouriteBank:Cash
2023-02-03 pad Assets:MyLessFavouriteBank:Cash Equity:OpeningBalances:MyLessFavouriteBank:Cash
2023-02-03 pad Assets:MyStockBroker:Cash Equity:OpeningBalances:MyStockBroker:Cash
2023-02-03 pad Assets:Unattributed:Physical:Cash Equity:OpeningBalances:Unattributed:Physical:Cash
; 2023-02-03 pad Liabilities:Shared:SomeDude Equity:OpeningBalances:Shared:SomeDude
2023-02-03 pad Assets:MyAutomaticBroker:Total Equity:OpeningBalances:MyAutomaticBroker:Total
Overall, Equity:* accounts (in my experience) will be pretty meaningless. At least in this guide they are used for technical purposes.
The primary content of all files under totals/ will be a series of balance checks for all accounts that you fill in regularly as described above (via the UI). Each block will have the same date in the directives: the date when the balance has been checked by you.
2024-02-04 balance Assets:MyFavouriteBank:Cash 1500 GBP
2024-02-04 balance Assets:MyLessFavouriteBank:Cash 180 GBP
2024-02-04 balance Assets:MyStockBroker:Cash 200 USD
2024-02-04 balance Assets:MyAutomaticBroker:Total 7522 USD
2024-02-04 balance Assets:Physical:Cash 40 GBP
2024-02-04 balance Assets:Physical:Cash 100 USD
As we don’t track any income or expenses manually or automatically yet, for each balance block there will be a corresponding pad block that will make sure that the changes are automatically assigned to corresponding Expenses or Income accounts. The date for these pad instructions will be one day earlier than the corresponding balance checks. For the first block of balances it will be padded against Equity:OpeningBalances:* accounts, for each following block it will be padded against corresponding Expenses: and Income: accounts:
2024-02-10 pad Assets:MyLessFavouriteBank:Cash Expenses:Unattributed:MyLessFavouriteBank
2024-02-10 pad Assets:MyFavouriteBank:Cash Expenses:Unattributed:MyFavouriteBank
; 2024-02-10 pad Assets:Physical:Cash Expenses:Unattributed:CashOnHands
2024-02-10 pad Assets:MyAutomaticBroker:Total Income:MyAutomaticBroker:PnL
2024-02-11 balance Assets:MyFavouriteBank:Cash 1500 GBP
2024-02-11 balance Assets:MyLessFavouriteBank:Cash 180 GBP
2024-02-11 balance Assets:MyStockBroker:Cash 200 USD
2024-02-11 balance Assets:MyAutomaticBroker:Total 7522 USD
2024-02-11 balance Assets:Physical:Cash 40 GBP
2024-02-11 balance Assets:Physical:Cash 100 USD
Each of the file has the following structure:
2023-02-03 pad blocks for Equity:OpeningBalances:*
2023-02-04 balance checks
Similarly:
2023-02-10 pad blocks for Expenses / Income accounts
2023-02-11 balance checks
Check for errors
After you’ve done the update, start the Fava and navigate to http://localhost:5000/beancount/errors/. You may in theory see one of these errors:
Unused Pad entry means that there were actually no changes to the account value and the pad directive is extraneous. This is fixed by commenting out that pad directive. Ideally there would be an option to ignore this warning but this is something that would need to be changed in Beancount itself (may look into this at some point).
Balance failed for is rather the opposite. Maybe you forgot to add a corresponding pad directive to the preceding block?
Result
Now you see your total net worth in the table and in the graph. In the beginning it’s just a single data point but once you fill in amounts in a week (or when you get to it), you will start to build a meaningful graph showing your total balances over time.
http://localhost:5000/beancount/balance_sheet/
Some other dashboards and visualizations may already be useful to you from now on.
Don’t forget to add the files you’ve generated to git and commit the changes. Do this regularly as you update your ledger.
Notes
Beancount only has precision up to a day. Your balances may change throughout the day. Your data will still be roughly right but if you want to be more precise and have cleaner data, put in balances how they were in the very beginning of the day (0:00 AM). For bank accounts that means add back all expenses that happened throughout that day and put in that value.
One account may contain variety of currencies/commodities. If it has several, multiple
balancechecks will need to be present to assert the current value of the account. A singlepaddirective is still enough to handle all values in the account (if you use Lazy Beancount UI, that should be handled correctly for you). Sometimes that will also mean that thes pad fixes will contain implicit and rough information about currency conversions happened (especially relevant for theAssets:Physical:Cashaccount).