Inspired by a Hacker News thread on GnuCash, a piece of software I used extensively for my personal finances, I had a look at beancount. It’s a plaintext accounting software with a CLI and a web interface. However, the beancount docs are maintained as Google Docs and are relatively long. I thought I’d share my experience setting up a beancount file and the basic usage so that it’s easy to dive in. It’s advisable to have a certain degree of familiarity with double-entry bookkeeping. Some of the following examples are plainly stolen from the beancount docs.
Beancount does plaintext accounting. That means that all is handled in a plaintext file, e.g.
There are five types of accounts:
Accounts are structured into parent and child accounts by separating them with colons (
:), but every account needs to be the child of one of the five types of root accounts above, e.g.
Income:Finance:Interests. Each component starts with an uppercase letter or number and continues with an arbitrary amount of upper/lowercase letters, numbers and dashes.
EUR are commodities, but you may also declare your own commodities such as stock symbols. Commodities may only include uppercase letters and
Strings are written with double quotes. Splitting a string over multiple lines includes the newline in the string.
The most important part are comments. In beancount, a comment is declared by a semicolon
Here I will give a short overview over the different directives one can use in beancount. This list only includes the simple stuff to get started fast.
Upon parsing a file, directives will be sorted by date internally. This allows you to organize your file any way you like.
Open a new account. Accounts must be opened before being referenced.
You may provide a currency constraint. All transactions must post to this accountn in the specified currencies.
Close an account. No transactions may post here after this date.
Declare a commodity or currency. This is optional but allows you to attach metadata. The metadata attached is completely optional and you may attach any metadata you like. This enables you to filter or aggregate based on metadata values.
The core of accounting. A basic transaction looks like this:
Each line below a transaction is called a posting. The sum of all postings must be 0. You may leave out one amount which will automatically get calculated:
Instead of the keyword txn, you may use a flag to indicate a transaction. There are to flags available:
It’s also possible to flag a single posting in a transaction:
Costs and Prices
Prices are the prices of conversion.
Prices are good for tracking currencies. We want to forget about the conversion rate after the transaction - it will just be 500 USD going forward. Beancount also allows tracking costs which will result in assets being “held at cost”. You can later identify these specific units by cost when they are removed from the account.
Add a tag to a transaction for filtering
Make sure the balance is correct. The calculation applies at the beginning of the day. Beancount will spit out an error if the balance is not OK.
Define the price of a commodity for a given date
Load a plugin
Set general options
Include a different file. Allows you to split your accounting into multiple files, e.g. per year transactions.
If you want to look at an example file, run:
bean-example | less
To check your file, run:
Where to continue
This is just an overview and a simple reference for myself. There are loads of commands and stuff you can do with beancount.
- For an easy commands overview, start with the cheat sheet
- Read the language syntax spec for more details
- Then, and only then, read Getting Started
For deeper dives, you may continue with