Glossary

Plain-text accounting borrows vocabulary from double-entry bookkeeping and adds a handful of Beancount-specific words of its own. This glossary defines the terms you will meet while reading these docs or your own ledger file, each with a short example where it helps. Every entry has its own link, so you can point a teammate straight at a definition.

Account​

An account is a named bucket that tracks one stream of value, written as a colon-separated hierarchy under one of five root types: Assets, Liabilities, Equity, Income or Expenses. The hierarchy is the whole organizing structure of your books — Assets:US:BofA:Checking and Expenses:Food:Restaurant sort and roll up automatically. Every account must be declared before it is used. See Beancount Language Syntax for the naming rules.

Accrual basis​

Accrual-basis accounting records income when it is earned and expenses when they are incurred, regardless of when the cash actually moves. Cash-basis accounting does the opposite: it recognizes both only when money changes hands. Accrual gives a truer picture of a period's performance, which is why an invoice you sent in March belongs to March even if the client pays in May.

Amortization​

Amortization spreads a single large payment across the periods it actually covers, so each month carries its fair share of the cost. An annual insurance premium paid in January is an expense of all twelve months, not just January. In Beancount you either write the split postings by hand or generate them with a plugin — see Amortize.

Balance assertion​

A balance assertion is a balance directive that states what an account's balance must be at the start of a given date, so your bank statement becomes an automatic check on your books. If the computed balance differs, Beancount fails loudly with the expected and actual amounts. Sprinkling one assertion per account per statement is the single cheapest way to keep a ledger trustworthy.

2026-01-01 balance Assets:US:BofA:Checking   4,321.00 USD

Beancount​

Beancount is an open-source double-entry accounting system whose ledger is a plain-text file you edit in any text editor and validate with a command-line tool. It gives you a strict, parseable syntax, a query language, and a web interface, without a database or a proprietary file format. Because the ledger is text, it lives happily in Git alongside your code. Start with Introduction to Beancount.

Beancount Query Language​

Beancount Query Language, usually abbreviated BQL, is the SQL-like language you use to ask your ledger questions. It runs over the parsed directives rather than a database, so SELECT account, sum(position) WHERE year = 2026 answers immediately from the same file you edit. Read the query language guide for the full grammar.

Booking method​

A booking method is the rule Beancount applies when a reduction has to pick which existing lots to draw down. The choices are STRICT (you must identify the lot yourself), FIFO, LIFO, AVERAGE and NONE, set per account on its open directive. The method you choose changes your realized capital gains, so pick the one your tax jurisdiction expects and keep it stable.

Chart of accounts​

A chart of accounts is the complete list of accounts your ledger uses, together with the structure that organizes them. In Beancount there is no separate chart file — the set of open directives is your chart of accounts. Designing it well early on saves a lot of renaming later; see Industry-Specific Setups for starting points.

Close directive​

A close directive marks the date after which an account may no longer be used, which is how you retire a bank account or a paid-off loan without deleting its history. Past transactions stay valid and reportable; only new postings are rejected. Closing unused accounts keeps reports readable as a ledger ages.

2026-03-31 close Assets:US:OldBank:Checking

Commodity​

A commodity is any unit of value your ledger tracks — a currency like USD, a stock ticker like AAPL, a crypto asset like BTC, or something you invent such as VACATION-DAYS. Beancount never converts between commodities behind your back, so an amount is always a number paired with the commodity it is denominated in. An optional commodity directive lets you attach metadata such as a name or an asset class.

Cost basis​

Cost basis is what you actually paid for a holding, recorded in the currency you paid with and carried alongside the holding for as long as you own it. Beancount writes it in braces — 10 AAPL {150.00 USD} means ten shares acquired at 150 dollars each. Because the basis travels with the position, capital gains fall out of the arithmetic when you sell. See Inventory Management.

Directive​

A directive is one dated instruction in a Beancount file, and directives are all a ledger contains. Every line that starts with a date is one: open, close, balance, price, note, document, pad, event, commodity, and the transaction itself. Beancount sorts directives by date before processing, so you can keep them in whatever order reads best.

Double-entry bookkeeping​

Double-entry bookkeeping is the practice of recording every economic event as at least two matching entries, so that the amounts always sum to zero. Money is never created or destroyed — it only moves between accounts, which is why the technique catches mistakes that a single-column list never would. Beancount enforces the rule strictly: a transaction whose postings do not balance is an error, not a warning.

Envelope budgeting​

Envelope budgeting sets aside money for a purpose before you spend it, so each category has its own limit instead of competing for one pooled balance. The name comes from the paper envelopes people once filled with cash on payday. In a plain-text ledger you model envelopes with dedicated accounts or budget directives — see Budgets.

Fava​

Fava is the web interface for Beancount: charts, balance sheets, income statements, a query editor and an entry form, served from your ledger file. It is read-mostly and runs locally, so it changes how you see your books without changing how you record them. beancount.io hosts a managed version alongside its own tooling; the UI Features guide covers what you can do there.

Inventory​

An inventory is the collection of positions an account currently holds, each with its own commodity and, where relevant, its own cost basis and acquisition date. A brokerage account that bought the same stock three times holds three separate lots in one inventory, not one blended number. Keeping lots distinct is what makes accurate gain calculations possible.

Journal​

The journal is the chronological list of everything that happened in your books — the raw stream of transactions, in date order, before any grouping or summarizing. It is the view you scan when you want to answer "what did I actually do in March?". Fava's journal page is usually the fastest place to spot a miscategorized entry.

Ledger​

A ledger is the complete set of accounting records for one entity, which in Beancount means your plain-text file (plus anything it includes). The word doubles as the name of the whole book of accounts and the name of the file itself. Because it is text, a ledger can be diffed, reviewed, branched and merged like source code.

Lot​

A lot is one specific acquisition of a commodity, identified by its cost basis and acquisition date. Buying the same ETF in January and again in June creates two lots, and selling later means choosing which lot you are selling. Lots are the reason Beancount can compute realized gains exactly instead of approximating them.

2026-06-15 * "Broker" "Buy VTI"
  Assets:US:Broker:VTI     5 VTI {260.00 USD, 2026-06-15}
  Assets:US:Broker:Cash            -1,300.00 USD

Narration​

The narration is the free-text description of what a transaction was for, written as the second quoted string on the transaction line. It is for humans: "Monthly rent", "Groceries and household". Beancount does not parse it, but it is what you will read when the entry no longer makes sense six months from now.

Open directive​

An open directive declares an account, the date it starts being usable, and optionally the commodities it may hold and the booking method it uses. Beancount requires every account to be opened before its first posting, which is what stops a typo from silently creating a brand-new account. Restricting the allowed commodities turns another whole class of mistakes into errors.

2026-01-01 open Assets:US:Broker:VTI   VTI   "FIFO"

Pad​

A pad directive tells Beancount to insert whatever amount is needed to make the next balance assertion on an account succeed, booking the difference to a second account. It exists for exactly one job: opening a ledger part-way through life without reconstructing years of history. Padding beyond that initial setup usually means a real error is being papered over.

Payee​

The payee is who you transacted with, written as the first quoted string on a transaction line. Keeping payees consistent — always "Whole Foods", never sometimes "WholeFoods" — is what makes payee-based reports and automated importers work. Beancount treats the payee as optional; a transaction may carry only a narration.

Plain-text accounting​

Plain-text accounting is the practice of keeping your books in a human-readable text file under version control, processed by open-source command-line tools. It trades a point-and-click interface for durability, auditability and automation: your data outlives any vendor, every change is a reviewable diff, and any script can read it. Beancount, Ledger and hledger are the three best-known implementations.

Plugin​

A plugin is a Python module Beancount loads while processing your file, allowing it to add, transform or validate directives before reports are built. Plugins are how forecasting, amortization schedules and custom checks are implemented without changing the core language. You enable one with a plugin line at the top of your ledger — the Forecast Plugin guide walks through a real example.

Posting​

A posting is one leg of a transaction: an account, an amount, and optionally a cost or price. A transaction needs at least two postings, and their amounts must sum to zero. At most one posting may leave its amount blank, in which case Beancount computes the balancing figure for you.

Price directive​

A price directive records the exchange rate between two commodities on a date, which is how Beancount converts a holding to its market value in reports. Prices are pure reference data — they never move money and never appear in a transaction. Without them, a portfolio still balances at cost but cannot be valued at market.

2026-06-30 price VTI   271.40 USD

Reconciliation​

Reconciliation is the act of proving that your books agree with an outside record such as a bank or brokerage statement. In plain-text accounting it is largely mechanical: add a balance assertion for each statement date and let the tool tell you whether the numbers match. A ledger that reconciles cleanly every month is one you can file taxes from without fear.

Tags and links​

Tags and links are the two labels you attach to transactions to group them outside the account hierarchy: a tag with # marks a theme such as #trip-japan, and a link with ^ ties related entries such as ^invoice-2026-014 together. Tags answer "show me everything in this category"; links answer "show me the entries that belong to this one event". Both are filterable in Fava and queryable in BQL — see Filtering and Searching.

Transaction​

A transaction is a dated economic event together with the postings that record it, and it is the directive you will write most often. It carries a flag (* for confirmed, ! for needs-review), an optional payee, a narration, and two or more postings whose amounts sum to zero. Everything else in a Beancount file exists to declare, check or annotate transactions.

2026-02-14 * "Blue Bottle" "Coffee with Dana"
  Expenses:Food:Coffee      9.50 USD
  Assets:US:BofA:Checking  -9.50 USD

Still stuck on a word? The Help Center indexes every guide on this site, and the Cheatsheet puts the syntax for each directive side by side.