beancount-cli 0.2.7__tar.gz → 0.2.9__tar.gz

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.8] - 2026-04-04
+
+### Added
+- `commodity list`: List all declared commodities, with optional `--asset-class` filter.
+- `commodity check`: Identify currencies used in transactions that are missing a `commodity` directive.
+- `price check`: Identify periods of missing price data for held assets. Supports `--rate` (daily, weekday, weekly, monthly) and `--tolerance` (days before flagging a gap).
+- `price fetch`: Fetch latest quotes via the `bean-price` library with `--update`, `--fill-gaps`, `--dry-run`, `--inactive`, and `--verbose` options.
+- `account balance`: Add a `balance` assertion directive to the ledger via `--json`.
+- `--target` flag on `transaction add`, `account create`, and `commodity create` to override the destination file, bypassing config-driven routing.
+- Structured JSON error output for `check --format json` with typed `error_type` and `exit_code` fields.
+
+### Changed
+- `price` is now a subcommand group (`price check`, `price fetch`), replacing the former single `price` command.
+- `check` now exits with code `2` on missing/unreadable files (system error) and code `1` on validation errors, instead of raising an uncaught exception.
+
 ## [0.2.6] - 2026-03-03
 
 ### Changed

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beancount-cli
-Version: 0.2.7
+Version: 0.2.9
 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
@@ -42,9 +42,9 @@ A robust command-line interface and Python library for programmatically managing
     -   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).
+    -   Manage Accounts (list, create, balance assertion).
+    -   Manage Commodities (list, create, check undeclared).
+    -   Manage Prices (check gaps, fetch/update via bean-price).
 -   **Formatting**:
     -   Auto-format ledgers (`bean-format` wrapper).
     -   Global output formatting: `--format` support (`table`, `json`, `csv`) for all data commands.
@@ -125,7 +125,7 @@ bean report trial-balance main.beancount
 bean report holdings main.beancount
 
 # Audit a specific currency (Source of Exposure)
-bean report audit USD main.beancount
+bean report audit --currency USD main.beancount
 ```
 
 > [!TIP]
@@ -167,7 +167,7 @@ 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.
+All creation commands (`transaction add`, `account create`, `commodity create`) support batch processing via JSON arrays on STDIN. Use `--target` to override the destination file.
 
 ```bash
 # Batch add transactions from a file
@@ -177,19 +177,46 @@ cat txs.json | bean transaction add --json -
 bean --format json account list --file old.beancount | bean account create --json -
 ```
 
-**Standard CLI usage:**
+**Accounts:**
 ```bash
-# List Accounts
+# List accounts
 bean account list
 
-# Create Account
+# Create account
 bean account create --name "Assets:NewBank" --currency "USD"
 
-# Create Commodity
+# Add a balance assertion
+bean account balance --json '{"date": "2024-01-01", "account": "Assets:Bank", "amount": {"number": 1000, "currency": "USD"}}'
+```
+
+**Commodities:**
+```bash
+# List all declared commodities
+bean commodity list
+
+# List by asset class
+bean commodity list --asset-class stock
+
+# Find currencies used in transactions but missing a commodity directive
+bean commodity check
+
+# Create a commodity
 bean commodity create "BTC" --name "Bitcoin"
+```
+
+**Prices:**
+```bash
+# Check for periods of missing price data
+bean price check
+
+# Check with weekly rate and 14-day tolerance
+bean price check --rate weekly --tolerance 14
+
+# Fetch latest quotes (dry run)
+bean price fetch --dry-run
 
-# Fetch and Update Prices
-bean price --update
+# Fetch and write new prices to the ledger
+bean price fetch --update
 ```
 
 `beancount-cli` is specifically optimized for AI agents, providing both operational guidance and machine-readable interfaces.

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/README.md

@@ -11,9 +11,9 @@ A robust command-line interface and Python library for programmatically managing
     -   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).
+    -   Manage Accounts (list, create, balance assertion).
+    -   Manage Commodities (list, create, check undeclared).
+    -   Manage Prices (check gaps, fetch/update via bean-price).
 -   **Formatting**:
     -   Auto-format ledgers (`bean-format` wrapper).
     -   Global output formatting: `--format` support (`table`, `json`, `csv`) for all data commands.
@@ -94,7 +94,7 @@ bean report trial-balance main.beancount
 bean report holdings main.beancount
 
 # Audit a specific currency (Source of Exposure)
-bean report audit USD main.beancount
+bean report audit --currency USD main.beancount
 ```
 
 > [!TIP]
@@ -136,7 +136,7 @@ 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.
+All creation commands (`transaction add`, `account create`, `commodity create`) support batch processing via JSON arrays on STDIN. Use `--target` to override the destination file.
 
 ```bash
 # Batch add transactions from a file
@@ -146,19 +146,46 @@ cat txs.json | bean transaction add --json -
 bean --format json account list --file old.beancount | bean account create --json -
 ```
 
-**Standard CLI usage:**
+**Accounts:**
 ```bash
-# List Accounts
+# List accounts
 bean account list
 
-# Create Account
+# Create account
 bean account create --name "Assets:NewBank" --currency "USD"
 
-# Create Commodity
+# Add a balance assertion
+bean account balance --json '{"date": "2024-01-01", "account": "Assets:Bank", "amount": {"number": 1000, "currency": "USD"}}'
+```
+
+**Commodities:**
+```bash
+# List all declared commodities
+bean commodity list
+
+# List by asset class
+bean commodity list --asset-class stock
+
+# Find currencies used in transactions but missing a commodity directive
+bean commodity check
+
+# Create a commodity
 bean commodity create "BTC" --name "Bitcoin"
+```
+
+**Prices:**
+```bash
+# Check for periods of missing price data
+bean price check
+
+# Check with weekly rate and 14-day tolerance
+bean price check --rate weekly --tolerance 14
+
+# Fetch latest quotes (dry run)
+bean price fetch --dry-run
 
-# Fetch and Update Prices
-bean price --update
+# Fetch and write new prices to the ledger
+bean price fetch --update
 ```
 
 `beancount-cli` is specifically optimized for AI agents, providing both operational guidance and machine-readable interfaces.

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "beancount-cli"
-version = "0.2.7"
+version = "0.2.9"
 description = "A CLI tool to manage Beancount ledgers"
 readme = "README.md"
 authors = [

beancount_cli-0.2.9/src/beancount_cli/__init__.py

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

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/src/beancount_cli/adapters.py

@@ -5,6 +5,7 @@ from beancount.core import amount, data, position
 from beancount_cli.models import (
     AccountName,
     AmountModel,
+    BalanceModel,
     CostModel,
     CurrencyCode,
     PostingModel,
@@ -98,3 +99,14 @@ def from_core_transaction(core: data.Transaction) -> TransactionModel:
         postings=[from_core_posting(p) for p in core.postings],
         meta=core.meta or {},
     )
+
+
+def to_core_balance(model: BalanceModel) -> data.Balance:
+    return data.Balance(
+        meta=model.meta or {},
+        date=model.date,
+        account=str(model.account),
+        amount=to_core_amount(model.amount),
+        diff_amount=None,
+        tolerance=None,
+    )

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/src/beancount_cli/cli.py

@@ -5,8 +5,9 @@ import agentyper as typer
 from beancount_cli import __version__
 from beancount_cli.commands.account import app as acc_app
 from beancount_cli.commands.commodity import app as comm_app
+from beancount_cli.commands.price import app as price_app
 from beancount_cli.commands.report import app as report_app
-from beancount_cli.commands.root import check, format_cmd, price, tree
+from beancount_cli.commands.root import check, format_cmd, tree
 from beancount_cli.commands.transaction import app as tx_app
 
 app = typer.Agentyper(
@@ -19,11 +20,11 @@ app.add_typer(report_app, name="report")
 app.add_typer(tx_app, name="transaction")
 app.add_typer(acc_app, name="account")
 app.add_typer(comm_app, name="commodity")
-
 app.command(name="check")(check)
 app.command(name="tree")(tree)
 app.command(name="format")(format_cmd)
-app.command(name="price")(price)
+
+app.add_typer(price_app, name="price")
 
 
 def main(args=None):

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/src/beancount_cli/commands/account.py

@@ -6,8 +6,13 @@ from pathlib import Path
 import agentyper as typer
 from pydantic import TypeAdapter
 
-from beancount_cli.commands.common import _is_table_format, console, get_ledger_file
-from beancount_cli.models import AccountModel
+from beancount_cli.commands.common import (
+    _is_table_format,
+    console,
+    get_ledger_file,
+    read_json_input,
+)
+from beancount_cli.models import AccountModel, BalanceModel
 from beancount_cli.services import AccountService
 
 app = typer.Agentyper(help="Manage accounts.")
@@ -53,27 +58,23 @@ def account_create(
     json_data: str | None = typer.Option(
         None, "--json", "-j", help="JSON string data (or '-' to read from STDIN)"
     ),
+    target: Path | None = typer.Option(None, "--target", help="Override target file to write to"),
 ):
     """Create a new account."""
     actual_file = get_ledger_file(ledger_file or file)
     service = AccountService(actual_file)
 
     if json_data:
-        if json_data == "-":
-            content = sys.stdin.read()
-        else:
-            content = json_data
-
-        data_input = json.loads(content)
+        data_input = json.loads(read_json_input(json_data))
         if isinstance(data_input, list):
             ta = TypeAdapter(list[AccountModel])
             models = ta.validate_python(data_input)
             for m in models:
-                service.create_account(m)
+                service.create_account(m, target_file=target)
                 console.print(f"[green]Account {m.name} created.[/green]")
         else:
             model = AccountModel(**data_input)
-            service.create_account(model)
+            service.create_account(model, target_file=target)
             console.print(f"[green]Account {model.name} created.[/green]")
     else:
         if not name:
@@ -86,5 +87,26 @@ def account_create(
 
         currencies = [c.strip() for c in currency_opt.split(",")] if currency_opt else []
         model = AccountModel(name=name, open_date=d, currencies=currencies)
-        service.create_account(model)
+        service.create_account(model, target_file=target)
         console.print(f"[green]Account {name} created.[/green]")
+
+
+@app.command(name="balance")
+def account_balance(
+    ledger_file: Path | None = typer.Argument(None, help="Path to ledger file"),
+    file: Path | None = typer.Option(
+        None, "--file", "-f", envvar="BEANCOUNT_FILE", help="Main beancount file"
+    ),
+    json_data: str = typer.Option(
+        ..., "--json", "-j", help="JSON string data (or '-' to read from STDIN)"
+    ),
+    target: Path | None = typer.Option(None, "--target", help="Override target file to write to"),
+):
+    """Add a balance directive for an account."""
+    actual_file = get_ledger_file(ledger_file or file)
+    service = AccountService(actual_file)
+
+    data_input = json.loads(read_json_input(json_data))
+    model = BalanceModel(**data_input)
+    service.add_balance(model, target_file=target)
+    console.print(f"[green]Balance check for {model.account} added.[/green]")

beancount_cli-0.2.9/src/beancount_cli/commands/commodity.py

@@ -0,0 +1,100 @@
+import json
+import sys
+from pathlib import Path
+
+import agentyper as typer
+
+from beancount_cli.commands.common import (
+    _is_table_format,
+    console,
+    get_ledger_file,
+    read_json_input,
+)
+from beancount_cli.services import CommodityService
+
+app = typer.Agentyper(help="Manage commodities.")
+
+
+@app.command(name="list")
+def commodity_list(
+    ledger_file: Path | None = typer.Argument(None, help="Path to ledger file"),
+    file: Path | None = typer.Option(
+        None, "--file", "-f", envvar="BEANCOUNT_FILE", help="Main beancount file"
+    ),
+    asset_class: str | None = typer.Option(
+        None, "--asset-class", "-c", help="Filter by asset-class meta (e.g. stock, Cash)"
+    ),
+):
+    """List all commodities."""
+    actual_file = get_ledger_file(ledger_file or file)
+    service = CommodityService(actual_file)
+    commodities = service.list_commodities(asset_class=asset_class)
+
+    if _is_table_format():
+        data = [
+            {
+                "Currency": c.currency,
+                "Date": str(c.date) if c.date else "",
+                "Name": c.meta.get("name", "") if c.meta else "",
+            }
+            for c in commodities
+        ]
+        typer.output(data, title=f"Commodities ({len(commodities)})")
+    else:
+        typer.output(commodities, title=f"Commodities ({len(commodities)})")
+
+
+@app.command(name="check")
+def commodity_check(
+    ledger_file: Path | None = typer.Argument(None, help="Path to ledger file"),
+    file: Path | None = typer.Option(
+        None, "--file", "-f", envvar="BEANCOUNT_FILE", help="Main beancount file"
+    ),
+):
+    """Check for currencies used in transactions but missing a commodity directive."""
+    actual_file = get_ledger_file(ledger_file or file)
+    service = CommodityService(actual_file)
+    undeclared = service.get_undeclared_commodities()
+
+    if _is_table_format():
+        if not undeclared:
+            console.print("[green]All used currencies are declared.[/green]")
+        else:
+            typer.output(undeclared, title=f"Undeclared Commodities ({len(undeclared)})")
+    else:
+        typer.output(undeclared, title="Undeclared Commodities")
+
+
+@app.command(name="create")
+def commodity_create(
+    currency: str | None = typer.Argument(None, help="Currency code (e.g. USD)"),
+    ledger_file: Path | None = typer.Argument(None, help="Path to ledger file"),
+    file: Path | None = typer.Option(
+        None, "--file", "-f", envvar="BEANCOUNT_FILE", help="Main beancount file"
+    ),
+    name: str | None = typer.Option(None, "--name", "-n", help="Full name"),
+    json_data: str | None = typer.Option(
+        None, "--json", "-j", help="JSON string data (or '-' to read from STDIN)"
+    ),
+):
+    """Create a new commodity."""
+    actual_file = get_ledger_file(ledger_file or file)
+    service = CommodityService(actual_file)
+
+    if json_data:
+        data_input = json.loads(read_json_input(json_data))
+        items = data_input if isinstance(data_input, list) else [data_input]
+        for item in items:
+            curr = item.get("currency")
+            comm_name = item.get("name")
+            if not curr:
+                console.print(f"[yellow]Skipping invalid commodity entry: {item}[/yellow]")
+                continue
+            service.create_commodity(curr, name=comm_name)
+            console.print(f"[green]Commodity {curr} created.[/green]")
+    else:
+        if not currency:
+            console.print("[red]Error: currency argument is required if not using --json.[/red]")
+            sys.exit(typer.EXIT_VALIDATION)
+        service.create_commodity(currency, name=name)
+        console.print(f"[green]Commodity {currency} created.[/green]")

{beancount_cli-0.2.7 → beancount_cli-0.2.9}/src/beancount_cli/commands/common.py

@@ -7,6 +7,14 @@ from rich.console import Console
 from rich.table import Table
 
 console = Console()
+error_console = Console(stderr=True)
+
+
+def read_json_input(json_data: str) -> str:
+    """Read JSON from a string or from STDIN when json_data is '-'."""
+    if json_data == "-":
+        return sys.stdin.read()
+    return json_data
 
 
 def get_ledger_file(override: str | Path | None = None) -> Path: