Command reference

This comprehensive reference covers all Aurelia CLI commands, their options, and usage patterns.

Global Commands

au new

Creates a new Aurelia project or plugin.

Syntax:

au new [project-name] [options]

Options:

• --plugin - Creates a plugin project instead of an application

• --here - Creates the project in the current directory

• --unattended - Uses default options without prompting

• --typescript - Uses TypeScript template

• --webpack - Uses Webpack bundler

• --require-js - Uses RequireJS module loader

• --system-js - Uses SystemJS module loader

Examples:

# Interactive project creation
au new my-app

# Create plugin project
au new my-plugin --plugin

# Create TypeScript app with Webpack
au new my-app --typescript --webpack

# Create project in current directory
au new --here

Prerequisites:

• Node.js v10.0.0 or higher

• Git client

• Available disk space (project templates ~50MB)

au help

Displays help information for CLI commands.

Syntax:

au help [command]

Examples:

# General help
au help

# Help for specific command
au help new
au help generate

au version / au -v

Displays the current CLI version.

Syntax:

au version
au -v

Project Commands

These commands work within an Aurelia project directory.

au run

Builds and serves the application for development.

Syntax:

au run [options]

Options:

• --env <environment> - Specifies environment (dev, stage, prod)

• --port <port> - Sets server port (default: 8080)

• --host <host> - Sets server host (default: localhost)

• --open - Opens browser automatically

• --hmr - Enables Hot Module Reload (Webpack only)

• --analyze - Runs webpack bundle analyzer (Webpack only)

• --extractCss - Extracts CSS to separate file (Webpack only)

• --watch - Watches for file changes and rebuilds

• --auto-install - Automatically installs missing packages (ESNext only)

Examples:

# Basic development server
au run

# Production environment
au run --env prod

# Custom port and auto-open browser
au run --port 3000 --open

# Hot module reload for Webpack projects
au run --hmr

# Auto-install missing dependencies
au run --auto-install

Environment Variables:

• AURELIA_CLI_SILENCE_WARNINGS - Suppresses CLI warnings

• NODE_ENV - Sets Node.js environment

au build

Builds the application for production deployment.

Syntax:

au build [options]

Options:

• --env <environment> - Specifies build environment

• --watch - Watches for changes and rebuilds

• --analyze - Analyzes bundle composition (Webpack only)

• --extractCss - Extracts CSS to separate file (Webpack only)

Examples:

# Production build
au build --env prod

# Development build with watching
au build --env dev --watch

# Analyze bundle size
au build --analyze

Output:

• Built files go to dist/ directory

• Source maps included based on environment configuration

au test

Runs the project's test suite.

Syntax:

au test [options]

Options:

• --watch - Runs tests in watch mode

• --debug - Enables debug mode

• --coverage - Generates code coverage report

• --env <environment> - Specifies test environment

Examples:

# Run tests once
au test

# Watch mode for continuous testing
au test --watch

# Generate coverage report
au test --coverage

Supported Test Frameworks:

• Jest (default for new projects)

• Karma + Jasmine

• Protractor (e2e testing)

au generate

Scaffolds Aurelia resources using built-in generators.

Syntax:

au generate <resource> <name> [options]

Available Resources:

• element - Custom element

• attribute - Custom attribute

• value-converter - Value converter

• binding-behavior - Binding behavior

• task - Gulp task

• generator - Custom generator

Options:

• --force - Overwrites existing files

Examples:

# Generate custom element
au generate element user-profile

# Generate custom attribute
au generate attribute highlight

# Generate value converter
au generate value-converter date-format

# Generate binding behavior  
au generate binding-behavior throttle

# Generate gulp task
au generate task deploy

# Force overwrite existing files
au generate element my-element --force

File Conventions:

• Uses kebab-case for file names

• Generates both view-model and template files for elements

• Creates corresponding test files when test framework is configured

Advanced Commands

au install

Installs and configures Aurelia plugins and third-party packages.

Syntax:

au install <package-name> [options]

Options:

• --save - Adds to dependencies in package.json

• --save-dev - Adds to devDependencies

• --force - Forces reinstallation

Examples:

# Install Aurelia plugin
au install aurelia-validation

# Install with save to dependencies
au install lodash --save

Auto-configuration:

• Updates aurelia.json dependencies automatically

• Configures known Aurelia plugins

• Handles font and asset copying for UI libraries

au clear-cache

Clears build caches to resolve build issues.

Syntax:

au clear-cache

What it clears:

• Webpack module cache

• TypeScript compilation cache

• CLI bundler cache

• Node modules cache

When to use:

• After major dependency updates

• When experiencing unexplained build errors

• After switching between branches with different dependencies

Flag Reference

Environment Flags

Built-in Environments:

• dev - Development (default)

• stage - Staging

• prod - Production

Custom Environments: Create additional environment files in aurelia_project/environments/

Debug Flags

Webpack Projects:

• --analyze - Bundle analyzer

• --extractCss - CSS extraction

• --hmr - Hot module reload

CLI Bundler Projects:

• --watch - File watching

• --auto-install - Package auto-install

Compatibility Flags

Legacy Support:

• --require-js - RequireJS loader

• --system-js - SystemJS loader

Platform Specific:

• Windows: Use CMD or PowerShell (not Git Bash)

• Docker: May need polling for file watching

Error Handling

Common Error Patterns

Installation Errors:

# Permission denied (Mac/Linux)
sudo npm install aurelia-cli -g

# Clear npm cache
npm cache clean --force

Build Errors:

# Clear all caches
au clear-cache

# Reinstall dependencies
rm -rf node_modules
npm install

Module Resolution Errors:

# For Webpack projects
# Ensure PLATFORM.moduleName() usage

# For CLI bundler projects  
# Check aurelia.json dependencies

Troubleshooting Commands

# Check CLI version
au -v

# Validate project structure
au help

# Clear caches and rebuild
au clear-cache && au build

# Debug mode for detailed output
au run --env dev --debug

Integration Commands

Git Integration

# Create project with git
au new my-app
cd my-app
git init
git add .
git commit -m "Initial commit"

Docker Integration

# Build for Docker
au build --env prod

# Dockerfile commands
FROM node:14
WORKDIR /app
COPY . .
RUN npm install && au build --env prod

CI/CD Integration

# Install CLI in CI environment
npm install aurelia-cli -g

# Run tests in CI
au test --coverage

# Build for deployment
au build --env prod

Performance Optimization

Build Performance

# Enable caching in aurelia.json
"options": {
  "cache": true
}

# Use webpack analyzer
au build --analyze

# Extract CSS for better caching
au build --extractCss

Development Performance

# Use auto-install for faster setup
au run --auto-install

# Enable HMR for instant updates
au run --hmr

# Use watch mode for continuous builds
au build --watch

Best Practices

Command Usage

1. Always use specific environments:

   au build --env prod  # Not just 'au build'

2. Clear cache when in doubt:

   au clear-cache

3. Use generators for consistency:

   au generate element user-card  # Not manual file creation

4. Test before building:

   au test && au build --env prod

Project Organization

1. Consistent naming:

   • Use kebab-case for generated resources

   • Follow CLI naming conventions

2. Environment configuration:

   • Keep environment-specific settings in environment files

   • Use aurelia.json for shared configuration

3. Dependency management:

   • Use au install for Aurelia packages

   • Update aurelia.json for complex dependencies

The Aurelia CLI provides a comprehensive toolset for managing Aurelia applications throughout their development lifecycle. Understanding these commands and their options enables efficient development workflows and troubleshooting capabilities.