{"id":18775164,"url":"https://github.com/robinvdvleuten/beancount","last_synced_at":"2026-01-16T10:53:41.517Z","repository":{"id":66127149,"uuid":"546815482","full_name":"robinvdvleuten/beancount","owner":"robinvdvleuten","description":"Fast, lightweight Beancount parser, formatter and editor written in Go","archived":false,"fork":false,"pushed_at":"2026-01-12T14:40:09.000Z","size":1245,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-12T21:13:15.032Z","etag":null,"topics":["accounting","beancount","cli","finance","go","ledger","plaintext","plaintext-accounting","solidjs"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robinvdvleuten.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2022-10-06T17:36:49.000Z","updated_at":"2026-01-12T14:41:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"a92d54f4-d272-4ec4-9e87-62b8d5c8b204","html_url":"https://github.com/robinvdvleuten/beancount","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/robinvdvleuten/beancount","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinvdvleuten%2Fbeancount","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinvdvleuten%2Fbeancount/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinvdvleuten%2Fbeancount/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinvdvleuten%2Fbeancount/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robinvdvleuten","download_url":"https://codeload.github.com/robinvdvleuten/beancount/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinvdvleuten%2Fbeancount/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accounting","beancount","cli","finance","go","ledger","plaintext","plaintext-accounting","solidjs"],"created_at":"2024-11-07T19:40:35.629Z","updated_at":"2026-01-16T10:53:41.507Z","avatar_url":"https://github.com/robinvdvleuten.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# beancount\n\n![beancounting-gopher](https://github.com/user-attachments/assets/e73f4046-22d2-4824-b8f0-11a1b4702cfa)\n\nA fast, lightweight [Beancount](https://beancount.github.io/) parser and formatter written in Go.\n\n[![Latest Release](https://img.shields.io/github/release/robinvdvleuten/beancount.svg?style=flat-square)](https://github.com/robinvdvleuten/beancount/releases)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/robinvdvleuten/beancount/build.yml?style=flat-square\u0026branch=main)](https://github.com/robinvdvleuten/beancount/actions?query=workflow%3Abuild)\n[![GPL-2.0 license](https://img.shields.io/github/license/robinvdvleuten/beancount.svg?style=flat-square)](https://github.com/robinvdvleuten/beancount/blob/main/COPYING)\n[![PkgGoDev](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/robinvdvleuten/beancount)\n[![Go ReportCard](https://goreportcard.com/badge/github.com/robinvdvleuten/beancount?style=flat-square)](https://goreportcard.com/report/robinvdvleuten/beancount)\n\n## What is it?\n\n[Beancount](https://beancount.github.io/) is a double-entry bookkeeping system that uses plain text files to track personal or business finances. It allows you to maintain your accounting ledger as readable text files, making it easy to version control, search, and programmatically manipulate your financial data. The Beancount file format uses a simple, human-readable syntax to record transactions, accounts, and other financial directives.\n\nThis project is a Go implementation of a Beancount file parser, formatter, and validator. While the official Beancount implementation is written in Python and includes a full accounting engine with balance calculations, reports, queries, and a web interface, this Go version focuses on parsing, formatting, and ledger validation. It's designed to be fast and lightweight, making it ideal for tooling, text editors, build pipelines, or any situation where you need to validate Beancount files without the overhead of the full accounting system.\n\n## Features\n\nThis implementation currently supports:\n\n- **Parsing**: Full parsing of Beancount file syntax\n- **Formatting**: Auto-align currencies, numbers, and accounts\n- **Validation**: Balance checks, account lifecycle, assertions\n- **Inventory**: Lot-based tracking with cost basis (FIFO/LIFO)\n- **Includes**: Recursive loading of modular Beancount files\n- **CLI Interface**: Simple command-line tools for common operations\n\n**Note**: This implementation includes ledger validation with transaction balancing, account management, and inventory tracking. It does not include reporting, queries, or a web interface like the official Python implementation.\n\n## Compatibility\n\nThis Go implementation is stricter than the official Python Beancount parser in some areas:\n\n- Arithmetic expressions in amounts must be enclosed in parentheses: `(155.74 + 304.58) USD` instead of `155.74 + 304.58 USD`\n- Amount values must include both a number and currency: `100.00 USD` (not just `100.00`)\n\n## Installation\n\n### Packages \u0026 Binaries\n\nIf you use Brew, you can simply install the package:\n\n```sh\nbrew install robinvdvleuten/tap/beancount\n```\n\nOr download a binary from the [releases](https://github.com/robinvdvleuten/beancount/releases)\npage. Linux (including ARM) binaries are available, as well as Debian, RPM AND APK\npackages.\n\n### Build From Source\n\nAlternatively you can also build `beancount` from source. Make sure you have a\nworking Go environment (Go 1.24 or higher is required). See the\n[install instructions](https://golang.org/doc/install.html).\n\nTo install beancount, simply run:\n\n```sh\ngo install github.com/robinvdvleuten/beancount\n```\n\n## Usage\n\n### Check a Beancount file\n\nValidate a Beancount file with full ledger checks:\n\n```sh\nbeancount check example.beancount\n```\n\nOr read from stdin (omit filename or use `-`):\n\n```sh\necho \"2024-01-01 open Assets:Checking USD\" | beancount check\n```\n\nThis command validates:\n- Transaction balance across all currencies\n- Account open/close dates are respected\n- Balance assertions match actual balances\n- All referenced accounts exist\n\nExample error output:\n```\nexample.beancount:15: Transaction does not balance: (-500.00 USD)\n\n   2020-01-15 * \"Grocery shopping\"\n     Assets:Checking   1000.00 USD\n     Expenses:Food      500.00 USD\n\n1 validation error(s) found\n```\n\n### Format a Beancount file\n\nFormat a Beancount file with automatic alignment:\n\n```sh\nbeancount format example.beancount\n\n# Specify currency column position\nbeancount format --currency-column 60 example.beancount\n\n# Customize account name and number widths\nbeancount format --prefix-width 50 --num-width 12 example.beancount\n```\n\nOr read from stdin (omit filename or use `-`):\n\n```sh\necho \"2024-01-01 open Assets:Checking USD\" | beancount format\n```\n\n### Telemetry\n\nUse the global `--telemetry` flag to see detailed timing breakdowns for any command:\n\n```sh\nbeancount --telemetry check example.beancount\nbeancount --telemetry format example.beancount\n```\n\nThis displays a hierarchical breakdown of where time is spent during execution:\n\n```\n✓ Check passed\n\ncheck example.beancount: 125ms\n├─ loader.load example.beancount: 85ms\n│  └─ loader.parse: 85ms\n│     ├─ parser.lexing: 75ms\n│     ├─ parser.parsing: 8ms\n│     ├─ parser.push_pop: ~1ms\n│     └─ parser.sorting: 245µs\n├─ loader.load accounts.beancount: 35ms\n│  └─ loader.parse: 35ms\n│     ├─ parser.lexing: 30ms\n│     ├─ parser.parsing: ~4ms\n│     ├─ parser.push_pop: 823µs\n│     └─ parser.sorting: 156µs\n├─ ast.merging: ~2ms\n└─ ledger.processing (1523 directives): ~3ms\n```\n\nThe telemetry output is written to stderr, making it easy to separate from command results.\n\n## Programmatic Usage\n\nThis library can be used programmatically in your Go applications to parse, manipulate, and generate Beancount files.\n\n### Parsing Beancount Files\n\nLoad and parse a Beancount file:\n\n```go\nimport (\n    \"context\"\n    \"github.com/robinvdvleuten/beancount/loader\"\n)\n\n// Load a single file\nldr := loader.New()\nast, err := ldr.Load(context.Background(), \"example.beancount\")\nif err != nil {\n    log.Fatal(err)\n}\n\n// Load with recursive include resolution\nldr = loader.New(loader.WithFollowIncludes())\nast, err = ldr.Load(context.Background(), \"main.beancount\")\n```\n\n### Building Transactions Programmatically\n\nCreate Beancount transactions using the builder API:\n\n```go\nimport \"github.com/robinvdvleuten/beancount/ast\"\n\n// Create a transaction with the functional options pattern\ndate, _ := ast.NewDate(\"2024-01-15\")\nchecking, _ := ast.NewAccount(\"Assets:Checking\")\ngroceries, _ := ast.NewAccount(\"Expenses:Groceries\")\n\ntxn := ast.NewTransaction(date, \"Grocery shopping\",\n    ast.WithFlag(\"*\"),\n    ast.WithPayee(\"Whole Foods\"),\n    ast.WithTags(\"food\", \"weekly\"),\n    ast.WithPostings(\n        ast.NewPosting(groceries, ast.WithAmount(\"125.43\", \"USD\")),\n        ast.NewPosting(checking), // Balancing posting\n    ),\n)\n```\n\n### Formatting Output\n\nFormat transactions back to Beancount syntax:\n\n```go\nimport (\n    \"context\"\n    \"os\"\n    \"github.com/robinvdvleuten/beancount/formatter\"\n)\n\n// Create a formatter\nfmtr := formatter.New()\n\n// Format a single transaction\nfmtr.FormatTransaction(txn, os.Stdout)\n\n// Format an entire AST\nfmtr.Format(context.Background(), ast, sourceContent, os.Stdout)\n```\n\n### Complete Example\n\nSee the [CSV Importer example](_examples/csv_importer/) for a complete working example that demonstrates:\n- Reading CSV files with Go's `encoding/csv`\n- Building transactions programmatically with the builder API\n- Automatic expense categorization\n- Error handling and validation\n- Formatting output\n\nRun the example:\n\n```sh\ncd _examples/csv_importer\ngo run main.go transactions.csv\n```\n\nFor more details on the builder API, see the [package documentation](https://pkg.go.dev/github.com/robinvdvleuten/beancount/ast).\n\n## Contributing\n\nEveryone is encouraged to help improve this project. Here are a few ways you can help:\n\n- [Report bugs](https://github.com/robinvdvleuten/beancount/issues)\n- Fix bugs and [submit pull requests](https://github.com/robinvdvleuten/beancount/pulls)\n- Write, clarify, or fix documentation\n- Suggest or add new features\n\nTo get started with development:\n\n```\ngit clone https://github.com/robinvdvleuten/beancount.git\ncd beancount\ngo test ./...\n```\n\nBefore submitting a pull request, please make sure to run\n`go fmt` on any Go source files you touched so the code stays consistent.\n\nFeel free to open an issue to get feedback on your idea before spending too much time on it.\n\n## License\n\nCopyright (c) Robin van der Vleuten\n\nLicensed under the GNU General Public License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    https://www.gnu.org/licenses/old-licenses/gpl-2.0.html\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinvdvleuten%2Fbeancount","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobinvdvleuten%2Fbeancount","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinvdvleuten%2Fbeancount/lists"}