Справочник по CLI Beancount

Используйте этот справочник, чтобы найти команды 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. Последующие записи add и import сохраняют права и уважают назначения только для чтения. Форматирование на месте использует нативный форматтер и сообщает о собственных файловых ошибках.

Добавить транзакции​

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 и настроенные имена корней.

Директива balance проверяет счёт на начало своей даты. Поддерживается синтаксис допуска, например --amount "1538 ~ 1 EUR". Допуск должен быть неотрицательным.

Используйте add balance --pad-from Equity:OpeningBalances, чтобы записать pad и его проверку баланса вместе. Pad по умолчанию относится к предыдущему дню; --pad-date может выбрать другой более ранний день. Оба счёта должны быть активны. Отдельный pad требует более поздней проверки баланса, чтобы быть использованным. --allow-errors может подготовить это промежуточное состояние, но не может обойти недопустимый счёт pad.

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"

Назначение указывается относительно корневого каталога. Оно должно уже быть включено; указание несвязанного файла отклоняется. Команды добавления, импорты и интерактивные записи ИИ поддерживают такое разделение.

Записи проверяют полный реестр-кандидат, включая плагины и учёт партий затрат. Параллельное изменение корня или графа его включений завершается с кодом 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. Все, кроме trial balance, также принимают --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 по умолчанию опускает зависимости ИИ. Пользователи 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 не поддерживается.

Запросы выполняются локально. Вопросы, контекст навыков и результаты инструментов отправляются в облачный сервис ИИ Beancount.io. Интерактивные записи предварительно просматриваются, подтверждаются, проверяются и записываются атомарно. Они принимают --into. Глобальный --yes не даёт разрешение на запись ИИ. Режим одного ответа не применяет предложенные записи.

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, чтобы изучить вашу установленную версию. Справочник по исходному репозиторию содержит дополнительные примеры и точные определения модели директив.