Referència de la CLI de Beancount

Utilitzeu aquesta referència per consultar les ordres bea i el seu comportament. Per al vostre primer llibre de comptes, seguiu la guia d'inici ràpid de la CLI. Per a fitxers bancaris, utilitzeu el tutorial d'importació.

Ordres d'un cop d'ull​

Opcions globals i camins​

Les opcions globals van abans de l'ordre:

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

init crea el seu propi directori/fitxer objectiu i ignora BEA_FILE. Accepta --file global en lloc del seu argument de directori. format utilitza el seu propi objectiu posicional, amb el directori de treball com a valor per defecte. --file global no selecciona l'objectiu de formatatge.

Crear un llibre de comptes​

bea init [DIRECTORY] utilitza el directori actual per defecte. Un directori crea main.bean; un camí .bean o .beancount anomena el nou fitxer directament.

La plantilla obre Assets:Checking, Assets:Savings, Assets:Cash, Liabilities:CreditCard, Income:Salary, Income:Interest, Expenses:Groceries, Expenses:Dining, Expenses:Rent, Expenses:Transport, Expenses:Utilities, Expenses:Fees i Equity:OpeningBalances.

Els saldos inicials es compensen amb Equity:OpeningBalances. El deute és negatiu. L'entrada de moneda es converteix en majúscules. Es permeten símbols personalitzats; un símbol que no siguin tres lletres majúscules activa un avís d'errata. Això no és una comprovació del registre de monedes ISO.

Els fitxers existents no se sobreescriuen mai. Els fitxers nous utilitzen permisos només del propietari, mode 0600 a POSIX. Les escriptures posteriors d'add, import i format conserven els permisos i respecten les destinacions de només lectura.

Afegir transaccions​

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'

Un apuntament pot ometre el seu import. Els apuntaments numerats poden ometre la moneda quan un compte té una moneda permesa o el llibre té una moneda operativa compatible. En cas contrari, proporcioneu el símbol.

La sintaxi nativa d'apuntaments admet aritmètica com ara 84/2 EUR, costos com {100 USD}, costos totals {{1000 USD}} i preus @ o @@. Utilitzeu imports decimals com 1000, no notació exponencial com 1e3.

Un intercanvi de moneda necessita la seva taxa de transacció real. Per exemple, apunteu 100 EUR @ 1.08 USD a un compte obert en EUR i -108 USD al compte corrent. Una compra d'inversió pot apuntar 2 AAPL {100 USD} a un compte obert en AAPL i -200 USD al compte corrent. Afegiu cotitzacions de price datades quan els informes necessiten valoració de mercat.

Les metadades accepten cadenes simples com --meta 'receipt:IMG_42.jpg'. Els números natius, booleans, dates i imports conserven els seus tipus. Els exemples inclouen --meta 'reviewed:TRUE', --meta 'received:2026-08-03' i --meta 'fee:2.50 USD'. Les cometes interiors forcen una cadena: --meta 'code:"1234"'. Les claus han de ser distintes; filename i lineno estan reservades.

Les altes individuals, les altes en massa i les importacions substitueixen els salts de línia en payees, narracions i metadades de cadena per espais. Les cometes i les barres invertides conserven el seu contingut.

Afegir altres directius​

Totes aquestes ordres requereixen --date YYYY-MM-DD. També accepten --into FILE i --allow-errors.

Els noms de compte tenen una arrel en majúscula i segments separats per dos punts. Cada subcompte comença amb una lletra majúscula o un dígit. Beancount admet lletres Unicode i noms d'arrel configurats.

Un balanç comprova el compte a l'inici de la seva data. Es admet la sintaxi de tolerància, com ara --amount "1538 ~ 1 EUR". La tolerància ha de ser no negativa.

Utilitzeu add balance --pad-from Equity:OpeningBalances per escriure un pad i la seva asserció de balanç junts. El pad utilitza per defecte el dia anterior; --pad-date pot seleccionar un altre dia anterior. Ambdós comptes han d'estar actius. Un pad aïllat necessita un balanç posterior per consumir-lo. --allow-errors pot preparar aquest estat intermedi, però no pot evitar un compte de pad no vàlid.

add price omet un duplicat exacte de data/mercaderia/preu a través de l'arrel i les seves incloses. Surt amb 0 i identifica la ubicació existent. Dates o preus diferents són altes noves.

Els camins dels documents es resolen al costat del fitxer que conté la directiva. Amb --into years/2026.bean, --filename receipt.pdf significa years/receipt.pdf, no un fitxer al costat del directori de treball del vostre shell.

Els tipus de valor personalitzats són text, number, amount, account, bool i date. Per exemple, un pressupost pot utilitzar --value "text:travel" --value "amount:500 USD".

Entrada JSON en massa​

bea add transactions --from transactions.json accepta una matriu JSON:

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

Cada transacció requereix date i postings. Els camps opcionals són flag, payee, narration, tags, links i meta.

Un apuntament utilitza amount o units, com {"number":"45.00","currency":"USD"}. Ometeu-los tots dos per a l'apuntament equilibrant. Els camps d'apuntament també inclouen cost, price, flag i meta. Els costos contenen number i currency, amb date i label opcionals. Els preus contenen number i currency.

Utilitzeu cadenes per als decimals. Les metadades utilitzen cadenes i booleans ordinaris, o valors etiquetats com {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} i {"kind":"amount","number":"2.50","currency":"USD"}. La ubicació source opcional de la transacció no s'escriu mai com a metadada.

El comportament per defecte és un lot atòmic: qualsevol fila rebutjada deixa el llibre de comptes sense canvis i surt amb 1. --partial escriu un subconjunt vàlid i encara surt amb 1 si es rebutgen files. Els errors JSON descriuen el resultat a error.result; els índexos de fila allà són basats en zero. Els números de fila humans són basats en un.

L'addició en massa accepta --into i --allow-errors. No deduplica. Utilitzeu bea import per a la revisió d'exportacions bancàries.

Llibres de comptes dividits i seguretat d'escriptura​

Mantingueu --file apuntant a l'arrel. Afegiu --into per seleccionar un fitxer inclòs existent:

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

La destinació és relativa al directori arrel. Ja ha d'estar inclosa; anomenar un fitxer no relacionat es rebutja. Les ordres d'addició, importacions i escriptures interactives de la IA admeten aquesta separació.

Les escriptures validen el llibre de comptes candidat complet, incloent-hi connectors i reserva de lots de costos. Un canvi concurrent a l'arrel o al seu gràfic d'inclusió surt amb 4. Una destinació de només lectura surt amb 3. Les addicions correctes utilitzen el mateix alineament que bea format, que pot realinear columnes existents en aquella destinació.

Llistar directius​

bea list TYPE admet els onze tipus: transaction, open, close, balance, pad, note, event, price, commodity, document i custom.

Altres tipus de directius conserven l'ordre cronològic. Una taula de transaccions filtrada per compte etiqueta la seva columna d'imports com a MATCHING POSTING AMOUNTS. Els detalls i el JSON encara inclouen tots els apuntaments de cada transacció seleccionada. Els detalls renderitzen les entrades carregades, incloent-hi els imports inferits; no són extractes bruts de la font.

Comprovar, formatar i consultar​

bea check valida l'arrel i les incloses. Surt amb 1 per errors del llibre de comptes i no té opció --allow-errors. Les consultes, llistes i informes també rebutgen errors del carregador tret que passeu explícitament la seva opció --allow-errors.

El formatatge pren un fitxer .bean/.beancount o un directori. Un directori es cerca recursivament.

Cada mode informa errors de sintaxi per fitxer i línia, omet aquests fitxers i surt amb 1. Una execució normal recursiva encara pot formatar els fitxers vàlids. El JSON informa de scanned, formatted, skipped, dry_run i check, sota error.result en cas de fallada.

bea query "BQL" executa una consulta Beancount. Ometre BQL obre un shell interactiu; exit o quit el tanquen. Un argument de consulta és requerit sense supervisió. La taula per defecte de BQL té una fila per apuntament. Les taules de consulta conserven la precisió. Els resultats buits imprimeixen (no rows) a stderr; el JSON retorna un data.rows buit i metadades de columnes a data.columns.

Informes financers​

Tots els informes accepten --conversion / -x, --time / -t, --account / -a i --allow-errors. Tots excepte el balanç de comprovació també accepten --interval / -i: monthly per defecte, o quarterly, yearly, weekly o daily.

Els filtres de temps inclouen un any, mes, data, trimestre, setmana o rang, com 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 o "2026-01 - 2026-08". Els períodes relatius inclouen year, quarter, month, week, day i desplaçaments com month-1. Els filtres de compte conserven tots els apuntaments d'una transacció que coincideix.

La conversió utilitza per defecte la moneda operativa única del llibre. En cas contrari, utilitza per defecte units, mantenint les mercaderies separades. at_cost utilitza els costos d'adquisició. at_value utilitza els valors de mercat amb una alternativa de cost.

Una conversió de moneda explícita necessita preus el dia o abans de cada data de valoració, incloent-hi les dates d'interval. Un error de preu absent nomena el buit real, com No EUR → USD price on or before 2026-01-31. Una cotització posterior no pot omplir un buit anterior. Afegiu un preu històricament apropiat, utilitzeu --conversion units o trieu --allow-errors per inspeccionar valors parcials.

Els informes parcials conserven les monedes d'origen i marquen els totals combinats com a no disponibles. El JSON inclou valuation: "partial", missing_prices i missing_price_dates. Els totals afectats de benefici net/patrimoni net són null en la moneda sol·licitada.

Els ingressos, passius i patrimoni normalment utilitzen signes negatius de Beancount. El benefici net és -(income + expenses), positiu per a un guany. La mateixa convenció s'aplica a les files de període de l'estat de resultats. La conciliació del balanç de situació es deriva per a l'informe; no escriu cap directiva. equity_reconciled identifica si hi ha disponible una conciliació completa.

El JSON de l'informe també identifica el període, la data final exclusiva, la data a què es refereix, la conversió, el filtre de compte i l'estat de validació del llibre. Comproveu aquests camps abans de comparar totals.

Assistència d'IA opcional​

bea ask necessita tant l'extra ask com les credencials de Beancount.io de bea cloud login o BEA_TOKEN. La instal·lació per defecte de Homebrew omet les dependències d'IA. Els usuaris de Homebrew poden executar:

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

Per a una instal·lació uv, instal·leu beancount-io[ask] i executeu bea ask directament. --print / -p respon una vegada i surt. En cas contrari, una sessió de terminal és interactiva, i una pregunta opcional preomple la seva entrada. L'ús no interactiu requereix una pregunta. El mode JSON no és compatible.

Les consultes s'executen localment. Les preguntes, el context d'habilitats i els resultats d'eines van al servei d'IA allotjat de Beancount.io. Les escriptures interactives es previsualitzen, confirmen, validen i s'escriuen atòmicament. Accepten --into. El --yes global no concedeix permís d'escriptura a la IA. El mode de resposta única no aplica escriptures proposades.

Ask llegeix NAME/SKILL.md de .agents/skills/ al directori de treball i de skills/ al directori de configuració de l'usuari. Les definicions de projecte guanyen per nom. Cada fitxer necessita camps YAML name i description. Les instruccions completes es carreguen sota demanda.

Llibres de comptes allotjats​

La creació també accepta --clone i --dir. L'accés a Git i SSH és necessari per clonar. Si el clonatge falla després de la creació, el llibre de comptes allotjat encara existeix. Les ordres locals no pugen el vostre llibre de comptes automàticament. No hi ha cap opció global --ledger.

JSON i codis de sortida​

El --json global posa els resultats correctes a stdout:

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

bea és la versió instal·lada; data depèn de l'ordre. Els objectius identifiquen un fitxer, directori, servidor o cap objectiu. Les escriptures incloses també identifiquen into. Els imports decimals i les dates utilitzen cadenes. Les llistes limitades inclouen limit i truncated.

Les fallades escriuen {"error":{"category":"validation","message":"…","exit_code":1}} a stderr. L'error també pot incloure details, result, un request_id del backend i un traceback amb --debug.

Comproveu error.result abans de reintentar una mutació. Un lot parcial pot escriure files acceptades, el formatatge recursiu pot canviar fitxers vàlids i crear-i-clonar pot crear un llibre de comptes allotjat abans de sortir amb un codi no zero.

Les indicacions de la CLI es desactiven amb --no-input, el mode JSON, stdin no terminal o CI vertader. L'eliminació al núvol encara necessita --yes explícit. Les importacions necessiten una decisió de duplicat explícita quan les coincidències necessiten revisió.

Excepcions de sortida: Ask rebutja el JSON; l'inici de sessió al núvol necessita interacció; el tancament de sessió i el clonatge correctes al núvol no retornen cap objecte d'èxit JSON. L'ajuda, la versió i la compleció conserven la sortida de text. upgrade pot transmetre la sortida del seu gestor de paquets a stderr, incloent-hi en mode JSON.

Configuració, actualitzacions i estat emmagatzemat​

Els valors vertaders són 1, true, yes i on, ignorant majúscules i espais circumdants. L'estat de configuració inclou credencials, historial de preguntes d'Ask, habilitats d'usuari, camins d'importadors recordats i memòries cau de comprovació d'actualitzacions. Els bloquejos d'escriptura viuen sota locks/ del directori de memòria cau, fora del vostre directori de llibre de comptes.

bea upgrade --check informa de versions i del mètode d'instal·lació sense actualitzar. bea upgrade invoca brew upgrade bea, uv tool upgrade beancount-io o pipx upgrade beancount-io. Les instal·lacions editables reben guia d'actualització manual. Les comprovacions passives s'executen com a màxim un cop al dia en còpies instal·lades interactives; upgrade --check explícit encara s'executa quan el notificador passiu està desactivat.

Desinstal·leu amb el gestor corresponent: brew uninstall bea, uv tool uninstall beancount-io o pipx uninstall beancount-io. Els vostres fitxers de llibre de comptes i configuració d'usuari romanen.

Correccions habituals​

Utilitzeu bea COMMAND --help per inspeccionar la vostra versió instal·lada. La referència del repositori font conté exemples addicionals i les definicions exactes del model de directius.