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
```
