<!-- source_url: https://docs.mynexusapi.com/v1/guias/cli-referencia | last_updated: 2026-11-13 -->

# 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 <entorno>` | `sandbox`, `produccion` u otro que hayas agregado con `entorno agregar` ([Cambiar de ambiente o de URL](#cambiar-de-ambiente-o-de-url)). |
| `-p`, `--perfil <perfil>` | Perfil de configuración. Por defecto, el activo. |
| `-o`, `--salida <formato>` | `tabla`, `json` o `csv`. Por defecto, tabla en la terminal y JSON si rediriges la salida. |
| `--campos <lista>` | Campos a mostrar, separados por coma. Admite rutas con punto (`estado,claveAcceso`). |
| `-q`, `--silencioso` | Muestra solo el resultado y los errores. |
| `--confirmar <entorno>` | Confirma sin preguntar una operación que escribe en producción. El valor es el nombre del entorno de producción: `produccion` o, en un entorno propio marcado con `--produccion`, su nombre. |
| `--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 <entradas...> [opciones]
```

El tipo (`01` factura, `03` liquidación de compra, `04` nota de crédito, `05`
nota de débito, `06` guía de remisión o `07` retención) elige la ruta de emisión
y no se envía en el cuerpo. Sale de `--tipo` o de la forma del comprobante (en un XML, de su raíz), como se explica en
[Emitir con el CLI](/v1/guias/cli-emision). Si no se puede decidir o hay
contradicción, el comprobante se rechaza antes de enviarlo con código de salida
2.

| Opción | Descripción |
|---|---|
| `<entradas...>` | Archivos `.json` (objeto o array), `.jsonl`, `.xml` (XML del SRI), `.csv` o `.xlsx` (con `--plantilla`), carpetas, o `-` para la entrada estándar. |
| `-w`, `--esperar` | Espera el resultado del SRI. Por defecto, el valor de la clave `esperar`. |
| `--espera-maxima <segundos>` | Tiempo máximo de espera, de 5 a 3600. Por defecto, 180. |
| `--descargar <tipos>` | Descarga `ride`, `xml` o `ride,xml` al autorizarse. Implica `--esperar`. |
| `-d`, `--destino <carpeta>` | Carpeta de las descargas. Por defecto, la clave `carpetaDescargas` (la carpeta actual). |
| `--tipo <tipo>` | Tipo de los comprobantes: `factura`, `liquidacion`, `nota-credito` (`nc`), `nota-debito` (`nd`), `guia`, `retencion`, o `01`, `03`, `04`, `05`, `06`, `07`. Sin la opción se deduce de la forma del comprobante. Si el archivo trae `infoTributaria.tipoDocumento`, el CLI avisa y lo quita al enviar. |
| `--plantilla <archivo>` | Plantilla para leer CSV o Excel ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). |
| `--patron <patrones>` | En carpetas, archivos a leer separados por `;`. Por defecto, `*.json;*.jsonl;*.ndjson;*.xml`. Para leer CSV o Excel de una carpeta, agrega `*.csv` o `*.xlsx`. |
| `-r`, `--recursivo` | En carpetas, incluye las subcarpetas. |
| `--validar-antes` | Antes de emitir, valida cada comprobante en la API (una petición más por comprobante). El que no cumple queda `invalido` y no se emite; las advertencias no bloquean. Por defecto, la clave `validarAntes` (`false`): sin esta opción se emite directo y la API responde 422 con los errores. |
| `--dry-run`, `--simular` | Valida cada comprobante en la API con las reglas de la emisión ([Validar sin emitir](/v1/guias/emision#validar-sin-emitir)) y muestra lo que enviaría, sin emitir nada. |
| `--continuar-con-errores` | Envía los válidos aunque otros tengan errores. |
| `--reporte <archivo>` | Guarda el resultado de cada comprobante en un `.csv` o `.json`. |
| `--mover-procesados <carpeta>` | Mueve ahí los archivos enviados bien. |
| `--mover-errores <carpeta>` | Mueve ahí los archivos con errores, junto a su `.error.json`. |
| `--concurrencia <n>` | 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 en la API sin emitirlos. Alias: `validate`.

```text
ecuafact validar <entradas...> [--tipo <tipo>] [--plantilla <archivo>] [--patron <patrones>] [-r]
```

`--tipo` funciona igual que en `emitir`. `validar` siempre envía cada comprobante
a la API, en la ruta de validación de su tipo, con todas las reglas de la
emisión, como se explica en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir). Un comprobante que la
API acepta queda en estado `valido`, con sus `advertencias` si las trae; uno que
no cumple queda `invalido` con los `errores` de la API. No emite ni consume cupo.
Localmente solo se comprueba que el archivo se pueda leer o convertir y que el
tipo permita elegir la ruta.

### ecuafact nuevo

Crea un comprobante de ejemplo. Alias: `new`.

```text
ecuafact nuevo <tipo> [-f, --archivo <archivo>] [--sobrescribir]
```

`<tipo>` 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 <n>]` | Lista los lotes, del más reciente al más antiguo. Por defecto, 20. Alias: `ls`. |
| `lote estado <lote>` | Muestra el estado de cada comprobante del lote. |
| `lote reanudar <lote> [--esperar] [--espera-maxima <segundos>] [--descargar <tipos>] [-d <carpeta>]` | Reenvía los pendientes sin duplicar. Se ejecuta en el entorno del lote; `--descargar` implica `--esperar`. Alias: `resume`. |
| `lote borrar <lote>` | 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 <carpeta> [opciones]
ecuafact vigilar instalar <carpeta> --nombre <nombre> [opciones]
ecuafact vigilar estado --nombre <nombre> [--lineas <n>]
ecuafact vigilar desinstalar --nombre <nombre>
```

| Opción | Descripción |
|---|---|
| `--plantilla`, `--patron` | Igual que en `emitir`. Con `--plantilla`, el patrón por defecto incluye también `*.csv` y `*.xlsx`. |
| `--validar-antes` | Valida cada comprobante en la API antes de emitirlo; el que no cumple va a `errores/`. Por defecto, la clave `validarAntes` (`false`). |
| `-w`, `--esperar` | Espera el resultado del SRI antes de mover el archivo. |
| `--descargar <tipos>`, `-d`, `--destino <carpeta>` | Igual que en `emitir`; `--descargar` implica `--esperar`. |
| `--intervalo <segundos>` | 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>` | Nombre del servicio (`instalar`, `estado`, `desinstalar`). |
| `--usuario` | En Linux y macOS, usa un servicio de tu usuario, sin `sudo`. Va en `instalar`, `estado` y `desinstalar`. |
| `--restringir-carpeta` | Al instalar, deja la carpeta solo para administradores y tu usuario. |
| `--permitir-carpeta-compartida` | En primer plano o al instalar, acepta que otros usuarios con permiso de escritura en la carpeta puedan emitir con tu API Key. |
| `--lineas <n>` | 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 <carpeta>] [--sobrescribir]` | Crea una plantilla y un CSV de ejemplo. Alias: `new`. |
| `plantilla probar <archivo> --plantilla <archivo> [--limite <n>] [--tipo <tipo>]` | Muestra los comprobantes que saldrían del archivo, sin enviarlos. Por defecto, 3. |

## Consulta

| Comando | Descripción |
|---|---|
| `estado <idOperacion>` | Muestra el seguimiento de una operación ([Seguimiento](/v1/guias/consulta-operacion)). Alias: `status`. |
| `operaciones listar [opciones]` | Lista los comprobantes de un contribuyente y un período ([Listado](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente)). Alias: `ls`. |
| `descargar <claveAcceso...> [--tipo ride,xml] [-d <carpeta>] [--sobrescribir]` | Descarga el RIDE y el XML de comprobantes autorizados, como `<claveAcceso>.pdf` y `<claveAcceso>.xml`. Por defecto, solo el RIDE. Alias: `download`. |
| `cuenta` | Muestra tu integración y sus contribuyentes. Alias: `contexto`. |
| `consumo` | Muestra tu cupo de documentos. Cada comprobante autorizado o rechazado consume un documento y uno cancelado lo libera. 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 <archivo>` | Cambia el logo del RIDE. Acepta PNG o JPEG de hasta 512 KB. |

`--ruc <ruc>` elige el contribuyente en los comandos que lo admiten, como
`perfil-emisor`; acepta la identificación completa que devuelve `GET /v1/contexto`,
por ejemplo el RUC de 13 dígitos. Por defecto, usa el de tu perfil o el único
habilitado.

```bash
ecuafact perfil-emisor editar --correo facturacion@ejemplo.com --telefono 042345678 --entorno sandbox
ecuafact descargar <claveAcceso> --tipo ride,xml -d ./octubre --entorno sandbox
```

### ecuafact operaciones listar

Lista los comprobantes de un contribuyente y un período, con paginación. Alias:
`ls`.

```text
ecuafact operaciones listar [--identificacion <identificacion>] [--desde <yyyy-MM-dd>]
  [--hasta <yyyy-MM-dd>] [--tipo <codigo>] [--buscar <texto>] [--pagina <n>]
  [--tamano <n>] [--json] [--csv]
```

| Opción | Descripción |
|---|---|
| `--identificacion <identificacion>` | Identificación del contribuyente, la misma de `GET /v1/contexto`. Si la omites, el comando usa el único contribuyente habilitado; con varios, se detiene y te pide esta opción, sin elegir uno. |
| `--desde <yyyy-MM-dd>`, `--hasta <yyyy-MM-dd>` | Fechas del período. Sin ninguna de las dos, la API usa los últimos 30 días. El rango máximo es de 366 días. |
| `--tipo <codigo>` | `01` factura, `03` liquidación de compra, `04` nota de crédito, `05` nota de débito, `06` guía de remisión o `07` retención. |
| `--buscar <texto>` | Texto libre de hasta 100 caracteres. |
| `--pagina <n>` | Página desde 1. Por defecto, 1. |
| `--tamano <n>` | Comprobantes por página, de 1 a 100. Por defecto, 20. |
| `--json` | Equivale a `--salida json`; devuelve la página completa, con `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`. |
| `--csv` | Equivale a `--salida csv`; escribe una fila por comprobante. |

La tabla muestra el número, el tipo, la fecha, el estado, el `codEstado`, el
total, la identificación de la contraparte y la clave de acceso. Si la respuesta
trae `hayMas` en `true`, repite el comando con `--pagina` una unidad mayor; el
mensaje de resumen te indica cuál. `--json` y `--csv` no se pueden combinar en la
misma llamada.

```bash
ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox
ecuafact operaciones listar --identificacion 0123456789001 --buscar FAC --pagina 2 --tamano 50 --json
ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv
```

## Consultas al SRI

| Comando | Descripción |
|---|---|
| `ruc consultar <identificacion> [--fusionar <true\|false>] [--fuente <fuente>]` | Muestra los datos de un contribuyente. `--fusionar` combina las fuentes (por defecto, `true`) y `--fuente` acepta `Todas` (por defecto) o `SriCatastro`. |
| `ruc buscar --apellidos <texto> [--nombres <texto>] [--clase <clase>] [--max <n>]` | Busca contribuyentes por nombre. `--clase` acepta `PersonaNatural` (por defecto), `Sociedad` o `SociedadPublica`; `--max`, de 1 a 30 (por defecto, 10). |
| `identificacion validar <numero>` | Valida una cédula, un RUC o un pasaporte. Alias del grupo: `cedula`. |
| `clave decodificar <claveAcceso>` | Descompone una clave de acceso. |
| `establecimientos <ruc> [--filtro <filtro>]` | Lista los establecimientos de un RUC. `--filtro` acepta `Todos` (por defecto), `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. |

## Estado del servicio y catálogos

`salud` y `estado-servicio` no requieren API Key ni sesión: consultan `GET /salud` y `GET /estado`. `catalogos` consulta
`GET /v1/catalogos` y `GET /v1/catalogos/{nombre}` con la API Key del perfil y el entorno actuales.

| Comando | Descripción |
|---|---|
| `salud` | Comprueba que el servicio responde (`GET /salud`, sin API Key). |
| `estado-servicio` | Muestra el estado público del servicio: el estado general, la disponibilidad de los últimos 90 días, el estado de cada componente y los incidentes. Alias: `servicio`. Con `--salida json` devuelve la respuesta completa. |
| `catalogos [nombre]` | Sin nombre, lista los catálogos del SRI con su clave y descripción. Con el nombre de un catálogo (por ejemplo `tarifas-iva`), muestra sus filas: código, descripción, valor y vigencia. En JSON conserva también `fuente` y los `atributos` de cada fila. Alias: `catalogo`. |

```bash
ecuafact estado-servicio
ecuafact estado-servicio --salida json --campos estado,disponibilidad90Dias
ecuafact catalogos
ecuafact catalogos tarifas-iva
ecuafact catalogos tarifas-iva --salida json --campos items
```

Si el nombre del catálogo no existe, el comando termina con el código de salida 8. Si `catalogos`
se ejecuta sin API Key, termina con el código 3.

## Webhooks

El grupo `webhooks destinos` administra los destinos por API con la API Key del
perfil y el entorno actuales. `webhooks probar` y `webhooks verificar` trabajan
con tu endpoint 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 destinos

Administra los destinos de [webhooks](/v1/guias/webhooks#administrar-destinos-por-api).
Las operaciones que escriben piden confirmación en producción, como el resto de
comandos del CLI.

| Comando | Descripción |
|---|---|
| `destinos listar` | Lista los destinos que puede ver la API Key (`GET /v1/webhooks/destinos`). Alias: `ls`. |
| `destinos crear --url <url> [--eventos <lista>] [--ruc <ruc>] [--mostrar-secreto]` | Crea un destino (`POST /v1/webhooks/destinos`). `--url` exige HTTPS en el puerto 443, sin credenciales ni fragmento. `--eventos` acepta una lista separada por coma; por defecto, los cuatro eventos. `--ruc` limita el destino a ese contribuyente. |
| `destinos ver <id>` | Muestra un destino (`GET /v1/webhooks/destinos/{id}`). Alias: `obtener`. |
| `destinos eventos <id> --eventos <lista>` | Reemplaza los eventos suscritos del destino (`PUT .../eventos`). Alias: `actualizar`. |
| `destinos probar-destino <id>` | Pide a la plataforma que envíe un evento de prueba firmado al destino registrado (`POST .../probar`). Para probar cualquier URL desde tu equipo usa `webhooks probar`. |
| `destinos pausar <id>` | Pausa las entregas nuevas (`POST /v1/webhooks/destinos/{id}/pausar`). |
| `destinos reanudar <id>` | Reactiva un destino pausado (`POST .../reanudar`). |
| `destinos rotar <id> [--mostrar-secreto]` | Genera un secreto nuevo y lo devuelve una vez (`POST .../rotar-secreto`). |
| `destinos entregas <id>` | Lista las últimas 50 entregas (`GET .../entregas`). |
| `destinos intentos <id> <entregaId>` | Lista los intentos de una entrega (`GET .../entregas/{entregaId}/intentos`). `entregaId` es el campo `publicId` de la entrega. |
| `destinos reintentar <id> <eventoId>` | Reenvía un evento ahora (`POST .../entregas/{eventoId}/reintentar`). `eventoId` es el campo `eventId` de la entrega. |
| `destinos deshabilitar <id>` | Da de baja el destino; no se puede reactivar (`POST .../deshabilitar`). |

`<id>` es el `publicId` del destino. `crear` y `rotar` devuelven el secreto una
sola vez: en la salida de tabla se muestra, y con `--salida json` o
`--salida csv` solo aparece si agregas `--mostrar-secreto`. El CLI no guarda el
secreto en ningún archivo ni lo escribe en un mensaje, así que cópialo y
guárdalo en tu servidor en ese momento.

```bash
ecuafact webhooks destinos listar --entorno sandbox
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact --entorno sandbox
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact \
  --eventos document.authorized,document.failed --ruc 0123456789001 --entorno sandbox
ecuafact webhooks destinos pausar <idDestino> --entorno sandbox
ecuafact webhooks destinos rotar <idDestino> --entorno sandbox
ecuafact webhooks destinos entregas <idDestino> --entorno sandbox
ecuafact webhooks destinos reintentar <idDestino> <eventoId> --entorno sandbox
ecuafact webhooks destinos deshabilitar <idDestino> --entorno sandbox
```

### 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>` | URL de tu endpoint. Exige HTTPS, sin credenciales ni fragmento; HTTP solo se acepta en `localhost`. Si tu endpoint no responde con un código de éxito, el comando termina con el código de salida 1. |
| `--evento <evento>` | `document.authorized` (por defecto), `document.rejected`, `document.failed` u `operation.requires_attention`. |
| `--cod-estado <codEstado>` | `codEstado` del cuerpo, un número de 4 dígitos. Solo admite las combinaciones que puede traer un evento real, que se detallan después de esta tabla. El `estado`, el `msgError` y `errores` del cuerpo se ajustan al código. |
| `--clave-acceso <clave>` | Clave de acceso del cuerpo. Por defecto, una de ejemplo. |
| `--id-operacion <id>` | `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. |

Cada evento admite solo los códigos con los que te llega en una entrega real.
`document.authorized` lleva siempre 2001. Con `document.rejected` puedes usar 3001, el rechazo del SRI, que es el valor
por defecto y llega con un mensaje del SRI de ejemplo en `errores`, o 4002, la
firma electrónica no válida. Con `document.failed` puedes usar 3002, 4001, 4002, 4003, 4004,
5001, 5006, que es el valor por defecto, o 5007. Con
`operation.requires_attention`, si no indicas `--cod-estado` recibes el evento
de prueba del portal, con `probe` en `"true"`. Si indicas 1001, o 1002 para
que traiga `claveAcceso`, recibes el aviso de que el comprobante sigue
`recibido` sin un resultado confirmado, con el motivo en `errores`. No hay
opción para 6001, porque un comprobante cancelado no genera evento. Si pides una combinación que
no existe, el comando termina con el código de salida 2 y no envía nada. Qué
significa cada código se explica en
[Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion).

```bash
ecuafact webhooks probar --a http://localhost:5000/webhooks
ecuafact webhooks probar --a http://localhost:5000/webhooks --evento document.failed --cod-estado 4002
ecuafact webhooks probar --a http://localhost:5000/webhooks --evento operation.requires_attention --cod-estado 1001
```

### 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>` | Valor de la cabecera `Ecuafact-Signature` (`t=...,v1=...`). |
| `--webhook-id <id>` | Valor de la cabecera `webhook-id`. |
| `--webhook-timestamp <segundos>` | Valor de la cabecera `webhook-timestamp`. |
| `--webhook-signature <firma>` | Valor de la cabecera `webhook-signature` (`v1,...`). |
| `--cuerpo <@archivo>` | Cuerpo crudo, desde un archivo o `-` para la entrada estándar. |
| `--tolerancia <segundos>` | Diferencia admitida con la marca de tiempo. Por defecto, 300. |
| `--ahora <segundos>` | 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
```

El resultado trae `valida`, `esquema`, `motivo`, `detalle`, `marca` (la marca
de tiempo de la firma) y `edadSegundos`. Si la firma es válida, `motivo` es
`null` y el comando termina con 0. Si no lo es, termina con 4 y `motivo` te dice
la causa, mientras `detalle` la explica:

| `motivo` | Qué pasó | Qué hacer |
|---|---|---|
| `cabecera_invalida` | La cabecera no trae `t` y `v1`, o faltan `webhook-id` o `webhook-timestamp` válidos. | Copia las cabeceras completas de la entrega. |
| `secreto_invalido` | El secreto no tiene el formato esperado para Standard Webhooks. | Copia el secreto completo desde el portal, con o sin el prefijo `whsec_`. |
| `firma_no_coincide` | La firma no corresponde a ese secreto y ese cuerpo. | Revisa que uses el secreto del destino correcto y el cuerpo exactamente como llegó, sin reformatearlo ni cambiar los fines de línea. |
| `fuera_de_tolerancia` | La firma es correcta, pero la marca de tiempo está fuera de la tolerancia. | Para revisar un evento antiguo, pasa `--ahora` con su marca de tiempo. |

## 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, la URL de la API y de dónde sale la API Key, sin mostrarla. Termina con el código 3 si no hay API Key. Alias: `whoami`. |
| `config ver` | Muestra la configuración efectiva, la URL de la API en uso y de dónde sale cada valor. |
| `config obtener <clave>`, `poner <clave> <valor>`, `quitar <clave>` | 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 <nombre>`, `listar`, `borrar <nombre>` | Activa (o crea), lista o borra perfiles. Alias de `listar`: `ls`. |
| `entorno listar`, `agregar <nombre> --api <url> [--produccion]`, `quitar <nombre>` | Lista los entornos y cuál está en uso, y agrega o quita entornos propios. `--produccion` hace que el entorno pida confirmación al escribir, como `produccion`. Alias de `listar`: `ls`. |
| `doctor [--sin-ip-publica]` | Revisa la versión, la configuración, el entorno (y de dónde sale), la conexión, el reloj, la API Key, la IP, el cupo y los contribuyentes. Termina con el código 1 si alguna revisión falla. Si la autenticación falla, consulta tu IP pública en `api.ipify.org`; `--sin-ip-publica` evita esa consulta. |

### Cambiar de ambiente o de URL

Para elegir el ambiente, usa `--entorno sandbox` o `--entorno produccion` en un
comando, define la variable `ECUAFACT_ENTORNO` o déjalo fijo en tu perfil con
`ecuafact config poner entorno <nombre>`. Si necesitas apuntar a otro servidor,
agrega un entorno propio con `ecuafact entorno agregar <nombre> --api <url>`.
La URL debe usar HTTPS, salvo `localhost`, y `sandbox` y `produccion` no se
pueden redefinir. Con `--produccion`, el entorno propio pide confirmación al
escribir y, en un script, se confirma con `--confirmar <nombre>`.

Cada entorno guarda su propia API Key: ejecuta `login` en cada uno, y el CLI
solo envía la API Key guardada al entorno con el que la guardaste. Si cambias la
URL de un entorno propio con `entorno agregar`, el CLI borra las API Key
guardadas para ese entorno y debes ejecutar `login` de nuevo.

Cuando prefieres no guardar la API Key, defínela en la variable
`ECUAFACT_API_KEY`. Como la entregas tú de forma explícita, el CLI la usa con
cualquier URL (`sandbox`, `produccion`, un entorno propio o una URL definida con
`ECUAFACT_API_URL`) y tiene prioridad sobre la guardada. Por eso conviene
definirla solo en el proceso que la necesita y comprobar a qué URL apunta con
`ecuafact sesion`, que muestra el entorno, la URL y el prefijo de la clave.

La variable `ECUAFACT_API_URL` reemplaza la URL del entorno actual y sirve para
apuntar a otro servidor, por ejemplo uno local. El entorno conserva su nombre y
su comportamiento, así que con `produccion` sigue pidiendo confirmación. Con
`ECUAFACT_API_URL` el CLI no usa la API Key guardada, porque ya no apunta al
entorno con el que la guardaste: si no defines `ECUAFACT_API_KEY`, el comando
termina con el código de salida 3 y te indica que la definas.

| Quieres usar | Qué API Key envía el CLI |
|---|---|
| `sandbox` o `produccion` | La de `ECUAFACT_API_KEY`; si no existe, la guardada con `login` en ese entorno. |
| Un entorno propio (`entorno agregar`) | La de `ECUAFACT_API_KEY`; si no existe, la guardada con `login --entorno <nombre>`. |
| Cualquier entorno con `ECUAFACT_API_URL` | Solo la de `ECUAFACT_API_KEY`. |

```bash
ecuafact entorno agregar pruebas --api https://api.ejemplo.com
ecuafact entorno listar
echo "$API_KEY" | ecuafact --entorno pruebas login --desde-stdin
ecuafact --entorno pruebas consumo

export ECUAFACT_API_URL=http://localhost:5000
export ECUAFACT_API_KEY="..."
ecuafact --entorno sandbox consumo
```

### Claves y variables de entorno

| Clave | Variable de entorno | Descripción |
|---|---|---|
| `entorno` | `ECUAFACT_ENTORNO` | Entorno por defecto: `sandbox`, `produccion` o uno propio. Por defecto, `produccion`. |
| `ruc` | `ECUAFACT_RUC` | Identificación completa del contribuyente por defecto, como la devuelve `GET /v1/contexto` (por ejemplo, el RUC de 13 dígitos). |
| `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. |
| `validarAntes` | `ECUAFACT_VALIDAR_ANTES` | Con `true`, todos los `emitir` y `vigilar` validan cada comprobante en la API antes de emitirlo. Por defecto, `false`. |

Además, `ECUAFACT_API_KEY` define la API Key y tiene prioridad sobre la
guardada, `ECUAFACT_API_URL` cambia la URL de la API ([Cambiar de ambiente o de URL](#cambiar-de-ambiente-o-de-url)) y `ECUAFACT_PERFIL` elige el perfil. `ECUAFACT_MAX_RESPUESTA_BYTES`
cambia el tamaño máximo, en bytes, de una respuesta de la API (por defecto, 64
MiB); `0` quita el tope. Si una respuesta lo supera, el comando termina con un
error que lo indica.

### 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, hasta la raíz Git más próxima o tu carpeta de usuario. Sin ninguno de esos límites, solo se consulta la carpeta actual.
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`.

Usa solo una configuración de proyecto de confianza. Antes de ejecutar comandos
en un repositorio clonado, revisa su archivo de configuración y los valores
efectivos. `carpetaDescargas` puede indicar una carpeta fuera del repositorio;
el límite de búsqueda del archivo no restringe el destino de las descargas.
Para elegir otra carpeta en un comando usa `--destino`. `--salida` cambia el
formato de presentación, no la carpeta.

```json
{
  "perfil": "empresa-b",
  "entorno": "sandbox",
  "ruc": "0123456789001",
  "salida": "json"
}
```

## Otros comandos

| Comando | Descripción |
|---|---|
| `api <metodo> <ruta> [--datos @archivo] [--idempotency-key <clave>] [--archivo-salida <archivo>]` | Llama a cualquier ruta de la API con tu API Key y muestra la respuesta tal cual. `<metodo>` acepta `GET`, `POST` o `PUT`. 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, o el comprobante quedó en `error`. |
| `2` | Uso incorrecto del comando. |
| `3` | Falló la autenticación, la IP o el permiso, o el comprobante quedó en `rechazo_configuracion` por la firma, la configuración del emisor o la suscripción. |
| `4` | Error de validación, o el comprobante quedó `rechazado` por su contenido, con el `codEstado` 3002 (`comprobante_invalido`). |
| `5` | El SRI rechazó el comprobante: quedó `rechazado` con el `codEstado` 3001 (`rechazo_sri`). |
| `6` | Se superó el límite de solicitudes o no hay cupo, ya sea porque la API respondió 429 o porque el comprobante quedó en `rechazo_configuracion` con el `codEstado` 4004 (`cupo_agotado`). |
| `7` | Resultado parcial: unos elementos salieron bien y otros no. |
| `8` | No encontrado o en conflicto, o el comprobante quedó `cancelado`, con el `codEstado` 6001 (`operacion_cancelada`). |

Cuando el código viene del resultado de un comprobante, depende de su `estado`
y de su `codEstado`:

| `estado` | `codEstado` | Código de salida |
|---|---|---|
| `autorizado` o `recibido` | 2001, 1001 o 1002 | `0` |
| `rechazado` | 3001 (`rechazo_sri`) | `5` |
| `rechazado` | 3002 (`comprobante_invalido`) | `4` |
| `rechazo_configuracion` | 4001 (`emisor_no_configurado`), 4002 (`firma_no_valida`) o 4003 (`suscripcion_inactiva`) | `3` |
| `rechazo_configuracion` | 4004 (`cupo_agotado`) | `6` |
| `error` | 5006 (`entrega_no_posible`), 5007 (`resultado_no_confirmado`) o 5001 (`error_interno`) | `1` |
| `cancelado` | 6001 (`operacion_cancelada`) | `8` |

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 `recibido`, que todavía no tienen un resultado final, 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.

Si la API no responde, o responde 500, 502, 503 o 504, o 429 con el `codEstado`
5005 (`limite_solicitudes`), el CLI repite la petición por su cuenta hasta tres veces,
con una espera entre intentos y respetando la cabecera `Retry-After` cuando
viene. Al emitir, cada reintento lleva la misma `Idempotency-Key`, así que no
duplica el comprobante: si la primera solicitud se aceptó, recibes el mismo
`idOperacion`. Si el error persiste después de los reintentos, el comando
termina con su código de salida, 1 para los errores del servidor y 6 para el
límite de solicitudes, y puedes reanudar el lote más tarde con
`ecuafact lote reanudar`. Un 429 con el `codEstado` 4004 (`cupo_agotado`) no se reintenta,
porque esperar no devuelve cupo.

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 inválidas.",
  "estadoHttp": 401,
  "estado": "rechazado",
  "codEstado": 3009,
  "idCorrelacion": "0HN7A2B3C4D5E:00000001",
  "codigoSalida": 3,
  "sugerencia": "Revisa la API Key ('ecuafact sesion') y, en produccion, 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`, `estado`, `codEstado` | Solo si el error vino de la API: el estado HTTP, el `estado` y el [`codEstado`](/v1/guias/errores#catalogo-de-codestado) del cuerpo de error. |
| `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.
