beancount-cli 0.2.0__tar.gz

beancount_cli-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Environments
+.venv/
+.env
+
+# Cache and temporary files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+tmp/
+*_out*.txt
+analyze_output.json
+dist/
+build/
+*.egg-info/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+.DS_Store

beancount_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-27
+
+### Changed
+- Renamed the CLI entry point from `beancount-cli` to `bean` for better ergonomics and branding.
+- Enhanced CLI help descriptions and examples for better AI agent discoverability.
+- Separated documentation for user-facing agents (`AGENTS.md`) and coding/development agents (`CODING_AGENTS.md`).
+- Added strict type validation and Pydantic schema discovery.
+
+## [0.1.0] - Initial Release
+
+
+### Added
+- Core Beancount CLI functionality.
+- Commands for adding transactions, checking balances, and more.
+- Built-in type hints and validation using Pydantic V2.

beancount_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Medvedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beancount_cli-0.2.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: beancount-cli
+Version: 0.2.0
+Summary: A CLI tool to manage Beancount ledgers
+Project-URL: Homepage, https://github.com/romamo/beancount-cli
+Project-URL: Repository, https://github.com/romamo/beancount-cli
+Project-URL: Issues, https://github.com/romamo/beancount-cli/issues
+Author-email: Roman Medvedev <pypi@romavm.dev>
+License: MIT
+License-File: LICENSE
+Keywords: accounting,agent,automation,beancount,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.9
+Requires-Dist: beancount>=3.0.0
+Requires-Dist: beanprice>=2.1.0
+Requires-Dist: beanquery>=0.1.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.8.2
+Description-Content-Type: text/markdown
+
+# beancount-cli
+
+A robust command-line interface and Python library for programmatically managing [Beancount](https://beancount.github.io/) ledgers. Designed for AI agents and automation workflows.
+
+## Features
+
+-   **Validation**: Wrap `bean-check` to validate ledgers programmatically.
+-   **Visualization**: View the file inclusion tree (`tree` command).
+-   **Transactions**:
+    -   List transactions with regex filtering (account, payee, tags).
+    -   Add transactions via CLI arguments or JSON (stdin supported).
+    -   Draft mode support (flag `!`).
+-   **Entities**:
+    -   Manage Accounts (list, create).
+    -   Manage Commodities (create).
+    -   Manage Prices (fetch, update).
+-   **Formatting**:
+    -   Auto-format ledgers (`bean-format` wrapper).
+    -   Global output formatting: `--format` support (`table`, `json`, `csv`) for all data commands.
+-   **Reporting**: Generate balance, holding, and audit reports with multi-currency conversion.
+-   **Composability**: Built for Unix piping (`json` | `csv`) and batch processing via STDIN.
+-   **Configuration**: Custom Beancount directives for routing new entries to specific files.
+
+## Installation
+
+Install using `uv` or `pip`:
+
+```bash
+uv pip install beancount-cli
+# or
+pip install beancount-cli
+```
+
+For development:
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Global Formatting Flag
+
+All data-retrieval and reporting commands support the `--format` flag.
+
+```bash
+# Default human-readable table
+bean report bs
+
+# Machine-readable CSV (highly token-efficient for AI agents)
+bean --format csv transaction list
+
+# Structural JSON (perfect for piping into jq or other scripts)
+bean --format json account list
+```
+
+### Check Ledger
+
+Validate your ledger file:
+
+```bash
+bean check main.beancount
+```
+
+### Format Ledger
+
+Format your ledger file in-place (uses `bean-format`):
+
+```bash
+bean format main.beancount
+```
+
+### View Inclusion Tree
+
+Visualize the tree of included files:
+
+```bash
+bean tree main.beancount
+```
+
+### Reports
+
+Generate specialized accounting reports with multi-currency support:
+
+```bash
+# Balance Sheet (Assets, Liabilities, Equity)
+bean report balance-sheet main.beancount
+
+# Trial Balance (All accounts including Income/Expenses)
+bean report trial-balance main.beancount
+
+# Holdings (Net worth per Asset account)
+bean report holdings main.beancount
+
+# Audit a specific currency (Source of Exposure)
+bean report audit USD main.beancount
+```
+
+> [!TIP]
+> Convenience aliases are supported: `bs` (balance-sheet) and `trial` (trial-balance).
+
+#### Unified Currency Reporting
+
+Use the `--convert` and `--valuation` flags for a consolidated view:
+
+```bash
+# View Trial Balance in USD using historical cost
+bean report trial main.beancount --convert USD --valuation cost
+
+# View Balance Sheet in EUR using current market prices
+bean report bs main.beancount --convert EUR --valuation market
+```
+
+| Valuation | Description | Use Case |
+| :--- | :--- | :--- |
+| `market` (default) | Uses latest prices from the ledger. | Current **Net Worth** tracking. |
+| `cost` | Uses historical price basis (`{}`). | **Accounting Verification** (proving balance). |
+
+**List Transactions:**
+```bash
+bean transaction list main.beancount --account "Assets:US:.*" --payee "Amazon"
+```
+
+**Add Transaction:**
+```bash
+# JSON via argument
+bean transaction add main.beancount --json '{"date": "2023-10-27", ...}'
+
+# JSON via stdin (Recommended for complex data)
+cat tx.json | bean transaction add main.beancount --json -
+
+# Create as Draft (!)
+bean transaction add main.beancount --json ... --draft
+```
+
+### Manage Accounts & Commodities
+
+All creation commands (`transaction add`, `account create`, `commodity create`) support batch processing via JSON arrays on STDIN.
+
+```bash
+# Batch add transactions from a file
+cat txs.json | bean transaction add --json -
+
+# Pipe accounts from one ledger to another
+bean --format json account list --file old.beancount | bean account create --json -
+```
+
+**Standard CLI usage:**
+```bash
+# List Accounts
+bean account list
+
+# Create Account
+bean account create --name "Assets:NewBank" --currency "USD"
+
+# Create Commodity
+bean commodity create "BTC" --name "Bitcoin"
+
+# Fetch and Update Prices
+bean price --update
+```
+
+`beancount-cli` is specifically optimized for AI agents, providing both operational guidance and machine-readable interfaces.
+
+### Agent Documentation
+We provide specialized documentation for different types of AI interactions:
+- [**AGENTS.md**](./AGENTS.md): Guide for **AI End Agents** operating the CLI (prompting strategies, token optimization, batch workflows).
+- [**CODING_AGENTS.md**](./CODING_AGENTS.md): Mandatory rules for **AI Coding Agents** modifying the source code (Value Objects, Fail-Fast rules, type safety).
+
+
+### Transaction Schema
+Agents can dynamically retrieve the JSON schema for transactions to ensure valid data generation:
+
+```bash
+bean transaction schema
+```
+
+### Complex Transaction Example
+Agents should aim to generate JSON in this format for a standard purchase with multiple postings:
+
+```json
+{
+  "date": "2023-10-27",
+  "payee": "Amazon",
+  "narration": "Office supplies",
+  "postings": [
+    {
+      "account": "Expenses:Office:Supplies",
+      "units": { "number": 45.99, "currency": "USD" }
+    },
+    {
+      "account": "Liabilities:US:Chase:Slate",
+      "units": { "number": -45.99, "currency": "USD" }
+    }
+  ]
+}
+```
+
+### Scripting with `uv run`
+For reliable cross-platform execution in agent workflows:
+```bash
+uv run bean transaction add --json - < tx.json
+```
+
+## Configuration
+
+### Ledger Discovery
+`bean` uses a 4-tier discovery logic to find your ledger file automatically:
+1.  **Explicit Argument**: Passing the filename directly (e.g. `bean check my.beancount`).
+2.  **`BEANCOUNT_FILE`**: Direct path to a ledger file.
+3.  **`BEANCOUNT_PATH`**: Looks for `main.beancount` inside this directory.
+4.  **Local Directory**: Fallback to `./main.beancount`.
+
+### Custom Directives
+You can configure where new entries are written using custom directives in your Beancount file.
+
+**Note:** `custom` directives require a date (e.g. `2023-01-01`).
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "inbox.beancount"
+2023-01-01 custom "cli-config" "new_account_file" "accounts.beancount"
+2023-01-01 custom "cli-config" "new_commodity_file" "commodities.beancount"
+```
+
+**Context-Aware Insertion:**
+You can use placeholders to route transactions to dynamic paths:
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "{year}/{month}/txs.beancount"
+```
+Supported placeholders: `{year}`, `{month}`, `{day}`, `{payee}`, `{slug}`.
+
+**Directory Mode (One file per transaction):**
+If `new_transaction_file` points to a **directory**, `bean` will create a new file for each transaction inside that directory, named with an ISO timestamp.
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "inbox/"
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```

beancount_cli-0.2.0/README.md

@@ -0,0 +1,246 @@
+# beancount-cli
+
+A robust command-line interface and Python library for programmatically managing [Beancount](https://beancount.github.io/) ledgers. Designed for AI agents and automation workflows.
+
+## Features
+
+-   **Validation**: Wrap `bean-check` to validate ledgers programmatically.
+-   **Visualization**: View the file inclusion tree (`tree` command).
+-   **Transactions**:
+    -   List transactions with regex filtering (account, payee, tags).
+    -   Add transactions via CLI arguments or JSON (stdin supported).
+    -   Draft mode support (flag `!`).
+-   **Entities**:
+    -   Manage Accounts (list, create).
+    -   Manage Commodities (create).
+    -   Manage Prices (fetch, update).
+-   **Formatting**:
+    -   Auto-format ledgers (`bean-format` wrapper).
+    -   Global output formatting: `--format` support (`table`, `json`, `csv`) for all data commands.
+-   **Reporting**: Generate balance, holding, and audit reports with multi-currency conversion.
+-   **Composability**: Built for Unix piping (`json` | `csv`) and batch processing via STDIN.
+-   **Configuration**: Custom Beancount directives for routing new entries to specific files.
+
+## Installation
+
+Install using `uv` or `pip`:
+
+```bash
+uv pip install beancount-cli
+# or
+pip install beancount-cli
+```
+
+For development:
+
+```bash
+uv sync
+```
+
+## Usage
+
+### Global Formatting Flag
+
+All data-retrieval and reporting commands support the `--format` flag.
+
+```bash
+# Default human-readable table
+bean report bs
+
+# Machine-readable CSV (highly token-efficient for AI agents)
+bean --format csv transaction list
+
+# Structural JSON (perfect for piping into jq or other scripts)
+bean --format json account list
+```
+
+### Check Ledger
+
+Validate your ledger file:
+
+```bash
+bean check main.beancount
+```
+
+### Format Ledger
+
+Format your ledger file in-place (uses `bean-format`):
+
+```bash
+bean format main.beancount
+```
+
+### View Inclusion Tree
+
+Visualize the tree of included files:
+
+```bash
+bean tree main.beancount
+```
+
+### Reports
+
+Generate specialized accounting reports with multi-currency support:
+
+```bash
+# Balance Sheet (Assets, Liabilities, Equity)
+bean report balance-sheet main.beancount
+
+# Trial Balance (All accounts including Income/Expenses)
+bean report trial-balance main.beancount
+
+# Holdings (Net worth per Asset account)
+bean report holdings main.beancount
+
+# Audit a specific currency (Source of Exposure)
+bean report audit USD main.beancount
+```
+
+> [!TIP]
+> Convenience aliases are supported: `bs` (balance-sheet) and `trial` (trial-balance).
+
+#### Unified Currency Reporting
+
+Use the `--convert` and `--valuation` flags for a consolidated view:
+
+```bash
+# View Trial Balance in USD using historical cost
+bean report trial main.beancount --convert USD --valuation cost
+
+# View Balance Sheet in EUR using current market prices
+bean report bs main.beancount --convert EUR --valuation market
+```
+
+| Valuation | Description | Use Case |
+| :--- | :--- | :--- |
+| `market` (default) | Uses latest prices from the ledger. | Current **Net Worth** tracking. |
+| `cost` | Uses historical price basis (`{}`). | **Accounting Verification** (proving balance). |
+
+**List Transactions:**
+```bash
+bean transaction list main.beancount --account "Assets:US:.*" --payee "Amazon"
+```
+
+**Add Transaction:**
+```bash
+# JSON via argument
+bean transaction add main.beancount --json '{"date": "2023-10-27", ...}'
+
+# JSON via stdin (Recommended for complex data)
+cat tx.json | bean transaction add main.beancount --json -
+
+# Create as Draft (!)
+bean transaction add main.beancount --json ... --draft
+```
+
+### Manage Accounts & Commodities
+
+All creation commands (`transaction add`, `account create`, `commodity create`) support batch processing via JSON arrays on STDIN.
+
+```bash
+# Batch add transactions from a file
+cat txs.json | bean transaction add --json -
+
+# Pipe accounts from one ledger to another
+bean --format json account list --file old.beancount | bean account create --json -
+```
+
+**Standard CLI usage:**
+```bash
+# List Accounts
+bean account list
+
+# Create Account
+bean account create --name "Assets:NewBank" --currency "USD"
+
+# Create Commodity
+bean commodity create "BTC" --name "Bitcoin"
+
+# Fetch and Update Prices
+bean price --update
+```
+
+`beancount-cli` is specifically optimized for AI agents, providing both operational guidance and machine-readable interfaces.
+
+### Agent Documentation
+We provide specialized documentation for different types of AI interactions:
+- [**AGENTS.md**](./AGENTS.md): Guide for **AI End Agents** operating the CLI (prompting strategies, token optimization, batch workflows).
+- [**CODING_AGENTS.md**](./CODING_AGENTS.md): Mandatory rules for **AI Coding Agents** modifying the source code (Value Objects, Fail-Fast rules, type safety).
+
+
+### Transaction Schema
+Agents can dynamically retrieve the JSON schema for transactions to ensure valid data generation:
+
+```bash
+bean transaction schema
+```
+
+### Complex Transaction Example
+Agents should aim to generate JSON in this format for a standard purchase with multiple postings:
+
+```json
+{
+  "date": "2023-10-27",
+  "payee": "Amazon",
+  "narration": "Office supplies",
+  "postings": [
+    {
+      "account": "Expenses:Office:Supplies",
+      "units": { "number": 45.99, "currency": "USD" }
+    },
+    {
+      "account": "Liabilities:US:Chase:Slate",
+      "units": { "number": -45.99, "currency": "USD" }
+    }
+  ]
+}
+```
+
+### Scripting with `uv run`
+For reliable cross-platform execution in agent workflows:
+```bash
+uv run bean transaction add --json - < tx.json
+```
+
+## Configuration
+
+### Ledger Discovery
+`bean` uses a 4-tier discovery logic to find your ledger file automatically:
+1.  **Explicit Argument**: Passing the filename directly (e.g. `bean check my.beancount`).
+2.  **`BEANCOUNT_FILE`**: Direct path to a ledger file.
+3.  **`BEANCOUNT_PATH`**: Looks for `main.beancount` inside this directory.
+4.  **Local Directory**: Fallback to `./main.beancount`.
+
+### Custom Directives
+You can configure where new entries are written using custom directives in your Beancount file.
+
+**Note:** `custom` directives require a date (e.g. `2023-01-01`).
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "inbox.beancount"
+2023-01-01 custom "cli-config" "new_account_file" "accounts.beancount"
+2023-01-01 custom "cli-config" "new_commodity_file" "commodities.beancount"
+```
+
+**Context-Aware Insertion:**
+You can use placeholders to route transactions to dynamic paths:
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "{year}/{month}/txs.beancount"
+```
+Supported placeholders: `{year}`, `{month}`, `{day}`, `{payee}`, `{slug}`.
+
+**Directory Mode (One file per transaction):**
+If `new_transaction_file` points to a **directory**, `bean` will create a new file for each transaction inside that directory, named with an ISO timestamp.
+
+```beancount
+2023-01-01 custom "cli-config" "new_transaction_file" "inbox/"
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```

beancount_cli-0.2.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "beancount-cli"
+version = "0.2.0"
+description = "A CLI tool to manage Beancount ledgers"
+readme = "README.md"
+authors = [
+    { name = "Roman Medvedev", email = "pypi@romavm.dev" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "beancount>=3.0.0",
+    "beanquery>=0.1.0",
+    "pydantic>=2.0.0",
+    "python-dateutil>=2.8.2",
+    "beanprice>=2.1.0",
+    "pydantic-settings>=2.0.0",
+]
+keywords = ["beancount", "cli", "accounting", "automation", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+
+[project.urls]
+Homepage = "https://github.com/romamo/beancount-cli"
+Repository = "https://github.com/romamo/beancount-cli"
+Issues = "https://github.com/romamo/beancount-cli/issues"
+
+[project.scripts]
+bean = "beancount_cli.cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/beancount_cli",
+    "tests",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+]
+exclude = [
+    ".agent",
+    ".github",
+    "uv.lock",
+    "tmp",
+    "dist",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beancount_cli"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+  "bandit>=1.8.6",
+  "mypy>=1.19.1",
+  "pytest>=8.0.0",
+  "pytest-cov>=4.0.0",
+  "ruff>=0.9.2",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]
+
+

beancount_cli-0.2.0/src/beancount_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"