Referencia CLI Beancount

Použite túto referenciu na vyhľadávanie príkazov bea a ich správania. Pre váš prvý predsedaňový register postupujte podľa Rýchly štart CLI. Na dokončenie celého mesiaca krok za krokom využite Váš prvý mesiac s bea. Pre bankové súbory použite návod na import.

Príkazy prehľadne​

Globálne možnosti a cesty​

Globálne možnosti idú pred príkaz:

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

init vytvára vlastný adresár/súborový cieľ a ignoruje BEA_FILE. Namiesto argumentu adresára akceptuje globálny --file. format používa svoj vlastný pozíciový cieľ. Zadajte názov súboru alebo adresára. Globálny --file nevyberá cieľ formátovania.

Vytvoriť hlavný účet​

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

Šablóna otvára 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 a Equity:OpeningBalances.

Počiatočné stavy sa kompenzujú voči Equity:OpeningBalances. Dlhy sú záporné. Zadávanie meny je veľkými písmenami. Vlastné symboly sú povolené; symbol, ktorý nie je tri veľké písmená, spustí upozornenie na preklep. Toto nie je kontrola ISO registra mien.

Existujúce súbory sa nikdy neprepíšu. Nové súbory používajú oprávnenia iba pre vlastníka, režim 0600 na POSIX. Neskoršie zápisy add a import zachovávajú oprávnenia a rešpektujú cieľové súbory iba na čítanie. Formátovanie na mieste používa natívny formátovač a hlási vlastné chyby systému súborov.

Pridať transakcie​

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'

Jeden zápis môže vynechať svoju sumu. Číslované zápisy môžu vynechať menu, ak účet má povolenú iba jednu menu alebo ak kniha má kompatibilnú prevádzkovú menu. Inak uveďte symbol meny.

Nativná syntax zápisov podporuje aritmetiku ako 84/2 EUR, náklady ako {100 USD}, celkové náklady {{1000 USD}} a ceny @ alebo @@. Používajte desatinné sumy typu 1000, nie exponentovú notáciu typu 1e3.

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

Metadata prijímajú holé reťazce ako --meta 'receipt:IMG_42.jpg'. Nativné čísla, boolovské hodnoty, 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 nútia reťazec: --meta 'code:"1234"'. Kľúče musia byť odlišné; filename a lineno sú vyhradené.

Jednotlivé prírastky, hromadné prírastky a importy nahrádzajú zalomenia riadkov v platiteľoch, popisoch a reťazcových metadátach medzerami. Úvodzovky a spätné lomky zachovávajú svoj obsah.

Pridajte ďalšie smernice​

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

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

Zostatok kontroluje účet na začiatku jeho dátumu. Podporuje syntax tolerancie, napríklad --amount "1538 ~ 1 EUR". Tolerancia musí byť nezáporná.

Použite add balance --pad-from Equity:OpeningBalances na zapísanie záporného riadku a jeho potvrdenia zostatku naraz. Predvolený záporný riadok je pre predchádzajúci deň; --pad-date môže vybrať iný skorší deň. Obe účty musia byť aktívne. Samostatný záporný riadok potrebuje neskorší zostatok na jeho spotrebu. --allow-errors môže pripraviť tento medzistav, ale nemôže obísť neplatný záporný účet.

add price preskočí presnú duplicitnú kombináciu dátumu/komodity/ceny cez koreň a jeho zahrnutia. Ukončí sa s návratovou hodnotou 0 a identifikuje existujúce miesto. Rôzne dátumy alebo ceny sú nové príspevky.

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

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

Hromadný JSON vstup​

bea add transactions --from transactions.json prijíma 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. Nepovinné polia sú flag, payee, narration, tags, links a meta.

Záznam používa buď amount alebo units, napríklad {"number":"45.00","currency":"USD"}. Obe vypustite pre vyrovnávací záznam. Polia záznamu tiež zahŕňajú cost, price, flag a meta. Náklady obsahujú number a currency, s nepovinnými date a label. Ceny obsahujú number a currency.

Pre desatinné čísla používajte reťazce. Metadata používajú obyčajné reťazce a boolean hodnoty alebo označené hodnoty ako {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} a {"kind":"amount","number":"2.50","currency":"USD"}. Nepovinné source umiestnenie transakcie sa nikdy nepíše ako metadata.

Predvolené je atomická dávka: akýkoľvek zamietnutý riadok nechá účet nezmenený a skončí s kódom 1. --partial zapíše platnú podmnožinu a stále skončí 1, ak sú zamietnuté nejaké riadky. Chyby JSON popisujú výsledok v error.result; indexy riadkov tam sú nulou začínajúce. Ľudské čísla riadkov sú začínajúce jedničkou.

Hromadné pridávanie akceptuje --into a --allow-errors. Neredukuje duplicitné. Použite bea import pre kontrolu bankového exportu.

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

Držte --file nasmerovaný 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 vzťahový ku koreňovému adresáru. Musí byť už zahrnutý; pomenovanie nesúvisiaceho súboru sa odmieta. Príkazy pridávania, importy a interaktívne AI zápisy podporujú toto rozdelenie.

Zápisy overujú celý kandidátsky účet, vrátane pluginov a záznamen nákladových lotov. Súbežná zmena koreňa alebo jeho grafu zahrnutia končí 4. Cieľ iba na čítanie končí 3. Úspešné prírastky zarovnávajú len nové riadky. Existujúce bajty zostávajú nezmenené. Použite bea format -i PATH, keď chcete znovu zarovnať celý súbor.

Zoznam 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. Transakčná tabuľka filtrovaná podľa účtu označuje svoj stĺpec s čiastkou ako MATCHING POSTING AMOUNTS. Detaily aj JSON stále obsahujú všetky zápisy každej vybranej transakcie. Detaily zobrazujú načítané záznamy vrátane odvodených čiastok; nie sú to surové ukážky zo zdroja.

Skontrolujte, naformátujte a dopytujte​

bea check overuje root a includes. Pri úspechu ukončí s 0 potichu a pri chybách v účtovníku 1. Globálny --json vracia overovací obal. Pre check neexistuje žiadna možnosť --allow-errors.

Dopyty, zoznamy a reporty varujú a vracajú čiastočné výsledky v interaktívnom termináli. Globálne --strict, --json, --no-input, pravdivý CI alebo nenástupový stdin zabezpečia prísne čítanie. Ich možnosť --allow-errors explicitne povoľuje čiastočné výsledky.

Formátovanie akceptuje súbory alebo rekurzívne vyhľadáva adresár. V zverejnenom balíku 0.2.0 je cesta povinná napriek predvolenej hodnote stdin zobrazená v nápovedách. Globálny --file nevyberá cieľ formátovania.

Formátovanie zarovnáva text; nevaliduje syntax ledgeru ani účtovníctvo. Spustite bea check samostatne. S globálnym --json vyberte -i, -o FILE, --check alebo --dry-run, aby stdout mohol niesť konverz. Nepresmerovávajte stdout cez vstupný súbor: použite -i na jeho prepísanie.

bea query "BQL" spúšťa Beancount query. Vynechanie BQL číta dotazy zo stdin alebo otvorí shell, keď je stdin terminál. Použite .exit, exit alebo quit na uzavretie shellu. Predvolená tabuľka BQL má jeden riadok na položku. Dotazové tabuľky si zachovávajú presnosť.

Vyberte ledger pred príkazom, napríklad bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". Globálny --json používa produktový konverz s data.rows a data.columns; je odlišný od rendering CSV. V zverejnenom vydaní 0.2.0 používajte shell redirekciu na uloženie JSON, ako bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: dotazy -o a -m sa na JSON v tomto vydaní nevzťahujú.

Natívne nástroje a voliteľné funkcie​

bea doctor context main.bean 42 zobrazuje kontext transakcie na riadku 42. bea doctor --help vymenúva ďalšie diagnostické príkazy. bea example -o example.bean vytvára ukážkovú históriu. bea treeify accounts.txt vykresľuje hierarchické mená zo súboru s textom; vynechajte súbor, aby sa čítalo zo stdin. Tieto príkazy posielajú nativne argumenty ďalej. Príklady vyššie tieto argumenty explicitne pomenúvajú.

Voliteľné nástroje povolíte raz s bea engine enable beanprice pre načítanie kurzov alebo bea engine enable beangulp pre importné workflow. Povolenie vyžaduje sieťový prístup; Beangulp tiež potrebuje systémovú knižnicu libmagic. Na kontrolu dostupnosti použite bea engine status. bea price --help a bea ingest --help popisujú svoje rozhrania. bea import --csv a bea add price nevyžadujú žiadnu z týchto voliteľných funkcií.

Spravované vložené súbory s kurzami​

Live Prices predstavuje samostatný postup pre spravované vložené súbory. Hostované účtovné denníky načítavajú podporované URL s kurzami; kompatibilné verzie bea podporujú aj spravované vložené súbory a lokálny export kurzov. Ak nainštalovaná verzia tieto príkazy nerozpoznáva, pozrite si príručku spravovaných kurzov pre príslušnú verziu.

CLI načítava spravované URL zo zoznamu povolených adries bez odosielania prihlasovacích údajov a odmieta presmerovania. Kanál, ktorý presmeruje na prihlásenie hostovanej služby, je preto pri novom lokálnom načítaní nedostupný; prihlásenie na webovej stránke neoverí požiadavku CLI na kurzy. Chyby zdrojov skontrolujte cez price status. Podľa potreby použite údaje z vyrovnávacej pamäte, dostupný podporovaný kanál alebo lokálne kurzy s dátumom.

price export zapisuje súbory kanálov do prices/ a prepisuje vložené odkazy na lokálne relatívne cesty. Pôvodné nástroje Beancount, Fava a Beanquery dokážu túto exportovanú kópiu načítať. Nedostupný zdroj znemožní export, pokiaľ nepoužijete --allow-errors; pri tejto voľbe môže jeho značka zdroja zostať bez kurzov.

Váš vlastný kurz s dátumom má prednosť pred spravovaným kurzom pre rovnaký dátum a pár. Záznamy kanálov sú iba na čítanie. Pri neúspešnej obnove sa zachová predtým overená revízia, ktorá môže byť zastaraná. Ostatné argumenty príkazu bea price sa naďalej odovzdávajú nástroju Beanprice; ak sa súbor s úlohou na získanie kurzov volá status, zadajte ./status, aby sa odlíšil od podpríkazu.

Homebrew inštaluje CLI aj jeho spravovaný engine. S PyPI prvý príkaz podporovaný enginom stiahne pevne stanovené závislosti; nechajte uv zapnutý v PATH a povolte sieťový prístup pri prvom spustení. Neskoršie lokálne príkazy engine používajú offline. Zákazníci inštalujú iba beancount-io, bez samostatného balíka Beancount alebo natívnych konzolových skriptov na správu.

Finančné výkazy​

Všetky výkazy akceptujú --conversion / -x, --time / -t, --account / -a a --allow-errors. Všetky okrem skúšobného zostatku tiež akceptujú --interval / -i: štandardne monthly, alebo quarterly, yearly, weekly či daily.

bea balance [ACCOUNT...] vypisuje podstromy zostatkov pre účty, ktorých názvy obsahujú nezávislé na veľkosti písmen podreťazce, alebo celý hlavný knihu, ak žiadne nenazvete. Akceptuje --conversion / -x, --time / -t a --allow-errors, a neakceptuje intervalové alebo účtovné voľby.

Časové filtre zahŕňajú rok, mesiac, dátum, štvrťrok, týždeň alebo rozsah, napríklad 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 posuny ako month-1. Filtre účtov uchovávajú každé zaúčtovanie zodpovedajúcej transakcie.

Konverzia predvolene používa jedinú prevádzkovú menu účtovnej knihy. Inak predvolene používa units, pričom komodity zostávajú oddelené. at_cost používa obstarávacie náklady. at_value používa trhové hodnoty s náhradou nákladmi.

Explicitná konverzia meny vyžaduje ceny na alebo pred každým dátumom ocenenia, vrátane intervalových dátumov. Chyba chýbajúcej ceny označuje skutočnú medzeru, napríklad No EUR → USD price on or before 2026-01-31. Neskorší kurz nemôže vyplniť skoršiu medzeru. Pridajte historicky vhodnú cenu, použite --conversion units alebo zvoľte --allow-errors na kontrolu čiastkových hodnôt.

Čiastočné správy zachovávajú zdrojové meny a označujú kombinované sumy ako nedostupné. JSON obsahuje valuation: "partial", missing_prices a missing_price_dates. Dotknuté čisté zisky/neto hodnota sú null v požadovanej mene.

Príjmy, záväzky a vlastné imanie zvyčajne používajú záporné znamienka Beancountu. Čistý zisk je -(income + expenses), kladný pri zisku. Rovnaký konvencia platí pre riadky výkazu ziskov a strát za obdobie. Zúčtovanie súvahy sa odvádza pre správu; nezapisuje žiadne pokyny. equity_reconciled určuje, či je k dispozícii kompletné zúčtovanie.

Report JSON tiež identifikuje obdobie, exkluzívny koncový dátum, dátum k, konverziu, filter účtu a stav validácie účtovnej knihy. Skontrolujte tieto polia pred porovnaním súčtov.

Voliteľná AI asistencia​

bea ask vyžaduje ako ask extra, tak ú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ý.

Dopyty 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ú predbežne zobrazené, potvrdené, overené a zápisované atomicky. Akceptujú --into. Globálne --yes nedáva povolenie na AI zápis. Režim jednej odpovede neaplikuje navrhované zápisy.

Ask číta NAME/SKILL.md z .agents/skills/ v pracovnom adresári a z skills/ v používateľskom konfiguračnom adresári. Definície projektov vyhrávajú podľa mena. Každý súbor potrebuje YAML polia name a description. Kompletné inštrukcie sa načítavajú na požiadanie. Pre rozloženie súboru a spracovaný príklad pozri Rozšírenie bea ask o schopnosti.

Hosťované účtovné knihy​

S globálnymi --json, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create a bea cloud ledger delete sa vydáva štandardná obálka. Prihlásenie vyžaduje interakciu; úspešné odhlásenie a klonovanie nevracajú JSON objekt úspechu.

Vytvorenie tiež akceptuje --clone a --dir. Na klonovanie je potrebný prístup Git a SSH. Ak klonovanie po vytvorení zlyhá, hosťovaná účtovná kniha stále existuje. Lokálne príkazy automaticky nenahrávajú vašu účtovnú knihu. Neexistuje globálna možnosť --ledger.

JSON a výstupné kódy​

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

{
  "bea": "0.2.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 bez cieľa. Vložné zápisy tiež identifikujú into. Desatinné sumy a dátumy používajú reťazce. Obmedzené zoznamy zahŕňajú limit a truncated.

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

Skontrolujte error.result pred opätovným pokusom o mutáciu. Č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ť hosťovanú účtovnú knihu pred východom s nenulovým stavom. Pre skript, ktorý číta tento obal s jq a vetví sa podľa týchto kódov, pozrite si Automatizovať účtovníctvo s bea.

Výzvy CLI sú deaktivované --no-input, režimom JSON, ne-terminálovým stdin alebo pravdivým CI. Vymazanie v cloude stále vyžaduje explicitné --yes. Importy potrebujú explicitné rozhodnutie o duplikáte, keď sú zhody potrebné na preskúmanie.

Výstupné výnimky: doctor, example, treeify, volania price preposlané nástroju Beanprice a ingest zachovávajú natívny výstup a stav ukončenia, aj pri globálnom --json; vyššie uvedené kategórie obalu a ukončenia nepopisujú tieto preposlané výsledky. Ask odmieta JSON; prihlásenie do cloudu vyžaduje interakciu; úspešné odhlásenie a klonovanie z cloudu nevracia JSON objekt úspechu. Help, version a completion si zachovávajú textový výstup. upgrade môže streamovať výstup svojho správcu balíkov na stderr, vrátane režimu JSON.

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

Pravdivé hodnoty sú 1, true, yes a on, bez ohľadu na veľkosť písmen a obalujúce medzery. Stav konfigurácie zahrňuje poverenia, históriu výziev Ask, používateľské zručnosti, zapamätané cesty importéra a cache kontrol aktualizácií. Zámky zápisu sa nachádzajú pod cache adresárom locks/ mimo vášho adresára denníka.

bea upgrade --check zobrazuje verzie a spôsob inštalácie bez aktualizácie. bea upgrade vyvolá brew upgrade bea, uv tool upgrade beancount-io alebo pipx upgrade beancount-io. Editovateľné inštalácie dostávajú manuálne usmernenia na aktualizáciu. Pasívne kontroly bežia najviac raz denne v interaktívnych inštalovaných kópiách; explicitné upgrade --check sa stále spúšťa, keď je pasívne upozornenie vypnuté.

Odstráňte inštaláciu pomocou príslušného správcu: brew uninstall bea, uv tool uninstall beancount-io alebo pipx uninstall beancount-io. Vaše súbory denníka a používateľská konfigurácia zostávajú nezmenené.

Bežné opravy​

Použite bea COMMAND --help na kontrolu nainštalovanej verzie. Zdrojové úložisko obsahuje ďalšie príklady a presné definície modelu direktív.