or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-system-integration.mdcli-commands.mdindex.mdpackage-management.mdprogrammatic-api.mdschematics-integration.mdworkspace-configuration.md
tile.json

programmatic-api.mddocs/

Programmatic API

The Angular CLI provides a limited programmatic interface for executing CLI commands from Node.js applications. This API is designed primarily for build tools, automation scripts, and testing environments that need to invoke Angular CLI functionality programmatically.

Capabilities

CLI Execution Function

Execute Angular CLI commands programmatically with full control over arguments and error handling.

/**
 * Execute Angular CLI commands programmatically
 * @param options - Configuration object containing CLI arguments
 * @returns Promise resolving to exit code (0 = success, non-zero = error)
 */
export default function cli(options: { cliArgs: string[] }): Promise<number>;

Usage Examples:

import cli from "@angular/cli";

// Build the project
const buildResult = await cli({
  cliArgs: ["build", "--configuration", "production"]
});

if (buildResult === 0) {
  console.log("Build successful");
} else {
  console.error(`Build failed with exit code: ${buildResult}`);
}

// Generate a component
const generateResult = await cli({
  cliArgs: ["generate", "component", "user-profile", "--skip-tests"]
});

// Run tests
const testResult = await cli({
  cliArgs: ["test", "--watch=false", "--browsers=ChromeHeadless"]
});

Error Handling:

The function handles various error scenarios and returns appropriate exit codes:

  • 0: Command executed successfully
  • 1: General error occurred
  • 3: Node.js version compatibility error
  • 127: Unhandled exception occurred

Advanced Usage:

import cli from "@angular/cli";

async function buildAllConfigurations() {
  const configurations = ["development", "staging", "production"];
  
  for (const config of configurations) {
    console.log(`Building ${config} configuration...`);
    
    const exitCode = await cli({
      cliArgs: ["build", "--configuration", config]
    });
    
    if (exitCode !== 0) {
      throw new Error(`Build failed for ${config} configuration`);
    }
  }
  
  console.log("All configurations built successfully");
}

// Execute with error handling
try {
  await buildAllConfigurations();
} catch (error) {
  console.error("Build process failed:", error.message);
  process.exit(1);
}

Version Information

Access current CLI version information for compatibility checks and logging.

/**
 * Current CLI version information
 */
export const VERSION: {
  /** Full version string (e.g., "20.2.2") */
  readonly full: string;
  /** Major version number (e.g., "20") */
  readonly major: string;
  /** Minor version number (e.g., "2") */
  readonly minor: string;
  /** Patch version number (e.g., "2") */
  readonly patch: string;
};

Usage Examples:

import { VERSION } from "@angular/cli";

console.log(`Angular CLI version: ${VERSION.full}`);
console.log(`Major version: ${VERSION.major}`);

// Version compatibility check
if (parseInt(VERSION.major) < 20) {
  console.warn("This script requires Angular CLI version 20 or higher");
}

// Version-specific feature detection
const supportsNewFeature = parseInt(VERSION.major) >= 20 && parseInt(VERSION.minor) >= 2;
if (supportsNewFeature) {
  // Use newer CLI features
}

Implementation Notes

Node.js Requirements

The programmatic API enforces the same Node.js version requirements as the CLI:

  • Minimum version: 20.19 or 22.12
  • Odd-numbered versions display warnings but are allowed
  • Incompatible versions return exit code 3

Logging Integration

The programmatic API redirects console output through Angular's internal logging system:

  • console.log and console.info → info level
  • console.warn → warn level
  • console.error → error level
  • Debug logging controlled by NG_DEBUG environment variable

Process Integration

The API integrates with the host process:

  • Sets process title for process monitoring
  • Handles process exit codes appropriately
  • Supports graceful shutdown and cleanup

Example with logging control:

import cli from "@angular/cli";

// Enable debug logging
process.env.NG_DEBUG = "true";

const result = await cli({
  cliArgs: ["build", "--verbose"]
});

// Restore normal logging
delete process.env.NG_DEBUG;