How to Access Astryx Component Documentation via CLI and API

Astryx exposes component documentation through both the astryx CLI and the @astryxdesign/cli/api programmatic module, using a shared component function that returns typed JSON responses or human-readable output.

The facebook/astryx repository provides a unified tooling layer for querying design system documentation. Developers can access Astryx component documentation interactively in the terminal or programmatically in Node.js applications, with both interfaces guaranteed to produce identical results because they delegate to the same implementation in packages/cli/src/api/component.mjs.

CLI Access to Astryx Component Documentation

The astryx command-line interface offers granular control over documentation retrieval through the component subcommand.

Retrieving Full Component Documentation

To fetch complete documentation for a specific component, use the astryx component command followed by the component name:

npx astryx component Button

This invokes the component function in packages/cli/src/api/component.mjs, which loads the component’s .doc.mjs file via packages/cli/src/lib/component-loader.mjs and returns a human-readable summary including the description, import path, and usage examples.

Filtering Output with Targeted Flags

The CLI supports several flags to narrow the output to specific documentation sections:

• --props – Returns only the props table (equivalent to component.detail.props in the API)
• --source – Dumps the raw component source file
• --showcase – Returns the showcase demo source code
• --blocks – Lists related showcase blocks
• --list – Enumerates all components in brief view (omit the component name)

For example, to retrieve only the props table for a Button component:

npx astryx component Button --props

Machine-Readable JSON Output

For integration with CI pipelines or external tooling, append the --json flag to emit a typed JSON envelope:

npx astryx component Button --json
npx astryx component Button --props --json
npx astryx component --list --json

The JSON response is a discriminated union where the type field indicates the content variant (component.detail, component.detail.props, component.list, etc.), as defined in the CLI manifest generated by packages/cli/src/lib/manifest.mjs.

Programmatic API Access

The programmatic interface exposes the same functionality through the @astryxdesign/cli/api package, enabling embedded documentation queries in build scripts or design tooling.

Importing the API Module

Import the component function from the API entry point:

import { component } from '@astryxdesign/cli/api';

This module exports the same implementation used by the CLI, ensuring parity between interactive and programmatic usage.

Querying Component Details

The component function accepts a component name and an options object that mirrors CLI flags:

// Full documentation (equivalent to `astryx component Button`)
const detail = await component('Button');
// → { type: 'component.detail', data: ComponentDoc }

// Props table only (equivalent to `astryx component Button --props`)
const props = await component('Button', { props: true });
// → { type: 'component.detail.props', data: PropDoc[] }

// Source code (equivalent to `astryx component Button --source`)
const source = await component('Button', { source: true });
// → { type: 'component.detail.source', data: { component: 'Button', source: '…' } }

// List all components (equivalent to `astryx component --list`)
const list = await component(undefined, { list: true });
// → { type: 'component.list', data: { … } }

The function returns a Promise that resolves to a discriminated union payload. The data property contains the requested documentation, while the type property allows consumers to narrow the response type safely.

Error Handling and Response Types

The API throws AstryxError instances with stable error codes for failure cases. For example, requesting a non-existent component throws an error with code ERR_UNKNOWN_COMPONENT:

import { component } from '@astryxdesign/cli/api';

try {
  await component('NonExistent');
} catch (error) {
  if (error.code === 'ERR_UNKNOWN_COMPONENT') {
    console.error('Component not found');
  }
}

Error handling is implemented in packages/cli/src/api/component.mjs (lines 84-98), ensuring consistent error codes across both CLI and API contexts.

Shared Implementation Architecture

Both the CLI and programmatic API delegate to the component function in packages/cli/src/api/component.mjs. This guarantees that flags passed to the CLI produce identical results to options passed to the API function. The CLI’s self-describing manifest, accessible via astryx manifest --json, advertises this contract and lists all available commands, flags, and response discriminators as implemented in packages/cli/src/lib/manifest.mjs.

Summary

• The astryx component command retrieves documentation for specific components, with flags like --props, --source, and --json controlling output format
• The @astryxdesign/cli/api module exposes a component function that accepts the same options as CLI flags, returning typed Promise-based responses
• Both interfaces share the implementation in packages/cli/src/api/component.mjs, ensuring consistent behavior
• Responses use discriminated unions with a type field (component.detail, component.detail.props, etc.) for reliable type narrowing
• Errors throw AstryxError with stable codes like ERR_UNKNOWN_COMPONENT for robust client-side handling

Frequently Asked Questions

How do I list all available components via the CLI?

Use the --list flag without specifying a component name: npx astryx component --list. For machine-readable output suitable for scripting, append --json to receive a typed envelope with the component.list discriminator.

Can I access component source code through the API?

Yes. Call component('ComponentName', { source: true }) to retrieve the raw source file. The response type will be component.detail.source, containing the source string in the data.source property, as implemented in packages/cli/src/api/component.mjs.

What format does the API return?

The API returns a discriminated union where the type field indicates the content variant (e.g., component.detail, component.detail.props, component.list). This structure, defined in the CLI manifest, enables TypeScript-powered narrowing so consumers can safely access data properties based on the response type.

How do I handle errors when querying non-existent components?

The API throws AstryxError instances with stable error codes. Check for ERR_UNKNOWN_COMPONENT in the error object’s code property. This error handling is consistent across both the CLI exit codes and the programmatic API, as both paths execute the same validation logic in packages/cli/src/api/component.mjs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}