# Referencia de comandos del CLI Consulta cada comando del CLI `ecuafact` con sus opciones, las variables de entorno que acepta y los códigos de salida para tus scripts. > [!IMPORTANT] > Ambiente de pruebas: sin validez fiscal. Los ejemplos que emiten usan el > entorno `sandbox`. ## Opciones globales Valen en cualquier comando. | Opción | Descripción | |---|---| | `-e`, `--entorno ` | `sandbox`, `produccion` u otro configurado. | | `-p`, `--perfil ` | Perfil de configuración. Por defecto, el activo. | | `-o`, `--salida ` | `tabla`, `json` o `csv`. Por defecto, tabla en la terminal y JSON si rediriges la salida. | | `--campos ` | Campos a mostrar, separados por coma. Admite rutas con punto (`estado,claveAcceso`). | | `-q`, `--silencioso` | Muestra solo el resultado y los errores. | | `--confirmar produccion` | Confirma sin preguntar una operación que escribe en producción. | | `--version` | Muestra la versión del CLI. | | `-h`, `--help` | Muestra la ayuda del comando. | ## Emisión ### ecuafact emitir Emite uno o varios comprobantes. Alias: `emit`. ```text ecuafact emitir [opciones] ``` | Opción | Descripción | |---|---| | `` | Archivos `.json` (objeto o array) o `.jsonl`, carpetas, o `-` para la entrada estándar. | | `-w`, `--esperar` | Espera el resultado del SRI. Por defecto, el valor de la clave `esperar`. | | `--espera-maxima ` | Tiempo máximo de espera, de 5 a 3600. Por defecto, 180. | | `--descargar ` | Descarga `ride`, `xml` o `ride,xml` al autorizarse. Implica `--esperar`. | | `-d`, `--destino ` | Carpeta de las descargas. Por defecto, la clave `carpetaDescargas` (la carpeta actual). | | `--plantilla ` | Plantilla para leer CSV o Excel ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). | | `--patron ` | En carpetas, archivos a leer separados por `;`. Por defecto, `*.json;*.jsonl;*.ndjson`. | | `-r`, `--recursivo` | En carpetas, incluye las subcarpetas. | | `--dry-run`, `--simular` | Valida y muestra lo que enviaría, sin enviar nada. | | `--continuar-con-errores` | Envía los válidos aunque otros tengan errores. | | `--reporte ` | Guarda el resultado de cada comprobante en un `.csv` o `.json`. | | `--mover-procesados ` | Mueve ahí los archivos enviados bien. | | `--mover-errores ` | Mueve ahí los archivos con errores, junto a su `.error.json`. | | `--concurrencia ` | Envíos simultáneos, de 1 a 10. Por defecto, la clave `concurrencia` (3). | | `--sin-verificar-cupo` | No compara el lote con el cupo antes de enviar. | ```bash ecuafact emitir factura.json --esperar --descargar ride --entorno sandbox ecuafact emitir ./pendientes -r --reporte resultado.csv --entorno sandbox ``` ### ecuafact validar Valida comprobantes sin enviarlos. Alias: `validate`. ```text ecuafact validar [--en-linea] [--plantilla ] [--patron ] [-r] ``` `--en-linea` comprueba además con la API que tu RUC y el tipo de comprobante estén habilitados. ### ecuafact nuevo Crea un comprobante de ejemplo. Alias: `new`. ```text ecuafact nuevo [-f, --archivo ] [--sobrescribir] ``` `` acepta `factura`, `liquidacion`, `nota-credito` (o `nc`), `nota-debito` (o `nd`), `guia`, `retencion` o el código, de `01` a `07`. ### ecuafact lote Consulta y reanuda las emisiones anteriores. Alias: `batch`. | Comando | Descripción | |---|---| | `lote listar [--limite ]` | Lista los lotes, del más reciente al más antiguo. Por defecto, 20. Alias: `ls`. | | `lote estado ` | Muestra el estado de cada comprobante del lote. | | `lote reanudar [--esperar] [--espera-maxima ] [--descargar ] [-d ]` | Reenvía los pendientes sin duplicar. Se ejecuta en el entorno del lote; `--descargar` implica `--esperar`. Alias: `resume`. | | `lote borrar ` | Borra el registro del lote. No afecta a los comprobantes. | ### ecuafact vigilar Emite cada archivo que aparece en una carpeta. Alias: `watch`. Guía: [Vigilar una carpeta](/v1/guias/cli-vigilar). ```text ecuafact vigilar [opciones] ecuafact vigilar instalar --nombre [opciones] ecuafact vigilar estado --nombre [--lineas ] ecuafact vigilar desinstalar --nombre ``` | Opción | Descripción | |---|---| | `--plantilla`, `--patron` | Igual que en `emitir`. | | `-w`, `--esperar` | Espera el resultado del SRI antes de mover el archivo. | | `--descargar `, `-d`, `--destino ` | Igual que en `emitir`; `--descargar` implica `--esperar`. | | `--intervalo ` | Cada cuánto revisa la carpeta, de 2 a 3600. Por defecto, 10. | | `--una-vez` | Revisa una vez y termina. El [código de salida](#codigos-de-salida) dice si algún archivo falló. | | `--nombre ` | Nombre del servicio (`instalar`, `estado`, `desinstalar`). | | `--usuario` | En Linux y macOS, usa un servicio de tu usuario, sin `sudo`. | | `--restringir-carpeta` | Al instalar, deja la carpeta solo para administradores y tu usuario. | | `--permitir-carpeta-compartida` | Al instalar, acepta una carpeta en la que puede escribir cualquier usuario del equipo, que así podría emitir con tu API Key. No es recomendable. | | `--lineas ` | En `estado`, las últimas líneas del registro del servicio. Por defecto, 15. | Alias de los subcomandos: `install`, `status` y `uninstall`. ### ecuafact plantilla Plantillas para emitir desde CSV o Excel. Alias: `template`. | Comando | Descripción | |---|---| | `plantilla nueva factura [-d ] [--sobrescribir]` | Crea una plantilla y un CSV de ejemplo. Alias: `new`. | | `plantilla probar --plantilla [--limite ]` | Muestra los comprobantes que saldrían del archivo, sin enviarlos. Por defecto, 3. | ## Consulta | Comando | Descripción | |---|---| | `estado ` | Muestra el seguimiento de una operación ([Seguimiento](/v1/guias/consulta-operacion)). Alias: `status`. | | `comprobantes listar [--desde] [--hasta] [--tipo] [--buscar] [--pagina ] [--tamano ] [--todas]` | Lista los comprobantes emitidos, del más reciente al más antiguo. Por defecto, los últimos 30 días, página 1 y 20 filas (máximo 100). `--todas` recorre todas las páginas. Alias: `ls`. | | `descargar [claveAcceso...] [--tipo ride,xml] [-d ] [--sobrescribir]` | Descarga el RIDE y el XML de comprobantes autorizados, como `.pdf` y `.xml`. Por defecto, solo el RIDE. Alias: `download`. | | `descargar --desde --hasta [--tipo-comprobante <01-07>]` | Sin claves, descarga todos los autorizados del período. | | `correo reenviar --a ` | Reenvía el comprobante por correo, hasta 20 direcciones separadas por coma. | | `cuenta` | Muestra tu integración y sus contribuyentes. Alias: `contexto`. | | `consumo` | Muestra tu cupo de documentos. Alias: `cupo`. | | `perfil-emisor ver` | Muestra los datos del emisor que salen en el RIDE ([Perfil del emisor](/v1/guias/perfil-emisor)). | | `perfil-emisor editar [--nombre-comercial] [--direccion-matriz] [--correo] [--telefono] [--ciudad] [--provincia]` | Cambia solo los datos que indicas. | | `perfil-emisor logo ` | Cambia el logo del RIDE. | `--ruc ` elige el contribuyente en `comprobantes`, `descargar` y `perfil-emisor`; acepta el RUC de 13 dígitos o la identificación de 10. Por defecto, el de tu perfil o el único habilitado. ```bash ecuafact perfil-emisor editar --correo facturacion@ejemplo.com --telefono 042345678 --entorno sandbox ecuafact descargar --desde 2026-10-01 --hasta 2026-10-31 --tipo ride,xml -d ./octubre --entorno sandbox ``` ## Consultas al SRI | Comando | Descripción | |---|---| | `ruc consultar ` | Muestra los datos de un contribuyente. | | `ruc buscar --apellidos [--nombres ] [--clase ] [--max ]` | Busca contribuyentes por nombre. `--clase` acepta `PersonaNatural` (por defecto), `Sociedad` o `SociedadPublica`; `--max`, de 1 a 30 (por defecto, 10). | | `identificacion validar ` | Valida una cédula, un RUC o un pasaporte. Alias del grupo: `cedula`. | | `clave decodificar ` | Descompone una clave de acceso. | | `establecimientos [--filtro ]` | Lista los establecimientos de un RUC. `--filtro` acepta `Todos` (por defecto), `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. | | `catalogos [nombre]` | Muestra un catálogo del SRI: `tipos-identificacion`, `formas-pago`, `tipos-comprobante`, `tipos-impuesto`, `tarifas-iva` o `tarifas-ice`. Sin nombre, los lista. | ## Webhooks Estos comandos prueban tu endpoint de [webhooks](/v1/guias/webhooks) y no llaman a la API. Los dos leen el secreto del destino de la variable `ECUAFACT_WEBHOOK_SECRET`, o de la entrada estándar con `--secreto-desde-stdin`. ### ecuafact webhooks probar Envía a tu endpoint un evento de ejemplo firmado y muestra lo que respondió. Alias: `test`. El evento lleva las mismas cabeceras de firma que una entrega real, `Ecuafact-Signature` y las de Standard Webhooks, así que sirve para probar tu endpoint con cualquiera de los dos esquemas. | Opción | Descripción | |---|---| | `--a ` | URL de tu endpoint. | | `--evento ` | `document.authorized` (por defecto), `document.rejected`, `document.failed` u `operation.requires_attention`. | | `--motivo ` | En `document.failed`: `entrega_no_posible` (por defecto), `emisor_no_vinculado`, `estructura_invalida`, `plan_agotado`, `resultado_desconocido` o `suscripcion_inactiva`. | | `--clave-acceso ` | Clave de acceso del cuerpo. Por defecto, una de ejemplo. | | `--id-operacion ` | `idOperacion` del cuerpo. Por defecto, uno nuevo en cada envío. | | `--firma-invalida` | Envía una firma incorrecta, para comprobar que tu endpoint la rechaza con un 401. | | `--secreto-desde-stdin` | Lee el secreto de la entrada estándar. | ```bash ecuafact webhooks probar --a http://localhost:5000/webhooks ecuafact webhooks probar --a http://localhost:5000/webhooks --evento document.failed --motivo plan_agotado ``` ### ecuafact webhooks verificar Comprueba la firma de un webhook que ya recibiste. Alias: `verify`. Verifica la cabecera `Ecuafact-Signature` con `--firma`, o las tres cabeceras de [Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks) con `--webhook-id`, `--webhook-timestamp` y `--webhook-signature` juntas; no se pueden combinar los dos esquemas en la misma llamada. El resultado indica en `esquema` cuál verificó. | Opción | Descripción | |---|---| | `--firma ` | Valor de la cabecera `Ecuafact-Signature` (`t=...,v1=...`). | | `--webhook-id ` | Valor de la cabecera `webhook-id`. | | `--webhook-timestamp ` | Valor de la cabecera `webhook-timestamp`. | | `--webhook-signature ` | Valor de la cabecera `webhook-signature` (`v1,...`). | | `--cuerpo <@archivo>` | Cuerpo crudo, desde un archivo o `-` para la entrada estándar. | | `--tolerancia ` | Diferencia admitida con la marca de tiempo. Por defecto, 300. | | `--ahora ` | Instante de comparación en segundos Unix, para revisar un evento antiguo. Por defecto, ahora. | | `--secreto-desde-stdin` | Lee el secreto de la entrada estándar. | ```bash ecuafact webhooks verificar --firma "t=1791385446,v1=a1ae..." --cuerpo @evento.json --ahora 1791385446 ecuafact webhooks verificar --webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b --webhook-timestamp 1791385446 --webhook-signature "v1,6Ygt..." --cuerpo @evento.json --ahora 1791385446 ``` ## Configuración ### ecuafact login Guarda la API Key del perfil y el entorno actuales. Sin opciones, la pide sin mostrarla. ```text ecuafact login [--desde-stdin] [--sin-verificar] ``` | Opción | Descripción | |---|---| | `--desde-stdin` | Lee la API Key de la entrada estándar, para scripts. | | `--sin-verificar` | Guarda la API Key sin probarla contra la API. | ```bash ecuafact login --entorno sandbox echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox ``` ### Otros comandos de configuración | Comando | Descripción | |---|---| | `logout` | Borra la API Key guardada del perfil y el entorno. | | `sesion` | Muestra el perfil, el entorno y de dónde sale la API Key, sin mostrarla. Alias: `whoami`. | | `config ver` | Muestra la configuración efectiva y de dónde sale cada valor. | | `config obtener `, `poner `, `quitar ` | Lee, guarda o borra una clave del perfil. Alias: `get`, `set`, `unset`. | | `config claves` | Lista las claves, su variable de entorno y su valor por defecto. | | `config ruta` | Muestra dónde está el archivo de configuración de tu usuario. | | `perfil usar `, `listar`, `borrar ` | Activa (o crea), lista o borra perfiles. Alias de `listar`: `ls`. | | `entorno listar`, `agregar --api [--produccion]`, `quitar ` | Gestiona entornos propios. `--produccion` hace que el entorno pida confirmación al escribir, como `produccion`. | | `doctor [--sin-ip-publica]` | Revisa la versión, la configuración, la conexión, la API Key, la IP, el cupo y los contribuyentes. Si la autenticación falla, consulta tu IP pública en `api.ipify.org`; `--sin-ip-publica` evita esa consulta. | ### Claves y variables de entorno | Clave | Variable de entorno | Descripción | |---|---|---| | `entorno` | `ECUAFACT_ENTORNO` | Entorno por defecto. Por defecto, `produccion`. | | `ruc` | `ECUAFACT_RUC` | RUC por defecto. | | `establecimiento` | `ECUAFACT_ESTABLECIMIENTO` | Establecimiento por defecto. | | `puntoEmision` | `ECUAFACT_PUNTO_EMISION` | Punto de emisión por defecto. | | `salida` | `ECUAFACT_SALIDA` | Formato de salida: `auto` (por defecto: tabla en la terminal y JSON si rediriges), `tabla`, `json` o `csv`. | | `concurrencia` | `ECUAFACT_CONCURRENCIA` | Envíos simultáneos. Por defecto, 3. | | `carpetaDescargas` | `ECUAFACT_CARPETA_DESCARGAS` | Carpeta de las descargas. | | `esperar` | `ECUAFACT_ESPERAR` | Con `true`, todos los `emitir` esperan el resultado del SRI. | | `descargar` | `ECUAFACT_DESCARGAR` | Archivos a descargar al autorizarse en todos los `emitir`; también activa la espera. | Además, `ECUAFACT_API_KEY` define la API Key y tiene prioridad sobre la guardada, y `ECUAFACT_PERFIL` elige el perfil. ### Precedencia y ecuafact.json Cada valor sale del primero que lo defina, en este orden: 1. La opción del comando (`--entorno`, `--salida`, `--perfil`). 2. La variable de entorno `ECUAFACT_*`. 3. Un archivo `ecuafact.json` en la carpeta actual o en una superior. 4. Tu perfil (`config poner`). 5. El valor por defecto. `ecuafact.json` fija la configuración de un proyecto y se puede guardar en tu repositorio, porque nunca lleva la API Key. Como tiene prioridad sobre tu perfil, si `config poner` parece no tener efecto, revisa si hay uno con `ecuafact config ver`. ```json { "perfil": "empresa-b", "entorno": "sandbox", "ruc": "0123456789001", "salida": "json" } ``` ## Otros comandos | Comando | Descripción | |---|---| | `api [--datos @archivo] [--idempotency-key ] [--archivo-salida ]` | Llama a cualquier ruta de la API con tu API Key y muestra la respuesta tal cual. Para emitir, pasa una `--idempotency-key` estable (`auto` genera una nueva en cada llamada). `--archivo-salida` es necesario para PDF y XML. | | `schema [comando]` | Describe el CLI en JSON, para scripts y agentes de IA. | | `docs [tema] [--imprimir]` | Abre esta documentación en el navegador; con `--imprimir`, solo muestra la URL. | | `ayuda [tema]` | Muestra guías breves que funcionan sin conexión. | ## Códigos de salida | Código | Significado | |---|---| | `0` | El comando terminó bien. | | `1` | Error general, de red o del servidor. | | `2` | Uso incorrecto del comando. | | `3` | Falló la autenticación, la IP o el permiso. | | `4` | Error de validación. | | `5` | El SRI rechazó el comprobante. | | `6` | Se superó el límite de solicitudes o no hay cupo. | | `7` | Resultado parcial: unos elementos salieron bien y otros no. | | `8` | No encontrado o en conflicto. | En los comandos que procesan varios elementos, el código resume el lote. En `emitir` y `lote reanudar` es 0 si ningún comprobante falló, 7 si unos salieron bien y otros no, y el código del primer fallo si ninguno salió bien (por ejemplo, 5 si el SRI rechazó todos). El 0 incluye los comprobantes en `enviado` o `en_proceso`, que todavía no tienen el resultado del SRI, así que no los des por autorizados: usa `--esperar` o revisa el estado de cada uno con `--reporte`. `vigilar --una-vez` sigue el mismo criterio con los archivos de la carpeta, y `descargar` devuelve 7 si solo fallaron algunas descargas. Cuando el CLI no se ejecuta en una terminal, por ejemplo desde un script, escribe el resultado en JSON por la salida estándar y los errores, también en JSON, por la salida de errores. Un error de la API se ve así: ```json { "error": "Credenciales invalidas.", "estadoHttp": 401, "codigo": "101", "idCorrelacion": "0HN7A2B3C4D5E:00000001", "codigoSalida": 3, "sugerencia": "Revisa la API Key ('ecuafact sesion') y que la IP publica de este equipo este registrada en el portal (Cuenta > IP permitidas). 'ecuafact doctor' muestra la IP detectada." } ``` | Campo | Descripción | |---|---| | `error` | Mensaje del error. | | `codigoSalida` | El mismo código con el que termina el comando. | | `sugerencia` | Qué hacer, cuando el CLI lo sabe. | | `estadoHttp`, `codigo` | Solo si el error vino de la API: el estado HTTP y el [código del error](/v1/guias/errores). | | `errores` | Solo si la API devolvió detalle de validación. | | `idCorrelacion` | Solo si el error vino de la API. Inclúyelo si escribes a soporte. | ## Siguientes pasos - [CLI de Ecuafact](/v1/guias/cli): instala el CLI y emite tu primera factura. - [Emitir con el CLI](/v1/guias/cli-emision): emite lotes y carpetas y descarga sus archivos.