README file from
GithubBeancount Ledger
A comprehensive Beancount integration for Obsidian that transforms your vault into a powerful plain-text accounting dashboard.
📘 Full Documentation Portal — Read the complete guide for features, configuration, and usage.
🔧 Requirements
This plugin integrates with your existing Beancount setup:
- Python 3.8+
- Beancount v3+: Install via
pip install beancount - bean-query: Command-line tool for querying Beancount files (
pip install beanquery) - bean-price (optional): For automatic commodity price fetching (
pip install beanprice) - WSL Support (optional): Full compatibility for Windows users running Beancount in WSL
Note:
bean-queryandbean-priceare separate packages from Beancount itself and require their ownpip installcommands. See the Requirements Documentation for more details.
📦 Installation
Install from community store
- Open Obsidian Settings and go to Community plugins.
- Click Browse and search for
Beancount Ledger. - Click Install, then Enable the plugin.
Manual Installation
- Download the latest release from GitHub Releases
- Extract files to
<vault>/.obsidian/plugins/beancount-finance/ - Enable the plugin in Obsidian Settings → Community Plugins
BRAT Beta Installation
For beta testers who want to try the latest development version:
-
Install BRAT Plugin:
- Install BRAT (Beta Reviewers Auto-update Tester) from Obsidian Community Plugins
- Enable BRAT in your Community Plugins settings
-
Add Beta Plugin:
- Open Command Palette (
Ctrl/Cmd + P) - Run: "BRAT: Add a beta plugin for testing"
- Enter repository:
mkshp-dev/obsidian-finance-plugin - Select branch:
dev(ormasterfor stable)
- Open Command Palette (
-
Enable Plugin:
- Go to Settings → Community Plugins
- Find "Beancount Ledger" and enable it
BRAT will automatically check for updates and notify you of new versions. This is the recommended way to test beta features before official releases.
Note: Beta versions may have bugs. Always keep backups of your Beancount files and vault data.
🔒 Permissions & Privacy
Beancount Ledger is a local-first plugin. It does not send ledger data, account names, query results, or prices to a project server.
| Access | Current use | Direction |
|---|---|---|
| Vault file access | Reads/writes Beancount files stored inside the current Obsidian vault, including generated prices.beancount output. |
All file I/O operations (reading, writing, backups, migration) are fully migrated to use the Obsidian Vault API. |
Filesystem access (fs) |
None. Direct filesystem access via the Node.js fs module has been completely eliminated from the codebase. |
Eliminated. Resolves community-plugin security warnings regarding direct filesystem access. |
Shell execution (child_process) |
Runs local Beancount tools such as bean-query, bean-check, and bean-price. |
Required to run the local Python packages (beancount, beanquery, beanprice). These CLI commands are executed safely via parameterized spawn calls bypassing the shell, and all user input is strictly whitelisted and sanitized to eliminate shell injection vulnerabilities. |
| Vault enumeration | Finds configured BQL/template files in the vault. | Required for plugin features. |
| Clipboard access | Copies query results or transaction text when the user clicks a copy action. | User-initiated only. |
Vault-only ledger requirement
For compatibility with Obsidian community plugin reviews and security standards, the plugin strictly requires your main ledger and included Beancount files to live inside the current vault. If your ledger currently lives outside the vault, move it into the vault and update the plugin settings to point to the vault-local file. The plugin strictly uses vault-local file access using the Obsidian Vault API, and direct filesystem writes outside the vault are not supported.
Security and Command Execution
Beancount is a Python library with no native JavaScript/WebAssembly counterpart. Therefore, to compute balances, render interactive charts, validate ledger files, and fetch prices, this plugin must interface with your local Python installation via child_process.spawn.
To ensure maximum security and privacy:
- No shell parsing: Commands are executed directly as process spawns without spawning shell instances (
shell: false), which prevents shell-injection exploits. - Strict Parameterization: Query strings, file paths, and options are passed as raw array parameters to the executable and are never parsed as part of a shell command line.
- Input Sanitization: User-configured parameters (such as price metadata sources) are whitelisted and sanitized using strict regular expressions before being processed.
- Zero Remote Access: All operations execute completely locally on your machine.
🤝 Contributing
We welcome contributions! Please see our CONTRIBUTING.md for details.
Development Setup
# Clone the repository
git clone https://github.com/mkshp-dev/obsidian-finance-plugin.git
cd obsidian-finance-plugin
# Install dependencies
npm install
# Start development build
npm run dev
# Build for production
npm run build
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
If this project helps your workflow, consider supporting its development with a ☕