Beancount CLI: краткое руководство

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

Это руководство начинается с 1000 долларов США на текущем счёте. После покупки кофе за 12,50 долларов США вы проверите баланс в размере 987,50 долларов США.

1. Установка команды​

С помощью Homebrew на macOS или Linux:

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

Если вы не используете Homebrew, установите uv и используйте uv tool install beancount-io. Для пакета Python требуется Python 3.12 или новее. Homebrew предоставляет учётный движок во время установки. При использовании PyPI держите uv доступным: первая локальная команда загружает управляемый движок, а последующие команды используют его повторно в автономном режиме. Устанавливать Beancount отдельно не нужно.

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"

Расход использует валюту счёта — доллары США. 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 -i main.bean, чтобы выровнять столбцы в файле. Без флага -i отформатированный текст выводится в стандартный поток вывода, а файл остаётся без изменений. Используйте bea format main.bean --check, когда скрипт должен завершиться ошибкой, если требуется форматирование.

Чтобы работать из другого каталога, явно укажите корневой файл:

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

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

Продолжение с вашими записями​

• Импорт банковской выписки с предпросмотром и проверкой дубликатов.
• Передайте внешнему агенту две задачи по учёту с копируемыми подсказками и эквивалентами команд CLI.
• Сравните пять бухгалтерских инструментов для ИИ-агентов по установке, аутентификации, области действия, данным, предпросмотру, выходным данным и повторениям, с указанием дат источников.
• Поиск команд и параметров для счетов, балансов, инвестиций, отчётов и автоматизации.
• Организация книги в нескольких файлах. Используйте --into для записи включённого файла с проверкой относительно корня.
• Использование браузерного интерфейса, если вы предпочитаете формы терминальным командам.

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