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 clients 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>

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

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.

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í.