@xds/cli

bash
npx xds --help
npx xds search button
npx xds component Button
npx xds docs tokens
npx xds docs migration
npx xds template --list

bash
$ npx xds search button
​
Results for "button" (20):
​
  [component]  Button
               Button triggers an action when clicked. Use it for form submissions…
               → npx xds component Button
​
  [component]  IconButton
               A button that shows only an icon with no visible text…
               → npx xds component IconButton
​
  [hook]       useClickableContainer
               Makes a container element clickable while preserving nested…
               → npx xds hook useClickableContainer
​
  [template]   Banner — Collapsible
               Combine an action button, dismiss control, and expandable detail area…
               → npx xds template BannerCollapsibleContent

json
{"type": "component.detail", "data": {"name": "Button", ...}}

json
{
  "error": "No component named \"Buttn\"",
  "code": "ERR_UNKNOWN_COMPONENT",
  "suggestions": [{"name": "Button", "reason": "similar name"}]
}

typescript
import {isError} from '@xds/cli/json';
​
const result = parseResponse(raw);
if (isError(result)) {
  switch (result.code) {
    case 'ERR_UNKNOWN_COMPONENT':
      // suggest the closest match
      break;
    case 'ERR_CORE_NOT_FOUND':
      // prompt the user to install @xds/core
      break;
    default:
      console.error(result.error);
  }
}

bash
xds manifest --json        # dedicated surface — type: "manifest"
xds --json                 # bare invocation — embeds the same payload under data.manifest

jsonc
{
  "apiVersion": 1,
  "type": "manifest",
  "data": {
    "name": "xds",
    "version": "0.0.14",
    "description": "Design system CLI — components, themes, and tooling",
    "globalOptions": [
      {"flag": "--json", "type": "boolean", "description": "Output as typed JSON…"},
      {"flag": "--lang <locale>", "type": "enum", "choices": ["en", "zh", "dense"]},
      {"flag": "--detail <level>", "type": "enum", "choices": ["full", "compact", "brief"], "default": "full"}
    ],
    "commands": [
      {
        "name": "component",
        "description": "List components or print component docs",
        "arguments": [{"name": "name", "required": false, "variadic": false, "description": ""}],
        "options": [{"flag": "--props", "type": "boolean", "description": "Print only the props table"}],
        "json": true,
        "responseTypes": ["component.list", "component.detail", "component.detail.props", "…"],
        "examples": ["xds component XDSButton --props --json"]
      }
      // …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
    ],
    "jsonSupported": ["component", "docs", "…"],
    "responseTypes": {"component": ["component.list", "…"], "theme build": ["theme.build"]}
  }
}

typescript
import {component, docs, discover, template, hook, search, XDSError} from '@xds/cli/api';
​
// Same result as: xds --json component Button
const btn = await component('Button');
btn.type; // 'component.detail'
btn.data.name; // 'Button' (typed as ComponentDoc)
​
// Same result as: xds --json component --list
const list = await component(undefined, {list: true});
list.data; // Record<string, string[]>
​
// Same result as: xds --json docs principles
const principles = await docs('principles');
principles.data.title; // 'XDS Principles'
​
// Same result as: xds --json hook useMediaQuery
const useMediaQuery = await hook('useMediaQuery');
useMediaQuery.data.params; // typed as HookParamDoc[]
​
// Errors throw XDSError with a stable .code and optional .suggestions
try {
  await component('Buttn');
} catch (e) {
  e.message; // 'No component named "Buttn"'
  e.code; // 'ERR_UNKNOWN_COMPONENT' (stable; branch on this)
  e.suggestions; // [{ name: 'Button', reason: 'similar name' }]
}

typescript
import {parseResponse, isError, assertResponse} from '@xds/cli/json';
import type {ComponentDetailResponse, CLIResult} from '@xds/cli/json';
​
const result = parseResponse(stdout);
if (isError(result)) {
  console.error(result.error);
} else {
  switch (result.type) {
    case 'component.detail':
      result.data.name; // TypeScript: ComponentDoc
      break;
  }
}
​
// Or assert directly (throws on error/mismatch):
const detail = assertResponse(stdout, 'component.detail');
detail.data.name; // already narrowed

$ xds doctor
xds doctor — diagnosing your setup
​
  ✓ Node.js version
      Node v22.13.0 meets the minimum (>=22.13.0).
  ✓ @xds/core installed
      @xds/core resolved (v0.0.14).
  ✓ @xds/core <-> @xds/cli alignment
      @xds/core v0.0.14 is in step with @xds/cli v0.0.14.
  ⚠ Theme packages
      No @xds/theme-* packages are installed.
      → fix: Install a theme, e.g. `npm install @xds/theme-default`, then import its CSS or set xds.theme.
  ℹ xds.config.mjs
      No xds.config.mjs found — using defaults.
  ℹ AI agent docs
      No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
      → fix: Generate agent docs with `xds init --features agents`.
  ✓ @xds/core peer dependencies
      All peer dependencies satisfied (react, react-dom).
  ℹ Package manager
      Detected package manager: yarn.
​
Summary: 4 passed, 1 warning, 0 failures, 3 info
​
No failures — but review the ⚠ warnings above when you can.

yaml
- run: npx xds doctor