Skip to content

cli

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

cli

README.md

@astryxdesign/cli

The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.

Run it one-off with the scoped package (works whether or not it's installed):

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

Once it's a project dependency (npm install -D @astryxdesign/cli), drop the scope and use the shorter astryx — e.g. npx astryx component Button or pnpm exec astryx component Button. Bare astryx resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.

Finding things: astryx search

When you don't know whether what you need is a component, a hook, a docs topic, or a template, search across all of them at once. Results are ranked by relevance (name and keyword matches outrank incidental prose mentions, with fuzzy matching for typos) and tagged with their domain plus the follow-up command to run:

$ 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

(The CLI prints the follow-up commands with your actual runner — npx astryx … when installed, or npx @astryxdesign/cli … when run one-off.)

Options:

  • --type <component|hook|doc|template>: restrict to a single domain
  • --limit <n>: cap the number of results (default 20)
  • --detail: include the import path and the match reason/score
  • --json: typed { type: 'search', data: { query, results } } envelope

Commands

Command Description
blog Read the Astryx blog from the published feed
build Build a page: composition kit for an idea, or the workflow playbook (no args)
component List components or print component docs
discover Discover external packages and components
docs Print reference docs
doctor Diagnose your XDS setup and report problems with fixes
hook List hooks or print hook docs
init Initialize the design system in your project
layout Generate XDS layouts from compressed expressions (XLE/XLO)
search Search components, hooks, docs, and templates in one ranked list
swizzle Copy component source for customization
template Inject a page or block template
theme Theme tools: build, export, and manage themes
upgrade Run codemods to migrate between versions
validate-integration Validate an Astryx integration package (manifest + contributions)

Global options

These flags work with any command:

  • --json: Output as typed JSON envelope: { type, data } (errors: { error, code, suggestions? })
  • --detail <level>: Detail level for list views, increasing in size: brief (names only, default for --list) < compact (names + 1-line descriptions) < full (full docs per entry). Single-item views default to full.
  • --zh: Output docs in Chinese Simplified
  • --dense: Compressed format (token-efficient, useful for AI agents)
  • --lang <locale>: Language/format shorthand (en, zh, dense)

JSON API

Every command supports --json for machine-readable output. Responses are typed envelopes:

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

Errors:

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

The code field is a stable, machine-readable identifier. Branch on it, never on the human-readable error string, which changes freely as we improve wording. Every error envelope carries a code (falling back to ERR_UNKNOWN when no more specific code applies). The same code is exposed on thrown AstryxError instances from the programmatic API, so both surfaces agree.

Codes are append-only: once shipped, a code's meaning never changes and a code is never removed. New error conditions get new codes.

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);
  }
}

Error codes

Code Meaning
ERR_UNKNOWN Fallback for any error without a more specific code.
ERR_UNKNOWN_COMMAND A top-level command name was not recognized (e.g. astryx bogus).
ERR_UNKNOWN_SUBCOMMAND A subcommand under a command group was not recognized (e.g. astryx theme bogus).
ERR_INVALID_OPTION An unknown flag/option was passed (Commander unknownOption).
ERR_INVALID_ARGUMENT An option/argument had a value Commander's parser rejected.
ERR_MISSING_ARGUMENT A required positional argument was omitted (Commander missingArgument).
ERR_INVALID_LANG --lang was given a value outside its choices (en, zh, dense).
ERR_INVALID_DETAIL --detail was given a value outside its choices (full, compact, brief).
ERR_NODE_VERSION The running Node.js version is below the supported minimum.
ERR_CORE_NOT_FOUND @astryxdesign/core could not be located (not installed / not in a monorepo).
ERR_UNKNOWN_COMPONENT No component matched the requested name.
ERR_UNKNOWN_HOOK No hook matched the requested name.
ERR_UNKNOWN_TOPIC No docs topic matched the requested name.
ERR_UNKNOWN_SECTION A docs topic exists but the requested section within it does not.
ERR_UNKNOWN_CATEGORY A --category filter value did not match any known category.
ERR_UNKNOWN_TEMPLATE No template matched the requested name.
ERR_AMBIGUOUS_TEMPLATE A template id matched more than one template (narrow with --type/--package).
ERR_AMBIGUOUS_COMPONENT A component name is owned by more than one package (narrow with --package).
ERR_UNKNOWN_THEME No theme matched the requested slug (theme add).
ERR_UNKNOWN_PACKAGE No package matched the requested name (discover).
ERR_UNKNOWN_AGENT An unrecognized --agent value was passed to agent-docs/init.
ERR_UNKNOWN_FEATURE An unrecognized --features value was passed to init.
ERR_UNKNOWN_CODEMOD A --codemod value did not match any registered codemod (upgrade).
ERR_CODEMOD_FAILED One or more codemods failed during an upgrade run.
ERR_NOT_FOUND A generic discover/lookup query matched nothing in any package.
ERR_NO_DOC A component exists but has no typed .doc.mjs file.
ERR_NO_SHOWCASE No showcase exists for the requested component.
ERR_NO_SOURCE No source file could be located for the requested component/template.
ERR_INVALID_DOC A component's docs failed validation (malformed .doc.mjs).
ERR_FILE_NOT_FOUND A required input file did not exist.
ERR_FILE_EXISTS Refused to overwrite an existing file in non-interactive mode.
ERR_PATH_TRAVERSAL A path escaped its allowed root, or a name contained traversal markers.
ERR_WRITE_FAILED Writing output files failed (and was rolled back).
ERR_THEME_INVALID A theme definition was missing a required property (e.g. name).
ERR_THEME_LOAD A theme file could not be loaded / parsed into a defineTheme result.
ERR_VERSION_DETECT The current @astryxdesign/core version could not be detected.
ERR_INVALID_VERSION A --from/--to value was not a valid semver string.
ERR_DEP_MISSING A required external dependency (e.g. jscodeshift) is missing.
ERR_GH_CLI GitHub CLI (gh) is not installed or not authenticated.
ERR_UNKNOWN_POST No blog post matched the requested slug in the feed.
ERR_FETCH_FAILED A network fetch (RSS feed or post text) failed.
ERR_LAYOUT_PARSE A layout expression failed to parse (syntax error, with line/col).
ERR_LAYOUT_INVALID A layout expression parsed but failed validation (unknown component/prop/enum/block).

Capability manifest (agent discovery)

Agents don't have to scrape --help to learn the CLI. A single call returns a self-describing manifest: every command, its arguments, flags (with types, choices, and defaults), whether it supports --json, and the response type discriminators each command can emit. Think of it as an OpenAPI spec for the CLI.

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

Shape:

{
  "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"],
    },
  },
}

The manifest is derived from Commander metadata (commands, arguments, options) so it can't drift from the real command definitions. The two facts Commander doesn't track (--json support and emitted response types) are layered on from the JSON_SUPPORTED allowlist and a small declarative RESPONSE_TYPES map in src/lib/manifest.mjs, guarded by a drift test (manifest.test.mjs) so adding a command without describing it fails CI.

Backwards-compat: the bare astryx --json envelope keeps type: "help" and its original shallow fields (name, version, commands as a string[] of names, jsonSupported); the full structured manifest is additive under data.manifest. For the standalone manifest envelope (type: "manifest"), use astryx manifest --json.

Programmatic API

The same logic that powers astryx --json is available as importable, type-safe functions:

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' }]
}

The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that @astryxdesign/cli/api and astryx --json always return identical data.

Consumer utilities

If you're spawning the CLI as a subprocess rather than importing the API directly:

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;
  }
}

Prefer narrowing at the call site? Wrap assertResponse (which throws on error/mismatch) with your reconstructed union:

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

Migration (removed in the structural-jsonOut release): the central CLIAnyResponse, CLIResponseType, and CLIResponseDataMap exports were removed. parseResponse / assertResponse no longer auto-narrow .data. Rebuild the union from the individual *Response types as shown above — they are all still exported from @astryxdesign/cli/json.

Type discriminators

Every response has a type discriminant. The full set is below (generated from the manifest). Each command's types are also listed in astryx manifest --json, and the matching *Response TypeScript types (e.g. ComponentDetailResponse) are exported from @astryxdesign/cli/json. Errors use CLIError, and unsupported commands use CLIUnsupportedError.

Type What data carries
component.list The component catalog grouped by category: detail (the level: names | compact | full) and components, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.
component.detail One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).
component.detail.props Just one component's props table (ComponentPropDoc[]).
component.detail.source One component's source file, as {component, source}.
component.detail.showcase One component's showcase example, as {component, aspectRatio, source}.
component.detail.blocks One component's example blocks, as {component, showcase, examples, related} of BlockEntry.
docs.list All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.
docs.detail One topic's full ReferenceDoc, with token-ref blocks inlined.
docs.detail.section A single ReferenceSection of a topic: the first whose title contains the section query.
blog.list The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.
blog.detail One post's metadata plus the feed URL and the post's full plaintext body.
discover.list The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".
discover.detail A single external package entry, for an @scope/name query.
discover.detail.doc The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.
discover.search The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.
search The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).
build.help A marker (playbook: true) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.
build.kit The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.
swizzle.list The names of swizzlable components discoverable from cwd's @astryxdesign/core.
swizzle.copy An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.
template.list Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.
template.show The resolved template's raw source plus its description, kind, and the component names it composes.
template.skeleton A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.
template.copy A scaffold receipt: template id, output directory, written file name, and file count.
template.cdn A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not — exists when a file was already there, which is a success.
hook.list The hook catalog grouped by category: detail (the level: names | compact | full) and components, the grouped map of hook names, brief entries, or a full HookDoc per entry.
hook.detail One hook's full authored HookDoc.
hook.detail.params Just one hook's parameters table (HookParamDoc[]).
theme.build A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.
theme.build.check The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing | outdated}), and the full list of checked paths. Writes nothing.
theme.build.batch Several themes built in one invocation: count plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.
theme.list Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.
theme.add A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.
theme.template A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — exists when a file was already there, which is a success.
upgrade.list Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.
upgrade.status A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.
upgrade.run The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.
manifest The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.
doctor The health-check report: checks (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a summary of counts per status.
integration.validate The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message}.
layout.expand The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).
layout.check The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).
layout.grammar The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.

Doctor

astryx doctor runs a series of health checks against your project and environment and reports PASS / WARN / FAIL for each, with an actionable fix for anything that isn't passing. It's read-only; it never installs or mutates anything, so it's safe to run anywhere, including CI.

$ 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.

Checks

Check Status it can return What it verifies
Node.js version pass / fail Running Node meets the CLI's minimum
@astryxdesign/core installed pass / fail @astryxdesign/core is resolvable from the project
Version alignment pass / warn / info Installed @astryxdesign/core is in step with @astryxdesign/cli
Theme packages pass / warn An @astryxdesign/theme-* package is installed and a theme is wired
astryx.config.mjs pass / fail / info Config (if present) loads cleanly with a valid shape
AI agent docs pass / warn / info Agent docs exist and contain the Astryx section markers
Peer dependencies pass / warn / info @astryxdesign/core's peer deps (react, …) are installed
Package manager info Reports the detected package manager

CI gate

The exit code is the contract: astryx doctor exits 0 when there are no failures (warnings are fine) and 1 when any check fails. That makes it usable directly as a CI step:

- run: npx @astryxdesign/cli doctor

Use --json for a structured envelope ({ apiVersion, type: "doctor", data: { checks, summary } }) that AI agents and scripts can parse.

Configuration

The CLI reads an optional astryx.config.{ts,mjs,js} from your project root (a sibling of package.json). Every field is optional; with no config file the CLI runs on defaults.

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

There is no factory: write a plain object. For editor autocomplete and type-checking, annotate it with the AstryxConfig type exported from @astryxdesign/cli/authoring.

Field Type Purpose
integrations string[] Integration package names to load (see Integrations).
issuesUrl string Where "report an issue" links point for your project. Defaults to the core issue tracker.
hooks.postCodemod PostCodemodHook[] Commands to run after astryx upgrade applies codemods (e.g. reinstall, rebuild, reformat).
experimental.xle.components Record<string, XleComponent> Register app-local components so layout (XLE) expressions can reference them by name. Unstable.

The config is validated against a strict schema when the CLI loads it, so an unknown field is a hard error rather than a silent no-op. astryx doctor reports whether the config loads cleanly.

Core codemod authoring

Core codemods live under packages/cli/assets/codemods/transforms/. Released codemods are grouped by the target package version (v0.3.0, v0.3.1, ...), which is the version that first contains the breaking change.

Do not guess that version in ordinary feature PRs. Add new codemods to packages/cli/assets/codemods/transforms/next/ instead:

  • put transform modules and tests in transforms/next/;
  • maintain transforms/next/index.mjs with the run order for the staged transforms;
  • leave transforms/next/README.md in place; it documents the staging area and is never promoted.

During the Version Packages PR, pnpm version-packages runs scripts/promote-codemod-next.mjs after changeset version. The script copies all staged entries except the README into transforms/v<new-core-version>/, registers that version in packages/cli/assets/codemods/registry.mjs, and clears the promoted files from next.

This mirrors Changesets: feature PRs stage migration work without knowing the future release number; the release PR assigns the exact version.

Integrations

An integration is any npm package that contributes its own components, templates, and upgrade codemods to Astryx. The CLI surfaces them next to core's, through the same commands, so a consumer can astryx component, astryx template, and astryx upgrade across core and every integration uniformly. Use it to ship a first-party add-on, publish a third-party component library, or share an internal design-system package across apps.

The system runs on two files, each with a small typed API:

File Written by Role
astryx.config.{ts,mjs,js} Consumer Lists which integration packages to load.
astryx.integration.{ts,mjs,js} Author Declares what a package contributes.

The consumer side is the integrations field of astryx.config. The author side is the integration manifest below.

The integration manifest

A package becomes an integration by exporting a manifest from astryx.integration.{ts,mjs,js} at its root (a sibling of package.json). The manifest points at where each kind of contribution lives; identity (name, version) comes from package.json, not the manifest.

export default {
  components: './components',
  templates: './templates',
  codemods: './codemods',
  issuesUrl: 'https://github.com/acme/widgets/issues',
};
Field Type Purpose
components string Directory holding the package's components and their .doc.* files.
templates string Directory holding the package's page/block templates.
codemods string Directory holding upgrade codemods run by astryx upgrade.
issuesUrl string Where "report an issue" links for this package's contributions point.

Every field is optional; declare only the roots the package ships. There is no factory: write a plain object, and annotate it with the AstryxIntegration type from @astryxdesign/cli/authoring for editor autocomplete and type-checking.

How it works

Every command loads the consumer's astryx.config, resolves each listed integration's manifest from node_modules, and discovers its contributions. Everything is validated against one strict schema at the load boundary, so the CLI presents core and integration contributions through a single, uniform surface.

Discovery is resilient: a broken or misconfigured integration is skipped with a one-line warning on stderr instead of crashing the CLI, and it never corrupts a --json envelope. To inspect problems, run astryx validate-integration <package> for a detailed report on one package, or astryx doctor for an overall health check.

For the full authoring walkthrough (component doc format, template packaging and exports requirements, and codemod authoring), see the guide:

astryx docs cli-integrations