Beancount Accounting Skill

Beancount is a plain-text double-entry accounting system. This skill provides expertise for creating, editing, and querying beancount files.

Core Concepts

Double-Entry Accounting

Every transaction must balance to zero. Money flows between accounts:

• Debits increase Assets/Expenses, decrease Liabilities/Income/Equity

• Credits decrease Assets/Expenses, increase Liabilities/Income/Equity

Five Account Types

Type Purpose Normal Balance

Assets

What you own (bank accounts, investments) Positive

Liabilities

What you owe (credit cards, loans) Negative

Income

Money coming in (salary, interest) Negative

Expenses

Money going out (food, rent) Positive

Equity

Net worth, opening balances Negative

Account Naming

Use colon-separated hierarchical names starting with capital letters:

Type:Country:Institution:Account:SubAccount

Examples:

Assets:Checking:Centennial:Joint Liabilities:Card:Chase:Sapphire Expenses:Food:Groceries Income:Salary:Employer

Transaction Syntax

Basic Format

YYYY-MM-DD flag "Payee" "Narration" Account1 Amount Currency Account2 Amount Currency ; optional comment

Flags

• Cleared/completed transaction

• !

• Pending/needs review

Examples

Simple expense:

2026-01-03 * "Starbucks" "Morning coffee" Expenses:Food:Coffee 5.75 USD Liabilities:Card:Chase:Sapphire

Paycheck with multiple postings:

2026-01-15 * "Employer" "Bi-weekly salary" Assets:Checking:Main 3500.00 USD Expenses:Taxes:Federal 800.00 USD Expenses:Taxes:State 200.00 USD Expenses:Insurance:Health 150.00 USD Income:Salary -4650.00 USD

Transfer between accounts:

2026-01-10 * "Transfer to savings" Assets:Savings:Ally 500.00 USD Assets:Checking:Main -500.00 USD

Amount Interpolation

One posting amount can be omitted - beancount calculates it:

2026-01-03 * "Grocery Store" "Weekly groceries" Expenses:Food:Groceries 125.43 USD Assets:Checking:Main ; Amount calculated as -125.43 USD

Essential Directives

open / close

Declare account lifecycle:

2026-01-01 open Assets:Checking:Main USD 2028-12-31 close Assets:Checking:Main

balance

Assert account balance at start of day (catches errors):

2026-01-31 balance Assets:Checking:Main 4583.84 USD

pad

Auto-generate balancing entry between two dates:

2026-01-01 pad Assets:Checking:Main Equity:Opening-Balances 2026-01-02 balance Assets:Checking:Main 4583.84 USD

include

Split files for organization:

include "2026-01.beancount" include "accounts.beancount"

option

Configure beancount behavior:

option "title" "Personal Finances" option "operating_currency" "USD"

Metadata and Tags

Metadata

Attach key-value pairs to directives or postings:

2026-01-03 * "Amazon" "Office supplies" order-id: "123-456-789" Expenses:Office 45.00 USD category: "equipment" Liabilities:Card:Chase

Tags and Links

Group related transactions:

2026-01-15 * "Hotel" "Conference lodging" #work-travel #conference-2026 Expenses:Travel:Lodging 299.00 USD Liabilities:Card:Chase

2026-02-01 * "Expense Report" "Reimbursement" ^conference-2026 Assets:Checking:Main 299.00 USD Income:Reimbursements

BQL Queries

Beancount Query Language (BQL) provides SQL-like queries. Run with bean-query :

bean-query finances/2026.beancount "SELECT account, sum(position) WHERE account ~ 'Expenses' GROUP BY 1"

Common Queries

Account balance:

SELECT account, sum(position) WHERE account ~ 'Assets:Checking' GROUP BY 1

Monthly expenses by category:

SELECT MONTH(date), account, sum(position) WHERE account ~ 'Expenses' AND year = 2026 GROUP BY 1, 2 ORDER BY 1, 2

Transactions for an account:

SELECT date, narration, payee, position, balance WHERE account = 'Assets:Checking:Centennial:Joint' ORDER BY date

Key BQL Functions

Function Purpose

SUM(position)

Aggregate amounts

YEAR(date) , MONTH(date)

Extract date parts

COST(position)

Get cost basis

account ~ 'pattern'

Regex match account

Working with Beancount Files

Reading Files

Before editing, read the beancount file to understand:

• Existing account structure

• Naming conventions used

• Transaction patterns

• Include file organization

Adding Transactions

• Match existing account names exactly

• Use consistent payee/narration style

• Ensure transaction balances to zero

• Add to chronologically appropriate location or include file

Validation

Run bean-check to validate syntax:

bean-check finances/2026.beancount

Common Patterns

Credit card payment:

2026-01-25 * "Chase" "Credit card payment" Liabilities:Card:Chase:Sapphire 500.00 USD Assets:Checking:Main -500.00 USD

Investment purchase with cost basis:

2026-01-20 * "Fidelity" "Buy index fund" Assets:Investments:Fidelity:FXAIX 10 FXAIX {150.00 USD} Assets:Investments:Fidelity:Cash -1500.00 USD

Mortgage payment breakdown:

2026-01-01 * "Rocket Mortgage" "Monthly mortgage" Liabilities:Loan:RocketMortgage 800.00 USD ; Principal Expenses:Housing:Interest 900.00 USD ; Interest Expenses:Housing:Escrow 300.00 USD ; Escrow Assets:Checking:Main -2000.00 USD

Best Practices

File Organization

• Use include to split by month or category

• Keep account definitions in main file

• Add transactions to appropriate include files

Account Hierarchy

• Be consistent with naming depth

• Use specific subcategories for visibility

• Group related accounts logically

Balance Assertions

• Add monthly balance assertions for bank accounts

• Reconcile against actual statements

• Catches data entry errors early

Error Prevention

• Always run bean-check after edits

• Use balance assertions frequently

• Keep transactions in chronological order

Additional Resources

Reference Files

For detailed syntax and patterns, consult:

• references/syntax.md

• Complete directive reference with all options

• references/bql.md

• Full BQL query language documentation

• references/examples.md

• Common transaction patterns and workflows

Command Line Tools

Command Purpose

bean-check file.beancount

Validate syntax

bean-query file.beancount "QUERY"

Run BQL query

bean-report file.beancount balances

Balance report

bean-web file.beancount

Web interface