{"id":20346642,"url":"https://github.com/arthurfdlr/beancount-starter","last_synced_at":"2025-09-12T11:33:24.727Z","repository":{"id":206587411,"uuid":"717242360","full_name":"ArthurFDLR/beancount-starter","owner":"ArthurFDLR","description":null,"archived":false,"fork":false,"pushed_at":"2023-11-11T23:41:57.000Z","size":18,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-14T22:31:38.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArthurFDLR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-11-10T22:28:17.000Z","updated_at":"2024-12-04T12:42:42.000Z","dependencies_parsed_at":"2024-11-14T22:13:55.509Z","dependency_job_id":"72aece66-4838-4d84-8c02-291175ed0e9e","html_url":"https://github.com/ArthurFDLR/beancount-starter","commit_stats":null,"previous_names":["arthurfdlr/beancount-starter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fbeancount-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fbeancount-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fbeancount-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fbeancount-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArthurFDLR","download_url":"https://codeload.github.com/ArthurFDLR/beancount-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241877415,"owners_count":20035403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-14T22:13:42.515Z","updated_at":"2025-03-04T15:47:42.596Z","avatar_url":"https://github.com/ArthurFDLR.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beancount Starter - A template to start your Beancount ledger \u003c!-- omit in toc --\u003e\n\n\nThis is a template to start your Beancount ledger. It includes a basic folder structure and some example files.\n\n- [Getting started](#getting-started)\n- [Import transactions from statements](#import-transactions-from-statements)\n- [Ledger structure](#ledger-structure)\n  - [`ledger/banking`](#ledgerbanking)\n  - [`ledger/setup`](#ledgersetup)\n    - [Assets](#assets)\n    - [Liabilities](#liabilities)\n    - [Expenses](#expenses)\n    - [Income](#income)\n    - [Commodities](#commodities)\n\n\n\n## Getting started\n\n1. Clone this repository:\n```bash\ngit clone git@github.com:ArthurFDLR/beancount-starter.git\n```\n\n2. Build the Docker image:\n```bash\ndocker build -t beancount-starter .\n``` \n\n3. Run the Docker container:\n```bash\ndocker run --rm -v $PWD:/ledger -e BEANCOUNT_FILE=/ledger/ledger-config.bean -p 5000:5000 beancount-starter\n```\n\n4. Open your browser at [http://localhost:5000](http://localhost:5000)\n\n## Import transactions from statements\n\n```bash\npython3 ./ledger-importers.py -s importers-input -o importers-output.bean -d documents\n```\n\n## Ledger structure\n\n### [`ledger/banking`](/ledger/banking/)\n\nThis folder contains all operations related to your bankings accounts: checking, savings, credit cards, etc.\nCreate a file for each account and credit/debit card you have. Ideally, the name of the files should match the account names definned in your [`setup` folder](/ledger/setup/).\n\nFor example, if you have a Chase checking account (`Assets:US:Chase:Checking`) and the Freedom Unlimited credit card (`Liabilities:US:Chase:FreedomUnlimited`), you should have the following files:\n```\nbanking\n├── chase-checking.bean\n└── chase-freedom-unlimited.bean\n```\n\nIn case of large number of transactions, you can split the transactions history per year:\n```\nbanking\n├── 2022\n│   └── chase-checking.bean\n└── 2023\n    ├── chase-checking.bean\n    └── chase-freedom-unlimited.bean\n```\n\n### [`ledger/setup`](/ledger/setup/)\n\nThis folder contains all the files related to your setup. It is the first folder you should create when starting a new ledger. It defines all your bank accounts, credit cards, investment accounts, expenses categories, etc. A good setup is the key to a good ledger. It will make your life easier when you will start to enter transactions and generate reports.\n\nA clear understanding of Double-Entry accounting is crucial to setting up your ledger. If you are not familiar with Double-Entry accounting, I recommend you to read [Beancount creator's article *The Double-Entry Counting Method*](https://beancount.github.io/docs/the_double_entry_counting_method.html) page.\n\n#### Assets\n\n\u003e Asset accounts represent something the owner has. A canonical example is banking accounts. Another one is a “cash” account, which counts how much money is in your wallet. Investments are also assets (their units aren’t dollars in this case, but rather some number of shares of some mutual fund or stock). Finally, if you own a home, the home itself is considered an asset (and its market value fluctuates over time).\n\u003e *The Double-Entry Counting Method*, Martin Blais\n\nLet's start by setting up a checking account with Chase which holds $1,000.00 when you start your ledger:\n\n```beancount\n2020-07-08 open Assets:US:Chase:Checking         USD\n2020-07-08 pad Assets:US:Chase:Checking Equity:Opening-Balances\n2020-07-20 balance Assets:US:Chase:Checking  10000.00 USD\n```\n\nLet's say that you have 100.00€ in cash remaining from your last trip to Europe:\n\n```\n2020-01-01 open Assets:Cash\n2020-01-01 pad Assets:Cash Equity:Opening-Balances\n2020-07-17 balance Assets:Cash                 100.00 EUR\n```\n\nYour investment must also be defined as assets. Their definitiion will evolve with the various financial objects you will buy and sell.\n\n```beancount\n2020-07-08 open Assets:US:Vanguard:401K       USD, VTI\n2020-08-01 open Assets:HardWallet:Ledger      BTC, ETH\n```\n\nIf someone owes you money, you can create a receivable entry for that person or entity:\n\n```beancount\n2000-01-01 open Assets:Receivables\n2000-01-01 open Assets:Receivables:John\n2000-01-01 open Assets:Receivables:SecurityDeposit\n```\n\n#### Liabilities\n\n\u003e A liability account represents something the owner owes. The most common example is a credit card. Again, the statement provided by your bank will show positive numbers, but from your own perspective, they are negative numbers. A loan is also a liability account. For example, if you take out a mortgage on a home, this is money you owe, and will be tracked by an account with a negative amount. As you pay off the mortgage every month the negative number goes up, that is, its absolute value gets smaller and smaller over time (e.g., -120,000 -\u003e -117,345).\n\u003e *The Double-Entry Counting Method*, Martin Blais\n\nLet's say that you have a Chase Freedom Unlimited credit card and a student loan:\n\n```beancount\n2021-11-16 open Liabilities:US:Chase:FreedomUnlimited      USD\n2020-01-01 open Liabilities:StudentLoan                 USD\n```\n\n#### Expenses\n\n\u003e An expense account represents something you’ve received, perhaps by exchanging something else to purchase it. This type of account will seem pretty natural: food, drinks, clothing, rent, flights, hotels and most other categories of things you typically spend your disposable income on. However, taxes are also typically tracked by an expense account: when you receive some salary income, the amount of taxes withheld at the source is recorded immediately as an expense. Think of it as paying for government services you receive throughout the year.\n\u003e *The Double-Entry Counting Method*, Martin Blais\n\nThe expenses accounts are the most subjective part of your ledger. You can create as many as you want. The more you create, the more detailed your reports will be. However, you should not create too many accounts. It will make your ledger harder to maintain and your reports harder to read. Also, you should organize your expenses accounts in sub-accounts. For example, you can create a `Expenses:Food` account and then create sub-accounts for each type of food you buy: `Expenses:Food:Groceries`, `Expenses:Food:Restaurants`, `Expenses:Food:Coffee`, etc.\n\n\n#### Income\n\n\u003e An income account is used to count something you’ve given away in order to receive something else (typically assets or expenses). For most people with jobs, that is the value of their time (a salary income). Specifically, here we’re talking about the gross income. For example, if you’re earning a salary of $120,000/year, that number is $120,000, not whatever amount remains after paying for taxes. Other types of income includes dividends received from investments, or interest paid from bonds held. There are also a number of oddball things received you might record as income, such the value of rewards received, e.g., cash back from a credit card, or monetary gifts from someone.\n\u003e *The Double-Entry Counting Method*, Martin Blais\n\nLet's say that you get a salary from a 9 to 5 job with 401K matching. And you also get a side income from a rental property and a side hustle:\n\n```beancount\n2020-01-01 open Income:Work:Paycheck USD\n2020-01-01 open Income:Work:401Kmatch USD\n2020-01-01 open Income:RentalProperty USD\n2020-01-01 open Income:SideHustle USD\n```\n\n#### Commodities\n\nThere is a “Commodity” directive that can be used to declare currencies, financial instruments, commodities (different names for the same thing in Beancount):\n```\nYYYY-MM-DD commodity Currency\n```\n\nThis directive is entirely optional: you can use commodities without having to really declare them this way. The purpose of this directive is to attach commodity-specific metadata fields on it, so that it can be gathered by plugins later on. For example, you might want to provide automatically fetch prices for a given commodity. The [`beanprice`](https://github.com/beancount/beanprice) interpretes the `price` metadata field to fetch conversion prices from various sources.\n\nUse [`/scripts/fetch_prices.py`](/scripts/fetch_prices.py) to fetch the prices of all your commodities. It will create a `prices.bean` file in your `ledger` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurfdlr%2Fbeancount-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurfdlr%2Fbeancount-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurfdlr%2Fbeancount-starter/lists"}