@astryxdesign/cli

bash
npx @astryxdesign/cli --help
npx @astryxdesign/cli search button
npx @astryxdesign/cli component Button
npx @astryxdesign/cli docs tokens
npx @astryxdesign/cli docs migration
npx @astryxdesign/cli template --list

bash
$ astryx search button
​
Results for "button" (20):
​
  [component]  Button
               Button triggers an action when clicked. Use it for form submissions…
               → astryx component Button
​
  [component]  IconButton
               A button that shows only an icon with no visible text…
               → astryx component IconButton
​
  [hook]       useClickableContainer
               Makes a container element clickable while preserving nested…
               → astryx hook useClickableContainer
​
  [template]   Banner — Collapsible
               Combine an action button, dismiss control, and expandable detail area…
               → astryx 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 '@astryxdesign/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 @astryxdesign/core
      break;
    default:
      console.error(result.error);
  }
}

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

jsonc
{
  "apiVersion": 1,
  "type": "manifest",
  "data": {
    "name": "astryx",
    "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": ["astryx component Button --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,
  AstryxError,
} from '@astryxdesign/cli/api';
​
// Same result as: astryx --json component Button
const btn = await component('Button');
btn.type; // 'component.detail'
btn.data.name; // 'Button' (typed as ComponentDoc)
​
// Same result as: astryx --json component --list
const list = await component(undefined, {list: true});
list.data; // Record<string, string[]>
​
// Same result as: astryx --json docs principles
const principles = await docs('principles');
principles.data.title; // 'Principles'
​
// Same result as: astryx --json hook useMediaQuery
const useMediaQuery = await hook('useMediaQuery');
useMediaQuery.data.params; // typed as HookParamDoc[]
​
// Errors throw AstryxError 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} from '@astryxdesign/cli/json';
import type {
  ComponentDetailResponse,
  ComponentListResponse,
  DocsListResponse,
  // ...import the response types for the commands you consume
} from '@astryxdesign/cli/json';
​
// parseResponse returns the structural { type, data, meta? } envelope; `data`
// is `unknown` until you narrow it. Reconstruct the union you care about from
// the per-command response types, then narrow on `type`:
type MyResponse =
  ComponentDetailResponse | ComponentListResponse | DocsListResponse;
​
const result = parseResponse(stdout);
if (isError(result)) {
  console.error(result.error);
} else {
  const r = result as MyResponse;
  switch (r.type) {
    case 'component.detail':
      r.data.name; // narrowed to ComponentDoc
      break;
  }
}

typescript
import {assertResponse} from '@astryxdesign/cli/json';
import type {ComponentDetailResponse} from '@astryxdesign/cli/json';
​
type MyResponse = ComponentDetailResponse; /* | ...others */
​
function assertTyped<T extends MyResponse['type']>(raw: unknown, type: T) {
  return assertResponse(raw, type) as Extract<MyResponse, {type: T}>;
}
​
const detail = assertTyped(stdout, 'component.detail');
detail.data.name; // narrowed

$ astryx doctor
astryx doctor — diagnosing your setup
​
  ✓ Node.js version
      Node v22.13.0 meets the minimum (>=22.13.0).
  ✓ @astryxdesign/core installed
      @astryxdesign/core resolved (v0.0.14).
  ✓ @astryxdesign/core <-> @astryxdesign/cli alignment
      @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
  ⚠ Theme packages
      No @astryxdesign/theme-* packages are installed.
      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
  ℹ astryx.config.mjs
      No astryx.config.mjs found — using defaults.
  ℹ AI agent docs
      No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
      → fix: Generate agent docs with `astryx init --features agents`.
  ✓ @astryxdesign/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 @astryxdesign/cli doctor

typescript
export default {
  integrations: ['@acme/astryx-widgets'],
  issuesUrl: 'https://github.com/your-org/your-repo/issues',
};

typescript
export default {
  components: './components',
  templates: './templates',
  codemods: './codemods',
  issuesUrl: 'https://github.com/acme/widgets/issues',
};