---

title: Configuration description: Configure rustledger with profiles and options

Configuration

rustledger can be configured via environment variables, config files, and command-line options.

Environment Variables

Variable	Description	Example
RLEDGER_CONFIG_DIR	Config directory, used as-is (holds config.toml and importers.toml)	~/dots/rledger
RLEDGER_FILE	Default beancount file	~/ledger.beancount
RLEDGER_PROFILE	Active profile name	business
NO_COLOR	Disable colored output	1

Set in your shell profile (~/.bashrc, ~/.zshrc):

export RLEDGER_FILE="$HOME/finances/main.beancount"

Config File

rustledger looks for configuration in these locations (highest to lowest priority):

1. .rledger.toml in the current directory (searching upward)
2. The user config, resolved as:
   • $RLEDGER_CONFIG_DIR/config.toml if set — an explicit config directory, used as-is (this also relocates importers.toml)
   • Otherwise the platform default:
     • Linux: $XDG_CONFIG_HOME/rledger/config.toml (usually ~/.config/rledger/config.toml)
     • macOS: ~/Library/Application Support/rledger/config.toml, falling back to an XDG-style ~/.config/rledger/config.toml when only that exists
     • Windows: %APPDATA%\rledger\config.toml
3. /etc/rledger/config.toml (system config, Unix only)

export RLEDGER_CONFIG_DIR="$HOME/dots/rledger"

Higher priority configs override lower ones. You can also generate a default config with:

rledger config init           # Create user config
rledger config init --project # Create project config (.rledger.toml)
rledger config edit           # Open config in editor
rledger config show           # Show merged configuration

Example Config

# ~/.config/rledger/config.toml

[default]
# Default beancount file
file = "~/finances/main.beancount"

# Editor for interactive commands (defaults to $EDITOR)
# editor = "nvim"

# Command-specific output settings
[commands.query.output]
format = "text"

[commands.report.output]
format = "text"

# Profiles for different ledgers
[profiles.personal]
file = "~/finances/personal.beancount"

[profiles.business]
file = "~/finances/business.beancount"

# Command aliases
[aliases]
bal = "report balances"
is = "report income"
bs = "report balsheet"

# WASM plugin and importer limits
[plugins]
# Time budget for each plugin or importer call (default: 30)
max_time_secs = 120

Plugin Time Budget

Each call into a WASM plugin or WASM importer gets a time budget, 30 seconds by default, after which it is stopped with all fuel consumed by WebAssembly. The budget is counted in wasm work, not on a clock, and is sized so that a call never runs longer than its budget even on a slow machine. So on a typical machine a call runs out much sooner: most code gets one twentieth to one fifth of the stated seconds. A plugin doing real work over a large ledger can need more. Raise it with [plugins] max_time_secs in any config file, or for one run with the global --plugin-max-time-secs <SECS> flag, which overrides the config. The value must be at least 1:

rledger check --plugin-max-time-secs 120 ledger.beancount

The budget is a setting of whoever runs rustledger, never of the ledger: nothing in a beancount file can raise it, so a service that loads ledgers it did not write keeps control of how much CPU their plugins get. A project .rledger.toml is found from the directory rledger runs in, not from where the ledger is. So running rledger inside someone else's repository applies their max_time_secs, as it applies their aliases and default file; run it from a directory you control to keep your own. Python plugins keep their own fixed budget.

Using Profiles

# Use a profile
rledger check -P personal
rledger report balances -P business

# Override ledger file
rledger check ~/other/ledger.beancount

Beancount Options

Set options in your beancount file:

option "title" "My Personal Finances"
option "operating_currency" "USD"
option "booking_method" "FIFO"

Common Options

Option	Description	Default
title	Ledger title	(none)
operating_currency	Main currency	(none)
booking_method	FIFO, LIFO, AVERAGE, etc.	STRICT
account_previous_balances	Opening-balances account, a leaf under name_equity	Opening-Balances
account_current_earnings	Current earnings account, a leaf under name_equity	Earnings:Current
inferred_tolerance_default	Per-currency balance tolerance (e.g. USD:0.005)	(none)

Booking Methods

; First-in, first-out
option "booking_method" "FIFO"

; Last-in, first-out
option "booking_method" "LIFO"

; Average cost
option "booking_method" "AVERAGE"

; Strict matching (default)
option "booking_method" "STRICT"

Shell Aliases

For quick commands, add aliases to your shell:

# ~/.bashrc or ~/.zshrc

export RLEDGER_FILE="$HOME/finances/main.beancount"

# Quick commands
alias rc='rledger check'
alias rq='rledger query'
alias rb='rledger report balances -a'
alias rr='rledger report journal -a'
alias rbal='rledger report balsheet'
alias ris='rledger report income'

# Usage:
# rc                    - check ledger
# rb Expenses:Food      - balance for food expenses
# rr Assets:Bank        - register for bank accounts

Editor Integration

VS Code

Install the rustledger VS Code extension (a thin LSP client around rledger-lsp). Point it at the LSP binary if it is not already on your PATH:

{
  "rustledger.server.path": "rledger-lsp"
}

Neovim

Using nvim-lspconfig (register the server manually, since it is not built in):

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

if not configs.rledger then
  configs.rledger = {
    default_config = {
      cmd = { 'rledger-lsp' },
      filetypes = { 'beancount' },
      root_dir = lspconfig.util.root_pattern('.git', '*.beancount'),
      settings = {},
    },
  }
end

lspconfig.rledger.setup {}

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "beancount"
language-servers = ["rustledger"]

[language-server.rustledger]
command = "rledger-lsp"

See Editor Integration for detailed setup instructions.

Next Steps

• Commands Reference - All CLI commands
• Shell Aliases - More alias examples
• Editor Integration - Full editor setup