---
name: balance
description: Interactúa con el CLI `bal` para gestionar finanzas personales (app Balance con Supabase). Usa cuando el usuario menciona registrar un gasto o ingreso, consultar saldo, ver movimientos recientes, cuadrar cuentas, o nombra cuentas de débito, crédito, efectivo o inversiones. Requiere que `bal login` ya haya corrido (sesión en ~/.balance/session.json) o que BAL_API_KEY esté exportada.
allowed-tools: Bash(bal *) Bash(node *) Bash(npx *)
---

# Balance — CLI de finanzas personales del usuario

El CLI `bal` es la interfaz principal para hablar con la base de datos de finanzas personales (Supabase). El modelo core es **Balance Assertion with Reconciliation**: cada peso está ubicado (en una cuenta) y explicado (por una transacción). El cuadre se mide por `delta = posición - acumulado` y debe ser 0.

## Cuándo activar este skill

- Menciones de montos en CLP ("8k", "15 mil", "$20.000") junto a verbos como gasté, pagué, anoté, cobré, transferí.
- Preguntas de estado: "¿cuánto tengo?", "¿cuadré?", "¿cuánto llevo este mes?".
- Pedidos sobre movimientos: "últimos gastos", "qué gasté en X", "muéstrame Y".
- Cuentas configuradas por el usuario: débito, tarjetas de crédito, efectivo, inversiones (Broker/Fintual), cuentas por cobrar/pagar.
- Categorías del dominio: `consumo.libre`, `ahorro`, `comida`, `transporte`, `servicios`, `apertura`.

## Archivos relacionados (cargar on-demand)

- [COMMANDS.md](COMMANDS.md) — referencia completa de cada comando y sus flags.
- [WORKFLOWS.md](WORKFLOWS.md) — flujos típicos (registrar gasto, consultar, parsear correos).
- [EXAMPLES.md](EXAMPLES.md) — tabla de prompts reales → comando exacto.

## Reglas innegociables

1. **Siempre `--json` para parsear**. El output humano es para mostrarle al usuario, no para consumir.
2. **CLP sin decimales**. Los montos son enteros. `8.5` no es válido; `8500` sí. El parser acepta separadores de miles (`8.000`, `8,000`).
3. **`--account` es obligatorio en `bal add`**. Si el usuario no lo menciona, preguntá antes de ejecutar — no asumas.
4. **Montos >$100.000 requieren confirmación** antes de correr `bal add`. Mostrá monto + categoría + cuenta y pedí sí/no.
5. **No reintentes `bal login` más de una vez**. Si falla, pedile al usuario que genere una API key nueva con `bal key create --name "<device>"`.
6. **Signo en la salida**: expense/debt_payment siempre se muestran con `-`, income/refund con `+`, adjustment/transfer siguen el signo natural del monto.

## Setup que debe existir antes de que funcione

Env vars requeridas en la terminal donde corre `bal`:
- `SUPABASE_URL=https://<your-project-ref>.supabase.co`
- `SUPABASE_ANON_KEY=sb_publishable_...`
- Opcional: `BAL_API_KEY=bal_...` (para `bal login` sin prompt)

Primera vez:
```
bal key create --name "mi-device"     # pide email+password, imprime key plaintext UNA vez
bal login --api-key bal_...           # guarda sesión JWT en ~/.balance/session.json
```

De ahí en adelante, los comandos de lectura/escritura usan la sesión automáticamente y la refrescan antes de expirar.

## Si el CLI no está instalado globalmente

Desde la raíz del repo `balance`:
```
npx tsx apps/cli/src/index.ts <comando>
```
o, con build:
```
node apps/cli/dist/index.js <comando>
```