Beancount Syntax

Below is a short reference of the Beancount language syntax. Also see the full Syntax Documentation and the Syntax Cheat Sheet.

Beancount defines a language in which financial transactions are entered into a text-file, which then can be processed by Beancount. There are a few building blocks that are important to understand Beancount's syntax:

  • Commodities,
  • Accounts,
  • Directives.

Commodities

All in CAPS: USD, EUR, CAD, GOOG, AAPL, RBF1005, HOME_MAYST, AIRMILES, HOURS.

Accounts

Account are given by a colon-separated list of capitalized words. They must begin with one of the five root accounts listed in the table below. The separation by colons defines an implicit hierarchy, for example we say that Assets:Cash is a sub-account of Assets.

Name Type Contains Examples
Assets + Cash, Checking-Account, etc. Assets:Checking
Liabilities - Credit Card, etc. Liabilities:CreditCard
Income - Salary, etc. Income:EmployerA
Expenses + Expense categories Expenses:Fun:Cinema
Equity - Almost always auto-generated Equity:Opening-Balances

The names of the five root accounts can be changed with the following options:

Directives

The basic building block are directives (also called entries). Most directives start with a date, then the type of the directive, and then directive-specific arguments. The ordering of directives in the input-file does not matter, because Beancount orders them based on the date of each directive.

General syntax: YYYY-MM-DD <directive> <arguments...>

Open and Close accounts

To open or close an account use the open and close directives:

Commodities

Declaring commodities is optional. Use this if you want to attach metadata by currency. If you specify a name for a currency like below, this name will be displayed as a tooltip on hovering over currency names in Fava. Likewise, with the precision metadata, you can specify the number of decimal digits to show in Fava, overriding the precision that is otherwise automatically inferred from the input data.

Prices

You can use this directive to fill the historical price database:

Notes

Documents

Transactions

Postings

Balance Assertions and Padding

Asserts the amount for only the given currency:

Automatic insertion of transaction to fulfill the following assertion:

Events

Options

See the Beancount Options Reference for the full list of supported options.

Other

Comments