NestJS CLI Starter

Este proyecto es una base para desarrollar CLI (Command Line Interface) personalizadas utilizando nest-commander. Está diseñado para agilizar el desarrollo de herramientas de línea de comandos con una arquitectura modular, extensible y desacoplada.

Su base es NestJS, un framework progresivo de NodeJS que permite construir aplicaciones eficientes, confiables y escalables, combinando elementos de la programación orientada a objetos, funcional y reactiva. Gracias a su enfoque modular y su compatibilidad completa con TypeScript, NestJS resulta ideal para estructurar una CLI robusta, organizada y fácil de mantener.

📦 Características principales

• Comandos con subcomandos desacoplados de ejemplo
• Decoradores personalizados de nest-commander
• Uso de inquirer, chalk, ora, cli-table3 y update-notifier para mejorar la experiencia de usuario
• Separación de lógica de interacción y lógica de negocio por cada comando
• Configuración persistente con configstore
• Configuración centralizada con ConfigModule

Glosario

• 📝 Requisitos
• 🛠️ Instalar dependencias
• ⚙️ Configuración
• 🚀 Probar la CLI localmente
• 💻 Scripts
• 📤 Commits
• 📄 Changelog
• 📜 License MIT

---

📝 Requisitos

• NodeJS ≥ 20.19.3 (descargar)
• Yarn ≥ 1.22.22 o Npm ≥ 11.5.2
• NestJS ≥ v11.1.6 (Documentación)

🛠️ Instalar dependencias

yarn install

npm install

⚙️ Configuración

Este proyecto no utiliza archivos .env, ni validationSchema, toda la configuración a nivel CLI se carga en el archivo configuration.ts, que luego es disponibilizado por el ConfigModule de NestJS para ser consumido en todo el proyecto por medio de la injection del ConfigService.

Por otro lado, también cuenta con la implementación de Configstore, que es para guardar configuración a nivel usuario, como podría ser un token de authorization, un UID de usuario, etc.

Para cambiar el nombre del comando CLI que se ejecuta desde terminal, modificá el campo bin en el package.json:

{
  //...
  "bin": {
    "nestjs-cli-starter": "dist/main.js"
  }
  //...
}

🚀 Probar la CLI localmente

Primero ejecutas el script build:local, una vez que finaliza el script, este se encarga de hacer ejecutable el bundle final con el script postbuild y luego lo linkea como paquete.

Para probar el comando localmente debes ejecutar el comando en la terminal:

nestjs-cli-starter --help

En caso de que falle y no te reconozca el comando, es muy probable que tengas que instalarlo globalmente (unica vez), y luego volver a realizar los pasos anteriores.

npm i -g .

yarn global add file:.

💻 Scripts

Realiza el build de la CLI

yarn build

npm run build

Hace que el bundle generado por el build sea ejecutable

yarn postbuild

npm run postbuild

Realiza el build de la CLI, lo transforma en ejecutable y lo linkea como paquete para probar localmente

yarn build:local

npm run build:local

Inicia los test con coverage

yarn test

npm run test

Des-linkea el paquete de npm

yarn unlink

npm run unlink

Otros scripts

Formatea el código

yarn format

npm run format

Eslintea el código

yarn lint

npm run lint

🧩 Diferencias entre Argumentos, Opciones y Flags

Tipo	¿Qué es?	Ejemplo CLI
Argumento	Valor posicional requerido u opcional para el comando.	my-cli generate module auth
Opción	Parámetro con valor que modifica el comportamiento. Se pasa con --clave.	my-cli deploy --env production
Flag	Forma específica de escribir una opción, es decir, un parámetro booleano (encendido/apagado). No necesita valor.	my-cli build --dry-run my-cli build -d

📌 Nomenclatura de uso

Forma	¿Qué significa?	Ejemplo
<valor>	Argumento obligatorio	my-cli login <env>
[valor]	Argumento opcional	my-cli login [user]
--flag	Opción sin valor (flag)	my-cli build --dry-run
--key <val>	Opción con valor obligatorio	my-cli deploy --env production
--key [val]	Opción con valor opcional	my-cli deploy --env

📤 Commits

Para los mensajes de commits se toma como referencia conventional commits.

<type>[optional scope]: <description>

[optional body]

[optional footer]

• type: chore, docs, feat, fix, refactor (más comunes)
• scope: indica la página, componente, funcionalidad
• description: comienza en minúsculas y no debe superar los 72 caracteres.

Ejemplo

git commit -m "docs(readme): add documentantion to readme"

Breaking change

git commit -am 'feat!: changes in application'

📄 Changelog

All notable changes to this project will be documented in Changelog file.

---

Made with ❤️