Beancount Accounting

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

1. Match existing account names exactly
2. Use consistent payee/narration style
3. Ensure transaction balances to zero
4. 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