xo is a local workflow engine for project scaffolding, feature addition, and task automation. Think of it as GitHub Actions — but running on your machine, against your project.

Define reusable actions, compose them into workflows, share them through the xo registry — all in plain YAML.

Install

npm install -g @xo-code/cli

Then use it as xo:

xo --version
xo add ui/button

Quick Start

# From the registry (registered name)
xo add payment/stripe
xo add ui/button

# Directly from GitHub — no registration needed
xo add @github/my-org/xo-stripe
xo add @github/my-org/xo-ui/button          # subpath (multi-component repo)
xo add @github/my-org/xo-ui/[email protected]   # pinned to tag
xo add @github/my-org/xo-ui/button#dev      # pinned to branch

| Command | What it does | |---|---| | xo create <template> | Scaffold a new project | | xo add <feature> | Add a feature to an existing project | | xo run <task> | Run a named task | | xo undo | Revert the last operation |

How It Works

xo has two core concepts: actions and workflows.

Actions are atomic, reusable units of work. They accept with: inputs and produce outputs. Built-in actions are prefixed xo/. You can also write custom actions as YAML composites or Node.js scripts.

Workflows compose actions into jobs with inputs, conditionals, and dependency ordering — exactly like GitHub Actions workflow files.

# workflow.yaml (lives in a generator repo on GitHub)
name: payment/stripe
on: [add]

inputs:
  secretKey:
    prompt: "Stripe secret key?"
    required: true

jobs:
  detect:
    steps:
      - uses: xo/detect-pm        # outputs: { value: "pnpm" }
        id: pm
      - uses: xo/pkg-installed    # outputs: { installed: true }
        id: hasNext
        with:
          pkg: next

  install:
    needs: [detect]
    steps:
      - uses: xo/install-pkg
        with:
          pkg: stripe

      - uses: xo/env
        with:
          file: .env.example
          variables:
            STRIPE_SECRET_KEY: ""

      - if: "steps.hasNext.outputs.installed == true"
        uses: xo/copy
        with:
          from: templates/stripe-route.ts
          to: app/api/stripe/route.ts

      - run: "{{steps.pm.outputs.value}} db:push"

Custom Actions

Package reusable logic as YAML composites or Node.js scripts and reference them from any workflow.

Composite action (./actions/add-barrel.yaml):

name: add-barrel-export
inputs:
  exportName:
    prompt: "Export name?"
outputs:
  exportLine:
    value: "export { default as {{inputs.exportName}} } from './{{inputs.exportName}}';"
steps:
  - uses: xo/append
    with:
      file: src/components/index.ts
      content: "export { default as {{inputs.exportName}} } from './{{inputs.exportName}}';"

Script action (./actions/validate.js):

export default async function run({ inputs, cwd, dryRun }) {
  // full Node.js — call APIs, read files, anything
  return { valid: true };
}

Published action (shared via GitHub):

- uses: @github/my-org/[email protected]
  with:
    strict: "true"

Local Generator Development

Test a generator locally without publishing using xo link:

cd ~/projects/xo-button
xo link                    # links ui/button → this directory

# from any project:
xo add ui/button           # resolves to your local directory

CLI Output

$ xo add payment/stripe

Running workflow: payment/stripe

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

✔ payment/stripe added successfully
  Operation ID: a3f1c2d4
  Run xo undo to revert.

Documentation

| Doc | Description | |---|---| | CLI Reference | All commands and flags | | Workflow Reference | workflow.yaml full schema | | Action Reference | Built-in + custom actions | | Generator Reference | Repo structure, registry, writing generators |

Requirements

• Node.js >= 18