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

Перечисление директив​

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 отчета также идентифицирует период, конечную дату, дату на дату, конвертацию, фильтр счетов и статус проверки книги. Проверяйте эти поля перед сравнением итогов.

Необязательная ИИ-помощь​

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 AI. Интерактивные записи предварительно просматриваются, подтверждаются, проверяются и записываются атомарно. Они принимают --into. Глобальный --yes не предоставляет разрешение на запись ИИ. Режим одного ответа не применяет предложенные записи.

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

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