---
name: xylabs-xy-cli
description: >
  Comprehensive reference for the `xy` CLI provided by `@xylabs/toolchain`.
  Use this skill whenever the user asks how to build, lint, test, deploy, or run any
  tooling command in an XY Labs monorepo — even if they just say something like
  "how do I compile" or "check my deps". Covers every command, common workflows,
  single-package targeting, and troubleshooting.
---
# xylabs-xy-cli

The `xy` CLI is the unified build toolchain for all XY Labs and XYO Network TypeScript
monorepos. It wraps compilation, linting, testing, dependency analysis, deployment, and
repo maintenance into a single tool.

**Always run `xy` commands from the repo root**, never from inside a package directory.

---

## Package Manager Detection

Before running any command, detect the repo's package manager by checking the repo root:
- `yarn.lock` present → use **yarn** (e.g. `yarn xy build`)
- `pnpm-lock.yaml` present → use **pnpm** (e.g. `pnpm xy build`)

All commands below are shown without a prefix. Prepend the detected package manager
when executing (e.g. `xy build` → `yarn xy build` or `pnpm xy build`).

---

## Installation

The CLI is provided by `@xylabs/toolchain`. It is already a devDependency in every
XY Labs repo — no separate install is needed. The toolchain auto-detects React
projects and enables React-specific commands (`start`, `analyze`, `sitemap`) when
appropriate.

---

## Global Options

All commands accept these flags:

| Flag | Description |
|---|---|
| `-j, --jobs` | Max parallel jobs |
| `-v, --verbose` | Run with verbose logging (default: false) |
| `-i, --incremental` | Only act on changed packages (default: false) |
| `-p, --profile` | Profile the action (default: false) |
| `--version` | Show version number |
| `--help` | Show help |

---

## Command Reference

### Build & Compile

| Command | Description |
|---|---|
| `xy build [package]` | Full build: compile + publint + deplint + lint |
| `xy compile [package]` | Compile all packages (TypeScript via tsup) + publint |
| `xy compile-only [package]` | Compile only (no publint) |
| `xy recompile [package]` | Clean compiled output, then compile again |
| `xy rebuild [package]` | Clean everything, then full build |
| `xy copy-assets [package]` | Copy non-TS assets from `src/` to `dist/` |
| `xy clean [package]` | Remove `dist/` and `build/` artifacts |

### Lint & Fix

| Command | Description |
|---|---|
| `xy check` | Run gitlint, publint, repo lint, and lintlint as a batch |
| `xy lint [package]` | Run ESLint across all packages |
| `xy fix [package]` | Run ESLint with `--fix` to auto-fix issues |
| `xy relint [package]` | Clean ESLint cache, then lint from scratch |
| `xy deplint [package]` | Verify imports match `package.json` dependency declarations |
| `xy publint [package]` | Validate `package.json` correctness for npm publishing |
| `xy dead [package]` | Check for dead (unreachable) code |
| `xy sonar` | Run SonarQube analysis |
| `xy lintlint` | Check for redundant or overridden ESLint rules vs shared config |

### Testing

| Command | Description |
|---|---|
| `xy test [target]` | Run Vitest tests |
| `xy retest [target]` | Clean test cache, then run tests |

### Deploy & Publish

| Command | Description |
|---|---|
| `xy deploy` | Patch version bump + build + publish |
| `xy deploy-minor` | Minor version bump + build + publish |
| `xy deploy-major` | Major version bump + build + publish |
| `xy deploy-next` | Deploy as `next` tag (pre-release) |
| `xy publish` | Publish packages to npmjs (without version bump) |

### Dependency Management

| Command | Description |
|---|---|
| `xy reinstall` | Remove `node_modules`, reinstall from scratch |
| `xy up` | Update all dependencies to latest compatible versions |
| `xy updo` | Update dependencies (interactive) |
| `xy statics` | Confirm static packages |

### Git & Repo Maintenance

| Command | Description |
|---|---|
| `xy gitlint [package]` | Lint git configuration (ignorecase, autocrlf, etc.) |
| `xy gitignore` | Generate root `.gitignore` and remove package-level ones |
| `xy npmignore-gen` | Generate `.npmignore` files |
| `xy license [package]` | Check dependency licenses for compliance |
| `xy gen-docs [package]` | Generate TypeDoc API documentation |
| `xy clean-docs` | Clean TypeDoc output |

### README Utilities

| Command | Description |
|---|---|
| `xy readme gen [package]` | Generate README.md files from template |
| `xy readme init` | Initialize README template and logo files |

`xy readme gen` accepts `--template <path>` to specify a custom template and
`--typedoc` to include TypeDoc reference sections.

### Repo Utilities

| Command | Description |
|---|---|
| `xy repo lint` | Check monorepo package structure (root private, workspace globs, etc.) |

### Package Manager Utilities

| Command | Description |
|---|---|
| `xy packman convert <target>` | Convert repo to a different package manager (pnpm or yarn) |
| `xy packman lint` | Check package manager configuration settings |

### Claude Code Integration

| Command | Description |
|---|---|
| `xy claude init` | Initialize all Claude configuration (commands, rules, skills, settings) |
| `xy claude check` | Check if Claude configuration is up to date with templates |
| `xy claude clean` | Remove all Claude configuration files |
| `xy claude commands` | Sync slash commands to `.claude/commands/` |
| `xy claude rules` | Sync rules to `.claude/rules/` |
| `xy claude skills` | Sync skills to `.claude/skills/` |
| `xy claude settings` | Initialize `.claude/settings.local.json` |

---

## Targeting a Single Package

Most commands accept an optional `[package]` argument to scope to one package:

```bash
xy compile my-package
xy lint my-package
xy deplint my-package
```

Use the **package name** from `package.json` (e.g. `@xylabs/assert`), not the directory
path. You can also use just the short name without the scope (e.g. `assert`).

---

## Common Workflows

### Before pushing code
```bash
xy build
```
This runs the full pipeline: compile, publint, deplint, and lint. If it passes, the code
is ready to push.

### After modifying dependencies
```bash
xy deplint
```
Catches missing or extraneous entries in `package.json` relative to actual imports.

### When lint results seem stale
```bash
xy relint
```
Clears the ESLint cache and re-lints everything.

### When tests seem stale
```bash
xy retest
```
Clears the Vitest cache and re-runs tests.

### When things are broken and you want a clean slate
```bash
xy rebuild
```
Cleans all artifacts, recompiles, and re-lints.

### Nuclear option — full reset
```bash
xy reinstall
```
Removes `node_modules` and reinstalls everything from scratch.

---

## Troubleshooting

### "Command not found: xy"
The `xy` binary comes from `@xylabs/toolchain`. Run `install` via your package
manager to ensure it is linked. The binary is at `node_modules/.bin/xy`.

### Compile errors in other packages
`@xylabs/toolchain` must compile before other packages that depend on it. The repo's
`compile` script handles this ordering automatically — always use `xy compile`
from the root, not `tsc` directly.

### Deplint false positives
Deplint scans TypeScript source imports and `tsconfig.json` extends chains. If a
dependency is used only in config files (not source), it may flag as unused. Check the
output carefully before removing.

### Version conflicts
All packages in a repo share a single version. Never edit version fields manually —
use `xy deploy` variants to bump versions.
