Getting Started

1. Install xo

Install the xocode package globally. The binary is available as xo.

$npm install -g xocode

Or with pnpm / yarn / bun:

$pnpm add -g xocode
$yarn global add xocode
$bun add -g xocode

2. Scaffold a new project

Use xo create to bootstrap a new project from a generator. Reference any public GitHub repo directly with the @github/ prefix — no registration needed.

$mkdir my-app && cd my-app
$xo create @github/my-org/xo-next-app

xo will:

1. Fetch workflow.yaml from the GitHub repo (cached locally)
2. Run any interactive prompts defined under inputs:
3. Execute all jobs and steps — copy files, render templates, run commands
4. Write xo.config.yaml to record the applied template

3. Add features to an existing project

xo add applies a generator's add workflow to your project. Before running, xo validates compatibility via detects, requires, and conflicts rules declared in the generator.

$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

Pin to a tag (@v1.2.0) for a stable, cached-forever version. Use a branch suffix (#main) to always pull latest.

4. Pre-fill inputs

Pass -i key=value to skip specific prompts. Useful for scripting or CI.

$xo add @github/my-org/xo-stripe -i secretKey=sk_test_abc
$xo create @github/my-org/xo-flutter -i appName='My App' -i projectName=my_app

5. Preview before applying

Use --dry-run to see exactly what a generator would do without writing any files or running any commands.

$xo add @github/my-org/xo-stripe --dry-run

Running workflow: @github/my-org/xo-stripe

  job: detect
    ✔ xo/detect-pm → pnpm
    ✔ xo/pkg-installed(next) → true (^14.0.0)
  job: install
    [dry-run] install-pkg: pnpm add stripe
    [dry-run] env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
  job: configure
    [dry-run] copy: templates/stripe-route.ts → app/api/stripe/route.ts
    [dry-run] run: pnpm db:push

Dry run — no files were written.

6. View history and undo

xo records every operation in .xo/state.json. Use xo history to list them and xo undo to revert the last one.

$xo history

Applied generators:

  a1b2c3d4  @github/my-org/xo-next-app   create   5/4/2025, 10:32:00 AM
  e5f6a7b8  @github/my-org/xo-stripe     add      5/4/2025, 10:45:12 AM

$xo undo

7. Build your own generator

A generator is a GitHub repo with a workflow.yaml file, templates, and optional custom actions. Use xo link to test it locally from any project — no publishing required.

$cd ~/projects/xo-my-generator
$xo link                  # register by name from workflow.yaml

$cd ~/my-app
$xo add my-generator      # resolves to ~/projects/xo-my-generator

Push to GitHub and share with the @github/owner/repo reference — no registry account needed.