Справочник на 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 и неговото балансово утвърждение заедно. 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"

Дестинацията е спрямо основната директория. Тя трябва вече да е включена; именуването на несвързан файл се отказва. Командите за добавяне, импортиранията и интерактивните 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 връща обвивката за валидация. Няма опция --allow-errors за check.

Заявките, списъците и отчетите предупреждават и връщат частични резултати в интерактивен терминал. Глобалният --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 на query не се прилагат към JSON в тази версия.

Native инструменти и допълнителни функции​

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

Незадължителна 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. Пълните инструкции се зареждат при поискване. За оформлението на файловете и работещ пример вижте Разширяване на 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, препратените към Beanprice извиквания на price и 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, за да прегледате инсталираната си версия. Справочникът в хранилището на изходния код съдържа допълнителни примери и точните дефиниции на модела на директивите.