beancount-io 0.1.0__tar.gz

beancount_io-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__
+
+# Build artifacts. `requirements.lock` is generated per release by
+# `make release-lock` and travels inside the sdist, never in git.
+dist/
+requirements.lock

beancount_io-0.1.0/Makefile

@@ -0,0 +1,114 @@
+# Beancount.io CLI - Development Makefile
+
+.PHONY: help install install-dev install-tool reinstall-tool dev lint deadcode deadcode-fix format format-check typecheck test codegen check-all release-check release-lock spec-check spec-sync docs docs-check
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  make install          - Install production dependencies"
+	@echo "  make install-dev      - Install all dependencies including dev"
+	@echo "  make install-tool     - Install CLI as a uv tool (editable)"
+	@echo "  make reinstall-tool   - Reinstall CLI tool"
+	@echo "  make dev              - Show CLI help"
+	@echo "  make lint             - Run ruff linter"
+	@echo "  make deadcode         - Detect unused Python code with Vulture"
+	@echo "  make deadcode-fix     - Remove fixable unused imports and variables"
+	@echo "  make format           - Format code with ruff"
+	@echo "  make format-check     - Check formatting without modifying files"
+	@echo "  make typecheck        - Run mypy type checks"
+	@echo "  make test             - Run tests with pytest across all cores"
+	@echo "  make codegen          - Regenerate the REST client and cloud command stubs from openapi/v1.json"
+	@echo "  make spec-check       - Fail if openapi/v1.json drifted from backend-cluster/idl's canonical spec"
+	@echo "  make spec-sync        - Refresh openapi/v1.json from the canonical spec"
+	@echo "  make release-check    - Validate the release tag against pyproject.toml"
+	@echo "  make release-lock     - Export the hash-pinned requirements.lock for a release"
+	@echo "  make docs             - Regenerate docs/REFERENCE.md from the command tree"
+	@echo "  make docs-check       - Fail if docs/REFERENCE.md drifted from the command tree"
+	@echo "  make check-all        - Run lint + format-check + typecheck + test + spec-check + docs-check"
+
+install:
+	uv sync
+
+install-dev:
+	uv sync --all-groups
+
+install-tool:
+	uv tool install --editable .
+
+reinstall-tool:
+	uv tool install --reinstall --editable .
+
+dev:
+	uv run bea --help
+
+lint:
+	uv run ruff check src/ tests/
+
+deadcode:
+	uv run vulture src/cli src/fava --min-confidence 100 --exclude src/cli/api/rest_client/,src/cli/commands/cloud/generated/ --ignore-names repo
+
+deadcode-fix:
+	uv run ruff check src/ tests/ --fix --select F401,F841
+	$(MAKE) deadcode
+
+format:
+	uv run ruff format src/cli tests/
+
+format-check:
+	uv run ruff format --check src/cli tests/
+
+typecheck:
+	uv run mypy src/cli
+
+test:
+	uv run pytest tests/ -n auto
+
+test-cov:
+	uv run pytest tests/ --cov=fava --cov=cli --cov-report=term-missing --cov-report=html --cov-report=json
+	@echo "📊 Coverage report generated in htmlcov/index.html"
+
+clean:
+	find . -type f -name "*.pyc" -delete
+	find . -type d -name "__pycache__" -delete
+	find . -type d -name "*.egg-info" -exec rm -rf {} +
+	find . -type f -name ".coverage" -delete
+	find . -type d -name "htmlcov" -exec rm -rf {} +
+	find . -type d -name ".pytest_cache" -exec rm -rf {} +
+	find . -type d -name ".mypy_cache" -exec rm -rf {} +
+	find . -type d -name ".ruff_cache" -exec rm -rf {} +
+
+# Release plumbing. `.github/workflows/release-cli.yml` runs exactly these, so
+# a tag that would fail in CI fails here first.
+release-check:
+	bash scripts/release-check.sh
+
+release-lock:
+	uv export --format requirements-txt --no-dev --no-emit-project --no-editable --hashes -o requirements.lock
+
+# The canonical spec lives in the backend package; the CLI builds only from its
+# own pinned copy so a `cli/` checkout is self-sufficient and reproducible.
+CANONICAL_SPEC = ../backend-cluster/backend-v2/docs/openapi/v1.json
+
+spec-check:
+	@diff -q $(CANONICAL_SPEC) openapi/v1.json >/dev/null \
+		|| { echo "openapi/v1.json drifted from $(CANONICAL_SPEC) — run 'make spec-sync && make codegen' and commit the diff."; exit 1; }
+
+spec-sync:
+	cp $(CANONICAL_SPEC) openapi/v1.json
+
+# docs/REFERENCE.md is generated from the Typer app, the same way the REST
+# client is generated from the OpenAPI spec: change a command once and the
+# drift gate tells you the reference needs regenerating.
+docs:
+	uv run python scripts/gen_reference.py
+
+docs-check:
+	uv run python scripts/gen_reference.py --check
+
+codegen:
+	uv run openapi-python-client generate --path openapi/v1.json \
+		--output-path src/cli/api/rest_client --meta none --overwrite
+	uv run python scripts/gen_cloud_commands.py
+	uv run ruff format src/cli/api/rest_client src/cli/commands/cloud/generated
+
+check-all: lint deadcode format-check typecheck test spec-check docs-check

beancount_io-0.1.0/NOTICE.fava

@@ -0,0 +1,25 @@
+fava-slim — third-party notices
+===============================
+
+fava-slim is a derivative work of Fava (https://github.com/beancount/fava),
+stripped down to its Python core (ledger loading, account trees, financial
+reports). Fava is distributed under the MIT license:
+
+    Copyright (c) 2015-2016 Dominik Aumayr <dominik@aumayr.name>
+
+The original copyright and permission notice are retained in this package's
+LICENSE file.
+
+Files with separate provenance
+------------------------------
+
+fava/plugins/amortize_over.py
+    Copyright (c) 2017 Cary Kempston
+    License: MIT (full license text retained in the file header)
+
+fava/plugins/forecast.py
+    Copyright (c) 2019-2026 Beancount.io, MIT — an independent
+    reimplementation of the narration-marker convention established by the
+    `beancount.plugins.forecast` example plugin from Beancount v2
+    (https://github.com/beancount/beancount). It is syntax-compatible with
+    that plugin but contains none of its (GPL-2.0-only) code.

beancount_io-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: beancount-io
+Version: 0.1.0
+Summary: Beancount.io CLI
+Project-URL: Homepage, https://beancount.io
+Project-URL: Repository, https://github.com/bex-co/beancount-io
+License: MIT
+License-File: NOTICE.fava
+Requires-Python: >=3.12
+Requires-Dist: attrs>=23
+Requires-Dist: beancount>=3.2
+Requires-Dist: beanquery>=0.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: ply>=3.11
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyexcel>=0.7.3
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: typer>=0.12
+Provides-Extra: ask
+Requires-Dist: openai>=1.0; extra == 'ask'
+Requires-Dist: pydantic-ai>=0.3; extra == 'ask'
+Description-Content-Type: text/markdown
+
+# beancount-io
+
+`bea` is the command-line interface for [Beancount.io](https://beancount.io).
+Create and edit plain-text Beancount ledgers, import bank exports, validate
+accounts, run BQL queries, and generate financial reports. Local bookkeeping
+needs no Beancount.io account. Optional AI assistance and hosted ledger
+management use your Beancount.io credentials.
+
+The Python distribution is **`beancount-io`**; its executable is **`bea`**.
+Run `bea --version` and `bea COMMAND --help` to check the version and options
+you have installed.
+
+## Contents
+
+- [Install](#install) · [Quick start](#quick-start) · [Command map](#command-map)
+- [Exit codes](#exit-codes) · [Learn more](#learn-more)
+- [Development](#development) · [Releases](#releases) · [License](#license)
+
+## Install
+
+```bash norun
+# Installs software; needs Homebrew or uv plus network.
+brew install bex-co/tap/bea      # macOS and Linuxbrew
+uv tool install beancount-io     # anywhere with uv and Python 3.12+
+```
+
+The default installation omits AI dependencies. For `bea ask`, install the
+extra (or run it without replacing your `bea`):
+
+```bash norun
+# Installs software; needs uv plus network.
+uv tool install 'beancount-io[ask]'
+uvx --from 'beancount-io[ask]' bea ask --help
+```
+
+## Quick start
+
+```bash
+bea --no-input init books --currency USD --date 2026-08-01 \
+  --opening-balance "Assets:Checking 1000"
+cd books
+bea add transaction "Coffee" --date 2026-08-02 \
+  --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
+bea check
+bea list transaction --limit 10
+bea report balance-sheet
+```
+
+The purchase leaves **987.50 USD** in checking: the currency comes from the
+account and Beancount fills in the balancing posting. For a bank export, see
+the [import guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/IMPORTING.md);
+for your first month end to end, follow the
+[tutorial](https://github.com/bex-co/beancount-io/blob/main/cli/docs/TUTORIAL.md).
+
+## Command map
+
+| Command | Purpose |
+| --- | --- |
+| `bea init [DIRECTORY]` | Create a local ledger with common accounts |
+| `bea add TYPE` | Append one of eleven directive types |
+| `bea import SOURCE` | Preview or apply a bank CSV (`--csv`) or importer (`--config`) |
+| `bea list TYPE` | Inspect directives and filter transactions |
+| `bea check` | Validate the complete ledger |
+| `bea format [PATH]` | Format a file or recursively format a directory |
+| `bea query [BQL]` | Run a query or start the interactive BQL shell |
+| `bea report TYPE` | Overview, income statement, balance sheet, or trial balance |
+| `bea balance [ACCOUNT…]` | Trial-balance subtrees for matching accounts |
+| `bea ask [QUESTION]` | Ask about a local ledger through the hosted AI service |
+| `bea cloud …` | Sign in and manage hosted ledgers |
+| `bea upgrade [--check]` | Check for an update or invoke the owning package manager |
+
+Global options come **before the command**; `--file` selects the root ledger:
+
+```bash
+bea --file main.bean check
+bea --json list transaction --limit 100
+```
+
+Every flag, default, and help string is listed in the generated
+[command reference](https://github.com/bex-co/beancount-io/blob/main/cli/docs/REFERENCE.md).
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success, including previews and intentional duplicate skips |
+| 1 | Ledger, schema, formatting-check, or other runtime failure |
+| 2 | Bad arguments, missing file or input, missing optional dependencies |
+| 3 | Authentication or permission failure, including a read-only destination |
+| 4 | Conflict: concurrent change, import review required, or uncertain remote write |
+
+The [usage guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/USAGE.md#exit-codes)
+documents the full contract: JSON error shape, cloud HTTP mapping, prompts,
+and output exceptions.
+
+## Learn more
+
+- [Tutorial](https://github.com/bex-co/beancount-io/blob/main/cli/docs/TUTORIAL.md):
+  your first month, from `init` to a month-end report.
+- [Usage](https://github.com/bex-co/beancount-io/blob/main/cli/docs/USAGE.md):
+  the contract — targets, JSON envelope, exit codes, prompts, environment.
+- [Importing](https://github.com/bex-co/beancount-io/blob/main/cli/docs/IMPORTING.md):
+  no-code CSV import, rules, and Python importers.
+- [Reference](https://github.com/bex-co/beancount-io/blob/main/cli/docs/REFERENCE.md):
+  every command's usage, arguments, and options, generated from the code.
+
+## Development
+
+```bash norun
+# Clones the repo and syncs dependencies; needs git and network.
+git clone https://github.com/bex-co/beancount-io.git
+cd beancount-io/cli
+uv sync --all-groups
+uv run bea --help
+make check-all
+```
+
+Python 3.12+, Typer, Beancount v3, Beanquery, Pydantic, and a vendored Fava
+reporting subset (it does not start the Fava web interface). `src/cli/` holds
+command UX; `src/fava/` the vendored library (retain `NOTICE.fava`
+attribution); `tests/` the pytest suite; `docs/` the guides above;
+`openapi/v1.json` the pinned contract for hosted commands. `make check-all`
+is the handoff gate: lint, deadcode, format-check, typecheck, test,
+spec-check, and docs-check. Do not hand-edit generated API clients, command
+stubs, `docs/REFERENCE.md`, or lockfiles; keep scratch files under `tmp/`.
+See the [package guide](https://github.com/bex-co/beancount-io/blob/main/cli/CLAUDE.md)
+for architecture boundaries and contribution rules.
+
+## Releases
+
+Releases ship to PyPI and Homebrew from `cli-vX.Y.Z` tags; the
+[release guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/RELEASING.md)
+holds the tagging procedure and one-time credentials setup.
+
+## License
+
+[MIT](https://github.com/bex-co/beancount-io/blob/main/LICENSE) © Beancount.io.
+Vendored Fava attribution is preserved in
+[NOTICE.fava](https://github.com/bex-co/beancount-io/blob/main/cli/NOTICE.fava).

beancount_io-0.1.0/README.md

@@ -0,0 +1,139 @@
+# beancount-io
+
+`bea` is the command-line interface for [Beancount.io](https://beancount.io).
+Create and edit plain-text Beancount ledgers, import bank exports, validate
+accounts, run BQL queries, and generate financial reports. Local bookkeeping
+needs no Beancount.io account. Optional AI assistance and hosted ledger
+management use your Beancount.io credentials.
+
+The Python distribution is **`beancount-io`**; its executable is **`bea`**.
+Run `bea --version` and `bea COMMAND --help` to check the version and options
+you have installed.
+
+## Contents
+
+- [Install](#install) · [Quick start](#quick-start) · [Command map](#command-map)
+- [Exit codes](#exit-codes) · [Learn more](#learn-more)
+- [Development](#development) · [Releases](#releases) · [License](#license)
+
+## Install
+
+```bash norun
+# Installs software; needs Homebrew or uv plus network.
+brew install bex-co/tap/bea      # macOS and Linuxbrew
+uv tool install beancount-io     # anywhere with uv and Python 3.12+
+```
+
+The default installation omits AI dependencies. For `bea ask`, install the
+extra (or run it without replacing your `bea`):
+
+```bash norun
+# Installs software; needs uv plus network.
+uv tool install 'beancount-io[ask]'
+uvx --from 'beancount-io[ask]' bea ask --help
+```
+
+## Quick start
+
+```bash
+bea --no-input init books --currency USD --date 2026-08-01 \
+  --opening-balance "Assets:Checking 1000"
+cd books
+bea add transaction "Coffee" --date 2026-08-02 \
+  --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
+bea check
+bea list transaction --limit 10
+bea report balance-sheet
+```
+
+The purchase leaves **987.50 USD** in checking: the currency comes from the
+account and Beancount fills in the balancing posting. For a bank export, see
+the [import guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/IMPORTING.md);
+for your first month end to end, follow the
+[tutorial](https://github.com/bex-co/beancount-io/blob/main/cli/docs/TUTORIAL.md).
+
+## Command map
+
+| Command | Purpose |
+| --- | --- |
+| `bea init [DIRECTORY]` | Create a local ledger with common accounts |
+| `bea add TYPE` | Append one of eleven directive types |
+| `bea import SOURCE` | Preview or apply a bank CSV (`--csv`) or importer (`--config`) |
+| `bea list TYPE` | Inspect directives and filter transactions |
+| `bea check` | Validate the complete ledger |
+| `bea format [PATH]` | Format a file or recursively format a directory |
+| `bea query [BQL]` | Run a query or start the interactive BQL shell |
+| `bea report TYPE` | Overview, income statement, balance sheet, or trial balance |
+| `bea balance [ACCOUNT…]` | Trial-balance subtrees for matching accounts |
+| `bea ask [QUESTION]` | Ask about a local ledger through the hosted AI service |
+| `bea cloud …` | Sign in and manage hosted ledgers |
+| `bea upgrade [--check]` | Check for an update or invoke the owning package manager |
+
+Global options come **before the command**; `--file` selects the root ledger:
+
+```bash
+bea --file main.bean check
+bea --json list transaction --limit 100
+```
+
+Every flag, default, and help string is listed in the generated
+[command reference](https://github.com/bex-co/beancount-io/blob/main/cli/docs/REFERENCE.md).
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success, including previews and intentional duplicate skips |
+| 1 | Ledger, schema, formatting-check, or other runtime failure |
+| 2 | Bad arguments, missing file or input, missing optional dependencies |
+| 3 | Authentication or permission failure, including a read-only destination |
+| 4 | Conflict: concurrent change, import review required, or uncertain remote write |
+
+The [usage guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/USAGE.md#exit-codes)
+documents the full contract: JSON error shape, cloud HTTP mapping, prompts,
+and output exceptions.
+
+## Learn more
+
+- [Tutorial](https://github.com/bex-co/beancount-io/blob/main/cli/docs/TUTORIAL.md):
+  your first month, from `init` to a month-end report.
+- [Usage](https://github.com/bex-co/beancount-io/blob/main/cli/docs/USAGE.md):
+  the contract — targets, JSON envelope, exit codes, prompts, environment.
+- [Importing](https://github.com/bex-co/beancount-io/blob/main/cli/docs/IMPORTING.md):
+  no-code CSV import, rules, and Python importers.
+- [Reference](https://github.com/bex-co/beancount-io/blob/main/cli/docs/REFERENCE.md):
+  every command's usage, arguments, and options, generated from the code.
+
+## Development
+
+```bash norun
+# Clones the repo and syncs dependencies; needs git and network.
+git clone https://github.com/bex-co/beancount-io.git
+cd beancount-io/cli
+uv sync --all-groups
+uv run bea --help
+make check-all
+```
+
+Python 3.12+, Typer, Beancount v3, Beanquery, Pydantic, and a vendored Fava
+reporting subset (it does not start the Fava web interface). `src/cli/` holds
+command UX; `src/fava/` the vendored library (retain `NOTICE.fava`
+attribution); `tests/` the pytest suite; `docs/` the guides above;
+`openapi/v1.json` the pinned contract for hosted commands. `make check-all`
+is the handoff gate: lint, deadcode, format-check, typecheck, test,
+spec-check, and docs-check. Do not hand-edit generated API clients, command
+stubs, `docs/REFERENCE.md`, or lockfiles; keep scratch files under `tmp/`.
+See the [package guide](https://github.com/bex-co/beancount-io/blob/main/cli/CLAUDE.md)
+for architecture boundaries and contribution rules.
+
+## Releases
+
+Releases ship to PyPI and Homebrew from `cli-vX.Y.Z` tags; the
+[release guide](https://github.com/bex-co/beancount-io/blob/main/cli/docs/RELEASING.md)
+holds the tagging procedure and one-time credentials setup.
+
+## License
+
+[MIT](https://github.com/bex-co/beancount-io/blob/main/LICENSE) © Beancount.io.
+Vendored Fava attribution is preserved in
+[NOTICE.fava](https://github.com/bex-co/beancount-io/blob/main/cli/NOTICE.fava).