# 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`. ## Instalación Instala el CLI con el gestor de paquetes que ya uses. **npm** ```bash npm install -g @ecuafact/cli@preview ``` **Windows (Scoop)** ```powershell scoop bucket add ecuafact https://github.com/Ecuanexus/ecuafact-scoop scoop install ecuafact/ecuafact-preview ``` **macOS y Linux (Homebrew)** ```bash brew install ecuanexus/ecuafact/ecuafact-preview ``` Para actualizar, repite la instalación con npm o ejecuta `scoop update ecuafact-preview` o `brew upgrade ecuafact-preview`, 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 `, y luego desinstálalo con el mismo gestor: `npm uninstall -g @ecuafact/cli`, `scoop uninstall ecuafact-preview` o `brew uninstall ecuafact-preview`. ## 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. Además, la IP de tu equipo 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 IDOPERACION CLAVEACCESO MENSAJE factura.json autorizado 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 (`.pdf`). ## Autenticación `ecuafact login` guarda la API Key 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: ```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@preview - 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. 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, carpetas, CSV o Excel ([Emitir con el CLI](/v1/guias/cli-emision)). | | `estado`, `comprobantes listar`, `lote` | Seguir operaciones, listar emitidos y reanudar lotes. | | `descargar`, `correo reenviar` | Descargar el RIDE y el XML, y reenviar el correo. | | `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`, `catalogos` | Hacer consultas al 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. | Si necesitas ayuda en la terminal, `ecuafact --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.