Getting Started

• New to Beancount
• Starting accounting
• Importing existing Beancount ledger

New to Beancount

After logging into Dashboard, you will find an automatically created ledger named "Your Ledger" with some example data. You can click Open Fava to open the Web UI:

In Fava, you can access the plain text editing editor by clicking Editor in the left navigation bar. Alternatively, you can quickly add a new transaction by clicking the plus sign on the right side of Editor.

You can also use Git to clone the ledger to your local computer (Ensure you have set up an SSH key beforehand):

$ git clone [email protected]:ledgers/1 'Your Ledger'

Then, open it with your preferred text editor:

If you're unfamiliar with Beancount, consider reading the following resources:

• Beancount User's Manual Official Documentation

Starting accounting

Each transaction in Beancount represents the flow of funds from one account to another. You may need to create some accounts depending on your accounting goals and the level of granularity you need:

2023-01-01 open Income:Salary              ; Salary income
2023-01-01 open Income:Investment          ; Investment income
2023-01-01 open Assets:Bank:ICBC           ; Bank savings account
2023-01-01 open Assets:Funds:Antfin        ; Funds investment account
2023-01-01 open Liabilities:CreditCard:CMB ; Credit card
2023-01-01 open Expenses:Food              ; Food expense
2023-01-01 open Expenses:Uncounted         ; Uncounted expense

Now you can start bookkeeping:

2023-11-10 * "Salary"
  Income:Salary     -10000.00 CNY
  Assets:Bank:ICBC  +10000.00 CNY

2023-11-11 * "A hot pot"
  Assets:Bank:ICBC  -250.00 CNY
  Expenses:Food     ; Omit the amount and let Beancount calculate it automatically.

2023-11-15 * "Credit card repayment"
  Assets:Bank:ICBC            -1500.00 CNY
  Liabilities:CreditCard:CMB  +1500.00 CNY

Of course, before you start using Beancount, you'll likely already have some balances in your asset accounts, and you'll need to tell Beancount the initial balances in those accounts:

2023-10-31 pad Assets:Bank:ICBC Equity:Opening-Balances
2023-11-01 balance Assets:Bank:ICBC 12345.00 CNY

2023-10-31 pad Liabilities:CreditCard:CMB Equity:Opening-Balances
2023-11-01 balance Liabilities:CreditCard:CMB -1250.00 CNY

If you don't want to record every small transaction, you can update the balance of your accounts by periodically adding the pad and balance commands to roughly categorize the difference to a given account (e.g. Equity:Opening-Balances in the example above):

; Categorize all balance changes since the last record to uncounted expenses
2023-11-30 pad Liabilities:CreditCard:CMB Expenses:Uncounted
2023-12-01 balance Liabilities:CreditCard:CMB -1300 CNY

; Categorize all balance changes since the last record to investment income
2023-11-30 pad Assets:Funds:Antfin Income:Investment
2023-12-01 balance Assets:Funds:Antfin 3,009.41 CNY

Importing existing Beancount ledger

After logging into Dashboard, you will see an automatically created ledger named "Your Ledger" along with its Git address ([email protected]:ledgers/1). If you already have your own Beancount ledger, you can push it to Hostedbeans, overwriting the automatically created one.

Once you have set up the SSH key, run the following in your local repository:

$ git remote add origin [email protected]:ledgers/1
$ git push --set-upstream --force origin :
Enumerating objects: 215, done.
Counting objects: 100% (215/215), done.
Compressing objects: 100% (204/204), done.
Writing objects: 100% (215/215), 68.42 KiB | 4.02 MiB/s, done.
remote: Resolving deltas: 100% (109/109), done.
To hostedbeans.io:ledgers/1
 + 42f54cc...8cf9ffd master -> master (forced update)
branch 'master' set up to track 'origin/master'.