Getting Started with Beancount

Ready to take control of your finances? This guide will get you up and running with Beancount in minutes. You'll learn how to create your first ledger, set up essential accounts, and record your first transactions.

Initial Setup

Creating Your First Ledger

; Basic structure for a new ledger
2024-01-01 open Assets:Checking
2024-01-01 open Equity:Opening-Balances

2024-01-02 * "Initial Deposit"
  Assets:Checking           100.00 USD
  Equity:Opening-Balances

Essential Configuration

option "title" "Personal Finance Ledger"
option "operating_currency" "USD"

File Organization

Recommended Structure

; 1. Configuration Options
option "title" "Personal Ledger"
option "operating_currency" "USD"

; 2. Account Declarations
2024-01-01 open Assets:Checking    USD
2024-01-01 open Assets:Savings     USD
2024-01-01 open Expenses:Food      USD

; 3. Initial Balances
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-01 balance Assets:Checking 1000.00 USD

; 4. Transactions
2024-01-15 * "Grocery Store" "Weekly groceries"
  Expenses:Food            50.00 USD
  Assets:Checking

Section Organization

1. Eternal Accounts

   2024-01-01 open Liabilities:Payables    USD
   2024-01-01 open Assets:Receivables      USD

2. Bank Accounts

   2024-01-01 open Assets:Bank:Checking     USD
   2024-01-01 open Assets:Bank:Savings      USD
   2024-01-01 open Income:Bank:Interest     USD

3. Investment Accounts

   2024-01-01 open Assets:Investment:Cash    USD
   2024-01-01 open Assets:Investment:Stocks  VTSAX
   2024-01-01 open Income:Investment:Dividend USD

Validation and Reporting

Basic Validation

# Check for errors
bean-check ledger.beancount

# View web interface
bean-web ledger.beancount

Common Reports

# Balance sheet
bean-report ledger.beancount balsheet

# Income statement
bean-report ledger.beancount income

# Account journal
bean-report ledger.beancount journal -a Assets:Checking

Managing Initial Balances

Padding Example

2024-01-01 open Assets:Checking    USD

; Pad account to match known balance
2024-01-01 pad Assets:Checking Equity:Opening-Balances

; Assert known balance
2024-01-01 balance Assets:Checking 1525.00 USD

Account Closure

2024-01-01 open Assets:OldBank:Checking   USD
2024-06-30 close Assets:OldBank:Checking  ; Account closed

Transaction De-duplication

Handling Transfers

; Credit card payment - combined view
2024-01-15 * "Credit Card Payment"
  Assets:Checking            -500.00 USD
  Liabilities:CreditCard     500.00 USD

; Flag for pending match
2024-01-15 * "Pending CC Payment"
  ! Assets:Checking         -500.00 USD
  Liabilities:CreditCard    500.00 USD

Balance Assertions

; Regular balance checks prevent duplicates
2024-01-31 balance Assets:Checking    2150.25 USD
2024-01-31 balance Liabilities:CreditCard  -350.00 USD

Best Practices

1. File Organization

   • Keep one main file initially
   • Use clear section headers
   • Group related accounts together

2. Account Names

   • Use consistent naming conventions
   • Include country/institution prefixes
   • Maintain logical hierarchy

3. Balance Verification

   • Regular balance assertions
   • Pad accounts appropriately
   • Track account closures

4. Currency Handling

   • Declare operating currencies
   • Use consistent commodity codes
   • Specify currency constraints

Next Steps

Now that you have a basic ledger set up:

1. Record Regular Transactions: Start with your daily expenses and income
2. Set Up Bank Account Imports: Use CSV imports or bank connections to automate data entry
3. Learn Advanced Syntax: Explore syntax reference for more complex scenarios
4. Generate Your First Reports: Use the UI features to create financial reports and analyze your spending

Quick Reference

Common Account Types:

• Assets:Bank:Checking - Your checking account
• Expenses:Food:Groceries - Grocery spending
• Income:Salary:Company - Employment income
• Liabilities:CreditCard:Visa - Credit card debt

Essential Commands:

• bean-check ledger.beancount - Validate your ledger
• bean-report ledger.beancount balsheet - Generate balance sheet
• bean-web ledger.beancount - Launch web interface

These guidelines establish a solid foundation for managing personal finances with Beancount. Ready to add your first transaction? Check out our UI transaction guide.