CLI

Instala, ejecuta y resuelve problemas del cliente de consola de xtaskjs.

Esta página cubre el flujo de trabajo de la consola xtask desde la primera instalación hasta el scaffolding diario de proyectos, incluyendo create, generate, la referencia de opciones y la guía de resolución de problemas del repositorio oficial.

Abrir instalación Abrir ejemplos

2 comandos + 5 grupos de opciones

Arranque de proyectos

El cliente de consola puede crear una aplicación XTaskJS nueva a partir del typescript-starter oficial y opcionalmente instalar dependencias con npm, pnpm, yarn o bun.

Generación de artefactos

El comando generate emite controladores, servicios, repositorios, DTOs, guards, middlewares, módulos, recursos, gateways, value objects, scaffolds de event-source y utilidades de throttler que siguen las plantillas oficiales.

Cache workflow

El comando cache se comunica con endpoints de gestión en runtime para inspeccionar modelos, inspeccionar entradas, limpiar caches y revisar metadata efectiva de cache HTTP/browser desde la terminal.

Flujo de instalación de módulos

El comando add instala módulos oficiales de @xtaskjs, soporta npm/pnpm/yarn/bun y puede listar las últimas versiones publicadas en npm para upgrades selectivos.

Instalación

Formas de ejecutar el cliente de consola xtask

Instalación global con npm

Instala el paquete publicado globalmente cuando quieras un binario xtask disponible en toda la shell para repetir scaffolding de proyectos y generación de código.

npm install -g @xtaskjs/cli
xtask --help

Ejecución puntual con npx

Usa npx para verificar el paquete publicado o ejecutar el cliente de consola sin cambiar la cadena global de herramientas de la máquina actual.

npx @xtaskjs/cli --help

Ejecutar desde el código fuente

Ejecuta la CLI desde el código fuente mientras iteras sobre plantillas, generadores o el empaquetado de releases.

git clone https://github.com/xtaskjs/xtask-cli.git
cd xtask-cli
npm install
npm run start -- --help

Crear una aplicación lista para cache

Usa el flujo verificado de create desde el repositorio de la CLI para arrancar una aplicación y después añadir el paquete de cache antes de conectar decoradores de cache en el código generado.

xtask create cache-demo
cd cache-demo
npm install @xtaskjs/cache

Comandos

Comandos principales de la CLI y ejemplos de invocación

xtask create

create

Crea una nueva aplicación XTaskJS a partir del archivo oficial typescript-starter y puede instalar dependencias justo después del scaffolding.

Uso

xtask create <project-name> [directory] [options]

Ejemplos

Crear una nueva aplicación

xtask create my-api

Omitir la instalación y elegir un gestor de paquetes

xtask create billing-api ./services/billing --package-manager pnpm --skip-install

xtask generate

generate

Emite archivos fuente orientados a funcionalidades dentro de una app XTaskJS existente, con soporte para scaffolds de controller, service, repository, dto, guard, middleware, module, resource, gateway, value-object, event-aggregate, event-subscriber, throttle-guard y throttle-config.

Uso

xtask generate <type> <name> [options]

Ejemplos

Generar un controlador

xtask generate controller users

Generar un recurso CRUD

xtask generate resource billing --path src/modules --crud

Generar un recurso preparado para cache

xtask generate resource cache-entries --path src/modules --crud --with-dto

Generar un scaffold de módulo con guard

xtask generate module reports --path src/modules --with-guard

Generar scaffolds de event-source y throttler

xtask generate event-aggregate orders --path src/domain
xtask generate throttle-guard api --path src/security

xtask cache

cache

Gestiona la cache de una app XTaskJS usando endpoints de administración en runtime, incluyendo inspección de modelos, inspección de entradas, invalidación y comprobaciones de políticas HTTP cache.

Uso

xtask cache <subcommand> [options]

Ejemplos

Listar modelos de cache e inspeccionar una entrada

xtask cache models
xtask cache entry products 42

Inspeccionar metadata HTTP cache de una ruta

xtask cache http-route --method GET --path /articles/landing

Apuntar a un endpoint de gestión personalizado

xtask cache models --server http://127.0.0.1:4000 --management-path /internal/cache

xtask add

add

Instala módulos oficiales de @xtaskjs en un proyecto existente y puede consultar npm para listar versiones publicadas actuales.

Uso

xtask add [modules...] [options]

Ejemplos

Instalar módulos seleccionados

xtask add cache queues socket-io

Instalar todos los módulos oficiales

xtask add --all

Listar versiones de módulos desde npm

xtask add --list core cache socket-io

Opciones

Flags de comando y controles de scaffolding

Flags globales

Se aplican al binario xtask de nivel superior independientemente del subcomando.

--help
Muestra la ayuda del comando y sale.
--version
Muestra la versión instalada de la CLI.

Opciones de creación de proyectos

Controla cómo el comando create elige el directorio de destino e instala dependencias.

-f, --force
Permite hacer scaffolding en un directorio de destino no vacío.
--skip-install
Descarga el starter pero no ejecuta después el gestor de paquetes seleccionado.
--package-manager <manager>
Elige qué gestor de paquetes ejecutar después del scaffolding: npm, pnpm, yarn o bun.

Opciones de generación de artefactos

Define dónde se escriben los archivos generados y cuánto código de scaffold se emite.

--path <directory>
Resuelve la salida generada respecto a un directorio fuente distinto.
--route <path>
Sobrescribe la ruta usada por los controladores generados.
--flat
Escribe archivos directamente en la ruta de destino en lugar de crear un subdirectorio de funcionalidad.
--with-guard
Genera un archivo guard y lo conecta a controladores de module o resource.
--with-dto
Para scaffolds de resource, emite también un archivo DTO para validación de peticiones.
--crud
Para scaffolds de resource, emite código de controller, service, repository y DTO con estilo CRUD.
-f, --force
Sobrescribe archivos existentes en lugar de abortar cuando el destino ya existe.

Opciones del comando cache

Controla cómo los subcomandos de cache alcanzan los endpoints de gestión en runtime.

--server <url>
Sobrescribe la URL base del servidor usada por las peticiones de cache (por defecto: http://127.0.0.1:3000).
--management-path <path>
Sobrescribe la ruta del controlador de gestión de cache (por defecto: /ops/cache).
cache http-route --method <method> --path <path>
Inspecciona la política efectiva de cache HTTP/browser de una ruta expuesta por createCacheManagementController().

Opciones de instalación de módulos

Controla cómo el comando add resuelve módulos oficiales y gestores de paquetes.

--all
Instala todos los módulos oficiales de @xtaskjs actualmente mapeados por la CLI.
--list
Muestra nombres de módulos con sus últimas versiones publicadas en npm en lugar de instalar.
--package-manager <manager>
Elige la familia de comandos de instalación para add: npm, pnpm, yarn o bun.

Resolución de problemas

Qué comprobar cuando la CLI no está disponible

1. Comprueba el entorno Node activo

Confirma node -v y el prefijo global activo de npm antes de asumir que el binario xtask está roto.

2. Inspecciona la instalación global

Ejecuta npm list -g --depth=0 @xtaskjs/cli y type -a xtask para ver si la shell actual puede resolver el paquete instalado.

3. Reinstala para el runtime activo

Si usas nvm o varias versiones de Node, reinstala @xtaskjs/cli en la versión activa y refresca la caché de la shell.

4. Verifica con una invocación directa

Usa xtask --help o npx @xtaskjs/cli --help para confirmar que el paquete publicado funciona antes de investigar comandos específicos del proyecto.

Notas

Detalles del generador que conviene conocer

El comando create descarga el proyecto starter desde xtaskjs/typescript-starter.
Tipos compatibles con generate: controller, service, repository, resource, dto, guard, middleware, module, gateway, value-object, event-aggregate, event-subscriber, throttle-guard y throttle-config.
Los scaffolds de resource y module crean un directorio de funcionalidad por defecto; usa --flat para escribir directamente en la ruta elegida.
La flag --with-guard añade un archivo guard y aplica @UseGuards(...) a los controladores generados de module o resource.
La flag --with-dto solo se aplica a scaffolds de resource, y --crud mejora ese mismo scaffold con código de controller, service, repository y DTO al estilo CRUD.
Los DTO generados asumen que class-validator está instalado y pueden requerir class-transformer para canalizaciones de validación más completas.
El comando cache espera que tu app exponga endpoints de gestión, normalmente usando createCacheManagementController({ path: "/ops/cache" }).
El comando add resuelve alias como cache o socket-io hacia paquetes oficiales de @xtaskjs e instala las últimas versiones publicadas.
La superficie actual de la CLI oficial no incluye un generador dedicado para cache; primero genera un módulo o un recurso y después añade la configuración y los decoradores de @xtaskjs/cache dentro de los archivos generados.