HomeAPIBlog
Edit

wheels generate app-wizard

Interactive wizard for creating a new Wheels application with guided setup.

Synopsis

wheels generate app-wizard [options]

#Can also be used as:
wheels g app-wizard [options]
wheels new [options]

Parameter Syntax

CommandBox supports multiple parameter formats:

  • Named parameters: name=value (e.g., name=MyApp, template=wheels-base-template@BE)

  • Flag parameters: --flag equals flag=true (e.g., --expert equals expert=true)

  • Flag with value: --flag=value equals flag=value (e.g., --skipInstall=true)

Note: Flag syntax (--flag) avoids positional/named parameter conflicts and is recommended for boolean options.

Description

The wheels generate app-wizard command provides an interactive, step-by-step wizard for creating a new Wheels application. It guides you through configuration options with helpful prompts, making it ideal for beginners or when you want to explore available options.

Arguments

Argument
Description
Default

name

Application name (optional - will prompt if not provided)

Prompted

Options

Option
Description
Valid Values
Default

template

App template to use

ForgeBox endpoint or slug

wheels-base-template@BE

directory

Directory to create app in

Valid directory path

{current directory}/{name}

reloadPassword

Reload password for the app

Any string

changeMe

datasourceName

Database datasource name

Valid datasource name

{app name}

cfmlEngine

CFML engine for server.json

lucee, adobe, lucee6, lucee5, adobe2023, etc.

lucee

useBootstrap

Add Bootstrap to the app

true, false

false

setupH2

Setup H2 database for development

true, false

true

init

Initialize directory as a package

true, false

false

force

Force installation into non-empty directory

true, false

false

nonInteractive

Run without prompts using defaults

true, false

false

expert

Show advanced configuration options

true, false

false

skipInstall

Skip dependency installation after creation

true, false

false

Interactive Wizard Steps

Step 1: Application Name

Please enter a name for your application: MyWheelsApp

  • Validates name format (alphanumeric, underscores, hyphens)

  • Checks for reserved names

  • Creates directory with this name

Step 2: Template Selection

Which Wheels Template shall we use?
❯ 3.0.x - Wheels Base Template - Bleeding Edge
  2.5.x - Wheels Base Template - Stable Release
  Wheels Template - HTMX - Alpine.js - Simple.css
  Wheels Starter App
  Wheels - TodoMVC - HTMX - Demo App
  Enter a custom template endpoint

Step 3: Reload Password

Please enter a 'reload' password for your application: changeMe

  • Used for ?reload=true&password=xxx functionality

  • Secures application reload via URL

Step 4: Database Configuration

Please enter a datasource name if different from MyWheelsApp: MyWheelsApp

  • Sets datasource name in configuration files

  • You'll configure the actual datasource in your CFML server admin

Step 5: CFML Engine Selection

Please select your preferred CFML engine?
❯ Lucee (Latest)
  Adobe ColdFusion (Latest)
  Lucee 6.x
  Lucee 5.x
  Adobe ColdFusion 2023
  Adobe ColdFusion 2021
  Adobe ColdFusion 2018
  Enter a custom engine endpoint

Step 6: H2 Database Setup (Lucee Only, if skipInstall=false)

H2 Java embedded SQL database for development? [y,n]

  • Only shown when using Lucee engine

  • Only asked if skipInstall=false

  • Sets up embedded H2 database for development

Step 7: Dependencies (if skipInstall=false)

========= Dependencies ======================
Configure dependencies and plugins for your application.

Would you like us to setup some default Bootstrap settings? [y/n]

  • Only shown if skipInstall=false

  • Configures Bootstrap CSS framework

  • Additional dependencies may be added here

Step 8: Package Initialization

Finally, shall we initialize your application as a package
by creating a box.json file? [y,n]

  • Creates box.json for ForgeBox package management

  • Always asked regardless of skipInstall setting

Step 9: Expert Mode (if expert=true)

========= Expert Mode: Advanced Configuration ==========
Configure advanced options for your application.

Custom server port (leave empty for default 8080): 8080
Custom JVM settings (e.g. -Xmx512m -Xms256m):
Setup custom environment configurations (dev, staging, production)? [y,n]
Enable advanced routing features (nested resources, constraints)? [y,n]
Custom plugin repositories (comma-separated URLs):
Build tool integration? [None/Apache Ant/Gradle/Maven/NPM Scripts]

Step 10: Configuration Review

+-----------------------------------------------------------------------------------+
| Great! Think we're all good to go. We're going to create a Wheels application for |
| you with the following parameters.                                                |
+-----------------------+-----------------------------------------------------------+
| Template              | wheels-base-template@BE                                   |
| Application Name      | MyWheelsApp                                              |
| Install Directory     | D:\path\to\MyWheelsApp                                   |
| Reload Password       | changeMe                                                 |
| Datasource Name       | MyWheelsApp                                              |
| CF Engine             | lucee                                                    |
| Setup H2 Database     | true                                                     | (if applicable)
| Setup Bootstrap       | false                                                    | (if applicable)
| Initialize as Package | true                                                     |
| Force Installation    | false                                                    |
| Skip Dependency Install | false                                                  |
+-----------------------+-----------------------------------------------------------+

Sound good? [y/n]

skipInstall Parameter Behavior

The skipInstall parameter significantly changes the wizard experience:

When skipInstall=false (default)

  • ✅ Asks about H2 database setup (if using Lucee)

  • ✅ Asks about Bootstrap dependencies

  • ✅ Shows "Dependencies" section

  • ✅ Includes dependency settings in summary table

  • ✅ Installs dependencies after app creation

When skipInstall=true

  • ❌ Skips H2 database question (even with Lucee)

  • ❌ Skips Bootstrap dependency question

  • ✅ Shows "Dependencies Skipped" message with explanation

  • ✅ Excludes dependency settings from summary table

  • ✅ Still asks about package initialization (box.json creation)

  • ✅ Still asks about core configuration (name, template, passwords, etc.)

  • ❌ Skips dependency installation after app creation

Dependencies Skipped Message

========= Dependencies Skipped ================
Dependency installation is disabled (skipInstall=true).
Dependencies like Bootstrap and H2 database will not be configured or installed.

Examples

Basic Interactive Wizard

wheels generate app-wizard

Runs full interactive wizard with all prompts.

Pre-configured App Name

wheels generate app-wizard name=MyApp

Skips name prompt, asks for other configuration.

Skip All Dependencies

wheels generate app-wizard --skipInstall

Runs wizard but skips H2 database and Bootstrap questions.

Expert Mode

wheels generate app-wizard --expert

Includes advanced configuration options like custom ports and JVM settings.

Non-Interactive Mode

wheels generate app-wizard --nonInteractive

Uses all defaults, no prompts. Creates app immediately.

Fully Configured

wheels generate app-wizard name=MyApp template=wheels-base-template@BE --skipInstall --expert --force

Pre-configured with expert mode and skipped dependencies.

Expert Mode Options

When --expert is enabled, additional configuration options are available:

Server Configuration

  • Custom server port: Override default port 8080

  • JVM settings: Custom memory and performance settings

Environment Setup

  • Custom environment configurations: Setup dev, staging, production configs

  • Advanced routing features: Enable nested resources and route constraints

Development Tools

  • Custom plugin repositories: Additional ForgeBox endpoints

  • Build tool integration: Ant, Gradle, Maven, or NPM integration

Non-Interactive Mode

Use --nonInteractive to bypass all prompts:

Default Values Used

  • Name: MyWheelsApp

  • Template: wheels-base-template@BE

  • Reload Password: changeMe

  • Datasource Name: Same as app name

  • CFML Engine: lucee

  • Directory: {current directory}/{name}

Override Defaults

wheels generate app-wizard --nonInteractive name=CustomApp template=wheels-starter-app --cfmlEngine=adobe

Post-Creation Steps

After successful creation:

Model generation complete!

Next steps:
   1. cd MyWheelsApp
   2. Review generated configuration files
   3. Configure your datasource in CFML server admin
   4. box server start (to start development server)
   5. Visit http://localhost:8080

Additional commands:
   - wheels generate model User name:string,email:string
   - wheels generate controller Users
   - wheels dbmigrate up (run database migrations)
   - wheels test run (run tests)

Validation Rules

Application Name

  • Must start with a letter

  • Can contain letters, numbers, underscores, and hyphens

  • Cannot contain spaces or special characters

  • Cannot exceed 50 characters

  • Cannot be a reserved name (con, prn, aux, nul, wheels, etc.)

Directory Path

  • Must be a valid file system path

  • Parent directory must exist and be writable

  • Will warn if target directory is not empty (unless --force used)

Error Handling

Common Issues and Solutions

Invalid application name:

'123app' is not valid. Application name must start with a letter.
Please try again: MyApp

Directory not empty:

Target directory is not empty. Use --force to overwrite, or choose a different location.

Missing dependencies:

Warning: Some dependencies could not be installed.
Run 'box install' in your application directory to install them manually.

Best Practices

  1. Use descriptive names: Choose clear, project-specific application names

  2. Review configuration: Check the summary table before confirming

  3. Consider skipInstall: Use --skipInstall for custom dependency management

  4. Expert mode for production: Use --expert for production-ready configurations

  5. Save time with non-interactive: Use --nonInteractive in automated scripts

  6. Template selection: Choose templates that match your project requirements

Common Patterns

API-Only Application

wheels generate app-wizard name=MyAPI template=wheels-base-template@BE --skipInstall --expert

Full-Stack Web Application

wheels generate app-wizard name=MyWebApp --useBootstrap --setupH2

Team Development Setup

wheels generate app-wizard --nonInteractive name=TeamProject template=wheels-starter-app --cfmlEngine=lucee --force

CI/CD Pipeline

wheels generate app-wizard --nonInteractive --skipInstall name=BuildApp template=wheels-base-template@BE

Troubleshooting

Wizard Hangs or Freezes

  1. Check terminal compatibility

  2. Try --nonInteractive mode

  3. Ensure adequate system resources

Installation Failures

  1. Verify internet connection for template downloads

  2. Check CommandBox version compatibility

  3. Try --skipInstall and install dependencies manually

  4. Check file permissions in target directory

Configuration Issues

  1. Review generated server.json file

  2. Verify datasource configuration in CFML admin

  3. Check application settings in /config/app.cfm

See Also

Previouswheels generate appNextwheels generate controller

Last updated

Was this helpful?