Referència de la CLI de Beancount

Utilitzeu aquesta referència per consultar les ordres de bea i el seu comportament. Per al vostre primer llibre, seguiu la guia ràpida de la CLI. Per tancar un mes sencer de principi a fi, consulteu El vostre primer mes amb bea. Per als fitxers bancaris, utilitzeu el tutorial d'importació.

Comandes d’un cop d’ull​

Opcions globals i rutes​

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 o fitxer de destinació i ignora BEA_FILE. Accepta l'opció global --file en lloc del seu argument de directori. format utilitza la seva pròpia destinació posicional. Proporcioneu un nom de fitxer o un directori. L'opció global --file no determina la destinació del formatatge.

Crear un llibre comptable​

bea init [DIRECTORY] per defecte utilitza el directori actual. Un directori crea main.bean; una ruta .bean o .beancount dóna nom directament al fitxer nou.

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, Expenses:Uncategorized i Equity:OpeningBalances.

Els saldos d'obertura es compensen contra Equity:OpeningBalances. El deute és negatiu. L'entrada de moneda es converteix a majúscules. Es permeten símbols personalitzats; un símbol que no sigui tres lletres majúscules genera un avís d'error tipogràfic. Aquesta no és una comprovació del registre de monedes ISO.

Els fitxers existents no se sobreescriuen mai. Els fitxers nous utilitzen permisos només per al propietari, mode 0600 a POSIX. Les escriptures posteriors d'addició i importació conserven els permisos i respecten les destinacions de només lectura. El formatatge in situ utilitza el formatador natiu i informa dels seus propis errors del sistema de fitxers.

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 apunt pot ometre el seu import. Els apunts numerats poden ometre la moneda quan un compte té una única moneda permesa o el llibre té una única moneda operativa compatible. En cas contrari, proporcioneu el símbol.

La sintaxi nativa d'apunts admet aritmètica com 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 el seu tipus de canvi real de la transacció. 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 price amb data quan els informes necessitin valoració de mercat.

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

Les addicions individuals, les addicions massives i les importacions substitueixen els salts de línia en beneficiaris, 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. S'admet la sintaxi de tolerància, com --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 afirmació de balanç alhora. El pad per defecte és el dia anterior; --pad-date pot seleccionar un altre dia anterior. Tots dos comptes han d'estar actius. Un pad independent 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/producte/preu a l'arrel i els seus fitxers inclosos. Surt amb codi 0 i identifica la ubicació existent. Dates o preus diferents són addicions noves.

Les rutes 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 de la vostra consola.

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 bloc​

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 apunt utilitza amount o units, com {"number":"45.00","currency":"USD"}. Ometeu tots dos per a l'apunt de compensació. Els camps d'apunt 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 metadades.

El valor per defecte és un lot atòmic: qualsevol fila rebutjada deixa el llibre sense canvis i surt amb codi 1. --partial escriu un subconjunt vàlid i encara surt amb codi 1 si es rebutja alguna fila. Els errors JSON descriuen el resultat a error.result; els índexs de fila allà són basats en zero. Els nombres de fila humans són basats en u.

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

Llibres majors dividits i seguretat de l'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; es rebutja nomenar un fitxer no relacionat. Les ordres d'addició, les importacions i les escriptures interactives de la IA admeten aquesta separació.

Les escriptures validen el llibre candidat complet, incloent-hi els connectors i la reserva de lots de cost. Un canvi concurrent a l'arrel o al seu graf d'inclusions surt amb codi 4. Una destinació de només lectura surt amb codi 3. Les addicions correctes alineen només les línies noves. Els bytes existents romanen sense canvis. Utilitzeu bea format -i PATH quan vulgueu realinear tot el fitxer.

Llista de directrius​

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

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

Comprovar, formatar i consultar​

bea check valida l'arrel i les inclusions. Surt amb codi 0 en silenci si té èxit i amb codi 1 per errors del llibre. L'opció global --json retorna l'embolcall de validació. No hi ha cap opció --allow-errors per a check.

Les consultes, llistes i informes avisen i retornen resultats parcials en un terminal interactiu. L'opció global --strict, --json, --no-input, una variable CI vertadera o una entrada estàndard no terminal fan que les lectures siguin estrictes. La seva opció --allow-errors permet explícitament resultats parcials.

El formatatge accepta fitxers o cerca recursivament en un directori. Al paquet publicat 0.2.0, es requereix una ruta malgrat el valor per defecte d'entrada estàndard que es mostra a l'ajuda. L'opció global --file no determina la destinació del formatatge.

El formatatge alinea el text; no valida la sintaxi del llibre ni la comptabilitat. Executeu bea check per separat. Amb l'opció global --json, seleccioneu -i, -o FILE, --check o --dry-run perquè la sortida estàndard pugui portar l'embolcall. No redirigiu la sortida estàndard sobre el fitxer d'entrada: utilitzeu -i per reescriure'l.

bea query "BQL" executa una consulta de Beancount. Ometre BQL llegeix les consultes de l'entrada estàndard o obre l'intèrpret quan l'entrada estàndard és un terminal. Utilitzeu .exit, exit o quit per tancar l'intèrpret. La taula per defecte de BQL té una fila per apunt. Les taules de consulta conserven la precisió.

Seleccioneu el llibre abans de l'ordre, per exemple bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". L'opció global --json utilitza l'embolcall del producte amb data.rows i data.columns; és diferent de la renderització CSV. A la versió publicada 0.2.0, utilitzeu la redirecció de la consola per desar JSON, com bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: les opcions -o i -m de query no s'apliquen a JSON en aquella versió.

Eines natives i funcionalitats opcionals​

bea doctor context main.bean 42 mostra el context de la transacció a la línia 42. bea doctor --help llista les altres ordres de diagnòstic. bea example -o example.bean crea un historial d'exemple. bea treeify accounts.txt renderitza noms jeràrquics a partir d'un fitxer de text; ometeu el fitxer per llegir l'entrada estàndard. Aquestes ordres reenvien arguments natius. Els exemples anteriors nomenen aquests arguments explícitament.

Habiliteu les eines opcionals una vegada amb bea engine enable beanprice per obtenir cotitzacions o bea engine enable beangulp per als fluxos de treball d'importadors. L'habilitació necessita accés a la xarxa; el Beangulp també necessita la biblioteca del sistema libmagic. Utilitzeu bea engine status per inspeccionar la disponibilitat. bea price --help i bea ingest --help descriuen les seves interfícies. bea import --csv i bea add price no necessiten cap de les dues funcions opcionals.

Inclusions de preus gestionades​

Live Prices és un flux de treball d'inclusió gestionada separat. Els llibres allotjats resolen els URL de preus admesos; les versions compatibles de bea també admeten inclusions gestionades i exportacions de preus locals. Consulteu la guia de preus gestionats específica de la versió si la vostra versió instal·lada no reconeix aquestes ordres.

La CLI resol els URL gestionats de la llista permesa sense enviar credencials i rebutja les redireccions. Per tant, un canal que redirigeix a un inici de sessió allotjat no està disponible per a una obtenció local nova; iniciar sessió al lloc web no autentica la petició de preus de la CLI. Inspeccioneu price status per als errors de les fonts. Utilitzeu dades de la memòria cau, un canal admès accessible o preus locals amb data, segons convingui.

price export escriu fitxers de canals a prices/ i reescriu les inclusions a rutes relatives locals. El Beancount, la Fava i Beanquery externs poden carregar aquesta còpia exportada. Una font no disponible rebutja l'exportació tret que s'utilitzi --allow-errors, cosa que pot deixar el seu marcador de font sense preus.

El vostre propi preu amb data substitueix un preu gestionat per a la mateixa data i parella. Les entrades dels canals són de només lectura. Les actualitzacions fallides conserven una revisió validada prèviament, que pot estar obsoleta. Els altres arguments de bea price encara es reenvien al Beanprice; si un fitxer de treball de cotitzacions es diu status, passeu ./status per distingir-lo de la subordre.

Homebrew instal·la tant la CLI com el seu motor gestionat. Amb PyPI, la primera ordre basada en el motor descarrega les dependències fixades; mantingueu uv al PATH i permeteu l'accés a la xarxa per a aquesta primera execució. Les ordres locals posteriors reutilitzen el motor sense connexió. Els clients només instal·len beancount-io, sense cap paquet Beancount separat ni scripts de consola natius per gestionar.

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.

bea balance [ACCOUNT...] mostra subarbres de saldos per als comptes que coincideixen amb subcadenes sense distinció de majúscules i minúscules, o tot el llibre quan no en nomena cap. Accepta --conversion / -x, --time / -t i --allow-errors, i no té cap opció d'interval ni de compte.

Els filtres de temps inclouen un any, mes, data, trimestre, setmana o interval, 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 apunts d'una transacció coincident.

La conversió per defecte és l'única moneda operativa del llibre. En cas contrari, per defecte és units, mantenint els productes separats. at_cost utilitza els costos d'adquisició. at_value utilitza valors de mercat amb un cost de reserva.

Una conversió de moneda explícita necessita preus en o abans de cada data de valoració, incloent-hi les dates dels intervals. Un error de preu absent nomena la mancança real, com No EUR → USD price on or before 2026-01-31. Una cotització posterior no pot omplir una mancança anterior. Afegiu un preu històricament adequat, 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 i 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ç 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 de finalització exclusiva, la data de referència, 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ó predeterminada 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ó amb 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 de les eines van al servei d'IA allotjat de Beancount.io. Les escriptures interactives es previsualitzen, es confirmen, es validen i s'escriuen atòmicament. Accepten --into. L'opció global --yes no atorga permís d'escriptura a la IA. El mode d'una sola resposta no aplica les 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 del projecte guanyen per nom. Cada fitxer necessita camps YAML name i description. Les instruccions completes es carreguen a demanda. Per a la disposició dels fitxers i un exemple pràctic, consulteu Amplieu bea ask amb habilitats.

Llibres majors allotjats​

Amb l'opció global --json, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create i bea cloud ledger delete emeten l'embolcall estàndard. L'inici de sessió requereix interacció; el tancament de sessió i la clonació correctes no retornen cap objecte d'èxit JSON.

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

JSON i codis de sortida​

L'opció global --json posa els resultats correctes a la sortida estàndard:

{
  "bea": "0.2.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. Les destinacions identifiquen un fitxer, directori, servidor o cap destinació. Les escriptures incloses també identifiquen into. Els imports decimals i les dates utilitzen cadenes. Les llistes limitades inclouen limit i truncated.

Els errors escriuen {"error":{"category":"validation","message":"…","exit_code":1}} a la sortida d'error. 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 allotjat abans de sortir amb un codi diferent de zero. Per a un script que llegeix aquest embolcall amb jq i es ramifica segons aquests codis, consulteu Automatitzeu la comptabilitat amb bea.

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

Excepcions de sortida: doctor, example, treeify, les invocacions de price reenviades al Beanprice i ingest conserven la sortida nativa i l'estat de sortida, fins i tot amb l'opció global --json; l'embolcall i les categories de sortida anteriors no descriuen aquests resultats reenviats. Ask rebutja JSON; l'inici de sessió al núvol necessita interacció; el tancament de sessió i la clonació al núvol correctes 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 la sortida d'error, incloent-hi el mode JSON.

Configuracions, actualitzacions i estat emmagatzemat​

Els valors vertaders són 1, true, yes i on, ignorant majúscules i minúscules i els espais circumdants. L'estat de configuració inclou credencials, historial de preguntes d'Ask, habilitats de l'usuari, rutes d'importador recordades i memòries cau de comprovació d'actualitzacions. Els bloquejos d'escriptura es troben a locks/ del directori de memòria cau, fora del directori del vostre llibre.

bea upgrade --check informa de les 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 orientació d'actualització manual. Les comprovacions passives s'executen com a màxim una vegada 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 fitxers del vostre llibre i la configuració de l'usuari romanen.

Solucions comunes​

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