Довідник Beancount CLI

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

Команди в огляді​

Глобальні опції та шляхи​

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

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, Expenses:Uncategorized та Equity:OpeningBalances.

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

Існуючі файли ніколи не перезаписуються. Нові файли використовують дозволи лише для власника, режим 0600 у POSIX. Подальші записи додавання та імпорту зберігають дозволи та поважають призначення лише для читання. Форматування на місці використовує нативний форматувальник і повідомляє про власні помилки файлової системи.

Додати транзакції​

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 -i PATH, коли хочете перевирівняти весь файл.

Список директив​

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

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

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

bea check перевіряє корінь та включення. Він беззвучно завершується кодом 0 у разі успіху та кодом 1 для помилок реєстру. Глобальний --json повертає конверт валідації. Для check немає параметра --allow-errors.

Запити, переліки та звіти попереджають і повертають часткові результати в інтерактивному терміналі. Глобальний --strict, --json, --no-input, істинний CI або нетермінальний stdin роблять читання строгими. Їхній параметр --allow-errors явно дозволяє часткові результати.

Форматування приймає файли або рекурсивно шукає каталог. У опублікованому пакеті 0.2.0 шлях обов'язковий, попри стандартне значення stdin, показане в довідці. Глобальний --file не вибирає ціль форматування.

Форматування вирівнює текст; воно не перевіряє синтаксис реєстру чи бухгалтерію. Запустіть bea check окремо. З глобальним --json виберіть -i, -o FILE, --check або --dry-run, щоб stdout міг нести конверт. Не перенаправляйте stdout поверх вхідного файлу: використовуйте -i, щоб його перезаписати.

bea query "BQL" виконує запит Beancount. Пропуск BQL читає запити з stdin або відкриває оболонку, коли stdin є терміналом. Використовуйте .exit, exit або quit, щоб закрити оболонку. Стандартна таблиця BQL має один рядок на проведення. Таблиці запитів зберігають точність.

Виберіть реєстр перед командою, наприклад bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". Глобальний --json використовує конверт продукту з data.rows та data.columns; він відрізняється від відображення CSV. У опублікованому випуску 0.2.0 використовуйте перенаправлення оболонки, щоб зберегти JSON, як-от bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: параметри запиту -o та -m не застосовуються до JSON у цьому випуску.

Нативні інструменти та необов’язкові функції​

bea doctor context main.bean 42 показує контекст транзакції в рядку 42. bea doctor --help перелічує інші діагностичні команди. bea example -o example.bean створює зразкову історію. bea treeify accounts.txt відображає ієрархічні назви з текстового файлу; пропустіть файл, щоб читати stdin. Ці команди пересилають нативні аргументи. Наведені вище приклади називають ці аргументи явно.

Увімкніть необов'язкові інструменти один раз за допомогою bea engine enable beanprice для отримання котирувань або bea engine enable beangulp для робочих процесів імпортера. Увімкнення потребує доступу до мережі; Beangulp також потребує системної бібліотеки libmagic. Використовуйте bea engine status, щоб оглянути доступність. bea price --help та bea ingest --help описують свої інтерфейси. bea import --csv та bea add price не потребують жодної з необов'язкових функцій.

Керовані включення цін​

Live Prices — це окремий робочий процес керованого включення. Хмарні реєстри розв'язують підтримувані URL цін; сумісні версії bea також підтримують керовані включення та локальні експорти цін. Перегляньте посібник з керованих цін для конкретної версії, якщо ваша встановлена версія не розпізнає ці команди.

CLI розв'язує дозволені керовані URL без надсилання облікових даних і відхиляє перенаправлення. Канал, що перенаправляє на хмарний вхід, таким чином недоступний для свіжого локального отримання; вхід на вебсайт не автентифікує запит цін CLI. Огляньте price status щодо помилок джерел. Використовуйте кешовані дані, доступний підтримуваний канал або локальні датовані ціни за потреби.

price export записує файли каналів у prices/ та переписує включення на локальні відносні шляхи. Зовнішні Beancount, Fava та Beanquery можуть завантажити цю експортовану копію. Недоступне джерело відмовляє в експорті, якщо не використано --allow-errors, що може залишити його маркер джерела без цін.

Ваша власна датована ціна перевизначає керовану ціну для тієї самої дати та пари. Записи каналу доступні лише для читання. Невдалі оновлення зберігають раніше перевірену ревізію, яка може бути застарілою. Інші аргументи bea price все ще пересилаються до Beanprice; якщо файл завдання котирувань названо status, передайте ./status, щоб відрізнити його від підкоманди.

Homebrew встановлює як CLI, так і його керований рушій. З PyPI перша команда з підтримкою рушія завантажує закріплені залежності; тримайте uv у PATH і дозвольте доступ до мережі для цього першого запуску. Пізніші локальні команди повторно використовують рушій офлайн. Клієнти встановлюють лише beancount-io, без окремого пакета Beancount або нативних консольних скриптів для керування.

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

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

bea balance [ACCOUNT...] виводить піддерева балансів для рахунків, що відповідають підрядкам без урахування регістру, або весь реєстр, коли ви не називаєте жодного. Він приймає --conversion / -x, --time / -t та --allow-errors, і не має параметра інтервалу чи рахунку.

Часові фільтри включають рік, місяць, дату, квартал, тиждень або діапазон, як-от 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 звіту також ідентифікує період, виключну кінцеву дату, дату станом на, конвертацію, фільтр рахунків та стан валідації реєстру. Перевірте ці поля перед порівнянням підсумків.

Опційна допомога ШІ​

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. Повні інструкції завантажуються за потреби. Щодо структури файлів та робочого прикладу дивіться Розширте bea ask за допомогою навичок.

Хостовані бухгалтерії​

З глобальним --json bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create та bea cloud ledger delete видають стандартний конверт. Вхід потребує взаємодії; успішний вихід та клонування не повертають об'єкт успіху JSON.

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

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

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

{
  "bea": "0.2.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 перед повторною спробою зміни. Частковий пакет може записати прийняті рядки, рекурсивне форматування може змінити дійсні файли, а створення-та-клонування може створити хмарний реєстр перед виходом з ненульовим кодом. Щодо скрипту, який читає цей конверт за допомогою jq і розгалужується за цими кодами, дивіться Автоматизуйте бухгалтерію з bea.

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

Винятки виводу: doctor, example, treeify, виклики price, переслані до Beanprice, та ingest зберігають нативний вивід і стан виходу, навіть із глобальним --json; конверт і категорії виходу вище не описують ці переслані результати. 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, щоб оглянути вашу встановлену версію. Довідник вихідного репозиторію містить додаткові приклади та точні визначення моделі директив.