gigstack CLI 0.3.0: Descarga Masiva SAT y soporte para agentes de IA

El terminal como interfaz para tu contabilidad

Hoy lanzamos gigstack CLI 0.3.0, una versión pensada tanto para desarrolladores que automatizan tareas fiscales como para agentes de IA que necesitan operar gigstack desde la línea de comandos. Si tu flujo incluye Claude Code, Cursor, GitHub Copilot Workspace, o cualquier asistente capaz de ejecutar comandos, este release te desbloquea.

Qué hay nuevo en 0.3.0

Descarga Masiva SAT desde la terminal

Por primera vez puedes contratar, configurar y consultar la Descarga Masiva SAT sin abrir el panel web. Toda la superficie vive bajo gigstack invoices sat:

• sat status — estado de activación + precios
• sat activate — contratar el servicio (con confirmación interactiva)
• sat list — listar facturas espejo del SAT, recibidas y emitidas
• sat get <uuid> — detalle de una factura
• sat retry <uuid> — reintentar la descarga del XML cuando falló
• sat pdf <uuid> — generar y guardar el PDF
• sat schedule — ver y ajustar las descargas programadas

La carga del FIEL sigue siendo solo desde la web por seguridad — los archivos .cer y .key no deben pasar por la línea de comandos.

Salida JSON paginada (cambio incompatible)

Cada comando que devuelve listas ahora responde con un sobre estructurado cuando le pasas --json:

{ "data": [...], "has_more": false, "next": null, "total": 599 }

Conecta next de vuelta como --next <token> para paginar. Si tienes scripts existentes, migra a leer .data de la respuesta. Adoptamos el patrón que usan Stripe y la CLI de GitHub porque los agentes ya lo entienden.

Conocimiento de dominio para agentes

El comando gigstack context ahora incluye el tema descarga_masiva_sat con conceptos, estados, acciones, relaciones y consejos pensados para que un agente de IA decida correctamente sin tener que adivinar la semántica del SAT. Para cargar todo el dominio de una sola vez:

gigstack context --all --json

Correcciones que tu agente notará de inmediato

• invoices complements dejó de devolver 405 — ahora apunta al endpoint correcto
• receipts list --client <id> ya filtra correctamente (faltaba un índice de Firestore)
• El spinner de carga ya no contamina la salida JSON cuando se canaliza por pipes

Cómo configurar el CLI con Claude Code u otro LLM

El CLI está pensado para que cualquier asistente con acceso a una shell pueda operar gigstack en menos de un minuto.

# Instalación global
npm install -g gigstack

# Autenticación vía variable de entorno (ideal para agentes en sandbox)
export GIGSTACK_API_KEY=gsk_xxx

# Verificar acceso
gigstack whoami
gigstack doctor

Para que un agente entienda de qué se trata gigstack antes de ejecutar acciones, agrega esta instrucción a tu prompt de sistema:

Tienes acceso a una shell con `gigstack` instalado.
Antes de responder preguntas sobre facturas, pagos o gastos,
carga el dominio con: gigstack context --all --json

Para datos, usa siempre --json. Descubre flags con `<cmd> --help`.
La autenticación está en GIGSTACK_API_KEY.

Tres recetas para agentes

1. Conciliación diaria SAT vs gigstack

Cada mañana el agente compara los CFDIs que el SAT registró contra los que tu equipo emitió y recibió en gigstack:

# CFDIs emitidos en gigstack los últimos 7 días
gigstack invoices list --from 7d --json | jq '.data | length'

# Mismo periodo desde el espejo SAT
gigstack invoices sat list --direction issued --from 7d --json | jq '.data | length'

# Gastos recibidos de proveedores
gigstack invoices sat list --direction received --from 7d --json

2. Cobranza con seguimiento automático

El agente identifica cuentas por cobrar, prioriza por antigüedad y envía recordatorios:

gigstack forecast --json
gigstack payments list --status pending --json \
  | jq '.data[] | select(.client.email)'

3. Captura inteligente de gastos

El agente revisa los CFDIs recibidos del SAT, descarga PDFs para contabilidad, y reintenta los que tuvieron problemas:

gigstack invoices sat list --direction received --json \
  | jq -r '.data[] | select(.resource_status == "error") | .uuid' \
  | xargs -I{} gigstack invoices sat retry {}

Filosofía: APIs estructuradas, no interfaces gráficas

Las interfaces gráficas no funcionan para agentes. Cada decisión de diseño en este release apunta al mismo objetivo: que cualquier LLM con acceso a una terminal pueda operar gigstack tan bien como un humano experto. Eso significa:

• Salida JSON predecible y paginada
• Errores legibles que se pueden propagar al usuario final
• Conocimiento de dominio cargable bajo demanda
• Sin contaminación de stderr cuando se usan pipes

Cómo actualizar

npm install -g gigstack@latest
gigstack --version  # debe mostrar 0.3.0

El código fuente está disponible en github.com/disruptive-learning/gigstack-cli. Si estás construyendo un agente sobre gigstack, escríbenos — queremos ver qué automatizas.