CLI

Install, run, and troubleshoot the xtaskjs console client.

This page covers the xtask console workflow from first install to day-to-day project scaffolding, including create, generate, option reference, and troubleshooting guidance from the upstream repository.

Open Install Open Samples

2 commands + 5 option groups

Project bootstrap

The console client can scaffold a fresh XTaskJS application from the official typescript-starter and optionally install dependencies with npm, pnpm, yarn, or bun.

Artifact generation

The generate command emits controllers, services, repositories, DTOs, guards, middlewares, modules, resources, gateways, value objects, event-source scaffolds, and throttler helpers that follow upstream templates.

Cache workflow

The cache command talks to runtime management endpoints so teams can inspect models, inspect entries, clear caches, and check effective HTTP/browser cache metadata from the terminal.

Module install workflow

The add command installs official @xtaskjs modules, supports npm/pnpm/yarn/bun, and can list the latest published versions from npm for selective upgrades.

Install

Ways to run the xtask console client

Global npm install

Install the published package globally when you want a shell-wide xtask binary for repeated project scaffolding and code generation.

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

One-off execution with npx

Use npx to verify the published package or run the console client without changing the current machine's global toolchain.

npx @xtaskjs/cli --help

Run from source

Run the CLI from source while iterating on templates, generators, or release packaging.

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

Create a cache-ready application

Use the verified create workflow from the CLI repo to bootstrap an app, then add the cache package before wiring cache decorators into generated code.

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

Commands

Core CLI commands and example invocations

xtask create

create

Bootstraps a new XTaskJS application from the official typescript-starter archive and can install dependencies immediately after scaffolding.

Usage

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

Examples

Scaffold a new application

xtask create my-api

Skip install and choose a package manager

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

xtask generate

generate

Emits feature-oriented source files inside an existing XTaskJS app, supporting controller, service, repository, dto, guard, middleware, module, resource, gateway, value-object, event-aggregate, event-subscriber, throttle-guard, and throttle-config scaffolds.

Usage

xtask generate <type> <name> [options]

Examples

Generate a controller

xtask generate controller users

Generate a CRUD resource

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

Scaffold a cache-backed resource

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

Generate a guarded module scaffold

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

Generate event-source and throttler scaffolds

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

xtask cache

cache

Manages an XTaskJS app cache using runtime admin endpoints, including model inspection, entry inspection, invalidation, and HTTP cache policy checks.

Usage

xtask cache <subcommand> [options]

Examples

List cache models and inspect one entry

xtask cache models
xtask cache entry products 42

Inspect HTTP cache metadata for one route

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

Target a custom management endpoint

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

xtask add

add

Installs official @xtaskjs modules into an existing project and can query npm to list current published versions.

Usage

xtask add [modules...] [options]

Examples

Install selected modules

xtask add cache queues socket-io

Install all official modules

xtask add --all

List module versions from npm

xtask add --list core cache socket-io

Options

Command flags and scaffolding controls

Global flags

Applies to the top-level xtask binary regardless of subcommand.

--help
Print command help and exit.
--version
Show the installed CLI version.

Project creation options

Controls how the create command chooses a destination directory and installs dependencies.

-f, --force
Allow scaffolding into a non-empty destination directory.
--skip-install
Download the starter but do not run the selected package manager afterward.
--package-manager <manager>
Choose which package manager to run after scaffolding: npm, pnpm, yarn, or bun.

Artifact generation options

Shapes where generated files are written and how much scaffold code is emitted.

--path <directory>
Resolve generated output relative to a different source directory.
--route <path>
Override the route path used by generated controllers.
--flat
Write files directly into the target path instead of creating a feature subdirectory.
--with-guard
Generate a guard file and wire it into module or resource controllers.
--with-dto
For resource scaffolds, also emit a DTO file for request validation.
--crud
For resource scaffolds, emit CRUD-style controller, service, repository, and DTO code.
-f, --force
Overwrite existing files instead of aborting when the destination already exists.

Cache command options

Controls how cache subcommands reach runtime management endpoints.

--server <url>
Override the base server URL used by cache requests (default: http://127.0.0.1:3000).
--management-path <path>
Override the cache management controller path (default: /ops/cache).
cache http-route --method <method> --path <path>
Inspect one route's effective HTTP/browser cache policy exposed by createCacheManagementController().

Module install options

Controls how the add command resolves official modules and package managers.

--all
Install every official @xtaskjs module currently mapped by the CLI.
--list
Print module names with latest published npm versions instead of installing.
--package-manager <manager>
Choose install command family for add: npm, pnpm, yarn, or bun.

Troubleshooting

What to check when the CLI is not available

1. Check the active Node environment

Confirm node -v and the active npm global prefix before assuming the xtask binary is broken.

2. Inspect the global install

Run npm list -g --depth=0 @xtaskjs/cli and type -a xtask to see whether the current shell can resolve the installed package.

3. Reinstall for the active runtime

If you use nvm or multiple Node versions, reinstall @xtaskjs/cli in the active version and refresh the shell hash.

4. Verify with a direct invocation

Use xtask --help or npx @xtaskjs/cli --help to confirm the published package works before troubleshooting project-specific commands.

Notes

Generator behavior worth knowing

The create command downloads the starter project from xtaskjs/typescript-starter.
Supported generate types: controller, service, repository, resource, dto, guard, middleware, module, gateway, value-object, event-aggregate, event-subscriber, throttle-guard, and throttle-config.
Resource and module scaffolds create a feature directory by default; pass --flat to write directly into the chosen path.
The --with-guard flag adds a guard file and applies @UseGuards(...) to generated module or resource controllers.
The --with-dto flag only applies to resource scaffolds, and --crud upgrades the same scaffold to CRUD-style controller, service, repository, and DTO code.
Generated DTOs assume class-validator is installed and may require class-transformer for richer validation pipelines.
The cache command expects your app to expose management endpoints, typically by using createCacheManagementController({ path: "/ops/cache" }).
The add command resolves aliases like cache or socket-io to official @xtaskjs packages and installs latest published versions.
The current upstream CLI surface does not ship a dedicated cache generator; scaffold a module or resource first, then add @xtaskjs/cache configuration and decorators inside the generated files.