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:
  1. Check your file for syntax errors using the bean-check command-line tool.
  2. Look for error messages at the bottom of the web page.
  3. Clear your browser cache.
• Slow Performance:
  1. Reduce the active date range in the UI.
  2. 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"