Uso

El árbol de comandos cubre todos los recursos de la API (factuarea <recurso> [<sub-recurso>] <acción>), generado desde la especificación OpenAPI para que nunca se desincronice de la superficie real.

Leer datos

# Listar (con paginación automática por cursor)
factuarea invoices list --json
factuarea contacts list --paginate --json

# Obtener uno
factuarea invoices show <uuid> --json

--json emite el cuerpo crudo de la API por stdout. --paginate recorre todas las páginas por ti, siguiendo next_cursor hasta que has_more sea falso. Consulta Paginación para la semántica del cursor subyacente.

Escribir datos

Pasa el cuerpo JSON con -d (en línea) o --data-file (una ruta). La API calcula los totales — no los redondees por adelantado.

factuarea invoices create -d '{"client_id":"…","series_id":"…","lines":[…]}'

Cada mutación recibe un Idempotency-Key automático para que una petición reintentada nunca cree el recurso dos veces. Consulta Idempotencia.

Acciones de dominio

Los cambios de estado son acciones discretas, no un flag de estado genérico — reflejando el propio diseño de la API:

factuarea invoices send <uuid>
factuarea invoices mark-paid <uuid>

Algunas acciones son irreversibles (borrados, void, conversiones, emisión fiscal). El CLI te pide confirmarlas antes de la llamada — consulta Operaciones irreversibles y la guía de scopes e irreversibilidad.

Control horario (fichajes y ausencias)

El add-on de control horario añade los recursos de jornada — empleados, horarios, fichajes, ausencias, presencia, festivos, cierres mensuales y el resumen de gestoría. Cada comando se genera desde la spec y queda protegido por su scope fino (employees:*, time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read, payroll_exports:*).

# Fichar entrada y salida (cada asiento encadena su huella — RD-ley 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Solicitar una ausencia y aprobarla
factuarea absence-requests create \
  -d '{"employee_id":"…","absence_type_id":"…","start_date":"2026-08-01","end_date":"2026-08-05"}'
factuarea absence-requests approve <uuid>

# Presencia del equipo en vivo
factuarea presence live --json

# Cerrar el registro mensual inalterable y exportarlo (ITSS RD-ley 8/2019)
factuarea monthly-time-record-closes create -d '{"year":2026,"month":7}'
factuarea monthly-time-record-closes export <uuid> --format rdley_8_2019 --json

Automatizaciones

El add-on de automations expone el motor de reglas: una regla escucha un evento, una condición decide si actuar, y se ejecuta una lista ordenada de acciones. El módulo protege todo el grupo, y cada comando lleva su scope fino — automations:read (8 comandos), automations:write (6), automation_runs:read (3) y automations:delete (1). Cuatro subgrupos espejan la API: catalog, rules (con rules versions), runs (con runs steps) y usage. Consulta la guía de automatizaciones para el modelo.

Empieza por el catálogo. Los campos evaluables de un disparador son una segunda llamada, una por disparador — no viajan dentro del catálogo:

# Qué se puede automatizar: disparadores, operadores y acciones registradas.
factuarea automations catalog show --json

# Los campos evaluables de un disparador concreto.
factuarea automations catalog trigger-fields invoice.paid --json

El alta de una regla va por el cuerpo JSON completo. actions es una lista de objetos, así que no se genera ninguna opción tipada para ella, y el binario se niega a mezclar opciones de campo con -d/--data-file — elige una. --skeleton imprime la plantilla del cuerpo sin llamar a la API:

factuarea automations rules create --skeleton

{
  "actions": [],
  "conditions": {
    "<key>": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "scope": "<empresa|cartera>",
  "trigger_type": "<string>"
}

# Rellénala y mándala entera. El `scope` se elige aquí y luego no se puede cambiar.
factuarea automations rules create --json -d '{
  "name": "Warn me on a large payment",
  "scope": "empresa",
  "trigger_type": "invoice.paid",
  "conditions": {"field": "total", "operator": "gte", "value": 1000},
  "actions": [
    {"type": "notify_in_app", "order": 0, "parameters": {
      "recipient_type": "role", "role": "admin", "category": "invoice",
      "title": "Large payment", "message": "An invoice over 1000 EUR has been paid"
    }}
  ]
}'

# Ensáyala contra un evento de ejemplo: devuelve la traza por paso y no materializa nada.
factuarea automations rules dry-run <rule_id> --json \
  -d '{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}'

# Una regla nace en draft y no dispara nada hasta que la actives.
factuarea automations rules activate <rule_id>
factuarea automations rules pause <rule_id>

# Léela y edítala — cada edición sella una versión nueva.
factuarea automations rules show <rule_id> --json
factuarea automations rules update <rule_id> --json -d '{"name":"Warn me on a payment over 2000"}'

# Lístalas con filtros, recorriendo el cursor por ti.
factuarea automations rules list --paginate --json
factuarea automations rules list --status active --trigger_type invoice.paid --json

# Solo las reglas de cartera de una gestoría.
factuarea automations rules list --scope cartera --json

# Las versiones selladas de la definición.
factuarea automations rules versions list <rule_id> --json
factuarea automations rules versions show <rule_id> 2 --json

# Qué ha disparado, y qué hizo cada paso.
factuarea automations runs list --paginate --json
factuarea automations runs list --automation_rule_id <rule_id> --status failed --json

# Qué hizo una regla de cartera sobre una empresa gestionada concreta.
factuarea automations runs list --subject_company_id <company_id> --json
factuarea automations runs show <run_id> --json
factuarea automations runs steps list <run_id> --json

# Consumo frente al presupuesto del plan para el periodo.
factuarea automations usage show --json

Cuatro listados paginan por cursor —rules list, rules versions list, runs list y runs steps list— y --paginate recorre todas las páginas por ti. El historial de versiones es el único cuyo cursor es una cadena numérica opaca en vez de un UUID, porque pagina por posición; devuelve el next_cursor que te dieron y no construyas uno a mano.

Tres comandos de este grupo son irreversibles y se niegan a adivinar:

# Relanzar vuelve a ejecutar DE VERDAD el trabajo aparcado: envía correo y entrega webhooks.
factuarea automations runs replay <run_id> --confirm <run_id>
factuarea automations runs steps replay <run_id> 0 --confirm 0

# Borrar una regla la deja sin disparar para siempre; sus versiones y ejecuciones siguen auditables.
factuarea automations rules delete <rule_id> --confirm <rule_id>

--confirm toma el último argumento posicional del comando: el id de la regla en rules delete, el id de la ejecución en runs replay y el índice del paso en runs steps replay. Sin terminal interactiva (o con --no-input) y sin --confirm, el comando sale con 2 en vez de adivinar. Además, toda mutación hecha con una clave fact_live_ necesita el flag explícito --live — consulta Modo de prueba y Operaciones irreversibles.

Descargas binarias y subidas

Los endpoints de PDF, ZIP y XML transmiten un binario que guardas con -o. Las subidas multipart toman el archivo con un flag --file-<campo>:

# Descargar un PDF
factuarea invoices pdf <uuid> -o invoice.pdf

# Subir un certificado (multipart)
factuarea verifactu certificates upload \
  -d '{"certificate_password":"…"}' --file-certificate_file cert.p12

El escape hatch `api`

Cualquier endpoint es accesible directamente con factuarea api <método> <ruta>, incluso los que aún no tienen un comando dedicado:

factuarea api get /v1/account --json
factuarea api post /v1/invoices -d '{…}'

El manifiesto de comandos

factuarea commands --json vuelca el manifiesto completo de comandos en una sola llamada — path, args, flags, si cada uno muta, si es binario o paginado, su scope requerido, si es irreversible, y un ejemplo. Un agente descubre toda la superficie en una sola llamada:

factuarea commands --json

Consulta Agentes y scripting para los campos del manifiesto y el contrato JSON.

Referencia de la API embebida

Una referencia rápida de la API viaja con el binario — las búsquedas no salen de tu máquina:

factuarea docs search invoice

docs search consulta la especificación OpenAPI embebida en el binario y responde a «¿qué comando llamo?». Devuelve operaciones — comando, resumen, método y ruta — y nunca toca la red.

Buscar en la documentación publicada

docs list, docs grep y docs get consultan la documentación publicada —el corpus llms-full de docs.factuarea.com— y responden a «¿qué dice la documentación sobre esto?». Devuelven páginas y secciones, de las guías, la referencia de la API y el catálogo de errores:

factuarea docs list                    # todas las páginas: <ruta> — <título>
factuarea docs list /guides            # solo las que cuelgan de ese prefijo
factuarea docs grep "idempotency-key"  # secciones de documentación que coinciden
factuarea docs get /guides/idempotency # la página entera, en Markdown

El corpus se descarga entero y una sola vez, se guarda en el directorio de caché del sistema (~/Library/Caches/factuarea/docs/ en macOS, ~/.cache/factuarea/docs/ en Linux) y se filtra en local. Mientras la copia tenga menos de 15 minutos, no hay ninguna petición de red, así que una sesión que encadene list, grep y get descarga una vez.

Tu término de búsqueda nunca sale de la máquina. La URL que se pide es fija y no depende de lo que teclees — no hay ningún servidor de búsqueda al otro lado. Ninguno de los cuatro subcomandos de docs lee ni envía una API key.

Opción	Qué hace
`--refresh`	Vuelve a descargar, ignorando una copia todavía vigente
`--lang`	Idioma de las guías: `en`, `es` o `ca` (por defecto `en`, el idioma fuente). La referencia de la API no se traduce y sale siempre
`--json`	Salida estable por stdout: `path`/`title` en `list`, `path`/`title`/`section`/`snippet` en `grep`, `path`/`title`/`markdown` en `get`

Si la descarga falla y hay una copia en caché —aunque esté caducada—, se usa esa copia, el aviso va a stderr para que el JSON de stdout siga siendo parseable, y el exit code es 0. Sin ninguna copia, el exit code es 10 (red). Apunta FACTUAREA_DOCS_URL a otro origen para descargar el corpus desde ahí.

Alternativa REST

El catálogo de comandos del CLI procede de su spec integrado. En la referencia de septiembre de 2026 está disponible la versión v0.2.0 y el spec de la rama principal contiene 414 entradas; faltan 38 endpoints REST en los comandos generados. Consulta factuarea commands --json para tu versión instalada. Usa el comando HTTP genérico para un endpoint REST disponible que falte en ese catálogo:

factuarea api get /v1/stores

En esta página