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

Използвайте този справочник, за да потърсите bea команди и тяхното поведение. За първия си ledger следвайте CLI краткото ръководство. За банкови файлове използвайте ръководството за импортиране.

Команди накратко​

Глобални опции и пътища​

Глобалните опции се поставят преди командата:

bea --file ~/my-books/main.bean check
bea --json list transaction --limit 100

init създава своя собствена директория/файлова цел и игнорира BEA_FILE. Приема глобално --file вместо аргумента за директория. format използва своя собствена позиционна цел, като по подразбиране е работната директория. Глобалното --file не избира целта за форматиране.

Създаване на ledger​

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'

Едно осчетоводяване може да пропусне своята сума. Номерираните осчетоводявания могат да пропуснат валутата, когато сметката има една разрешена валута или ledger-ът има една съвместима основна валута. В противен случай предоставете символа.

Естественият синтаксис за осчетоводявания поддържа аритметика като 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 са запазени.

Единичните add, груповите add и импортирането заменят новите редове в payees, narrations и низови метаданни с интервали. Кавичките и обратните наклонени черти запазват съдържанието си.

Добавяне на други директиви​

Всички тези команди изискват --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 на транзакцията никога не се записва като метаданни.

По подразбиране е атомарен пакет: всеки отхвърлен ред оставя ledger-а непроменен и излиза с 1. --partial записва валидно подмножество и все още излиза с 1, ако някакви редове са отхвърлени. JSON грешките описват резултата в error.result; индексите на редове там са базирани на нула. Човешките номера на редове са базирани на единица.

Груповият add приема --into и --allow-errors. Не дедуплицира. Използвайте bea import за преглед на банкови експорти.

Разделени ledgers и безопасност при запис​

Дръжте --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"

Дестинацията е относителна към основната директория. Тя трябва вече да е включена; именуването на несвързан файл се отказва. Add команди, импортирания и интерактивни AI записи поддържат това разделение.

Записите валидират пълния кандидат ledger, включително плъгини и осчетоводяване на разходни партиди. Едновременна промяна на основния файл или неговия граф на включване излиза с 4. Само за четене дестинация излиза с 3. Успешните добавки използват същото подравняване като bea format, което може да подравни отново съществуващи колони в тази дестинация.

Изброяване на директиви​

bea list TYPE поддържа единадесетте типа: transaction, open, close, balance, pad, note, event, price, commodity, document и custom.

Други типове директиви запазват хронологичен ред. Таблица с транзакции, филтрирана по сметка, обозначава колоната си за суми като MATCHING POSTING AMOUNTS. Details и JSON все още включват всички осчетоводявания на всяка избрана транзакция. Details показват заредените записи, включително изведени суми; те не са сурови извадки от източника.

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

bea check валидира основния файл и включените файлове. Излиза с 1 при грешки в ledger-а и няма опция --allow-errors. Заявките, списъците и отчетите също отхвърлят грешки при зареждане (loader 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. Всички освен trial balance също приемат --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. Филтрите по сметка запазват всяко осчетоводяване на съвпадаща транзакция.

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

Опционална 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 режим не се поддържа.

Заявките се изпълняват локално. Въпросите, контекста за умения и резултатите от инструменти отиват към хостираната Beancount.io AI услуга. Интерактивните записи се преглеждат, потвърждават, валидират и записват атомарно. Те приемат --into. Глобалното --yes не дава AI право за запис. Режимът с един отговор не прилага предложените записи.

Ask чете NAME/SKILL.md от .agents/skills/ в работната директория и от skills/ в потребителската конфигурационна директория. Дефинициите на проекта печелят по име. Всеки файл се нуждае от YAML полета name и description. Пълните инструкции се зареждат при поискване.

Хостирани ledgers​

Създаването също приема --clone и --dir. Git и SSH достъп са необходими за клониране. Ако клонирането се провали след създаването, хостираният ledger все още съществува. Локалните команди не качват автоматично вашия ledger. Няма глобална опция --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, преди да повторите мутация. Частичен пакет може да запише приети редове, рекурсивното форматиране може да промени валидни файлове, а създаване-и-клониране може да създаде хостиран ledger, преди да излезе с ненулев код.

CLI подканите се деактивират от --no-input, JSON режим, не-терминален stdin или истинска CI. Изтриването в облака все още изисква изрично --yes. Импортиранията изискват изрично решение за дубликат, когато съвпаденията се нуждаят от преглед.

Изключения на изхода: Ask отхвърля JSON; входът в облака изисква взаимодействие; успешното излизане от облака и клонирането не връщат JSON обект за успех. Помощта, версията и завършването запазват текстов изход. upgrade може да предава изхода на своя пакетен мениджър към stderr, включително в JSON режим.

Настройки, актуализации и запазено състояние​

Истинните стойности са 1, true, yes и on, независимо от главните букви и заобикалящите интервали. Конфигурационното състояние включва идентификационни данни, история на Ask подкани, потребителски умения, запомнени пътища за импортиране и кешове за проверка на актуализации. Lock файловете за запис се намират под locks/ в кеш директорията, извън вашата ledger директория.

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. Вашите ledger файлове и потребителска конфигурация остават.

Често срещани корекции​

Използвайте bea COMMAND --help, за да инспектирате вашата инсталирана версия. Справочникът в хранилището на източниците съдържа допълнителни примери и точните дефиниции на моделите на директивите.