Convierte CLI en API JavaScript – millionco 2026

cli-to-js es un generador que transforma cualquier herramienta de línea de comandos en una API JavaScript completamente tipada, sin dependencias externas. Lee automáticamente el esquema de la CLI (via –help), genera código TypeScript con métodos y opciones validadas, y permite invocar comandos como funciones seguras desde Node.js. Especialmente útil para agentes de IA que necesitan ejecutar CLIs externas de forma estructurada.

cli-to-js es un generador de APIs JavaScript que convierte binarios CLI en interfaces tipadas. Tomás cualquier herramienta de línea de comandos (git, docker, aws, lo que sea), ejecutás cli-to-js contra ella, y obtenés código JavaScript listo para usar con tipos completos, validación de argumentos y cero dependencias en tiempo de ejecución.

Qué es cli-to-js y por qué transformó la integración de CLIs

Ponele que estás armando un agente de IA que necesita ejecutar comandos de git: hoy día lo tenés que hacer con child_process.exec(), pasando un string donde armás el comando a mano. Si el agente mete un espacio donde no va, se rompe. Si intenta un flag que no existe, lo descubrís cuando ya corrió el comando. Todo muy frágil (y además, peligroso de seguridad).

Ahí llega cli-to-js. En lugar de eso, vos generás una API tipada que representa la CLI. Entonces en tu código TypeScript tenés métodos fuertemente tipados, autocompletado IDE, validación de argumentos ANTES de ejecutar, y un contrato claro entre vos y la herramienta externa.

Lo genial es que no estás metiendo una dependencia más en tu proyecto. cli-to-js es solo una herramienta de build time. El código que genera es JavaScript puro que vos podés auditar, entender, y debugguear si necesitás.

Cómo funciona: de binario a API en TypeScript

El flujo es relativamente simple pero ingenioso. cli-to-js llama al binario que le pasés con la flag --help, parsea la salida (porque prácticamente todo responde a –help), extrae los subcomandos y opciones, y genera una clase o módulo que representa esa estructura de forma tipada. Cubrimos ese tema en detalle en ejecutar agentes sin dependencias externas.

Cada subcomando se convierte en un método. Cada opción de ese subcomando se convierte en una propiedad del objeto de opciones tipado. Si el CLI tiene git log --oneline --all, vos en TypeScript llamás git.log({ oneline: true, all: true }). El IDE te autocompleta todo. Si pasás una opción que no existe, TypeScript te grita en tiempo de compilación.

Cuando ejecutás la API, cli-to-js genera el comando de shell apropiado por debajo, invoca el binario real, y retorna la salida.

Instalación y generación de tu primer wrapper

Para empezar es una línea:

npx cli-to-js git

Eso genera un módulo JavaScript que encapsula git. Si querés TypeScript:

npx cli-to-js git --ts

Y si querés guardarlo en un archivo específico en lugar de stdout:

npx cli-to-js git --ts -o git-api.ts

El archivo generado contiene la definición completa de tipos más la lógica de invocación. No necesitás instalar nada después — importás y usás directo.

Tipado automático en TypeScript: subcomandos como métodos

El verdadero poder está en los tipos. Tomá este ejemplo real con git:

const logs = await git.log({ n: 5, oneline: true });

Acá TypeScript te autocompleta todas las flags válidas de git log. Si escribís git.log({ oneline: true, porcerline: true }) (typo en “porcelain”), el compilador falla antes de que siquiera intentes ejecutar nada. Y los valores que pasás también están validados: si -n espera un número, TypeScript no te deja pasar un string.

Cada método retorna una Promise con el output tipado (por defecto string), así que vos podés chainear y el IDE te ayuda en todo momento.

Validación inteligente de argumentos: Levenshtein y sugerencias

cli-to-js no solo valida tipos. También usa distancia Levenshtein para detectar typos en opciones y sugerir alternativas. Si escribís git.log({ oneline: true, porcelain: true }), la validación detecta que “porcelain” no existe pero hay un “porcelain-v1” disponible, y lanza un error con la sugerencia. Ya lo cubrimos antes en seguridad al ejecutar herramientas CLI.

Esto previene esos casos donde te pasas horas debuggeando un comando que simplemente tenía una letra mal escrita en una flag obscura.

Casos de uso: desde automatización hasta agentes de IA

Agentes de IA segura: Esto es donde cli-to-js realmente brilla. Imaginá que usás Claude o cualquier otro LLM en modo agente, y querés que ejecute comandos de shell de forma segura. En lugar de dejarle hacer exec("git " + variable_cualquiera), le limitás a un set predefinido de operaciones tipadas. El agente llama git.log({ n: 5 }), vos validás que eso tenga sentido, y recién ahí ejecutás. Cero inyección de comandos, cero sorpresas.

Automatización robusta: Scripts de deploy, setup de ambientes, orchestración de herramientas. En lugar de armar comandos como strings (con sus tildes y espacios y comillas), usás métodos tipados.

Documentación automática: La generación de tipos es también la generación de documentación. Otros desarrolladores ven en el IDE exactamente qué opciones tiene cada subcomando.

Integración multi-herramienta: Podés generar wrappers para docker, aws-cli, terraform, kubectl. Tu orquestador Node.js habla con todas ellas como APIs normales, sin estrategias de parsing distintas para cada una.

cli-to-js vs child_process: cuándo usar cada uno

La regla simple: si estás ejecutando un binario conocido de forma repetida y querés seguridad + tipos, cli-to-js. Si necesitás máxima flexibilidad o el CLI es super raro, child_process directo. Complementá con herramientas modernas para desarrollo.

Integración con agentes: habilitar CLIs en Claude, OpenAI, Anthropic

Esto es especialmente bueno para las APIs de agent frameworks. Tomá Claude con Anthropic SDK en modo agent. Vos definís una “herramienta” que el modelo puede invocar. cli-to-js ya genera un schema JSON que representa la CLI.

En lugar de dejar que el agent arme comandos de shell libres (peligroso), le pasás un schema JSON que dice “podés llamar git.log con estas opciones exactas”. El agent llama la herramienta de forma estructurada, vos validás que tenga sentido, ejecutás cli-to-js, y devolvés el resultado.

Esto convierte agentes AI en orquestadores de CLI seguros. Subís el modelo, lo probás en local, funciona bárbaro, lo mandás a producción y de repente todo se rompe porque configuraste una opción que cambió entre versiones — pero con tipos, eso lo atrapás antes.

Errores comunes

Asumir que funciona con cualquier CLI

cli-to-js parsea --help, pero si la salida de –help de un CLI es muy no-estándar, puede fallar. Probá primero con CLIs conocidos (git, docker, npm) que tienen formato standard.

No volver a generar cuando la CLI se actualiza

Si el CLI que wrapeaste lanza una versión nueva con opciones diferentes, tu código generado sigue siendo viejo. Tenés que regenerar. Considerá poner la generación en tu build script.

Confundir el output del CLI con una API estructurada

cli-to-js te da una interfaz tipada para INVOCAR el CLI, pero el output del comando sigue siendo lo que devuelve el CLI (generalmente un string). Si necesitás parsear ese output, hacelo vos.

Olvidar que seguís dependiendo del binario instalado

El código generado no tiene dependencias npm, pero SÍ necesita que el binario CLI esté instalado y en el PATH. Si lo corrés en una máquina que no tiene git, falla. Documentá eso. Esto se conecta con lo que analizamos en plataformas de control de versiones.

Preguntas Frecuentes

¿Cómo convertir una herramienta CLI a una API de JavaScript con tipos?

Ejecutás npx cli-to-js nombre-del-cli --ts -o api.ts una sola vez. Eso genera un archivo TypeScript que importás y usás. Los tipos se mantienen sincronizados con el CLI siempre que regeneres cuando éste se actualice.

¿Puedo usar cli-to-js para que agentes de IA ejecuten comandos seguros?

Sí, es exactamente uno de los casos de uso principales. Generás el wrapper, lo exponés como una herramienta estructurada al agente (con schema JSON), y el agente llama métodos tipados en lugar de armar strings de shell libres. Eso elimina la mayoría de los riesgos de inyección.

¿Qué pasa si el CLI no tiene –help o es muy raro?

cli-to-js puede fallar. En ese caso, volvés a child_process o escribís el wrapper a mano. No es la panacea, pero cubre la mayoría de los CLIs modernos.

¿El código generado tiene dependencias externas?

No. El código que cli-to-js genera es JavaScript/TypeScript puro. La propia herramienta cli-to-js es la dependencia, pero el output no lleva nada extra. Eso significa que una vez que generás, podés prescindir de cli-to-js si necesitás.

¿Cómo integro esto en mi build process?

Metés npx cli-to-js mi-cli --ts -o src/generated/cli-api.ts en tu script de build o en un hook pre-commit. Regenerás cada vez que la versión del CLI que wrapeás se actualiza, o en cada build si preferís estar siempre sincronizado.

Conclusión

cli-to-js resuelve un problema concreto: cómo integrar CLIs externas en Node.js sin pisar esos agujeros de seguridad típicos de strings de shell. La generación automática de tipos ahorra tiempo, el output zero-dependency es fácil de auditar, y el validation automático atrapa errores antes de que sucedan.

Para agentes de IA que necesitan ejecutar herramientas CLI, es casi una obligación: les deja al modelo exactamente las operaciones seguras que puede hacer, sin libertad para armar comandos malformados o injecciones. Para automatización en general, convierte scripts bash frágiles en código TypeScript tipado que otros desarrolladores pueden entender sin documentación adicional (el IDE es la documentación).

Si trabajás en proyectos que orquestan múltiples CLIs o si estás integrando IA con herramientas de línea de comandos, probalo. La inversión es de minutos y el retorno en seguridad y claridad de código es bastante claro. Si te interesa profundizar en automatización segura con JavaScript, donweb.com tiene recursos sobre infraestructura y tooling para desarrolladores.

Fuentes

• millionco/cli-to-js en GitHub — repositorio oficial con código fuente y documentación
• Node.js child_process documentation — documentación oficial de child_process para referencia de comparación
• oclif framework — framework para construir CLIs en Node.js, con soporte para structured help
• Tutorial: Cómo lanzar child processes en Node.js — referencia para entender child_process