Beancount CLI: швидкий старт

Створіть локальну книгу та запишіть свою першу покупку за допомогою bea — інструменту командного рядка Beancount.io. Для локального ведення обліку обліковий запис Beancount.io не потрібен.

Цей покроковий посібник починається з 1000 USD на поточному рахунку. Після покупки кави на 12.50 USD ви перевірите баланс у розмірі 987.50 USD.

1. Встановлення команди​

За допомогою Homebrew на macOS або Linux:

brew install bex-co/tap/bea
bea --version

Якщо ви не користуєтеся Homebrew, встановіть uv та використайте uv tool install beancount-io. Цей пакет Python вимагає Python 3.12 або новішої версії.

2. Створення вашої книги​

Оберіть новий каталог. Цей приклад створює main.bean усередині ~/my-books:

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

Шаблон відкриває типові рахунки для поточних рахунків, готівки, кредитних карток, доходів та витрат. Початковий баланс зараховується на рахунок Equity:OpeningBalances.

Для власних книг оберіть найранішу дату, яку ви плануєте записувати. Усі рахунки з шаблону відкриваються на цю дату. Початковий баланс має описувати стан рахунку на цей день. Заборгованість за кредитною карткою вказується як від’ємна сума.

init ніколи не перезаписує існуючу книгу. Нові файли є приватними на системах POSIX: лише власник може їх читати та записувати. Щоб поділитися з вашою локальною групою користувачів, явно змініть права доступу за допомогою chmod 640 main.bean.

Для інтерактивного налаштування запустіть bea init ~/my-books у терміналі. Майстер запитає вашу валюту, дату початку історії та баланс поточного рахунку.

3. Запис покупки​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

Витрата використовує валюту рахунку — USD. Beancount автоматично заповнює іншу проводку як -12.50 USD. Ви можете пропустити --date для покупок, здійснених сьогодні.

Кожне додавання перевіряється на відповідність повній книзі перед заміною файлу. Невідомий рахунок або незбалансована транзакція призведе до помилки з підказками.

4. Перевірка результату​

bea check
bea list transaction --limit 10
bea report balance-sheet

Список транзакцій показує найновіші записи спочатку, із сумами проводок. Балансовий звіт показує 987.50 USD на поточному рахунку.

Щоб безпосередньо перевірити цю суму:

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Таблиці запитів зберігають точність результату. Для структурованого виводу поставте глобальний прапорець --json перед командою:

bea --json list transaction --limit 10

5. Підтримання книги в належному стані​

Запустіть bea check після ручного редагування файлу. Запустіть bea format main.bean, щоб вирівняти стовпці. Використовуйте bea format main.bean --check, щоб скрипт завершувався помилкою, якщо форматування потрібне.

Щоб працювати з іншого каталогу, явно вкажіть кореневий файл:

bea --file ~/my-books/main.bean check

Корінь обирається за допомогою --file, потім BEA_FILE, а потім main.bean у робочому каталозі. Глобальні опції йдуть перед командою. Форматування приймає власний аргумент файлу або каталогу.

Продовжуйте з власними записами​

• Імпорт банківських виписок із попереднім переглядом та перевіркою дублікатів.
• Ознайомтеся з командами та опціями для рахунків, балансів, інвестицій та автоматизації.
• Організуйте книгу за файлами. Використовуйте --into, щоб писати у включений файл, перевіряючи його проти кореня.
• Використовуйте браузерний інтерфейс, якщо вам зручніші форми, а не команди термінала.

Перевіряйте наявність оновлень за допомогою bea upgrade --check. Запустіть bea upgrade, щоб викликати менеджер пакунків, який встановив вашу копію. Використовуйте bea --help або bea add transaction --help, щоб переглянути доступні опції у вашій встановленій версії.