Referencia de la CLI de Beancount

Use esta referencia para consultar los comandos bea y su comportamiento. Para su primer libro, siga la guía rápida de CLI. Para archivos bancarios, use el tutorial de importación.

Comandos de un vistazo​

Opciones globales y rutas​

Las opciones globales van antes del comando:

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

init crea su propio destino de directorio/archivo e ignora BEA_FILE. Acepta la opción global --file en lugar de su argumento de directorio. format usa su propio destino posicional, con valor predeterminado al directorio de trabajo. La opción global --file no elige el destino de formato.

Crear un libro​

bea init [DIRECTORY] tiene como valor predeterminado el directorio actual. Un directorio crea main.bean; una ruta .bean o .beancount nombra directamente el nuevo archivo.

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

Los saldos iniciales se compensan contra Equity:OpeningBalances. La deuda es negativa. La entrada de moneda se convierte a mayúsculas. Se permiten símbolos personalizados; un símbolo que no sea tres letras mayúsculas genera una advertencia de error tipográfico. Esto no es una verificación del registro de monedas ISO.

Los archivos existentes nunca se sobrescriben. Los archivos nuevos usan permisos solo para el propietario, modo 0600 en POSIX. Las escrituras posteriores de add, import y format preservan los permisos y respetan los destinos de solo lectura.

Agregar transacciones​

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 asiento puede omitir su monto. Los asientos numerados pueden omitir la moneda cuando una cuenta tiene una moneda permitida o el libro tiene una moneda operativa compatible. De lo contrario, proporcione el símbolo.

La sintaxis nativa de asientos admite aritmética como 84/2 EUR, costos como {100 USD}, costos totales {{1000 USD}} y precios @ o @@. Use montos decimales como 1000, no notación exponencial como 1e3.

Una conversión de moneda necesita su tasa de transacción real. Por ejemplo, registre 100 EUR @ 1.08 USD en una cuenta abierta en EUR y -108 USD en la cuenta corriente. Una compra de inversión puede registrar 2 AAPL {100 USD} en una cuenta abierta en AAPL y -200 USD en la cuenta corriente. Agregue cotizaciones price con fecha cuando los informes necesiten valoración de mercado.

Los metadatos aceptan cadenas simples como --meta 'receipt:IMG_42.jpg'. Los números nativos, booleanos, fechas y montos conservan sus tipos. Ejemplos incluyen --meta 'reviewed:TRUE', --meta 'received:2026-08-03' y --meta 'fee:2.50 USD'. Las comillas internas fuerzan una cadena: --meta 'code:"1234"'. Las claves deben ser distintas; filename y lineno están reservadas.

Las adiciones individuales, masivas e importaciones reemplazan los saltos de línea en beneficiarios, narraciones y metadatos de cadena con espacios. Las comillas y barras invertidas conservan su contenido.

Agregar otras directivas​

Todos estos comandos requieren --date YYYY-MM-DD. También aceptan --into FILE y --allow-errors.

Los nombres de cuenta tienen una raíz en mayúscula y segmentos separados por dos puntos. Cada subcuenta comienza con una letra mayúscula o un dígito. Beancount admite letras Unicode y nombres de raíz configurados.

Un balance verifica la cuenta al inicio de su fecha. Se admite sintaxis de tolerancia, como --amount "1538 ~ 1 EUR". La tolerancia debe ser no negativa.

Use add balance --pad-from Equity:OpeningBalances para escribir un pad y su aserción de balance juntos. El pad tiene como valor predeterminado el día anterior; --pad-date puede seleccionar otro día anterior. Ambas cuentas deben estar activas. Un pad independiente necesita un balance posterior para consumirlo. --allow-errors puede escalonar ese estado intermedio pero no puede omitir una cuenta de pad inválida.

add price omite una duplicación exacta de fecha/commodity/precio en la raíz y sus includes. Sale con código 0 e identifica la ubicación existente. Fechas o precios diferentes son adiciones nuevas.

Las rutas de documentos se resuelven junto al archivo que contiene la directiva. Con --into years/2026.bean, --filename receipt.pdf significa years/receipt.pdf, no un archivo junto al directorio de trabajo de su shell.

Los tipos de valor personalizados son text, number, amount, account, bool y date. Por ejemplo, un presupuesto puede usar --value "text:travel" --value "amount:500 USD".

Entrada JSON masiva​

bea add transactions --from transactions.json acepta una matriz 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ón requiere date y postings. Los campos opcionales son flag, payee, narration, tags, links y meta.

Un asiento usa amount o units, como {"number":"45.00","currency":"USD"}. Omita ambos para el asiento de equilibrio. Los campos de asiento también incluyen cost, price, flag y meta. Los costos contienen number y currency, con date y label opcionales. Los precios contienen number y currency.

Use cadenas para decimales. Los metadatos usan cadenas y booleanos ordinarios, o valores etiquetados como {"kind":"number","value":"1.125"}, {"kind":"date","value":"2026-08-04"} y {"kind":"amount","number":"2.50","currency":"USD"}. La ubicación opcional source de la transacción nunca se escribe como metadatos.

El valor predeterminado es un lote atómico: cualquier fila rechazada deja el libro sin cambios y sale con código 1. --partial escribe un subconjunto válido y aún así sale con código 1 si se rechaza alguna fila. Los errores JSON describen el resultado en error.result; los índices de fila allí son de base cero. Los números de fila humanos son de base uno.

La adición masiva acepta --into y --allow-errors. No deduplica. Use bea import para la revisión de exportaciones bancarias.

Libros divididos y seguridad de escritura​

Mantenga --file apuntando a la raíz. Agregue --into para seleccionar un archivo incluido existente:

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

El destino es relativo al directorio raíz. Debe estar ya incluido; nombrar un archivo no relacionado se rechaza. Los comandos add, imports y escrituras interactivas de IA admiten esta separación.

Las escrituras validan el libro candidato completo, incluidos plugins y registro de lotes de costos. Un cambio concurrente en la raíz o su grafo de includes sale con código 4. Un destino de solo lectura sale con código 3. Las adiciones exitosas usan la misma alineación que bea format, que puede realinear columnas existentes en ese destino.

Listar directivas​

bea list TYPE admite los once tipos: transaction, open, close, balance, pad, note, event, price, commodity, document y custom.

Otros tipos de directivas conservan el orden cronológico. Una tabla de transacciones filtrada por cuenta etiqueta su columna de montos MATCHING POSTING AMOUNTS. Los detalles y JSON aún incluyen todos los asientos de cada transacción seleccionada. Los detalles muestran entradas cargadas, incluidos montos inferidos; no son extractos de fuente crudos.

Verificar, formatear y consultar​

bea check valida la raíz y los includes. Sale con código 1 para errores del libro y no tiene opción --allow-errors. Las consultas, listas e informes también rechazan errores del cargador a menos que pase explícitamente su opción --allow-errors.

El formateo toma un archivo .bean/.beancount o un directorio. Un directorio se busca recursivamente.

Cada modo informa errores de sintaxis por archivo y línea, omite esos archivos y sale con código 1. Una ejecución recursiva normal aún puede formatear los archivos válidos. JSON informa scanned, formatted, skipped, dry_run y check, bajo error.result en caso de fallo.

bea query "BQL" ejecuta una consulta Beancount. Omitir BQL abre un shell interactivo; exit o quit lo cierra. Se requiere un argumento de consulta sin supervisión. La tabla predeterminada de BQL tiene una fila por asiento. Las tablas de consulta conservan precisión. Los resultados vacíos imprimen (no rows) en stderr; JSON devuelve data.rows vacío y metadatos de columnas en data.columns.

Informes financieros​

Todos los informes aceptan --conversion / -x, --time / -t, --account / -a y --allow-errors. Todos excepto trial-balance también aceptan --interval / -i: monthly por defecto, o quarterly, yearly, weekly o daily.

Los filtros de tiempo incluyen un año, mes, fecha, trimestre, semana o rango, como 2026, 2026-08, 2026-08-31, 2026-Q3, 2026-W32 o "2026-01 - 2026-08". Los períodos relativos incluyen year, quarter, month, week, day y desplazamientos como month-1. Los filtros de cuenta conservan cada asiento de una transacción coincidente.

La conversión tiene como valor predeterminado la única moneda operativa del libro. De lo contrario, tiene como valor predeterminado units, manteniendo los commodities separados. at_cost usa costos de adquisición. at_value usa valores de mercado con un respaldo de costo.

Una conversión de moneda explícita necesita precios en o antes de cada fecha de valoración, incluidas las fechas de intervalo. Un error de precio faltante nombra la brecha real, como No EUR → USD price on or before 2026-01-31. Una cotización posterior no puede llenar una brecha anterior. Agregue un precio históricamente apropiado, use --conversion units o elija --allow-errors para inspeccionar valores parciales.

Los informes parciales conservan las monedas de origen y marcan los totales combinados como no disponibles. JSON incluye valuation: "partial", missing_prices y missing_price_dates. Los totales afectados de beneficio neto/patrimonio neto son null en la moneda solicitada.

Los ingresos, pasivos y patrimonio normalmente usan signos negativos de Beancount. El beneficio neto es -(income + expenses), positivo para una ganancia. La misma convención aplica a las filas de período del estado de resultados. La conciliación del balance general se deriva para el informe; no escribe directivas. equity_reconciled identifica si una conciliación completa está disponible.

El JSON del informe también identifica el período, la fecha final exclusiva, la fecha de corte, la conversión, el filtro de cuenta y el estado de validación del libro. Verifique esos campos antes de comparar totales.

Asistencia de IA opcional​

bea ask necesita tanto el extra ask como credenciales de Beancount.io desde bea cloud login o BEA_TOKEN. La instalación predeterminada de Homebrew omite las dependencias de IA. Los usuarios de Homebrew pueden ejecutar:

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

Para una instalación con uv, instale beancount-io[ask] y ejecute bea ask directamente. --print / -p responde una vez y sale. De lo contrario, una sesión de terminal es interactiva, y una pregunta opcional precompleta su entrada. El uso no interactivo requiere una pregunta. El modo JSON no se admite.

Las consultas se ejecutan localmente. Las preguntas, el contexto de habilidades y los resultados de herramientas van al servicio de IA alojado de Beancount.io. Las escrituras interactivas se previsualizan, confirman, validan y escriben atómicamente. Aceptan --into. La opción global --yes no otorga permiso de escritura a la IA. El modo de una respuesta no aplica escrituras propuestas.

Ask lee NAME/SKILL.md de .agents/skills/ en el directorio de trabajo y de skills/ en el directorio de configuración del usuario. Las definiciones del proyecto ganan por nombre. Cada archivo necesita campos YAML name y description. Las instrucciones completas se cargan bajo demanda.

Libros alojados​

La creación también acepta --clone y --dir. Se requiere acceso Git y SSH para clonar. Si la clonación falla después de la creación, el libro alojado aún existe. Los comandos locales no suben su libro automáticamente. No hay opción global --ledger.

JSON y códigos de salida​

La opción global --json coloca resultados exitosos en stdout:

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

bea es la versión instalada; data depende del comando. Los destinos identifican un archivo, directorio, servidor o ningún destino. Las escrituras incluidas también identifican into. Los montos decimales y fechas usan cadenas. Las listas limitadas incluyen limit y truncated.

Los fallos escriben {"error":{"category":"validation","message":"…","exit_code":1}} en stderr. El error también puede incluir details, result, un request_id del backend y un traceback con --debug.

Verifique error.result antes de reintentar una mutación. Un lote parcial puede escribir filas aceptadas, el formateo recursivo puede cambiar archivos válidos y crear-y-clonar puede crear un libro alojado antes de salir con código distinto de cero.

Las indicaciones de la CLI se deshabilitan con --no-input, modo JSON, stdin no terminal o CI verdadero. La eliminación en la nube aún necesita --yes explícito. Las importaciones necesitan una decisión de duplicado explícita cuando las coincidencias necesitan revisión.

Excepciones de salida: Ask rechaza JSON; cloud login necesita interacción; cloud logout y clone exitosos no devuelven un objeto JSON de éxito. La ayuda, la versión y la finalización conservan salida de texto. upgrade puede transmitir la salida de su administrador de paquetes a stderr, incluso en modo JSON.

Configuración, actualizaciones y estado almacenado​

Los valores verdaderos son 1, true, yes y on, ignorando mayúsculas y espacios circundantes. El estado de configuración incluye credenciales, historial de indicaciones de Ask, habilidades del usuario, rutas de importador recordadas y cachés de verificación de actualizaciones. Los bloqueos de escritura residen bajo el directorio locks/ del caché, fuera de su directorio de libro.

bea upgrade --check informa versiones y el método de instalación sin actualizar. bea upgrade invoca brew upgrade bea, uv tool upgrade beancount-io o pipx upgrade beancount-io. Las instalaciones editables reciben guía de actualización manual. Las verificaciones pasivas se ejecutan como máximo una vez al día en copias instaladas interactivas; upgrade --check explícito aún se ejecuta cuando el notificador pasivo está deshabilitado.

Desinstale con el administrador correspondiente: brew uninstall bea, uv tool uninstall beancount-io o pipx uninstall beancount-io. Sus archivos de libro y configuración de usuario permanecen.

Soluciones comunes​

Use bea COMMAND --help para inspeccionar su versión instalada. La referencia del repositorio fuente contiene ejemplos adicionales y las definiciones exactas del modelo de directivas.