Referencia de CLI de Beancount

Use esta referencia para consultar los comandos de bea y su comportamiento. Para su primer libro mayor, siga la guía de inicio rápido de la CLI. Para cerrar un mes completo de principio a fin, realice Su primer mes con bea. 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 el --file global en lugar de su argumento de directorio. format usa su propio destino posicional. Proporcione un nombre de archivo o directorio. El --file global no elige el destino de formato.

Crear un libro mayor​

bea init [DIRECTORY] usa por defecto el directorio actual. Un directorio crea main.bean; una ruta .bean o .beancount nombra el nuevo archivo directamente.

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

Los saldos de apertura 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 sean tres letras mayúsculas activa una advertencia de error tipográfico. Esto no es una comprobació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 añadir e importar conservan los permisos y respetan los destinos de solo lectura. El formateo in situ usa el formateador nativo y notifica sus propios errores del sistema de archivos.

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 posting puede omitir su importe. Los postings numerados pueden omitir la moneda cuando una cuenta tiene una única moneda permitida o el libro mayor tiene una única moneda operativa compatible. De lo contrario, proporcione el símbolo.

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

Un intercambio de divisas 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. Añada cotizaciones price con fecha cuando los informes necesiten valoración de mercado.

Los metadatos aceptan cadenas sin comillas como --meta 'receipt:IMG_42.jpg'. Los números, booleanos, fechas e importes nativos conservan sus tipos. Los 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, las adiciones masivas y las importaciones reemplazan los saltos de línea en los beneficiarios, las narraciones y los metadatos de cadena por espacios. Las comillas y las 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 comprueba la cuenta al inicio de su fecha. Se admite la 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 usa por defecto el día anterior; --pad-date puede seleccionar otro día anterior. Ambas cuentas deben estar activas. Un pad independiente necesita un balance posterior que lo consuma. --allow-errors puede preparar ese estado intermedio, pero no puede eludir una cuenta de pad no válida.

add price omite un duplicado exacto de fecha/commodity/precio en la raíz y sus inclusiones. Sale con el código 0 e identifica la ubicación existente. Fechas o precios diferentes son adiciones nuevas.

Las rutas de los 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 un array 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 posting usa amount o units, como {"number":"45.00","currency":"USD"}. Omita ambos para el posting de compensación. Los campos de posting también incluyen cost, price, flag y meta. Los costes contienen number y currency, con date y label opcionales. Los precios contienen number y currency.

Use cadenas para los 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 source opcional de la transacción nunca se escribe como metadatos.

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

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

Libros mayores divididos y seguridad en la escritura​

Mantenga --file apuntando a la raíz. Añada --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. Ya debe estar incluido; nombrar un archivo no relacionado se rechaza. Los comandos de adición, las importaciones y las escrituras interactivas de la IA admiten esta separación.

Las escrituras validan el libro mayor candidato completo, incluidos los plugins y el booking de lotes de coste. Un cambio concurrente en la raíz o su grafo de inclusión sale con el código 4. Un destino de solo lectura sale con el código 3. Las adiciones exitosas alinean solo las nuevas líneas. Los bytes existentes permanecen sin cambios. Use bea format -i PATH cuando quiera realinear todo el archivo.

Listar directivas​

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

Los demás tipos de directiva conservan el orden cronológico. Una tabla de transacciones filtrada por cuenta etiqueta su columna de importe como MATCHING POSTING AMOUNTS. Los detalles y el JSON siguen incluyendo todos los postings de cada transacción seleccionada. Los detalles muestran las entradas cargadas, incluidos los importes inferidos; no son extractos sin procesar del origen.

Verificar, formatear y consultar​

bea check valida la raíz y las inclusiones. Sale con el código 0 en silencio si tiene éxito y con 1 si hay errores en el libro mayor. El --json global devuelve el sobre de validación. No hay opción --allow-errors para check.

Las consultas, listas e informes advierten y devuelven resultados parciales en una terminal interactiva. El --strict global, --json, --no-input, un CI verdadero o una entrada estándar no terminal hacen que las lecturas sean estrictas. Su opción --allow-errors permite explícitamente resultados parciales.

El formateo acepta archivos o busca recursivamente en un directorio. En el paquete 0.2.0 publicado, se requiere una ruta a pesar del valor predeterminado de entrada estándar que se muestra en la ayuda. El --file global no elige el destino de formato.

El formateo alinea el texto; no valida la sintaxis del libro mayor ni la contabilidad. Ejecute bea check por separado. Con el --json global, seleccione -i, -o FILE, --check o --dry-run para que la salida estándar pueda llevar el sobre. No redirija la salida estándar sobre el archivo de entrada: use -i para reescribirlo.

bea query "BQL" ejecuta una consulta de Beancount. Omitir BQL lee las consultas de la entrada estándar o abre el shell cuando la entrada estándar es una terminal. Use .exit, exit o quit para cerrar el shell. La tabla predeterminada de BQL tiene una fila por posting. Las tablas de consulta conservan la precisión.

Seleccione el libro mayor antes del comando, por ejemplo bea --file main.bean query -f csv -o balances.csv "SELECT account, sum(position) GROUP BY account". El --json global usa el sobre del producto con data.rows y data.columns; es distinto de la representación CSV. En la versión 0.2.0 publicada, use la redirección del shell para guardar JSON, como bea --json query "SELECT account, sum(position) GROUP BY account" > result.json: -o y -m de query no se aplican a JSON en esa versión.

Herramientas nativas y funciones opcionales​

bea doctor context main.bean 42 muestra el contexto de la transacción en la línea 42. bea doctor --help lista los otros comandos de diagnóstico. bea example -o example.bean crea un historial de ejemplo. bea treeify accounts.txt representa nombres jerárquicos desde un archivo de texto; omita el archivo para leer de la entrada estándar. Estos comandos reenvían argumentos nativos. Los ejemplos anteriores nombran esos argumentos explícitamente.

Habilite las herramientas opcionales una vez con bea engine enable beanprice para la obtención de cotizaciones o bea engine enable beangulp para los flujos de trabajo de importación. La habilitación necesita acceso a la red; Beangulp también necesita la biblioteca libmagic del sistema. Use bea engine status para inspeccionar la disponibilidad. bea price --help y bea ingest --help describen sus interfaces. bea import --csv y bea add price no necesitan ninguna de las dos funciones opcionales.

Inclusiones de precios gestionados​

Precios en vivo es un flujo de trabajo separado de inclusión gestionada. Los libros mayores alojados resuelven las URL de precios compatibles; las versiones compatibles de bea también admiten inclusiones gestionadas y exportaciones de precios locales. Consulte la guía de precios gestionados específica de la versión si su versión instalada no reconoce estos comandos.

La CLI resuelve las URL gestionadas de la lista de permitidos sin enviar credenciales y rechaza las redirecciones. Por lo tanto, un feed que redirige a un inicio de sesión alojado no está disponible para una obtención local nueva; iniciar sesión en el sitio web no autentica la solicitud de precios de la CLI. Inspeccione price status para ver los errores de la fuente. Use datos en caché, un feed compatible accesible o precios locales con fecha, según corresponda.

price export escribe los archivos de feed en prices/ y reescribe las inclusiones a rutas relativas locales. Beancount, Fava y Beanquery posteriores pueden cargar esa copia exportada. Una fuente no disponible rechaza la exportación a menos que se use --allow-errors, lo que puede dejar su marcador de fuente sin precios.

Su propio precio con fecha anula un precio gestionado para la misma fecha y par. Las entradas de feed son de solo lectura. Las actualizaciones fallidas conservan una revisión validada previamente, que puede estar obsoleta. Otros argumentos de bea price todavía se reenvían a Beanprice; si un archivo de trabajo de cotizaciones se llama status, pase ./status para distinguirlo del subcomando.

Homebrew instala tanto la CLI como su motor gestionado. Con PyPI, el primer comando respaldado por el motor descarga las dependencias fijadas; mantenga uv en PATH y permita el acceso a la red para esa primera ejecución. Los comandos locales posteriores reutilizan el motor sin conexión. Los clientes solo instalan beancount-io, sin ningún paquete de Beancount aparte ni scripts de consola nativos que gestionar.

Reportes financieros​

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

bea balance [ACCOUNT...] imprime subárboles de saldo para las cuentas que coinciden con subcadenas sin distinción de mayúsculas, o todo el libro mayor cuando no nombra ninguna. Acepta --conversion / -x, --time / -t y --allow-errors, y no toma ninguna opción de intervalo o cuenta.

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 todos los postings de una transacción coincidente.

La conversión usa por defecto la única moneda operativa del libro mayor. De lo contrario, usa por defecto units, manteniendo los commodities separados. at_cost usa los costes de adquisición. at_value usa los valores de mercado con un respaldo de coste.

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. Añada 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. El 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, los pasivos y el patrimonio normalmente usan signos negativos de Beancount. El beneficio neto es -(income + expenses), positivo para una ganancia. La misma convención se aplica a las filas de período del estado de resultados. La conciliación del balance se deriva para el informe; no escribe ninguna directiva. equity_reconciled identifica si hay disponible una conciliación completa.

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

Asistencia opcional de IA​

bea ask necesita tanto el extra ask como las credenciales de Beancount.io de 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 rellena previamente su entrada. El uso no interactivo requiere una pregunta. No se admite el modo JSON.

Las consultas se ejecutan localmente. Las preguntas, el contexto de las habilidades y los resultados de las herramientas van al servicio de IA alojado de Beancount.io. Las escrituras interactivas se previsualizan, confirman, validan y escriben de forma atómica. Aceptan --into. El --yes global no otorga permiso de escritura a la IA. El modo de una sola respuesta no aplica las 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 a demanda. Para la estructura de archivos y un ejemplo práctico, consulte Ampliar bea ask con habilidades.

Libros contables alojados​

Con el --json global, bea cloud status, bea cloud ledger list, bea cloud ledger show, bea cloud ledger create y bea cloud ledger delete emiten el sobre estándar. El inicio de sesión requiere interacción; el cierre de sesión y la clonación exitosos no devuelven un objeto de éxito JSON.

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

JSON y códigos de salida​

El --json global pone los resultados exitosos en la salida estándar:

{
  "bea": "0.2.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 importes decimales y las fechas usan cadenas. Las listas limitadas incluyen limit y truncated.

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

Compruebe 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 mayor alojado antes de salir con un código distinto de cero. Para ver un script que lee este sobre con jq y bifurca según estos códigos, consulte Automatizar la contabilidad con bea.

Los mensajes de la CLI se desactivan con --no-input, el modo JSON, una entrada estándar no terminal o un CI verdadero. La eliminación en la nube todavía necesita --yes explícito. Las importaciones necesitan una decisión explícita sobre duplicados cuando las coincidencias requieren revisión.

Excepciones de salida: doctor, example, treeify, las invocaciones de price reenviadas a Beanprice y ingest conservan la salida nativa y el estado de salida, incluso con el --json global; el sobre y las categorías de salida anteriores no describen esos resultados reenviados. Ask rechaza JSON; el inicio de sesión en la nube necesita interacción; el cierre de sesión y la clonación exitosos en la nube no devuelven ningún objeto de éxito JSON. La ayuda, la versión y el autocompletado conservan la salida de texto. upgrade puede transmitir la salida de su gestor de paquetes a la salida de error, incluso en modo JSON.

Configuraciones, 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 preguntas de Ask, habilidades del usuario, rutas de importador recordadas y cachés de comprobación de actualizaciones. Los bloqueos de escritura se encuentran en locks/ del directorio de caché, fuera de su directorio de libro mayor.

bea upgrade --check informa las 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 orientación de actualización manual. Las comprobaciones pasivas se ejecutan como máximo una vez al día en copias instaladas interactivas; el upgrade --check explícito todavía se ejecuta cuando el notificador pasivo está desactivado.

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

Correcciones comunes​

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