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 <generator> [options]

Runs the generator's create workflow to scaffold a new project from scratch. Generators are resolved by direct GitHub reference (@github/owner/repo), registered name, or local path.

Option	Description
--dry-run	Preview all actions without writing any files
-i <key>=<val>	Pre-fill an input, skipping the interactive prompt for that value. Repeatable.
--local	Run a generator from a local path without linking

terminal

$xo create @github/my-org/xo-next-app
$xo create flutter-app
$xo create @github/betaversionio/xo-flutter
$xo create ./my-template --local --dry-run

xo add

Add a feature to an existing project

xo add <generator> [options]

Applies a generator to the current project. Validates compatibility (detects, requires, conflicts) before running any steps.

Option	Description
--dry-run	Preview all actions without writing any files
-i <key>=<val>	Pre-fill an input. Repeatable.
--local	Run from a local path without linking

terminal

$xo add @github/my-org/xo-stripe
$xo add @github/my-org/xo-ui/button
$xo add @github/my-org/xo-ui/button@v1.2.0
$xo add payment/stripe --dry-run
$xo add ui/button -i componentName=Button -i variant=primary

Validation order

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

xo run

Run a generator's run workflow

xo run <generator> [options]

Triggers the generator's run workflow. Useful for task runners or one-off generators.

Option	Description
--dry-run	Preview without writing files
-i <key>=<val>	Pre-fill an input

terminal

$xo run db:migrate
$xo run @github/my-org/xo-codegen

xo undo

Revert the last operation

xo undo

Reverts the most recent xo add or xo create operation. Files that were created are deleted; files that were modified are restored from their before-snapshot.

terminal

$xo undo

File changes only

xo undo restores file content but does not reverse shell commands (like flutter pub get). 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, trigger, and timestamp.

terminal

$xo history

Local development

These commands are for generator authors building and testing a generator locally.

xo link [name]

Register the current directory as a named generator. xo reads the name field from workflow.yaml automatically — pass a name only to override. Once linked, xo add <name> from any project resolves to your local directory. Changes to workflow.yaml or templates are picked up immediately.

terminal

$cd ~/projects/xo-stripe
$xo link
$xo link payment/stripe

xo unlink [name]

Remove the link for the current directory. Run inside the generator repo.

terminal

$cd ~/projects/xo-stripe
$xo unlink

xo links

List all locally linked generators with their names, paths, and link dates.

terminal

$xo links

Registry

xo registry add <name>

terminal

$xo registry add payment/stripe --url https://github.com/my-org/xo-stripe
$xo registry add ui/button --url https://github.com/my-org/xo-ui --path button

xo registry list

List all registered generators.

terminal

$xo registry list

xo registry remove <name>

Remove a generator from the local registry.

terminal

$xo registry remove payment/stripe

Cache

xo caches generator files fetched from GitHub in ~/.xo/cache/. Branch refs are always re-fetched on each run. Tag refs are cached forever (immutable).

xo cache list

List all cached generators with their owner, repo, ref, and cache path.

terminal

$xo cache list

xo cache clear [owner]

Clear the entire GitHub cache, or only the cache for a specific GitHub owner.

terminal

$xo cache clear
$xo cache clear my-org

Generator resolution

xo resolves a generator name in this order:

Local path

Name starts with ./ or / → reads directly from that path. Requires --local flag.

Linked generators

Checks ~/.xo/links.json for a match — set by xo link inside a generator repo.

Registry

Checks ~/.xo/registry.json for a registered URL — set by xo registry add.

@github/ reference

Name starts with @github/ → fetches workflow.yaml from GitHub and caches it in ~/.xo/cache/.

Use @github/owner/repo/subpath to reference a generator in a subdirectory of a repo — e.g. @github/my-org/xo-ui/button.

Project files written by xo

xo.config.yaml

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

template: flutter-app
packageManager: pnpm
features:
  - payment/stripe
  - 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": "@github/betaversionio/xo-flutter",
      "type": "create",
      "files": [
        { "filePath": "lib/main.dart", "action": "created" },
        { "filePath": "pubspec.yaml",  "action": "modified", "before": "..." }
      ]
    }
  ]
}