README
¶
go-beancount
A Go library and toolchain for Beancount plain-text accounting.
Project status
This project is in early development. No stable API yet; expect breaking changes without notice.
The component listings below distinguish between implemented packages and commands (which exist and build today) and planned ones (which are designed in PLAN.md but not yet written). Do not assume that a name appearing in this README corresponds to working code unless it is in an "Implemented" section.
Overview
go-beancount re-implements Beancount's ledger processing in Go, aiming for full compatibility with the Beancount file format and query language. It is designed as a layered system: a low-level parsing library, higher-level semantic libraries, and a suite of end-user tools built on top.
Python compatibility is explicitly out of scope. Custom plugins must be written in Go.
Components
Implemented packages
| Package | Description |
|---|---|
pkg/syntax |
Concrete Syntax Tree (CST) parser with error recovery |
pkg/ast |
Abstract Syntax Tree (AST) with include resolution |
pkg/format |
Canonical formatter |
pkg/printer |
File generation from CST or AST |
pkg/inventory |
Lot-based inventory tracking with FIFO/LIFO/STRICT cost basis |
pkg/validation |
Balance checks, account lifecycle, padding, document validation (subpackages: balance, document, pad, validations) |
pkg/ext |
Plugin system: Go .so loader (pkg/ext/goplug) and post-parse / pre-validation runner with bundled std plugins (pkg/ext/postproc) |
pkg/loader |
High-level entry point that loads Beancount source through the full pipeline (parse → AST → plugins → validation); mirrors upstream loader.py. Exposes Load, LoadReader, LoadFile. |
pkg/quote |
Plugin-extensible commodity price quoter (subpackages: api, meta, pricedb, sourceutil, std/ecb) |
pkg/distribute |
Stateless directive-distribution library backing beanfile: route directives to files (route), detect duplicates across active and commented-out entries (dedup), recognize/emit commented directives (comment), and perform CST-preserving atomic writes (merge) |
Planned packages
| Package | Description |
|---|---|
pkg/query |
Beancount Query Language (BQL) engine (PLAN.md Phase 9) |
Implemented commands
| Command | Description |
|---|---|
beanfmt |
Canonical ledger file formatter |
beancheck |
Loads a ledger through the full pipeline (pad, balance, validations, plugins) and reports diagnostics; supports -strict |
beanprice |
Commodity price fetcher built on pkg/quote |
beanfile |
Stateless directive distributor for multi-file ledgers: reads a directive stream and files each directive into the appropriate destination with a three-way write / comment / skip decision |
Planned commands
| Command | Description |
|---|---|
beancount-lsp |
Language Server Protocol server for editor integration (PLAN.md Phase 11) |
bean-daemon |
Background server: in-memory ledger store, BQL queries, HTTP/JSON API (PLAN.md Phase 10) |
beansprout |
User-facing CLI: price quoting, transaction importing, and more (PLAN.md Phase 12) |
Building
This project uses Bazel via Bazelisk.
# Build everything
bazel build //...
# Run all tests
bazel test //...
# After adding or modifying .go files
bazel run //:gazelle
# After modifying go.mod
bazel run //:gazelle -- update-repos -from_file=go.mod
Go Module
github.com/yugui/go-beancount
Requires Go 1.25 or later.
Roadmap
See PLAN.md for the detailed technical design and phased development plan.
License
Copyright (C) 2007-2022 Martin Blais. All Rights Reserved. Copyright (C) 2026 Yugui Sonoda. All Rights Reserved.
This code is distributed under the terms of the "GNU GPLv2 only". See COPYING file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
beancheck
command
Command beancheck loads a beancount ledger through the full processing pipeline (pad, balance, validations, plugins) and reports every diagnostic it finds.
|
Command beancheck loads a beancount ledger through the full processing pipeline (pad, balance, validations, plugins) and reports every diagnostic it finds. |
|
beanfile
command
Command beanfile is a stateless offline CLI that reads a beancount directive stream (stdin or one or more positional files) and files each directive into the appropriate file in a multi-file ledger.
|
Command beanfile is a stateless offline CLI that reads a beancount directive stream (stdin or one or more positional files) and files each directive into the appropriate file in a multi-file ledger. |
|
beanfmt
command
Command beanfmt formats beancount source files.
|
Command beanfmt formats beancount source files. |
|
beanimport
command
Command beanimport drives the pkg/importer + pkg/importer/hook pipeline against a single input file.
|
Command beanimport drives the pkg/importer + pkg/importer/hook pipeline against a single input file. |
|
beanprice
command
Command beanprice fetches commodity prices using the Phase 7 quote pipeline.
|
Command beanprice fetches commodity prices using the Phase 7 quote pipeline. |
|
internal
|
|
|
atomicfile
Package atomicfile writes files atomically.
|
Package atomicfile writes files atomically. |
|
formatopt
Package formatopt defines formatting options for beancount output.
|
Package formatopt defines formatting options for beancount output. |
|
loadopt
Package loadopt defines options for loading beancount source.
|
Package loadopt defines options for loading beancount source. |
|
pkg
|
|
|
ast
Package ast defines the abstract syntax tree types for beancount files.
|
Package ast defines the abstract syntax tree types for beancount files. |
|
ast/asttest
Package asttest provides test fixtures for ast values.
|
Package asttest provides test fixtures for ast values. |
|
compat/beancompat
Package beancompat consumes the upstream beancompat JSON fixture suite to measure go-beancount's behavioral conformance against other beancount implementations.
|
Package beancompat consumes the upstream beancompat JSON fixture suite to measure go-beancount's behavioral conformance against other beancount implementations. |
|
compat/beancompat/adapter/beanparse
command
Command beanparse reads a beancount file through the full loader pipeline (parse + plugins + pad/balance/validations) and writes its contents to stdout as a JSON object in beancompat's portable {directives, errors, options} schema.
|
Command beanparse reads a beancount file through the full loader pipeline (parse + plugins + pad/balance/validations) and writes its contents to stdout as a JSON object in beancompat's portable {directives, errors, options} schema. |
|
distribute/comment
Package comment recognizes commented-out beancount directives in source text and emits ast.Directive values back as commented-out blocks.
|
Package comment recognizes commented-out beancount directives in source text and emits ast.Directive values back as commented-out blocks. |
|
distribute/dedup
Package dedup builds and queries an equivalence index over the active and commented-out directives of a beancount ledger so a caller can decide whether a new directive duplicates one that is already filed.
|
Package dedup builds and queries an equivalence index over the active and commented-out directives of a beancount ledger so a caller can decide whether a new directive duplicates one that is already filed. |
|
distribute/merge
Package merge writes new directives into a destination beancount file while preserving every byte of surrounding content.
|
Package merge writes new directives into a destination beancount file while preserving every byte of surrounding content. |
|
distribute/route
Package route resolves an ast.Directive to a destination file path under the standard convention.
|
Package route resolves an ast.Directive to a destination file path under the standard convention. |
|
distribute/route/routeconfig
Package routeconfig loads a beanfile TOML routing configuration into a route.Config.
|
Package routeconfig loads a beanfile TOML routing configuration into a route.Config. |
|
ext/goplug
Package goplug loads beancount postprocessor plugins from Go plugin shared objects (.so files) built with `go build -buildmode=plugin`.
|
Package goplug loads beancount postprocessor plugins from Go plugin shared objects (.so files) built with `go build -buildmode=plugin`. |
|
ext/postproc
Package postproc provides the in-process plugin registry and runner for beancount ledger transformation plugins.
|
Package postproc provides the in-process plugin registry and runner for beancount ledger transformation plugins. |
|
ext/postproc/api
Package api defines the stable interface for beancount postprocessors.
|
Package api defines the stable interface for beancount postprocessors. |
|
ext/postproc/std
Package std is the Go port of beancount's standard plugin library (upstream: github.com/beancount/beancount, beancount/plugins/*.py).
|
Package std is the Go port of beancount's standard plugin library (upstream: github.com/beancount/beancount, beancount/plugins/*.py). |
|
ext/postproc/std/autoaccounts
Package autoaccounts is the Go port of upstream beancount's auto_accounts plugin — it synthesizes Open directives for any account referenced in the ledger but never explicitly opened.
|
Package autoaccounts is the Go port of upstream beancount's auto_accounts plugin — it synthesizes Open directives for any account referenced in the ledger but never explicitly opened. |
|
ext/postproc/std/checkclosing
Package checkclosing is the Go port of upstream beancount's check_closing plugin — it expands a `closing: TRUE` posting metadata into a zero-balance assertion dated one day after the transaction.
|
Package checkclosing is the Go port of upstream beancount's check_closing plugin — it expands a `closing: TRUE` posting metadata into a zero-balance assertion dated one day after the transaction. |
|
ext/postproc/std/checkcommodity
Package checkcommodity is the Go port of upstream beancount's check_commodity plugin — it diagnoses every currency that appears in the ledger without a matching Commodity directive.
|
Package checkcommodity is the Go port of upstream beancount's check_commodity plugin — it diagnoses every currency that appears in the ledger without a matching Commodity directive. |
|
ext/postproc/std/checkdrained
Package checkdrained is the Go port of upstream beancount's check_drained plugin — it enforces that balance-sheet accounts are empty at the moment they are closed.
|
Package checkdrained is the Go port of upstream beancount's check_drained plugin — it enforces that balance-sheet accounts are empty at the moment they are closed. |
|
ext/postproc/std/closetree
Package closetree is the Go port of upstream beancount's close_tree plugin — when an account is closed, the plugin synthesizes Close directives for every still-open descendant of that account so that a single user-authored Close shuts down the entire subtree.
|
Package closetree is the Go port of upstream beancount's close_tree plugin — when an account is closed, the plugin synthesizes Close directives for every still-open descendant of that account so that a single user-authored Close shuts down the entire subtree. |
|
ext/postproc/std/coherentcost
Package coherentcost is the Go port of upstream beancount's coherent_cost plugin — it diagnoses any (account, commodity) pair that is held both with and without a cost annotation in the same ledger.
|
Package coherentcost is the Go port of upstream beancount's coherent_cost plugin — it diagnoses any (account, commodity) pair that is held both with and without a cost annotation in the same ledger. |
|
ext/postproc/std/excludetag
Package excludetag is the Go port of upstream beancount's exclude_tag plugin — it removes ast.Transaction directives that carry a designated tag from the ledger, so a single tag can be used to mark transactions that should be hidden from the booked stream (canonical use case: virtual transactions used to demonstrate or rehearse postings without affecting balances).
|
Package excludetag is the Go port of upstream beancount's exclude_tag plugin — it removes ast.Transaction directives that carry a designated tag from the ledger, so a single tag can be used to mark transactions that should be hidden from the booked stream (canonical use case: virtual transactions used to demonstrate or rehearse postings without affecting balances). |
|
ext/postproc/std/implicitprices
Package implicitprices is the Go port of upstream beancount's implicit_prices plugin — it synthesizes ast.Price directives from the cost annotations and explicit price annotations carried on transaction postings, so that the price database is automatically populated as transactions occur.
|
Package implicitprices is the Go port of upstream beancount's implicit_prices plugin — it synthesizes ast.Price directives from the cost annotations and explicit price annotations carried on transaction postings, so that the price database is automatically populated as transactions occur. |
|
ext/postproc/std/leafonly
Package leafonly is the Go port of upstream beancount's leafonly plugin — it diagnoses any non-leaf account that is used in a transaction posting.
|
Package leafonly is the Go port of upstream beancount's leafonly plugin — it diagnoses any non-leaf account that is used in a transaction posting. |
|
ext/postproc/std/noduplicates
Package noduplicates is the Go port of upstream beancount's noduplicates plugin — it diagnoses ast.Transaction directives that appear to be duplicates of an earlier transaction in the same ledger.
|
Package noduplicates is the Go port of upstream beancount's noduplicates plugin — it diagnoses ast.Transaction directives that appear to be duplicates of an earlier transaction in the same ledger. |
|
ext/postproc/std/nounused
Package nounused is the Go port of upstream beancount's nounused plugin — it diagnoses any account that is opened but never subsequently referenced by another directive.
|
Package nounused is the Go port of upstream beancount's nounused plugin — it diagnoses any account that is opened but never subsequently referenced by another directive. |
|
ext/postproc/std/onecommodity
Package onecommodity is the Go port of upstream beancount's onecommodity plugin — it diagnoses any account that holds postings (or balance assertions) in more than one commodity.
|
Package onecommodity is the Go port of upstream beancount's onecommodity plugin — it diagnoses any account that holds postings (or balance assertions) in more than one commodity. |
|
ext/postproc/std/sellgains
Package sellgains is the Go port of upstream beancount's sellgains plugin — a diagnostic-only check that cross-validates declared gains against the price-times-units side of capital-gain transactions.
|
Package sellgains is the Go port of upstream beancount's sellgains plugin — a diagnostic-only check that cross-validates declared gains against the price-times-units side of capital-gain transactions. |
|
ext/postproc/std/uniqueprices
Package uniqueprices is the Go port of upstream beancount's unique_prices plugin — it diagnoses ast.Price directives whose (date, base, quote) triple has another Price directive declared on the same date but with a different price value.
|
Package uniqueprices is the Go port of upstream beancount's unique_prices plugin — it diagnoses ast.Price directives whose (date, base, quote) triple has another Price directive declared on the same date but with a different price value. |
|
format
Package format provides public formatting options for beancount output.
|
Package format provides public formatting options for beancount output. |
|
importer
Package importer defines the Beancount import framework: the Importer interface, the Factory pattern for creating configured instances, and the registry-driven dispatch pipeline.
|
Package importer defines the Beancount import framework: the Importer interface, the Factory pattern for creating configured instances, and the registry-driven dispatch pipeline. |
|
importer/hook
Package hook defines the post-import hook pipeline.
|
Package hook defines the post-import hook pipeline. |
|
importer/hook/std/classify
Package classify is the reference classifier hook.
|
Package classify is the reference classifier hook. |
|
importer/importerutil
Package importerutil offers small, pure per-directive transforms that importer authors call from inside their Extract methods.
|
Package importerutil offers small, pure per-directive transforms that importer authors call from inside their Extract methods. |
|
importer/std/csvimp
Package csvimp is the reference CSV/TSV importer.
|
Package csvimp is the reference CSV/TSV importer. |
|
inventory
Package inventory implements lot-based inventory tracking for Beancount ledgers.
|
Package inventory implements lot-based inventory tracking for Beancount ledgers. |
|
loader
Package loader provides a high-level entry point for loading beancount source with plugin processing, mirroring beancount's upstream loader.py.
|
Package loader provides a high-level entry point for loading beancount source with plugin processing, mirroring beancount's upstream loader.py. |
|
loader/booking
Package booking adapts the inventory layer's booking pass to the post-processor plugin interface.
|
Package booking adapts the inventory layer's booking pass to the post-processor plugin interface. |
|
printer
Package printer writes beancount AST nodes as formatted text.
|
Package printer writes beancount AST nodes as formatted text. |
|
quote
Package quote fetches prices from external market and FX sources and emits them as ast.Price directives ready to feed into the rest of the go-beancount pipeline.
|
Package quote fetches prices from external market and FX sources and emits them as ast.Price directives ready to feed into the rest of the go-beancount pipeline. |
|
quote/api
Package api defines the stable interface shared between the orchestrator in pkg/quote, source authors writing in-tree quoters, and out-of-tree goplug (the mechanism for loading out-of-tree quoters from `.so` files at runtime) plugins that contribute additional sources.
|
Package api defines the stable interface shared between the orchestrator in pkg/quote, source authors writing in-tree quoters, and out-of-tree goplug (the mechanism for loading out-of-tree quoters from `.so` files at runtime) plugins that contribute additional sources. |
|
quote/meta
Package meta parses bean-price-compatible "price" metadata strings off ast.Commodity directives into the typed PriceRequest values that the orchestrator consumes.
|
Package meta parses bean-price-compatible "price" metadata strings off ast.Commodity directives into the typed PriceRequest values that the orchestrator consumes. |
|
quote/pricedb
Package pricedb is the small post-processing layer between the quote orchestrator and the CLI's stdout: it deduplicates the ast.Price values returned from one or more sources and writes them out in a deterministic order via pkg/printer.
|
Package pricedb is the small post-processing layer between the quote orchestrator and the CLI's stdout: it deduplicates the ast.Price values returned from one or more sources and writes them out in a deterministic order via pkg/printer. |
|
quote/sourceutil
Package sourceutil provides composable decorators and adapters that quote-source authors stack to express their natural batching axis and operational policies (concurrency, rate limiting, retry, caching) without the orchestrator having to know about any of them.
|
Package sourceutil provides composable decorators and adapters that quote-source authors stack to express their natural batching axis and operational policies (concurrency, rate limiting, retry, caching) without the orchestrator having to know about any of them. |
|
quote/std/ecb
Package ecb fetches Eurozone foreign-exchange reference rates published by the European Central Bank, registered as the quote source named "ecb".
|
Package ecb fetches Eurozone foreign-exchange reference rates published by the European Central Bank, registered as the quote source named "ecb". |
|
syntax
Package syntax provides a concrete syntax tree (CST) representation of beancount source along with the lexer and parser that build it.
|
Package syntax provides a concrete syntax tree (CST) representation of beancount source along with the lexer and parser that build it. |
|
validation
Package validation performs semantic checks on a loaded beancount ledger.
|
Package validation performs semantic checks on a loaded beancount ledger. |
|
validation/balance
Package balance implements the balance-assertion check as an api.Plugin.
|
Package balance implements the balance-assertion check as an api.Plugin. |
|
validation/document
Package document implements the document-directive pre-builtin plugin, mirroring the verify_document_files_exist phase from beancount/ops/documents.py: every Document directive in the ledger is checked against the filesystem, and a document-missing-file diagnostic is emitted for any path that does not exist.
|
Package document implements the document-directive pre-builtin plugin, mirroring the verify_document_files_exist phase from beancount/ops/documents.py: every Document directive in the ledger is checked against the filesystem, and a document-missing-file diagnostic is emitted for any path that does not exist. |
|
validation/internal/accountstate
Package accountstate defines the per-account state tracked during ledger validation.
|
Package accountstate defines the per-account state tracked during ledger validation. |
|
validation/internal/tolerance
Package tolerance derives per-currency residual tolerances for transaction balancing and balance assertions.
|
Package tolerance derives per-currency residual tolerances for transaction balancing and balance assertions. |
|
validation/pad
Package pad implements the pad directive as an api.Plugin.
|
Package pad implements the pad directive as an api.Plugin. |
|
validation/validations
Package validations implements the validations-layer plugin of the postprocessing pipeline.
|
Package validations implements the validations-layer plugin of the postprocessing pipeline. |
Click to show internal directories.
Click to hide internal directories.