A Guide to the beancount.io Web Interface
The beancount.io web interface (powered by Fava) provides a comprehensive suite of tools to manage, query, and visualize your financial data. This guide covers its main features, from basic data entry to advanced customization and troubleshooting.
1. Editing and Data Entry
The Built-in Editor
The interface includes a powerful text editor for making direct changes to your Beancount files. Key features include:
- Auto-completion: Press
Tab
to complete account names, payees, tags, and links. - Keyboard Shortcuts:
Ctrl+Space
: Trigger auto-completion.Ctrl+/
: Comment or uncomment lines.Ctrl+D
: Duplicate the current line.Alt+Up/Down
: Move the current line up or down.
- Smart Cursor Placement: Use the
$insert-entry$
option in your file to automatically place the cursor at the most recent entry for a specific account when the editor opens.option "insert-entry" "Expenses:Food:Dining-Out"
Adding Transactions
Click the +
button (or press n
) to open the transaction form.
- Quick Entry: The form suggests recent accounts and remembers common amounts for payees.
- Inline Tags/Links: Add tags and links directly in the narration field (e.g.,
Lunch #food ^receipt-001
). - Transaction Templates: Create future-dated entries with a
#template
tag. You can then use the form to find and fill them out.2099-01-01 * "Monthly Rent Payment" #template
Expenses:Housing:Rent 1500.00 USD
Assets:Checking -1500.00 USD
2. Document Management
Efficiently link receipts, statements, and other files to your transactions.
- Upload via Drag-and-Drop:
- Drop a file onto an account name to store it in that account's folder.
- Drop a file onto a transaction in the journal to link it directly.
- Document Storage: Files are saved to the folder specified by the
$option "documents" "path/to/your/documents"$
directive in your Beancount file. - Automated Linking: Beancount can automatically discover and link documents to transactions. Enable this with the following plugins:
plugin "fava.plugins.link_documents"
plugin "fava.plugins.tag_discovered_documents"
3. Querying and Analysis with BQL
The Query page allows you to run Beancount Query Language (BQL) queries, similar to the command-line bean-query
tool.
- Visualization: Query results are automatically rendered as tables. If your query returns two columns (like a date/string and a number), the interface will also generate a line, bar, or treemap chart.
- Export: Download any query result as a CSV file.
Practical Query Examples
- Monthly Expense Summary:
SELECT account, SUM(position) AS total
FROM postings
WHERE account ~ '^Expenses' AND date >= 2024-01-01 AND date < 2024-02-01
GROUP BY account
ORDER BY total DESC; - Income vs. Expenses by Month:
SELECT YEAR(date) as year, MONTH(date) as month,
SUM(IIF(account ~ '^Income', -position, 0)) as income,
SUM(IIF(account ~ '^Expenses', position, 0)) as expenses
FROM postings
GROUP BY year, month
ORDER BY year, month;
4. Customization and Workflow
Customizing the View
Tailor the interface display with these options in your Beancount file:
- Account Visibility: Control which accounts appear in the sidebar.
option "show-closed-accounts" "false"
option "show-accounts-with-zero-balance" "false"
option "collapse-pattern" "Assets:Investments:.*" - Up-to-Date Indicators: Colored dots next to accounts show their status (green for passing balance, red for failed, yellow for no recent balance check). Enable this in an account's
open
directive:2020-01-01 open Assets:Checking fava-uptodate-indication: "TRUE"
Sidebar Links
Add custom links to frequently used reports or filtered views in the sidebar.
2024-01-01 custom "fava-sidebar-link" "This Month's Expenses" "/income_statement/?time=month"
2024-01-01 custom "fava-sidebar-link" "All Documents" "/journal/?show=document"
General Configuration
- Multiple Files: If you load multiple
.beancount
files, you can switch between them using the dropdown at the top-left. - External Editor: Configure the UI to open files directly in your local editor using the
$use-external-editor$
option and a URL handler. - Language: Set the interface language with the
$language$
option, or let it auto-detect from your browser. - Exporting: Export any filtered journal view in Beancount format using the Export button.
5. Performance and Troubleshooting
Handling Large Files
For ledgers with thousands of transactions, improve performance by:
- Using Includes: Split your ledger into multiple files by year or month and use the
include
directive.include "accounts.beancount"
include "transactions/2023.beancount"
include "transactions/2024.beancount" - Filtering: Use time and filter options to limit the amount of data displayed at once.
Common Issues and Fixes
- Interface Not Loading:
- Check your file for syntax errors using the
bean-check
command-line tool. - Look for error messages at the bottom of the web page.
- Clear your browser cache.
- Check your file for syntax errors using the
- Slow Performance:
- Reduce the active date range in the UI.
- Simplify complex BQL queries.
- Configuration Mistakes: Ensure option names and custom directive types are enclosed in quotes.
; Correct
option "documents" "/path/to/docs"
custom "fava-sidebar-link" "Label" "URL"
; Incorrect (will cause errors)
option documents "/path/to/docs"
custom fava-sidebar-link "Label" "URL"