Visión general
Instala y autentica el CLI oficial factuarea — maneja la API REST v1 desde tu terminal con brew, npm o un instalador curl. Agent-first, inspirado en Stripe.
El CLI oficial factuarea maneja la API REST v1
desde tu terminal. Es agent-first — salida JSON estable, exit codes
semánticos y descubrimiento en una sola llamada — e inspirado en Stripe: el
árbol de comandos completo se genera desde la especificación OpenAPI, así que
nunca se desincroniza de la superficie real.
¿Prefieres que un agente de IA maneje Factuarea directamente? El CLI está hecho para eso. Consulta Agentes y scripting para el contrato JSON y los exit codes, y el servidor MCP para la alternativa basada en tools.
Instalación
Los canales empaquetados se activan con la primera release publicada. Hasta entonces, compila desde el código.
macOS y Linux:
brew install --cask factuarea/tap/factuareaCualquier plataforma con Node 20 o superior:
npm i -g @factuarea/cli # o: npx @factuarea/cli <comando>Instala un binario firmado en ~/.local/bin:
curl -fsSL https://github.com/factuarea/factuarea-cli/releases/latest/download/install.sh | shLos binarios están firmados (cosign) y vienen con checksums.txt en
Releases.
Requiere Go 1.26 o superior:
git clone https://github.com/factuarea/factuarea-cli && cd factuarea-cli
make build # genera ./factuareaLa notarización en macOS y la firma Authenticode en Windows llegan en una fase
posterior. Por ahora, en macOS usa brew o npm, o ejecuta
xattr -d com.apple.quarantine ./factuarea sobre un binario suelto.
Autenticación
El CLI usa tu API key de Factuarea. El prefijo de la key decide el entorno — no hay un flag aparte:
fact_test_…→ el sandbox aislado: datos de prueba, sin efectos reales (no transmite a la AEAT, no envía email, no entrega webhooks).fact_live_…→ producción: datos reales.
Inicia sesión
factuarea login # te pide la key en un prompt ocultoLa key se lee en un prompt oculto — nunca se pasa como argumento visible. Se
guarda en el keyring del sistema (con fallback a ~/.config/factuarea/config.toml,
permisos 600). Soporta múltiples perfiles con --profile.
O define una variable de entorno
Para entornos no interactivos:
export FACTUAREA_API_KEY=fact_test_xxxxxxxxxxxxxxxxxxxxxxxxVerifica
factuarea whoami # muestra la cuenta y el entorno (TEST/LIVE)Empieza toda integración con una key fact_test_. La superficie de
comandos es idéntica a producción — cambia el prefijo a fact_live_ solo
cuando tu flujo funcione de principio a fin. Las mutaciones en producción (con
una key fact_live_) requieren además el flag explícito --live como red de
seguridad.
Qué sigue
Uso
El árbol de comandos generado — list, show, create, acciones de dominio,
descargas binarias, el escape hatch api y commands --json.
Devloop
Prueba webhooks en local sin desplegar ni ngrok: listen reenvía los
eventos a tu máquina, trigger produce eventos reales en sandbox.
Agentes y scripting
El contrato agent-first: JSON estable por stdout, errores estructurados por stderr, exit codes semánticos, scope-check y confirmación tipada.
Errores y límites de peticiones
Formas de error JSON-RPC mapeadas desde el contrato v1, la tabla completa de códigos y throttling por token / por plan con Retry-After.
Uso
El árbol de comandos de factuarea — list, show, create, acciones de dominio, descargas binarias, subidas multipart, el escape hatch genérico api y el manifiesto commands --json.