Referencia CLI Beancount

Túto referenciu použite na vyhľadanie príkazov bea a ich správania. Pre vaše prvé účtovníctvo postupujte podľa Rýchleho štartu CLI. Pre bankové súbory použite Návod na import.

Prehľad príkazov​

Globálne možnosti a cesty​

Globálne možnosti sa píšu pred príkaz:

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

init vytvára vlastný adresár/súbor a ignoruje BEA_FILE. Akceptuje globálny --file namiesto argumentu adresára. format používa vlastný pozičný cieľ, pričom predvolene používa pracovný adresár. Globálny --file nevyberá cieľ formátovania.

Vytvorte účtovníctvo​

bea init [DIRECTORY] predvolene používa aktuálny adresár. Adresár vytvorí main.bean; cesta .bean alebo .beancount pomenuje nový súbor priamo.

Šablóna vytvorí Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees a Equity:OpeningBalances.

Počiatočné stavy sa kompenzujú proti Equity:OpeningBalances. Dlh je záporný. Vstup meny je písaný veľkými písmenami. Vlastné symboly sú povolené; symbol, ktorý nie sú tri veľké písmená, spôsobí varovanie o preklepe. Toto nie je kontrola ISO registra mien.

Existujúce súbory sa nikdy neprepisujú. Nové súbory majú povolenia iba pre vlastníka, režim 0600 na POSIX. Neskoršie add, import a format zápisy zachovávajú povolenia a rešpektujú ciele len na čítanie.

Pridávanie transakcií​

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'

Jedno zúčtovanie môže vynechať svoju sumu. Číslované zúčtovania môžu vynechať menu, ak má účet jednu povolenú menu alebo ak má účtovníctvo jednu kompatibilnú prevádzkovú menu. Inak zadajte symbol.

Natívna syntax zúčtovania podporuje aritmetiku ako 84/2 EUR, náklady ako {100 USD}, celkové náklady {{1000 USD}} a ceny @ alebo @@. Použite desatinné sumy ako 1000, nie exponenciálny zápis ako 1e3.

Menová výmena vyžaduje skutočný kurz transakcie. Napríklad zaúčtujte 100 EUR @ 1.08 USD na účet otvorený v EUR a -108 USD na bežný účet. Nákup investície môže zaúčtovať 2 AAPL {100 USD} na účet otvorený v AAPL a -200 USD na bežný účet. Pridajte datované price kotácie, keď správy potrebujú trhové ocenenie.

Metadáta akceptujú holé reťazce ako --meta 'receipt:IMG_42.jpg'. Natívne čísla, booleany, dátumy a sumy si zachovávajú svoje typy. Príklady zahŕňajú --meta 'reviewed:TRUE', --meta 'received:2026-08-03' a --meta 'fee:2.50 USD'. Vnútorné úvodzovky vynútia reťazec: --meta 'code:"1234"'. Kľúče musia byť odlišné; filename a lineno sú vyhradené.

Jednotlivé add, hromadné add a import nahrádzajú konce riadkov v príjemcoch, opisoch a reťazcových metadátach s medzerami. Úvodzovky a spätné lomky si zachovávajú svoj obsah.

Pridávanie iných direktív​

Všetky tieto príkazy vyžadujú --date YYYY-MM-DD. Tiež akceptujú --into FILE a --allow-errors.

Názvy účtov majú veľké koreňové písmeno a segmenty oddelené dvojbodkou. Každý podúčet začína veľkým písmenom alebo číslicou. Beancount podporuje písmená Unicode a nakonfigurované koreňové názvy.

Kontrola zostatku kontroluje účet na začiatku svojho dátumu. Tolerančná syntax je podporovaná, napríklad --amount "1538 ~ 1 EUR". Tolerancia musí byť nezáporná.

Použite add balance --pad-from Equity:OpeningBalances na zápis padu a jeho kontrolu zostatku spolu. Pad je predvolene od predchádzajúceho dňa; --pad-date môže vybrať iný skorší deň. Oba účty musia byť aktívne. Samostatný pad potrebuje neskoršiu kontrolu zostatku, ktorá ho spotrebuje. --allow-errors môže zinscenovať prechodný stav, ale nemôže obísť neplatný padový účet.

add price preskočí presnú duplicitu dátumu/komodity/ceny naprieč koreňom a jeho zahrnutými súbormi. Ukončí sa kódom 0 a identifikuje existujúce miesto. Rôzne dátumy alebo ceny sú nové prídavky.

Cesty dokumentov sa interpretujú vedľa súboru obsahujúceho direktívu. S --into years/2026.bean, --filename receipt.pdf znamená years/receipt.pdf, nie súbor vedľa shellu vášho pracovného adresára.

Druhy hodnôt pre vlastné sú text, number, amount, account, bool a date. Napríklad rozpočet môže použiť --value "text:travel" --value "amount:500 USD".

Hromadný JSON vstup​

bea add transactions --from transactions.json akceptuje JSON pole:

[
  {
    "date": "2026-08-04",
    "narration": "Groceries",
    "postings": [
      { "account": "Expenses:Groceries", "amount": "45.00 USD" },
      { "account": "Assets:Checking" }
    ],
    "meta": { "receipt": "R-43", "reviewed": true }
  }
]

Každá transakcia vyžaduje date a postings. Voliteľné polia sú flag, payee, narration, tags, links a meta.

Zúčtovanie používa buď amount alebo units, napríklad {"number":"45.00","currency":"USD"}. Vynechajte obe pre vyrovnávacie zúčtovanie. Polia zúčtovania tiež zahŕňajú cost, price, flag a meta. Náklady obsahujú number a currency, s voliteľným date a label. Ceny obsahujú number a currency.

Pre desatinné čísla použite reťazce. Metadáta používajú obyčajné reťazce a booleany, alebo tagované hodnoty ako {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} a {"kind":"amount","number":"2.50","currency":"USD"}. Voliteľné source miesto transakcie sa nikdy nezapisuje ako metadáta.

Predvolené je atómová dávka: akýkoľvek odmietnutý riadok ponechá účtovníctvo nezmenené a ukončí sa kódom 1. --partial zapíše platnú podmnožinu a stále sa ukončí kódom 1, ak sú niektoré riadky odmietnuté. JSON chyby opisujú výsledok v error.result; indexy riadkov sú tam založené na nule. Ľudské čísla riadkov sú založené na jednotke.

Hromadné add akceptuje --into a --allow-errors. Nevykonáva deduplikáciu. Použite bea import na kontrolu bankových exportov.

Rozdelené účtovníctva a bezpečnosť zápisu​

Udržujte --file ukazujúci na koreň. Pridajte --into na výber existujúceho zahrnutého súboru:

bea --file ~/my-books/main.bean add transaction --into 2026.bean \
  --date 2026-08-02 -n "Groceries" \
  -p "Expenses:Groceries 30" -p "Assets:Checking"

Cieľ je relatívny ku koreňovému adresáru. Musí byť už zahrnutý; odmietne sa pomenovanie nesúvisiaceho súboru. Príkazy add, importy a interaktívne AI zápisy podporujú toto oddelenie.

Zápisy overujú úplného kandidáta účtovníctva vrátane pluginov a bookovania nákladových dávok. Súbežná zmena koreňa alebo jeho grafu zahrnutých súborov sa ukončí kódom 4. Cieľ len na čítanie sa ukončí kódom 3. Úspešné prídavky používajú rovnaké zarovnanie ako bea format, ktoré môže preformátovať existujúce stĺpce v tomto cieli.

Vypisovanie direktív​

bea list TYPE podporuje jedenásť typov: transaction, open, close, balance, pad, note, event, price, commodity, document a custom.

Ostatné typy direktív zachovávajú chronologické poradie. Tabuľka transakcií filtrovaná podľa účtu označuje svoj stĺpec sumy MATCHING POSTING AMOUNTS. Detaily a JSON stále zahŕňajú všetky zúčtovania každej vybranej transakcie. Detaily zobrazujú načítané záznamy vrátane odvodených súm; nie sú to surové výňatky zo zdroja.

Check, format a query​

bea check overuje koreň a zahrnuté súbory. Ukončí sa kódom 1 pre chyby účtovníctva a nemá možnosť --allow-errors. Dotazy, zoznamy a správy tiež odmietajú chyby načítania, pokiaľ explicitne neodovzdáte ich možnosť --allow-errors.

Formátovanie preberá súbor .bean/.beancount alebo adresár. Adresár sa prehľadáva rekurzívne.

Každý režim hlási chyby syntaxe podľa súboru a riadku, preskočí tieto súbory a ukončí sa kódom 1. Rekurzívny normálny beh môže stále naformátovať platné súbory. JSON hlási scanned, formatted, skipped, dry_run a check, pod error.result pri zlyhaní.

bea query "BQL" spúšťa Beancount dotazovací jazyk. Vynechanie BQL otvorí interaktívny shell; zatvorí ho exit alebo quit. Argument dotazu je v neinteraktívnom režime povinný. Predvolená tabuľka BQL má jeden riadok na zúčtovanie. Tabuľky dotazov zachovávajú presnosť. Prázdne výsledky vytlačia (no rows) na stderr; JSON vráti prázdne data.rows a metadáta stĺpcov v data.columns.

Finančné správy​

Všetky správy akceptujú --conversion / -x, --time / -t, --account / -a a --allow-errors. Všetky okrem skúšobnej súvahy tiež akceptujú --interval / -i: predvolene monthly, alebo quarterly, yearly, weekly, daily.

Časové filtre zahŕňajú rok, mesiac, dátum, štvrťrok, týždeň alebo rozsah, ako 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 alebo "2026-01 - 2026-08". Relatívne obdobia zahŕňajú year, quarter, month, week, day a odchýlky ako month-1. Filtre účtov zachovávajú každé zúčtovanie zodpovedajúcej transakcie.

Konverzia predvolene používa jedinú prevádzkovú menu účtovníctva. Inak je predvolená units, pričom meny sú oddelené. at_cost používa obstarávacie náklady. at_value používa trhové hodnoty s náhradou nákladov.

Konverzia na explicitnú menu potrebuje ceny v deň alebo pred každým dátumom ocenenia, vrátane dátumov intervalov. Chyba chýbajúcej ceny pomenuje skutočnú medzeru, ako No EUR → USD price on or before 2026-01-31. Neskoršia kotácia nemôže vyplniť skoršiu medzeru. Pridajte historicky vhodnú cenu, použite --conversion units alebo vyberte --allow-errors na kontrolu čiastočných hodnôt.

Čiastočné správy zachovávajú zdrojové meny a označujú kombinované súčty ako nedostupné. JSON zahŕňa valuation: "partial", missing_prices a missing_price_dates. Ovplyvnené súčty čistého zisku/čistého imania sú null v požadovanej mene.

Príjmy, pasíva a vlastné imanie bežne používajú záporné znamienka Beancount. Čistý zisk je -(income + expenses), kladný pre zisk. Rovnaká konvencia sa vzťahuje na riadky období výkazu ziskov a strát. Odsúhlasenie súvahy je odvodené pre správu; nezapisuje žiadne direktívy. equity_reconciled identifikuje, či je k dispozícii úplné odsúhlasenie.

JSON správy tiež identifikuje obdobie, výhradný dátum konca, dátum k, konverziu, filter účtov a stav validácie účtovníctva. Skontrolujte tieto polia pred porovnaním súčtov.

Voliteľná AI asistencia​

bea ask vyžaduje extra ask a prihlasovacie údaje Beancount.io z bea cloud login alebo BEA_TOKEN. Predvolená inštalácia Homebrew vynecháva AI závislosti. Používatelia Homebrew môžu spustiť:

bea cloud login
uvx --from 'beancount-io[ask]' bea ask "What did I spend last month?" --print

Pre inštaláciu uv nainštalujte beancount-io[ask] a spustite bea ask priamo. --print / -p odpovie raz a ukončí sa. Inak je terminálová relácia interaktívna a voliteľná otázka predvyplní jej vstup. Neinteraktívne použitie vyžaduje otázku. Režim JSON nie je podporovaný.

Dotazy sa spúšťajú lokálne. Otázky, kontext zručností a výsledky nástrojov idú do hostovanej AI služby Beancount.io. Interaktívne zápisy sú náhľadové, potvrdené, overené a zapísané atómovo. Akceptujú --into. Globálny --yes neudeľuje AI oprávnenie na zápis. Režim jednej odpovede nepoužíva navrhované zápisy.

Ask číta NAME/SKILL.md z .agents/skills/ v pracovnom adresári a z skills/ v adresári používateľskej konfigurácie. Projektové definície vyhrávajú podľa názvu. Každý súbor potrebuje polia YAML name a description. Úplné inštrukcie sa načítavajú na požiadanie.

Hostované účtovníctva​

Vytvorenie tiež akceptuje --clone a --dir. Na klonovanie sa vyžaduje Git a SSH prístup. Ak klonovanie zlyhá po vytvorení, hostované účtovníctvo stále existuje. Lokálne príkazy nenahrávajú vaše účtovníctvo automaticky. Neexistuje žiadna globálna možnosť --ledger.

JSON a výstupné kódy​

Globálny --json vkladá úspešné výsledky na stdout:

{
  "bea": "0.1.0",
  "target": { "file": "/home/alice/my-books/main.bean" },
  "data": [],
  "truncated": false,
  "limit": 50
}

bea je nainštalovaná verzia; data závisí od príkazu. Ciele identifikujú súbor, adresár, server alebo žiadny cieľ. Zahrnuté zápisy tiež identifikujú into. Desatinné sumy a dátumy používajú reťazce. Obmedzené zoznamy zahŕňajú limit a truncated.

Zlyhania zapisujú {"error":{"category":"validation","message":"…","exit_code":1}} na stderr. Chyba môže tiež zahŕňať details, result, backend request_id a traceback s --debug.

Skontrolujte error.result pred opakovaním mutácie. Čiastočná dávka môže zapísať prijaté riadky, rekurzívne formátovanie môže zmeniť platné súbory a vytvorenie-a-klonovanie môže vytvoriť hostované účtovníctvo pred ukončením s nenulovým kódom.

Výzvy CLI sú deaktivované pomocou --no-input, režimu JSON, ne-terminálového stdin alebo pravdivého CI. Cloudové vymazanie stále vyžaduje explicitné --yes. Importy vyžadujú explicitné rozhodnutie o duplicite, keď zhody vyžadujú kontrolu.

Výnimky výstupu: Ask odmieta JSON; cloudové prihlásenie vyžaduje interakciu; úspešné cloudové odhlásenie a klonovanie nevracajú žiadny JSON objekt úspechu. Pomoc, verzia a doplnenie si zachovávajú textový výstup. upgrade môže streamovať výstup svojho správcu balíkov na stderr, dokonca aj v režime JSON.

Nastavenia, aktualizácie a uložený stav​

Pravdivé hodnoty sú 1, true, yes a on, pričom sa ignoruje veľkosť písmen a okolité medzery. Stav konfigurácie zahŕňa prihlasovacie údaje, históriu výziev Ask, používateľské zručnosti, zapamätané cesty importéra a vyrovnávacie pamäte kontroly aktualizácií. Zámky zápisu sú pod locks/ v adresári vyrovnávacej pamäte, mimo vášho účtovníctva.

bea upgrade --check hlási verzie a spôsob inštalácie bez inovácie. bea upgrade vyvolá brew upgrade bea, uv tool upgrade beancount-io alebo pipx upgrade beancount-io. Editable inštalácie dostávajú manuálne pokyny na aktualizáciu. Pasívne kontroly bežia najviac raz denne v interaktívnych nainštalovaných kópiách; explicitné upgrade --check stále beží, keď je pasívny notifikátor deaktivovaný.

Odinštalujte pomocou zodpovedajúceho správcu: brew uninstall bea, uv tool uninstall beancount-io alebo pipx uninstall beancount-io. Vaše účtovnícke súbory a používateľská konfigurácia zostávajú.

Bežné opravy​

Použite bea COMMAND --help na kontrolu vašej nainštalovanej verzie. Referencia zdrojového úložiska obsahuje ďalšie príklady a presné definície modelu direktív.