Довідник Beancount CLI

Використовуйте цей довідник, щоб знайти команди bea та їхню поведінку. Для своєї першої бухгалтерської книги перегляньте швидкий старт CLI. Для банківських файлів використовуйте покроковий посібник з імпорту.

Команди з першого погляду​

Глобальні параметри та шляхи​

Глобальні параметри вказуються перед командою:

bea --file ~/my-books/main.bean check
bea --json list transaction --limit 100

init створює власну ціль для каталогу/файлу та ігнорує BEA_FILE. Він приймає глобальний --file замість аргументу каталогу. format використовує власну позиційну ціль, за замовчуванням — робочий каталог. Глобальний --file не визначає ціль форматування.

Створення бухгалтерської книги​

bea init [DIRECTORY] за замовчуванням використовує поточний каталог. Каталог створює main.bean; шлях .bean або .beancount безпосередньо називає новий файл.

Шаблон відкриває Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees та Equity:OpeningBalances.

Вхідні залишки компенсуються через Equity:OpeningBalances. Борг від'ємний. Введена валюта переводиться у верхній регістр. Дозволені власні символи; символ, який не є трьома великими літерами, викликає попередження про друкарську помилку. Це не перевірка ISO-реєстру валют.

Існуючі файли ніколи не перезаписуються. Нові файли використовують права лише для власника, режим 0600 на POSIX. Подальші записи через add, import та format зберігають права та поважають захищені від запису призначення.

Додавання транзакцій​

bea add transaction -n "Groceries" --payee "Corner Market" \
  -p "Expenses:Groceries 30" -p "Assets:Checking" \
  --flag '!' --tag household --link receipt-42 --meta 'receipt:IMG_42.jpg'

Одна проводка може пропускати свою суму. Проводки з номерами можуть пропускати валюту, якщо рахунок має одну дозволену валюту або книга має одну сумісну робочу валюту. Інакше вкажіть символ.

Вбудований синтаксис проводок підтримує арифметику, як-от 84/2 EUR, витрати, як-от {100 USD}, загальні витрати {{1000 USD}}, та ціни @ або @@. Використовуйте десяткові суми, як-от 1000, а не експоненціальний запис, як-от 1e3.

Обмін валюти потребує фактичного курсу транзакції. Наприклад, проведіть 100 EUR @ 1.08 USD на рахунок, відкритий в EUR, та -108 USD на чековий рахунок. Інвестиційна покупка може провести 2 AAPL {100 USD} на рахунок, відкритий в AAPL, та -200 USD на чековий. Додайте котирування price з датами, коли звітам потрібна ринкова оцінка.

Метадані приймають прості рядки, як-от --meta 'receipt:IMG_42.jpg'. Вбудовані числа, булеві значення, дати та суми зберігають свої типи. Приклади: --meta 'reviewed:TRUE', --meta 'received:2026-08-03' та --meta 'fee:2.50 USD'. Внутрішні лапки примушують рядок: --meta 'code:"1234"'. Ключі мають бути унікальними; filename та lineno зарезервовані.

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

Додавання інших директив​

Усі ці команди вимагають --date YYYY-MM-DD. Вони також приймають --into FILE та --allow-errors.

Назви рахунків мають корінь із великої літери та сегменти, розділені двокрапкою. Кожен субрахунок починається з великої літери або цифри. Beancount підтримує літери Unicode та налаштовані назви коренів.

Балансова перевірка рахунку відбувається на початку його дати. Підтримується синтаксис допуску, як-от --amount "1538 ~ 1 EUR". Допуск має бути невід'ємним.

Використовуйте add balance --pad-from Equity:OpeningBalances, щоб записати пад та його балансову перевірку разом. Пад за замовчуванням використовує попередній день; --pad-date може вибрати інший раніший день. Обидва рахунки мають бути активними. Окремий пад потребує пізнішої балансової перевірки, щоб його використати. --allow-errors може підготувати цей проміжний стан, але не може обійти недійсний рахунок паду.

add price пропускає точний дублікат дати/товару/ціни у корені та його включеннях. Він завершується кодом 0 і вказує існуюче місце розташування. Інші дати або ціни — це нові доповнення.

Шляхи документів розв'язуються поруч із файлом, що містить директиву. З --into years/2026.bean, --filename receipt.pdf означає years/receipt.pdf, а не файл поруч із робочим каталогом вашої оболонки.

Види власних значень: text, number, amount, account, bool та date. Наприклад, бюджет може використовувати --value "text:travel" --value "amount:500 USD".

Масовий JSON-ввід​

bea add transactions --from transactions.json приймає JSON-масив:

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

Кожна транзакція потребує date та postings. Опціональні поля: flag, payee, narration, tags, links та meta.

Проводка використовує або amount, або units, як-от {"number":"45.00","currency":"USD"}. Пропустіть обидва для балансуючої проводки. Поля проводки також включають cost, price, flag та meta. Витрати містять number та currency, з опціональними date та label. Ціни містять number та currency.

Використовуйте рядки для десяткових чисел. Метадані використовують звичайні рядки та булеві значення, або теговані значення, як-от {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} та {"kind":"amount","number":"2.50","currency":"USD"}. Опціональне розташування source транзакції ніколи не записується як метадані.

За замовчуванням — атомарний пакет: будь-який відхилений рядок залишає книгу незмінною і завершується кодом 1. --partial записує дійсний підмножину і все одно завершується кодом 1, якщо будь-які рядки відхилені. JSON-помилки описують результат у error.result; індекси рядків там нумеруються з нуля. Людські номери рядків нумеруються з одиниці.

Масове додавання приймає --into та --allow-errors. Воно не дедуплікує. Використовуйте bea import для перегляду банківських експортів.

Розділені книги та безпека запису​

Тримайте --file спрямованим на корінь. Додайте --into, щоб вибрати існуючий включений файл:

bea --file ~/my-books/main.bean add transaction --into 2026.bean \
  --date 2026-08-02 -n "Groceries" \
  -p "Expenses:Groceries 30" -p "Assets:Checking"

Призначення відносне до кореневого каталогу. Воно має вже бути включеним; називання непов'язаного файлу відхиляється. Команди додавання, імпорти та інтерактивні AI-записи підтримують цей розподіл.

Записи перевіряють повну книгу-кандидата, включаючи плагіни та облік партій витрат. Одночасна зміна кореня або його графа включень завершується кодом 4. Призначення, захищене від запису, завершується кодом 3. Успішні доповнення використовують те саме вирівнювання, що й bea format, яке може перевирівняти існуючі стовпці в цьому призначенні.

Перелік директив​

bea list TYPE підтримує одинадцять типів: transaction, open, close, balance, pad, note, event, price, commodity, document та custom.

Інші типи директив зберігають хронологічний порядок. Таблиця транзакцій, відфільтрована за рахунком, позначає свій стовпець суми як MATCHING POSTING AMOUNTS. Деталі та JSON все одно включають усі проводки кожної вибраної транзакції. Деталі показують завантажені записи, включаючи виведені суми; це не сирі фрагменти джерела.

Перевірка, форматування та запити​

bea check перевіряє корінь та включення. Він завершується кодом 1 за помилок книги і не має опції --allow-errors. Запити, списки та звіти також відхиляють помилки завантаження, якщо ви явно не передаєте їх опцію --allow-errors.

Форматування приймає файл .bean/.beancount або каталог. Каталог обробляється рекурсивно.

Кожен режим повідомляє про синтаксичні помилки за файлом і рядком, пропускає ці файли та завершується кодом 1. Рекурсивний звичайний запуск може все одно відформатувати дійсні файли. JSON повідомляє scanned, formatted, skipped, dry_run та check у error.result при збої.

bea query "BQL" виконує запит Beancount. Пропуск BQL відкриває інтерактивну оболонку; exit або quit закриває її. Аргумент запиту обов'язковий без нагляду. Таблиця BQL за замовчуванням має один рядок на проводку. Таблиці запитів зберігають точність. Порожні результати виводять (no rows) у stderr; JSON повертає порожні data.rows та метадані стовпців у data.columns.

Фінансові звіти​

Усі звіти приймають --conversion / -x, --time / -t, --account / -a та --allow-errors. Усі, крім пробного балансу, також приймають --interval / -i: за замовчуванням monthly, або quarterly, yearly, weekly чи daily.

Часові фільтри включають рік, місяць, дату, квартал, тиждень або діапазон, як-от 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 або "2026-01 - 2026-08". Відносні періоди включають year, quarter, month, week, day та зсуви, як-от month-1. Фільтри рахунків зберігають кожну проводку відповідної транзакції.

Конверсія за замовчуванням використовує єдину робочу валюту книги. Інакше за замовчуванням — units, зберігаючи товари окремо. at_cost використовує вартість придбання. at_value використовує ринкову вартість із резервом за вартістю.

Явна конвертація валюти потребує цін на або до кожної дати оцінки, включаючи дати інтервалів. Помилка про відсутню ціну називає фактичну прогалину, як-от No EUR → USD price on or before 2026-01-31. Пізніше котирування не може заповнити ранішу прогалину. Додайте історично відповідну ціну, використовуйте --conversion units або оберіть --allow-errors, щоб переглянути часткові значення.

Часткові звіти зберігають вихідні валюти та позначають комбіновані підсумки недоступними. JSON включає valuation: "partial", missing_prices та missing_price_dates. Відповідні підсумки чистого прибутку/чистої вартості дорівнюють null у запитаній валюті.

Доходи, зобов'язання та власний капітал зазвичай використовують від'ємні знаки Beancount. Чистий прибуток — це -(income + expenses), додатний для прибутку. Та сама конвенція застосовується до рядків періодів звіту про прибутки та збитки. Узгодження балансового звіту виводиться для звіту; він не записує директиви. equity_reconciled вказує, чи доступне повне узгодження.

JSON звіту також визначає період, виключну кінцеву дату, дату станом на, конверсію, фільтр рахунку та статус валідації книги. Перевірте ці поля перед порівнянням підсумків.

Опціональна AI-допомога​

bea ask потребує як додаткового компонента ask, так і облікових даних Beancount.io з bea cloud login або BEA_TOKEN. Стандартне встановлення Homebrew пропускає AI-залежності. Користувачі Homebrew можуть запустити:

bea cloud login
uvx --from 'beancount-io[ask]' bea ask "What did I spend last month?" --print

Для встановлення через uv встановіть beancount-io[ask] і запустіть bea ask безпосередньо. --print / -p відповідає один раз і завершується. Інакше термінальна сесія інтерактивна, і опціональне питання попередньо заповнює її ввід. Неінтерактивне використання вимагає питання. Режим JSON не підтримується.

Запити виконуються локально. Питання, контекст навичок і результати інструментів надсилаються до хмарного AI-сервісу Beancount.io. Інтерактивні записи попередньо переглядаються, підтверджуються, валідуються та записуються атомарно. Вони приймають --into. Глобальний --yes не надає дозвіл на AI-запис. Режим однієї відповіді не застосовує запропоновані записи.

Ask читає NAME/SKILL.md з .agents/skills/ у робочому каталозі та з skills/ у каталозі конфігурації користувача. Визначення проєкту виграють за назвою. Кожен файл потребує полів YAML name та description. Повні інструкції завантажуються на вимогу.

Хмарні книги​

Створення також приймає --clone та --dir. Для клонування потрібен доступ до Git та SSH. Якщо клонування не вдається після створення, хмарна книга все одно існує. Локальні команди не завантажують вашу книгу автоматично. Глобальної опції --ledger немає.

JSON та коди виходу​

Глобальний --json виводить успішні результати у stdout:

{
  "bea": "0.1.0",
  "target": { "file": "/home/alice/my-books/main.bean" },
  "data": [],
  "truncated": false,
  "limit": 50
}

bea — це встановлена версія; data залежить від команди. Цілі визначають файл, каталог, сервер або відсутність цілі. Включені записи також визначають into. Десяткові суми та дати використовують рядки. Обмежені списки включають limit та truncated.

Збої записують {"error":{"category":"validation","message":"…","exit_code":1}} у stderr. Помилка також може включати details, result, request_id бекенду та traceback з --debug.

Перевірте error.result перед повторною спробою мутації. Частковий пакет може записати прийняті рядки, рекурсивне форматування може змінити дійсні файли, а create-and-clone може створити хмарну книгу перед виходом із ненульовим кодом.

Запити CLI вимикаються --no-input, режимом JSON, не-термінальним stdin або істинним CI. Видалення в хмарі все одно потребує явного --yes. Імпорти потребують явного рішення про дублікати, коли збіги потребують перегляду.

Винятки виводу: Ask відхиляє JSON; вхід у хмару потребує взаємодії; успішний вихід із хмари та клон не повертають JSON-об'єкт успіху. Довідка, версія та завершення зберігають текстовий вивід. upgrade може потоково виводити вивід свого менеджера пакунків у stderr, включно з режимом JSON.

Налаштування, оновлення та збережений стан​

Істинні значення: 1, true, yes та on, без урахування регістру та оточуючих пробілів. Стан конфігурації включає облікові дані, історію запитів Ask, навички користувача, запам'ятовані шляхи імпортерів та кеші перевірки оновлень. Замки запису розташовані в locks/ під каталогом кешу, поза вашим каталогом книги.

bea upgrade --check повідомляє версії та метод встановлення без оновлення. bea upgrade викликає brew upgrade bea, uv tool upgrade beancount-io або pipx upgrade beancount-io. Редагувальні встановлення отримують посібник із ручного оновлення. Пасивні перевірки виконуються щонайбільше раз на день в інтерактивних встановлених копіях; явний upgrade --check все одно виконується, коли пасивний сповіщувач вимкнено.

Видаліть через відповідний менеджер: brew uninstall bea, uv tool uninstall beancount-io або pipx uninstall beancount-io. Ваші файли книги та конфігурація користувача залишаються.

Типові виправлення​

Використовуйте bea COMMAND --help, щоб переглянути свою встановлену версію. Довідник вихідного репозиторію містить додаткові приклади та точні визначення моделі директив.