Skip to main content
Version: 2.3.1

Settings

The Settings page is where you configure the plugin to work with your Beancount ledger. Settings are organized into six tabs for easy navigation and configuration.

📋 Overview​

Settings are accessible via Settings → Community Plugins → Beancount Ledger. The interface is organized into these tabs:

  1. General - Currency, automatic price fetching, and debug settings
  2. Connection - Beancount executable and system configuration
  3. File Organization - Structured layout options
  4. BQL - Query display preferences and editor settings
  5. Performance - Data fetch limits
  6. Backup - Backup and recovery settings

⚙️ General Tab​

Operating Currency​

  • Purpose: The primary currency for reporting and as the default in transaction forms.
  • Examples: USD, EUR, INR, GBP
  • Impact: All balance calculations and Net Worth displays use this currency as the base.
  • Validation: Validated as a valid 3-letter currency code on input.

Debug Mode​

  • Purpose: Enable detailed logging to the browser console for troubleshooting.
  • When to Enable: If you encounter issues and need to inspect what the plugin is doing.
  • Access Logs: Open Obsidian's Developer Console with Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS).
  • Output Prefix: Plugin logs are prefixed with [Beancount] for easy filtering.

Automatic Price Fetching​

This section controls how the plugin runs bean-price to keep your commodity prices up to date.

  • Enable automatic price fetching: When enabled, the plugin runs bean-price <ledger> at a regular interval, extracts price directives from stdout, and appends any new ones to prices.beancount (duplicates are skipped automatically).
  • Fetch interval (hours): How frequently the automatic fetch runs (default: 24 hours).
  • Last automatic fetch: Displays when the most recent automatic fetch ran, shown as a relative time (e.g., 2 hours ago).

Tip: You can also trigger a manual fetch at any time via Command Palette → "Fetch Commodity Prices".

See the Automated Price Fetching guide for details on annotating commodities with price sources.

🔌 Connection Tab​

This tab manages the connection between the plugin and your Beancount installation.

Automatic System Detection​

On startup, the plugin automatically detects:

  • Python Executable: Searches PATH and standard installation locations for Python 3.
  • Beancount Installation: Verifies bean-query command is available.
  • Beancount File: Finds your main ledger file (if it was previously configured).
  • WSL Availability: Checks if Windows Subsystem for Linux is running (for Windows users).

Status Indicators​

After detection, you'll see status icons for:

  • ✅ Ready: The component is correctly configured and working.
  • ⚠️ Warning: The component exists but may have issues.
  • ❌ Error: The component is not found or not working. Click to see error details.

Manual Configuration​

If automatic detection fails, you can:

  1. Set Python Executable Path: Enter the full path to your Python 3 executable.
  2. Set Beancount File Path: Enter the absolute path to your .beancount file.
  3. Set Beancount Command Path: Enter the full path to bean-query.

Test Commands​

Verify your setup with individual test buttons:

  • Test Bean Check: Validates Beancount file syntax (runs bean-check).
  • Test Bean Query: Tests BQL query execution.
  • Test Bean Query CSV: Validates CSV output format.
  • Test All Commands: Runs all tests sequentially.

📁 File Organization Tab​

Configure how your Beancount ledger is organized.

Structured Layout​

The plugin organizes your finances using a structured folder layout with multiple files by type:

Finances/
├── ledger.beancount          # Main file with includes
├── accounts.beancount        # Account opening directives
├── commodities.beancount     # Commodity declarations
├── prices.beancount          # Price directives
├── balances.beancount        # Balance assertions
├── pads.beancount            # Pad directives
├── notes.beancount           # Note directives
├── events.beancount          # Event directives
├── queries.beancount         # Named query directives
└── transactions/             # Folder for transaction files
    ├── 2024.beancount        # Transactions by year
    ├── 2025.beancount
    └── 2026.beancount

Configuration Options​

  • Folder Name: Name of the root folder for structured layout (default: Finances).
  • Importing Existing Ledgers: If you have an existing single-file ledger, the plugin can import and organize it into this structured layout via the onboarding wizard.

📊 BQL Tab​

Customize how Beancount Query Language results are displayed in your notes.

Show Query Tools​

  • Default: Enabled ✅
  • Purpose: Displays toolbar buttons above BQL code block results:
    • Refresh (⟳): Re-run the query with fresh data.
    • Copy (📋): Copy raw CSV results to clipboard.
    • Download (📥): Export results as a CSV file.

Show Query Text​

  • Default: Disabled ❌
  • Purpose: Shows the original BQL query above results.

Editor Settings​

  • Account Name Autocomplete: Toggle account name popup while typing.
  • Editor Autocomplete: Toggle payee, narration, currency, tag, and link autocomplete.
  • User-defined snippets: Enable loading custom transaction templates from a standalone snippets.beancount file inside your structured layout folder.
  • Editor Diagnostics (Linting): Select between Off, On save, or On change validation.
  • Format on Save: Format .beancount files automatically on save.

⚡ Performance Tab​

Optimize plugin performance for your hardware and ledger size.

Max Transaction Results​

  • Default: 2000
  • Purpose: Limits the number of transactions fetched for the Transactions tab. Lower this if the Dashboard feels sluggish.

Max Journal Results​

  • Default: 1000
  • Purpose: Limits entries displayed per page in the Journal tab.

💾 Backup Tab​

Configure automatic backups for data safety.

Create Backups​

  • Default: Enabled ✅
  • Purpose: Automatically creates timestamped backup files before modifying your Beancount files.
  • Backup Format: <filename>.backup.<YYYYMMDD-HHMMSS>

Max Backup Files​

  • Default: 10
  • Purpose: Maximum number of backup files to keep (set to 0 for unlimited). Oldest backups are automatically deleted when the limit is exceeded.