USING THE CLI3 MIN READ · MARKDOWN ↗

Creating a project

Interactive mode, reproducible scaffolding, Astro shell, and generated TypeScript.

See versions, changes and requirements in Framework 4.0 and CLI 1.2.

Reproducible creation

wu create conocimiento --template react --shell astro

Quick mode activates when a name and template are provided. It writes conocimiento/, an Astro shell, a React microapp named conocimiento, configuration, and manifests. This mode does not install dependencies. At the end it suggests entering the folder and running wu install and wu dev.

conocimiento/
  .gitignore
  package.json
  wu.config.json
  shell/
    package.json
    astro.config.mjs
    src/pages/index.astro
    src/styles/wu-shell.css
  mf-conocimiento/
    package.json
    index.html
    vite.config.js
    src/main.tsx
    src/App.tsx

The structure shows the main files for that combination. Other frameworks choose different extensions, components, and configurations. The generator does not write a source wu.json: the development server can synthesize one, and the build writes the production manifest. Create one explicitly when the app needs to declare contracts or permissions.

A new project includes .gitignore for dependencies, builds, caches, logs, PEM keys and .env, retaining .env.example. wu upgrade can add those rules to an older project without replacing existing ones.

Recognized options

Argument	Alias	Effect
Positional name	—	Project directory and first app name in quick mode
`--template <framework>`	`-t`	Generated microapp framework
`--shell <framework>`	`-s`	Shell framework in quick mode

If you omit --shell, the shell uses the --template selection; its actual form may be a framework-specific or framework-agnostic shell. --shell without --template does not configure the wizard: the interactive flow asks for the shell again.

There is no --no-install for create, because quick mode already leaves installation pending. There are also no public --typescript, --yes, --package-manager, or --apps flags. Use only the contract in the table to automate this version.

Interactive wizard

wu create

The wizard uses raw terminal mode. It requests a name, shell, and microapps one by one; it offers TypeScript where the template supports it. App ports start at 5001 and increment. The interactive flow supports up to 16 apps; use explicit configuration for larger topologies.

The wizard asks to confirm generation and installation and runs wu install. A failed installation returns 1; without a terminal it also returns 1 and shows quick mode. Ctrl+C cancels with 130. Quick mode still does not install dependencies.

Names and validation

Creation rejects an existing directory with exit code 1. An unknown template also fails. Astro and Next are in the shell catalog but are rejected as the --template for a microapp.

App names are normalized and validated against ^[a-z][a-z0-9-]{0,31}$, excluding Windows reserved names. The project allows up to 64 characters without paths or spaces; the first app in quick mode must also meet its 32-character limit. A generation failure leaves no partial directory.

Astro inside a WU project

Astro compiles the shell with its own bundler. WU serves that output and mounts microapps from their WU entrypoints. The scaffold does not turn React or Vue into Astro islands: composition between applications belongs to the WU runtime.

The generated shell imports its stylesheet, initializes the framework, and consumes the app catalog inserted by the CLI. Configuration declares npx astro dev and npx astro build. In native development mode, WU uses Astro’s build output and rebuilds it when its sources change.

Implementation references

wu-cli/src/commands/create.zig
wu-cli/src/config/names.zig
wu-cli/src/config/catalog.zig
wu-cli/src/commands/templates/astro-shell.index.astro
wu-cli/tests/create-exit-code.test.cjs
wu-cli/tests/wizard-keys.test.cjs
wu-cli/tests/gitignore.test.cjs