# How to Access Astryx Component Documentation via CLI and API

> Access Astryx component documentation easily via CLI or API. Learn how to retrieve typed JSON or human-readable output for your components using the shared component function.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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:

```bash
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:

```bash
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:

```bash
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:

```javascript
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:

```typescript
// 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`:

```typescript
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`.