create-auto-app

create-auto-app

Create Auto Engineer apps with no configuration.

Purpose

create-auto-app is a CLI scaffolding tool that generates complete Auto Engineer project structures. It copies a selected template, resolves the latest @auto-engineer/* package versions from npm, generates a unique project fileId, and optionally installs dependencies. It supports both interactive prompts and non-interactive flags.

Installation

# Global install
npm install -g create-auto-app

# Or run directly with npx (no install needed)
npx create-auto-app

Requires Node.js >= 18.0.0.

Quick Start

# 1. Scaffold a new project (interactive mode)
npx create-auto-app

# 2. Or pass a project name directly (uses the "typical" template by default)
npx create-auto-app my-app

# 3. Enter the project directory
cd my-app

# 4. Run Auto Engineer
auto

When run without arguments, the CLI prompts for:

1. Project name (default: my-auto-app)
2. Template (if multiple templates are available)
3. Install dependencies? (default: yes)

How-to Guides

Scaffold in the current directory

npx create-auto-app .

The project name is inferred from the current directory name.

Use a specific template

npx create-auto-app my-app --template minimal

Choose a package manager

The CLI auto-detects your package manager (checks pnpm, then yarn, then falls back to npm). To override:

npx create-auto-app my-app --use-pnpm
npx create-auto-app my-app --use-yarn
npx create-auto-app my-app --use-npm

Skip dependency installation

npx create-auto-app my-app --no-install

CI/CD usage

Combine flags to avoid interactive prompts:

npx create-auto-app my-app --template typical --no-install --use-pnpm

All required values are provided via flags, so no TTY is needed.

CLI Reference

create-auto-app [project-name] [options]

If project-name is omitted, the CLI enters interactive mode.

Options

Option	Alias	Default	Description
--template <name>	-t	typical	Project template to use
--no-install			Skip dependency installation
--use-npm			Force npm as the package manager
--use-yarn			Force yarn as the package manager
--use-pnpm			Force pnpm as the package manager
--version	-V		Print version number
--help	-h		Show help

Available templates

Template	Description
typical	A handpicked set of builders curated by the Auto team (default)
minimal	Minimal template with a single plugin for testing

Templates are discovered dynamically from the templates/ directory via template.json metadata files.

Generated project structure

my-app/
├── .context/           # Design system context files
├── narratives/         # Narrative-driven development files
├── server/             # Server-side code
├── auto.config.ts      # Auto Engineer pipeline configuration
├── package.json
├── pnpm-workspace.yaml
└── .env.example

The generated auto.config.ts receives a unique fileId (via @auto-engineer/id) so each project is independently identifiable.

Troubleshooting

Debug logging

The CLI uses ora spinners and chalk colored output. Errors are printed to stderr with red highlighting. To see full stack traces, check the terminal output directly -- the CLI does not swallow errors silently.

Directory already exists

Symptom: Prompted "Directory X already exists. Overwrite?"

Fix: Confirm the overwrite prompt, or choose a different project name. There is no --force flag; the CLI always asks for confirmation before deleting an existing directory.

Template not found

Symptom: Template "foo" not found at ...

Fix: Run create-auto-app --help to see the template names listed in the --template option description. Use one of the listed names.

Package manager not found

Symptom: Dependency installation fails.

Fix: Install the desired package manager globally, or use a different one:

npm install -g pnpm
npx create-auto-app my-app --use-pnpm

Dependencies fail to install

Symptom: Failed to install dependencies message.

Fix: The spinner will show the failure. Common causes:

• Network issues reaching the npm registry.
• Conflicting lockfiles. Delete node_modules and the lockfile, then run the install command manually.
• Missing pnpm-workspace.yaml. The CLI creates one automatically if absent, but if something interrupts the process, create it manually:

packages:
  - '*'

Version resolution fails

Symptom: @auto-engineer/* packages show as latest instead of a pinned version.

Cause: npm view <package> version failed (network issue or package not yet published).

Fix: After scaffolding, manually set the versions in package.json and re-run pnpm install.

Architecture

graph TD
    A[create-auto-app CLI] --> B[commander: parse args]
    B --> C{project-name provided?}
    C -->|No| D[inquirer: interactive prompts]
    C -->|Yes| E[resolve options from flags]
    D --> F[createProject]
    E --> F
    F --> G[prepareTargetDirectory]
    G --> H[createFromTemplate]
    H --> I[fs-extra: copy template files]
    I --> J[collectAllAutoEngineerPackages]
    J --> K[npm view: fetch latest versions]
    K --> L[updatePackageVersions]
    L --> M["replaceTemplateFileId (@auto-engineer/id)"]
    M --> N{--no-install?}
    N -->|No| O[execa: run package manager install]
    N -->|Yes| P[print success message]
    O --> P

Loading

Source layout

src/
└── index.ts            # CLI entry point, all scaffolding logic
scripts/
└── copy-templates.ts   # Build script: copies examples/ into templates/
templates/
├── typical/            # Full-featured template
└── minimal/            # Single-plugin template

Dependencies

Package	Purpose
@auto-engineer/id	Generate unique 9-character fileId for each project
commander	CLI argument parsing and help text
inquirer	Interactive terminal prompts
chalk	Colored terminal output
ora	Loading spinners for async operations
execa	Execute shell commands (package manager detection, installs, npm view)
fs-extra	File system operations (copy, readJson, ensureDir)
@scarf/scarf	Anonymous install analytics