Inicio rápido de Beancount CLI

Crea un libro mayor local y registra tu primera compra con bea, la herramienta de línea de comandos de Beancount.io. La contabilidad local no requiere una cuenta de Beancount.io.

Este recorrido comienza con 1,000 USD en cuenta corriente. Después de una compra de café por 12.50 USD, verificarás un saldo de 987.50 USD.

1. Instalar el comando​

Con Homebrew en macOS o Linux:

brew install bex-co/tap/bea
bea --version

Si no usas Homebrew, instala uv y usa uv tool install beancount-io. El paquete Python requiere Python 3.12 o superior. Homebrew provee el motor contable durante la instalación. Con PyPI, mantén uv disponible: el primer comando local descarga el motor gestionado, luego los comandos posteriores lo reutilizan sin conexión. No necesitas instalar Beancount por separado.

2. Crea tu libro mayor​

Elige un directorio nuevo. Este ejemplo crea main.bean dentro de ~/my-books:

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

La plantilla abre cuentas comunes de cuenta corriente, ahorro, efectivo, tarjeta de crédito, ingresos y gastos. El saldo inicial se compensa contra Equity:OpeningBalances.

Para tus propios libros, elige la fecha más temprana que piensas registrar. Todas las cuentas de la plantilla abren en esa fecha. El saldo inicial debe describir la cuenta en ese día. La deuda de tarjeta de crédito usa un monto negativo.

init nunca sobrescribe un libro mayor existente. Los archivos nuevos son privados en sistemas POSIX: sólo el propietario puede leer y escribirlos. Para compartir con tu grupo local, cambia explícitamente los permisos con chmod 640 main.bean.

Para una configuración guiada, ejecuta bea init ~/my-books en una terminal. El asistente pregunta por tu moneda, fecha de inicio del historial y saldo de cuenta corriente.

3. Registra una compra​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

El gasto usa la moneda USD de la cuenta. Beancount completa la otra imputación como -12.50 USD. Puedes omitir --date para compras hechas hoy.

Cada adición se verifica contra el libro completo antes de reemplazar el archivo. Una cuenta desconocida o una transacción desbalanceada produce un error con instrucciones.

4. Verifica el resultado​

bea check
bea list transaction --limit 10
bea report balance-sheet

La lista de transacciones muestra las entradas más recientes primero, con sus montos imputados. El balance muestra 987.50 USD en cuenta corriente.

Para verificar esa cantidad directamente:

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Las tablas de consulta preservan la precisión del resultado. Para salida estructurada, coloca la bandera global --json antes del comando:

bea --json list transaction --limit 10

5. Mantén tus libros en buen estado​

Ejecute bea check después de editar el archivo manualmente. Ejecute bea format -i main.bean para alinear sus columnas en el lugar. Sin -i, el texto formateado se envía a stdout y el archivo permanece sin cambios. Use bea format main.bean --check cuando un script debería fallar si se necesita formatear.

Para trabajar desde otro directorio, seleccione explícitamente el archivo raíz:

bea --file ~/my-books/main.bean check

La raíz se selecciona con --file, luego BEA_FILE, luego main.bean en el directorio de trabajo. Las opciones globales van antes del comando. El formateo toma su propio argumento de archivo o directorio.

Continúe con sus propios registros​

• Importar una exportación bancaria con vista previa y revisión de duplicados.
• Asignar a un agente externo dos trabajos contables con indicaciones copiables y equivalentes en CLI.
• Comparar cinco herramientas contables para agentes de IA sobre instalación, autenticación, alcance, datos, vista previa, salida y repeticiones, con fuentes fechadas.
• Consultar comandos y opciones para cuentas, saldos, inversiones, informes y automatización.
• Organizar un libro mayor a través de archivos. Use --into para escribir un archivo incluido mientras valida contra la raíz.
• Usar la interfaz del navegador si prefiere formularios en lugar de comandos de terminal.

Verifique actualizaciones con bea upgrade --check. Ejecute bea upgrade para invocar al gestor de paquetes que instaló su copia. Use bea --help o bea add transaction --help para inspeccionar las opciones disponibles en su versión instalada.