Beancount Language Syntax

Core Structure

Directives

All directives follow the basic format:

YYYY-MM-DD <directive-type> ...

Key characteristics:

• Date must be in ISO 8601 format (YYYY-MM-DD)
• Directives are processed in chronological order, not file order
• Each directive represents a specific type of financial event

Account Names

Structure: Type:Component1:Component2:ComponentN

Account types:

Assets
Liabilities
Equity
Income
Expenses

Rules:

• Components must be capitalized
• Separators are colons
• No spaces allowed
• Can use numbers and dashes

Transaction Format

Basic Structure

YYYY-MM-DD * "Payee" "Narration"
  Account1    Amount1 CURRENCY
  Account2    Amount2 CURRENCY

Posting Features

# Cost Basis
  Assets:Stocks    1 STOCK {100.00 USD}

# Price Information
  Assets:Cash    -100 USD @ 1.25 CAD

# Amount with Total Price
  Assets:Cash    -100 USD @@ 125.00 CAD

# Implicit Balance
  Assets:Cash    -100 USD
  Assets:Bank

Special Features

Balance Assertions

2024-01-01 balance Assets:Checking  1000.00 USD

Account Declarations

2024-01-01 open Assets:Checking  USD
2024-12-31 close Assets:Checking

Metadata

2024-01-01 * "Transaction" #tag ^link
  invoice: "1234"
  department: "sales"
  Assets:Cash  100 USD
    receipt: "receipt.pdf"
  Expenses:Food

Price Declarations

2024-01-01 price STOCK 100.00 USD

Document Control

Options

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "documents" "/path/to/docs"

Plugins

plugin "beancount.plugins.module_name"
plugin "beancount.plugins.module_name" "config"

File Organization

include "path/to/include/file.beancount"
pushtag #project
; ... transactions ...
poptag #project

Important Rules

Balancing Rules

1. Sum of all postings must equal zero
2. Cost basis is used for balance calculation when present
3. Price annotations (@) are for information only

Account Constraints

1. Accounts must be opened before use
2. Currency constraints can be specified at account opening
3. Closing prevents further posting

Balance Assertions

1. Applied at start of day
2. Only verify specified currency
3. Can be used on parent accounts
4. Work with cost basis amounts

Common Patterns

Opening Accounts with Initial Balance

2024-01-01 open Assets:Checking    USD
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-01 balance Assets:Checking 1000.00 USD

Investment Transaction

2024-01-01 * "Buy stock"
  Assets:Broker:Stock    10 STOCK {100.00 USD}
  Assets:Broker:Cash   -1000.00 USD

Multi-Currency Transaction

2024-01-01 * "Currency exchange"
  Assets:USD     -100.00 USD @ 1.25 CAD
  Assets:CAD      125.00 CAD

Document Integration

2024-01-01 document Assets:Checking "path/to/statement.pdf"

This technical reference covers the essential syntax and rules for Beancount's double-entry accounting system. For specific use cases and examples, refer to the Cookbook and Getting Started guides.