Angular Schematics CLI

Angular Schematics CLI is a command-line interface tool for running Angular schematics, which are templates that generate or modify code in Angular applications. The CLI provides a standalone interface for executing schematic collections, built-in schematics for creating new schematic projects, and various options for controlling execution behavior.

Package Information

• Package Name: @angular-devkit/schematics-cli
• Package Type: npm
• Language: TypeScript
• Installation: npm install -g @angular-devkit/schematics-cli

Core Imports

This package is primarily used as a CLI tool via the schematics command, but programmatic usage is possible:

import { main, MainOptions } from '@angular-devkit/schematics-cli/bin/schematics';

For Node.js CommonJS:

const { main } = require('@angular-devkit/schematics-cli/bin/schematics');

Basic Usage

The primary usage is through the command line:

# Install globally
npm install -g @angular-devkit/schematics-cli

# Create a blank schematic project
schematics blank my-schematics

# Create a full schematic template
schematics schematic --name my-custom-schematic

# Run a schematic from a collection
schematics @angular/core:component --name my-component

# List available schematics in a collection
schematics --list-schematics @angular/core:

Architecture

The Angular Schematics CLI is built around several key components:

• CLI Interface: Main executable that parses command-line arguments and orchestrates schematic execution
• Built-in Schematics: Two pre-built schematics for creating new schematic projects
• Workflow Integration: Integration with Angular DevKit's NodeWorkflow for schematic execution
• Interactive Prompts: Support for user input during schematic execution
• Collection System: Ability to run schematics from local or npm-published collections

Capabilities

Command Line Interface

The main CLI functionality for running schematics and managing schematic collections.

/**
 * Main CLI execution function
 * @param options - Options object containing args and optional output streams
 * @returns Promise resolving to exit code (0 for success, 1 for failure)
 */
function main(options: MainOptions): Promise<0 | 1>;

Command Line Options:

• --debug: Enable debug mode (auto-enabled for local collections)
• --allow-private: Allow private schematics to run (default: false)
• --dry-run: Show actions without executing (auto-enabled in debug mode)
• --force: Force overwrite existing files (default: false)
• --list-schematics: List all schematics in a collection
• --no-interactive: Disable interactive prompts
• --verbose: Show detailed information
• --help: Show usage information

Usage Examples:

# Basic usage pattern
schematics [collection-name:]schematic-name [options, ...]

# Run built-in schematics
schematics blank my-project
schematics schematic --name my-schematic --author "John Doe"

# Run external collection schematics
schematics @angular/core:component --name my-component
schematics @ngrx/schematics:store --name app --statePath state

# Debug and development
schematics my-schematic --debug --dry-run
schematics my-schematic --force --verbose

# List schematics
schematics --list-schematics
schematics --list-schematics @angular/core:

Built-in Schematics

Two pre-built schematics for creating new schematic projects.

Blank Schematic

Creates an empty schematic project or adds a blank schematic to an existing project.

interface BlankSchemaOptions {
  /** Package name for the new schematic (optional, can be provided as positional argument) */
  name?: string;
  /** Package manager to use (default: "npm") */
  packageManager?: "npm" | "yarn" | "pnpm" | "cnpm" | "bun";
  /** Author for the new schematic */
  author?: string;
}

Usage:

# Create a new blank schematic project
schematics blank my-schematics

# Specify package manager and author
schematics blank my-schematics --packageManager=yarn --author="Jane Doe"

Schematic Template

Creates a complete schematic template that can be built and published to NPM.

interface SchematicTemplateOptions {
  /** Package name for the new schematic (required) */
  name: string;
  /** Author for the new schematic */
  author?: string;
  /** Package manager to use (default: "npm") */
  packageManager?: "npm" | "yarn" | "pnpm" | "cnpm" | "bun";
}

Usage:

# Create a new schematic template
schematics schematic --name my-custom-schematic

# With author and package manager
schematics schematic --name my-custom-schematic --author="John Doe" --packageManager=pnpm

Programmatic Usage

For advanced use cases, the CLI can be used programmatically.

Example:

import { main } from '@angular-devkit/schematics-cli/bin/schematics';

// Run a schematic programmatically
const exitCode = await main({
  args: [
    'blank',
    'my-project',
    '--packageManager=yarn'
  ]
});

if (exitCode === 0) {
  console.log('Schematic executed successfully');
} else {
  console.log('Schematic execution failed');
}

Types

interface MainOptions {
  /** Command line arguments */
  args: string[];
  /** Optional output stream */
  stdout?: ProcessOutput;
  /** Optional error stream */
  stderr?: ProcessOutput;
}

interface ProcessOutput {
  write(chunk: string): boolean;
}

Error Handling

The CLI handles various error conditions:

• Collection not found: Returns exit code 1 when specified collection cannot be located
• Schematic not found: Returns exit code 1 when specified schematic doesn't exist in collection
• Schema validation errors: Prompts for missing required options or validates input types
• File conflicts: Respects --force flag for overwriting existing files
• Workflow execution errors: Catches and reports UnsuccessfulWorkflowExecution exceptions

Common error patterns:

# Collection not found
$ schematics nonexistent:schematic
# Error: Collection "nonexistent" cannot be resolved.

# Missing required option
$ schematics schematic
# Error: Required option "--name" is missing.

# File conflicts without --force
$ schematics blank existing-project
# Error: Path "/existing-project" already exists.

Integration with Angular DevKit

The CLI integrates with several Angular DevKit packages:

• @angular-devkit/core: Logging, JSON utilities, and schema validation
• @angular-devkit/schematics: Core schematics engine and rule system
• @angular-devkit/schematics/tools: NodeWorkflow for schematic execution
• @angular-devkit/schematics/tasks: Built-in tasks like NodePackageInstallTask

This integration enables the CLI to execute schematics with full Angular DevKit ecosystem support, including file system virtualization, change tracking, and task scheduling.