Introduction to Beancount 3

Experimental Documentation This repository is an experiment to verify if Artificial Intelligence can create high-quality technical documentation. The content you see here was generated by an AI agent.

Welcome to the Beancount 3 documentation.

Beancount is a double-entry bookkeeping system that runs on your computer. Unlike traditional accounting software (like Quicken, YNAB, or GnuCash) that stores data in complex databases or proprietary file formats, Beancount defines a simple language to describe financial transactions in plain text files.

You use your favorite text editor to write down what happened with your money, and Beancount provides the tools to read those files, verify that the math works out, and generate financial reports.

The Philosophy: Plain Text Accounting

Beancount belongs to the family of Plain Text Accounting (PTA) tools. This approach offers several unique advantages:

• You own your data: Your financial history is stored in text files that will be readable 50 years from now, regardless of whether Beancount still exists.
• Version Control: Because it’s text, you can manage your finances with Git. You can track changes, revert mistakes, and sync across devices securely.
• Speed and Efficiency: Entering data is as fast as you can type. There are no slow graphical interfaces or mouse clicks required to enter a coffee purchase.
• Programmability: Since the data is text, it is trivial to write scripts to manipulate it, generate custom charts, or import data from your bank.

Why Beancount?

Among the PTA tools (which includes Ledger and Hledger), Beancount is known for:

1. Strictness: Beancount enforces rules (like requiring you to declare accounts before using them) that prevent typos and errors from creeping into your history.
2. Python: Beancount is written in Python (with a C++ core in v3), making it incredibly extensible for anyone who knows the language.
3. Inventory Booking: It has a robust model for tracking investments, handling stock lots, cost basis, and capital gains automatically.

How this guide is organized

This documentation follows the Diátaxis framework to help you find exactly what you need:

• Tutorials: Learning-oriented lessons. Start here if you are brand new to Beancount. We’ll walk you through your first file step-by-step.
• How-to Guides: Task-oriented recipes. Go here if you want to know “How do I track a stock trade?” or “How do I handle a shared expense?”.
• Reference: Information-oriented descriptions. Look here for the technical details of the syntax or CLI commands.
• Explanation: Understanding-oriented discussions. Read these to understand the concepts behind double-entry accounting and Beancount’s design decisions.