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

# CLI de Ecuafact

Emite, sigue y descarga comprobantes electrónicos desde la terminal con el CLI `ecuafact`, sin escribir código.

Si necesitas hacer revisiones rápidas o conectar nuestros servicios de
facturación a un proceso automatizado, puedes usar nuestro CLI `ecuafact`. Con
él creas un comprobante de ejemplo, lo validas, lo emites, esperas la respuesta
del SRI y descargas el RIDE con un par de comandos, sin programar las llamadas
HTTP. Te sirve tanto para probar la API por primera vez como para emitir desde
los archivos que genera tu ERP.

En esta página instalas el CLI, lo conectas con tu API Key de pruebas y emites
tu primera factura. Al final encontrarás la lista de comandos, agrupados por
tarea, con enlaces a las guías y a la referencia donde se explica cada uno.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos de esta página usan el
> entorno `sandbox`.

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Instala el CLI de Ecuafact y emite una factura de prueba desde esta terminal. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/cli.md antes de escribir código; no inventes campos. Si ecuafact ya está instalado, reutilízalo; si no, instálalo con npm install -g @ecuafact/cli (o con Scoop o Homebrew si prefiero ese gestor). Fija el entorno con ecuafact config poner entorno sandbox. No pidas ni leas mi API Key: pídeme que ejecute yo mismo ecuafact login en mi terminal (la guarda sin mostrarla) o que defina ECUAFACT_API_KEY en mi entorno; nunca la pases como argumento de un comando, nunca la pegues en el chat ni la imprimas. Ejecuta ecuafact doctor y corrige lo que indique (clave, IP permitida, cupo); crea el comprobante con ecuafact nuevo factura --archivo factura.json, completa el RUC del emisor y los datos con los datos de prueba de la guía, valídalo con ecuafact validar factura.json y emítelo con ecuafact emitir factura.json --esperar. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado (numérico), usa urlEstado tal cual (URL absoluta) y lee errores como arreglo. Ejecuta los comandos e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer.
```

## Instalación

Instala el CLI con el gestor de paquetes que ya uses.

**npm**

```bash
npm install -g @ecuafact/cli
```

**Windows (Scoop)**

```powershell
scoop bucket add ecuafact https://github.com/Ecuanexus/ecuafact-scoop
scoop install ecuafact/ecuafact
```

**macOS y Linux (Homebrew)**

```bash
brew install ecuanexus/ecuafact/ecuafact
```

Para actualizar, repite la instalación con npm o ejecuta
`scoop update ecuafact` o `brew upgrade ecuafact`, según el
gestor. Para comprobar qué versión tienes, ejecuta `ecuafact --version`. Si
no muestra la versión que acabas de instalar, tienes otra instalación antes en
el `PATH`: desinstala la que no uses.

Para desinstalar el CLI, quita primero los servicios de
[vigilancia de carpetas](/v1/guias/cli-vigilar) que hayas instalado, con
`ecuafact vigilar desinstalar --nombre <nombre>`, y luego desinstálalo con el
mismo gestor: `npm uninstall -g @ecuafact/cli`, `scoop uninstall ecuafact`
o `brew uninstall ecuafact`.

## Inicio rápido

Necesitas una [API Key](/v1/guias/glosario#api-key) de pruebas. Si todavía no
tienes una, crea tu [sandbox](/v1/guias/sandbox) desde el Portal del Cliente.
En sandbox no hay que registrar la IP de tu equipo; en producción debe estar
registrada en el portal, en **Cuenta > IP permitidas**.

```bash
ecuafact config poner entorno sandbox
ecuafact login
ecuafact doctor
ecuafact nuevo factura --archivo factura.json
ecuafact emitir factura.json --esperar --descargar ride
```

Estos comandos hacen lo siguiente, en orden:

1. `config poner entorno sandbox` deja fijo en tu perfil el entorno de pruebas.
2. `login` te pide la API Key sin mostrarla en pantalla y la guarda.
3. `doctor` revisa la conexión, la API Key, tu IP y tu
   [cupo](/v1/guias/glosario#cupo). Si algo falla, te dice qué hacer.
4. `nuevo factura` crea una factura de ejemplo. Abre el archivo, pon tu
   [RUC](/v1/guias/glosario#ruc) y revisa los datos con la guía de
   [Factura](/v1/guias/emision-01).
5. `emitir` envía la factura, espera la
   [autorización](/v1/guias/glosario#autorizacion) del SRI y descarga el
   [RIDE](/v1/guias/glosario#ride).

Si todo funcionó, el último comando muestra el comprobante con el estado
`autorizado`:

```text
ORIGEN        ESTADO      CODESTADO  IDOPERACION                           CLAVEACCESO                                        MENSAJE
factura.json  autorizado  2001       3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f  0710202601012345678900110010010000001231234567811  Autorizado por el SRI.
```

El CLI guarda el RIDE en la carpeta actual, con la clave de acceso como nombre
de archivo (`<claveAcceso>.pdf`).

## Autenticación

El CLI se autentica siempre con una API Key. `ecuafact login` la guarda para el
perfil y el entorno que estás usando. Para ver cuál está activa, ejecuta `ecuafact sesion`; para borrarla,
`ecuafact logout`.

En un servidor o en un proceso de integración continua, define la API Key en la
variable de entorno `ECUAFACT_API_KEY`. El CLI la usa en lugar de la guardada
en `sandbox` y `produccion`:

```bash
export ECUAFACT_API_KEY="..."
ecuafact --entorno sandbox consumo
```

> [!WARNING]
> No pases la API Key como argumento de un comando, porque queda guardada en el
> historial de la terminal.

## En scripts y CI

Puedes usar el CLI en un servidor, una tarea programada o un pipeline de
integración continua, porque ahí no te pregunta nada. Escribe el resultado en
JSON por la salida estándar, los
mensajes y los errores por la salida de errores, y termina con un
[código de salida](/v1/guias/cli-referencia#codigos-de-salida) que tu script
puede comprobar para saber si todo salió bien.

Entrega la API Key con la variable `ECUAFACT_API_KEY`, que es lo más simple en
un pipeline. Si prefieres guardarla una vez en el equipo, pásala por la entrada
estándar con `login --desde-stdin`, para que no quede en el historial ni en la
lista de procesos:

```bash
echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox
```

En `produccion`, los comandos que emiten o cambian datos se detienen si no
agregas `--confirmar produccion`, porque en un script nadie puede responder la
confirmación. Este es un paso de GitHub Actions que emite una carpeta en pruebas,
espera el resultado y guarda un reporte:

```yaml
- run: npm install -g @ecuafact/cli
- run: ecuafact --entorno sandbox emitir ./salida -r --esperar --reporte resultado.json
  env:
    ECUAFACT_API_KEY: ${{ secrets.ECUAFACT_API_KEY_SANDBOX }}
```

Revisa el código de salida y, si es distinto de 0, el reporte: ahí está el
estado de cada comprobante.

## Entornos

Puedes trabajar con dos entornos, uno por cada ambiente de la API.

| Entorno | Para qué |
|---|---|
| `sandbox` | Pruebas, sin validez fiscal. |
| `produccion` | Comprobantes reales. Es el entorno por defecto. |

Como un perfil nuevo trabaja en `produccion`, elige el entorno antes de
empezar a probar. Puedes indicarlo en cada comando con `--entorno sandbox` o
dejarlo fijo en tu perfil con `ecuafact config poner entorno sandbox`. Cada
entorno usa su propia API Key, así que ejecuta `login` una vez en cada uno.
También puedes elegirlo con la variable `ECUAFACT_ENTORNO`, agregar entornos
propios con `ecuafact entorno agregar` o probar contra un servidor local con
`ECUAFACT_API_URL`; todo eso se explica en
[Cambiar de ambiente o de URL](/v1/guias/cli-referencia#cambiar-de-ambiente-o-de-url).

En `produccion`, los comandos que emiten o cambian datos te piden confirmación
antes de seguir. Si los ejecutas desde un script, donde nadie puede responder,
agrega `--confirmar produccion`.

## Configuración

Con `config` guardas valores por defecto para no repetirlos en cada comando, y
con `perfil` separas la configuración y las API Keys de cada integración, por
ejemplo si trabajas para varias empresas.

```bash
ecuafact config poner ruc 0123456789001
ecuafact config ver
ecuafact perfil usar empresa-b
```

Puedes guardar el entorno, el RUC, el establecimiento, el punto de emisión y el
formato de salida, entre otros. Todas las claves están en la
[referencia](/v1/guias/cli-referencia#configuracion).

Si trabajas en un proyecto, puedes fijar su configuración en un archivo
`ecuafact.json` dentro del repositorio, sin la API Key. Ese archivo tiene
prioridad sobre tu perfil; el orden completo está en
[Precedencia y ecuafact.json](/v1/guias/cli-referencia#precedencia-y-ecuafact.json).

## Comandos

Los comandos se agrupan por tarea. Cada grupo enlaza a la guía que lo explica
con ejemplos, y la [referencia](/v1/guias/cli-referencia) tiene todas sus
opciones.

| Comando | Para qué |
|---|---|
| `emitir`, `validar`, `nuevo` | Crear, validar y emitir comprobantes desde JSON, JSONL, XML del SRI, carpetas, CSV o Excel ([Emitir con el CLI](/v1/guias/cli-emision)). |
| `estado`, `lote` | Seguir operaciones y reanudar lotes. |
| `descargar` | Descargar el RIDE y el XML. |
| `vigilar` | Emitir lo que tu ERP deja en una carpeta ([Vigilar una carpeta](/v1/guias/cli-vigilar)). |
| `plantilla` | Mapear las columnas de un CSV o Excel ([Emitir desde CSV o Excel](/v1/guias/cli-csv-excel)). |
| `cuenta`, `consumo`, `perfil-emisor` | Ver tu integración, tu cupo y los datos del emisor. |
| `ruc`, `identificacion`, `clave`, `establecimientos` | Hacer consultas al SRI. |
| `salud`, `estado-servicio`, `catalogos` | Comprobar que el servicio responde y consultar su estado público (sin API Key), y consultar los catálogos del SRI. |
| `webhooks` | Probar tu endpoint de webhooks. |
| `login`, `config`, `perfil`, `entorno`, `doctor` | Gestionar credenciales y configuración, y diagnosticar problemas. |
| `api`, `schema` | Llamar a cualquier ruta del API y describir el CLI en JSON. |

El tipo del comprobante (`01` a `07`) elige la ruta de emisión y no viaja en el
cuerpo. Lo indicas con `--tipo`, o el CLI lo deduce de la forma del comprobante ([Emitir con el CLI](/v1/guias/cli-emision)).

Si necesitas ayuda en la terminal, `ecuafact <comando> --help` muestra la ayuda
de cada comando y `ecuafact ayuda` lista guías breves que funcionan sin
conexión.

## Siguientes pasos

- [Emitir con el CLI](/v1/guias/cli-emision): emite lotes y carpetas, sigue cada comprobante y descarga sus archivos.
- [Emitir desde CSV o Excel](/v1/guias/cli-csv-excel): emite desde las filas de tu archivo sin escribir JSON.
- [Referencia de comandos](/v1/guias/cli-referencia): consulta todas las opciones y los códigos de salida.
