LcsGrz/arcli

CLI para previsualizar y emitir comprobantes electrónicos de ARCA (ex AFIP) desde la terminal. Sin emitir hasta que lo pedís, con validaciones locales y salida lista para automatizar.

Empezar sin saber de terminal

Si usás un asistente de IA que puede manejar tu computadora (Claude, ChatGPT, Gemini, Copilot…), copiale el prompt de Instalar o actualizar con IA: hace los pasos 1 a 3 por vos. Si no, son estos:

1. Instalá Node.js 22.22.1 o superior desde nodejs.org (la versión LTS).
2. Abrí la terminal (en Mac: Cmd+Espacio y escribí "Terminal"; en Windows: menú Inicio y escribí "PowerShell") y pegá npm install -g arcli.
3. Pegá arcli acceso-directo: deja un ícono de ARCLI en el escritorio.
4. Abrí ARCLI con doble clic en el ícono y seguí la configuración guiada. Desde ahí sacás el certificado de ARCA y emitís tu primera factura de prueba en testing, sin validez fiscal.

Más adelante va a haber un instalador que no necesita Node.

Características

• Modo interactivo: arcli sin argumentos abre un asistente que guía la emisión, repite facturas anteriores, arma notas de crédito y débito, consulta comprobantes y configura el CLI. Cada paso muestra el comando equivalente.
• Vista previa por defecto: sin --emitir, muestra la solicitud y, en una terminal, pregunta antes de emitir.
• Comprobantes: Factura, Nota de Crédito y Nota de Débito A, B y C; sus versiones de Factura de Crédito Electrónica (FCE), con CBU, transferencia, anulación y consulta del régimen del receptor; y Recibo C.
• Factura de exportación E: arcli fe emite con WSFEX, con cliente y país de destino, incoterm, ítems detallados y permisos de embarque; acepta certificado propio con exportacion.cert.* / exportacion.key.*.
• Entrada y salida flexibles: flags o JSON (incluso lotes); salida legible, --json o respuesta bruta de ARCA.
• Validaciones locales basadas en el manual de ARCA, para detectar errores antes de llamar al servicio.
• Consultas sin emitir: últimos comprobantes, detalle de uno, estado de los servidores, tablas de parámetros, cotización oficial y padrón de un CUIT.
• IVA receptor automático: con --cuit y sin --ir, toma la condición IVA del padrón de ARCA.
• PDF con el QR de ARCA mediante un plugin que se descarga solo si lo usás.

Instalación

Requiere Node.js 22.22.1 o superior. Si no lo tenés, bajá la versión LTS de nodejs.org: trae npm.

npm install -g arcli

También con otros gestores de paquetes:

pnpm add -g arcli
yarn global add arcli   # Yarn 1; Yarn 2 o superior no instala paquetes globales

Para probarlo sin instalar nada: npx arcli --ayuda.

Para actualizar, repetí la instalación con arcli@latest (por ejemplo, npm install -g arcli@latest). Cuando hay una versión nueva, el aviso de arcli muestra el comando del gestor con que lo instalaste. Funciona en macOS, Linux y Windows.

Instalar o actualizar con IA

Copiá esto y pegáselo a tu asistente de IA. Sirve para instalar y para actualizar:

Instalá o actualizá arcli en esta computadora. Es un programa para emitir facturas de ARCA: https://www.npmjs.com/package/arcli

1. Revisá si tengo Node.js 22.22.1 o superior (node --version). Si no lo tengo o es más viejo, instalá la versión LTS de https://nodejs.org con el instalador oficial para mi sistema.
2. Instalá o actualizá arcli con: npm install -g arcli@latest. Si da un error de permisos, explicame la opción más segura antes de usar sudo o permisos de administrador.
3. Verificá con arcli --version y decime qué versión quedó.
4. Si es la primera vez que lo instalo, creá el ícono en el escritorio con: arcli acceso-directo

Si podés ejecutar comandos, hacelo vos; si no, guiame paso a paso, como a alguien que nunca usó la terminal. No toques certificados, claves ni la configuración de arcli, y no emitas comprobantes.

Después abrí ARCLI con doble clic en el ícono y seguí la configuración guiada.

Opcional: autocompletado con Tab de comandos, flags y valores, en bash, zsh o fish. Se instala con arcli completado instalar y se saca con arcli completado desinstalar (detalle).

Opcional: un ícono para abrir ARCLI con doble clic, con arcli acceso-directo (detalle).

Configuración

Necesitás tu CUIT, un punto de venta y un certificado con su clave privada de ARCA. Si todavía no tenés el certificado, arcli certificado generar arma el pedido para ARCA y arcli certificado importar carga el que te devuelve; el paso a paso está en Cómo obtener los certificados.

Lo más simple es correr arcli y seguir la configuración guiada. Para hacerlo por comandos (por ejemplo, en un servidor):

arcli config establecer cuit 20168598204
arcli config establecer puntoVenta 3
arcli certificado generar --testing     # arma la clave y el pedido (CSR) para subir a ARCA
# en ARCA: subí el CSR, bajá el .crt y autorizalo a facturar (wsfe), ver la guía
arcli certificado importar testing.crt  # carga el certificado que te devuelve ARCA
arcli config revisar

Esa es la forma recomendada. Si ya tenés el certificado y la clave (por ejemplo, los hiciste con openssl), cargalos directo con arcli config establecer cert.testing <ruta> y arcli config establecer key.testing <ruta>.

arcli config revisar revisa localmente la config de cada entorno (testing y producción): archivos, vencimientos y datos. No prueba el certificado contra ARCA; para eso, arcli estado. Todas las claves disponibles están en Configuración.

Uso

arcli fc -m 15000 --cs --consumidor-final            # vista previa de una Factura C
arcli fc -m 15000 --cs --consumidor-final --emitir   # emitir
arcli fc --cargar ./facturas.json --emitir --json            # lote desde JSON, salida JSON
arcli fc -m 15000 --cs --consumidor-final --emitir --exportar-pdf
arcli fe -m 1500 --cliente "ACME LLC" --domicilio-cliente "123 Main St" --pais-destino 203 \
  --numero 1 --actividad 620100 --previsualizar                             # Factura de exportación E

Otras consultas: arcli ultimos, arcli consultar, arcli estado, arcli parametros, arcli fce-obligado, arcli padron. Para ver todos los comprobantes y ejemplos: arcli --ayuda y arcli ejemplos.

La prioridad de los valores es flags > JSON > config > defaults. Ver el modelo mental y la referencia del CLI.

Testing y producción

Por defecto se usa el entorno testing, con cert.testing y key.testing. Para emitir en producción hay que configurar cert.produccion y key.produccion y pasar --produccion (o guardar entorno produccion; en el asistente, Configuración → Modificar configuración → Entorno). Con la config por defecto, además hace falta --emitir o confirmar la pregunta.

Documentación

El índice completo está en docs/. Lo principal:

• Modo interactivo y Patrones de uso
• Referencia del CLI y Configuración
• Entrada y salida: formato del JSON
• PDF de comprobantes
• Cómo obtener los certificados
• Troubleshooting, Reglas de validación y Limitaciones
• llms.txt: referencia condensada para agentes de IA con acceso a terminal
• Changelog

Desarrollo

git clone https://github.com/LcsGrz/arcli.git
cd arcli
yarn install
yarn dev --ayuda

Antes de abrir un PR: yarn typecheck, yarn lint y yarn test. Más en la guía de desarrollo y la arquitectura.

Ayuda y soporte

• Preguntas y dudas de uso (configuración, certificados, cómo facturar algo): GitHub Discussions.
• Bugs y propuestas: issues, con las plantillas.
• Vulnerabilidades: en privado, como dice SECURITY.md.

Antes de preguntar, puede que ya esté en Troubleshooting. No pegues certificados, claves, tickets ni la salida de --bruto en ningún lado.

Estabilidad

ARCLI usa versionado semántico. Son contrato público, y solo cambian de forma incompatible en una versión mayor y avisándolo en el CHANGELOG:

• los comandos y sus flags,
• las claves de configuración,
• el JSON de entrada (--cargar) y de salida (--json), incluidos los codigo de error.

La salida en texto (tablas, mensajes, colores) es para leer, no para parsear, y puede cambiar en cualquier versión. Para scripts, usá --json.

Contribuir

Leé CONTRIBUTING.md y el código de conducta. Para vulnerabilidades, ver SECURITY.md; no subas certificados, claves ni tokens reales a issues ni PRs.

Agradecimientos

• @arcasdk/core y @arcasdk/pdf, de Rodrigo Alcorta.
• Arpit Bhayani, por ceder el nombre arcli en npm.
• Manuel Aller, por la factura de exportación E.
• Guillermo Britos, por el Recibo C.
• Kevin Tea, por la condición de venta en el PDF.

Si el proyecto te resulta útil, podés dejar una estrella o invitarme un Cafecito.

Licencia

MIT © LcsGrz. Ver LICENSE.