Tools

CLI Reference

The xo CLI is the primary way to interact with the generator engine. Install it globally with npm install -g xocode.

xo create

Scaffold a new project

xo create <template> [options]

Downloads and runs a project-type generator to scaffold a new project from scratch. The template is resolved by GitHub path (owner/repo) or local path (./path/to/generator).

Option	Description
--dry-run	Preview all actions without writing any files
--dir <path>	Target directory (default: current working directory)

terminal

$xo create acme/nextjs-starter
$xo create acme/nestjs-api --dir ./api
$xo create ./local-template --dry-run
$xo create acme/generators/monorepo-base

xo add

Add a feature to an existing project

xo add <feature> [options]

Applies a feature-type generator to the current project. Validates compatibility (detects, requires, conflicts) before running any actions.

Option	Description
--dry-run	Preview all actions without writing any files

terminal

$xo add acme/shadcn-setup
$xo add acme/auth-jwt
$xo add acme/prisma --dry-run

Validation order

Before running, xo checks detects rules (signals compatible?), then requires (prerequisites applied?), then conflicts (no conflicting generators?). All three must pass.

xo run

Run any generator by name

xo run <name> [options]

Runs a generator regardless of its declared type. Useful for one-off generators or task runners.

Option	Description
--dry-run	Preview all actions without writing any files

terminal

$xo run acme/scaffold-module
$xo run ./internal/codegen

xo undo

Revert the last operation

xo undo

Reverts the most recent xo create, xo add, or xo run operation. Files that were created are deleted; files that were modified are restored.

terminal

$xo undo

File changes only

xo undo restores file content but does not reverse shell commands (like pnpm install). Reverse those manually if needed.

xo history

List applied generators

xo history

Lists every generator applied in the current project in chronological order, with operation ID, generator name, and timestamp.

terminal

$xo history

Generator resolution

xo looks for generator.json in this order:

Local path

Name starts with ./ or / → reads directly from that directory.

Project-local

.xo/generators/<name>/generator.json in the current project.

Global cache

~/.xo/generators/<name>/generator.json.

GitHub fetch

Fetches from https://raw.githubusercontent.com/<owner>/<repo>/main/generator.json and caches globally.

Subpath generators

The name owner/repo/subpath maps to …/owner/repo/main/subpath/generator.json — letting you host multiple generators in a single GitHub repo.

Project files written by xo

xo.config.json

Records the applied template and features. Used by requires/conflicts validation on subsequent runs. Commit this file.

{
  "template": "acme/nextjs-starter",
  "features": ["acme/shadcn-setup", "acme/auth-jwt"]
}

.xo/state.json

Stores every operation with before-snapshots for undo. Commit this file so your team shares generator history.

{
  "operations": [
    {
      "id": "a1b2c3d4-...",
      "timestamp": "2025-05-04T10:32:00.000Z",
      "generator": "acme/nextjs-starter",
      "type": "create",
      "files": [
        { "filePath": "src/app/page.tsx", "action": "created" },
        { "filePath": "package.json",     "action": "modified", "before": "..." }
      ]
    }
  ]
}