Inicio rápido de la CLI de Beancount

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 tutorial comienza con 1,000 USD en la cuenta corriente. Después de una compra de café de 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 de Python requiere Python 3.12 o superior.

2. Crear 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 corriente, ahorro, tarjetas 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 pretendes registrar. Todas las cuentas de la plantilla se abren en esa fecha. El saldo inicial debe describir la cuenta en ese día. La deuda de tarjeta de crédito se registra como un monto negativo.

init nunca sobrescribe un libro mayor existente. Los archivos nuevos son privados en sistemas POSIX: solo el propietario puede leerlos y escribirlos. Para compartirlos con tu grupo de usuarios local, cambia explícitamente los permisos con chmod 640 main.bean.

Para la configuración guiada, ejecuta bea init ~/my-books en una terminal. El asistente te pedirá tu moneda, fecha de inicio y saldo de corriente.

3. Registrar una compra​

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

El gasto usa la moneda de la cuenta. Beancount completa la otra entrada como -12.50 USD. Puedes omitir --date para compras realizadas hoy.

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

4. Verificar 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 de entrada. El balance general muestra 987.50 USD en corriente.

Para verificar ese monto 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​

Ejecuta bea check después de editar manualmente. Ejecuta bea format main.bean para alinear sus columnas. Usa bea format main.bean --check cuando un script deba fallar si el formato no es correcto.

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

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

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

Continúa con tus propios registros​

• Importa una exportación bancaria con vista previa y revisión de duplicados.
• Consulta comandos y opciones para cuentas, saldos, inversiones, automatización y más.
• Organiza un libro mayor en varios archivos. Usa --into para escribir en un archivo incluido mientras validas contra la raíz.
• Usa la interfaz de navegador si prefieres formularios a la terminal.

Verifica actualizaciones con bea upgrade --check. Ejecuta bea upgrade para invocar al administrador de paquetes que instaló tu copia. Usa bea --help o bea add transaction --help para inspeccionar las opciones disponibles en tu versión instalada.