How to Use the Astryx CLI `component --list` and `component <Name>` Commands for Documentation

The Astryx CLI provides a unified component command that either lists available components via the --list flag or displays detailed documentation for a specific component when you provide its name.

The facebook/astryx repository includes a powerful documentation system accessible directly from the command line. Understanding how to use the Astryx CLI component --list and component <Name> commands for documentation allows developers to discover available UI components and inspect their APIs without leaving the terminal.

Listing Components with the --list Flag

When you run astryx component --list, the CLI triggers the list leaf, which aggregates and displays a grouped catalog of all available components.

Command Dispatch and Implementation

The command options are defined in packages/cli/clients/cli/commands/component.doc.mjs at lines 13‑30. When the dispatcher in packages/cli/api/component/component.mjs detects a list view (evaluating list || category || !name at lines 97‑100), it forwards the request to the componentList function.

The actual listing logic resides in packages/cli/api/component/list/list.mjs. This module gathers core components, integration components, and external packages, then groups them by category. It supports optional filtering via the --category flag and detail level configuration through the --detail option with values compact, full, or brief.

Listing Command Examples

# List every component, grouped by category

astryx component --list

# Filter components by category (e.g., "inputs")

astryx component --category inputs

# Output compact listing format

astryx component --list --detail compact

Viewing Component Documentation with component <Name>

Supplying a specific component name (e.g., astryx component Button) invokes the detail leaf, loading the component's authored .doc.mjs file and rendering its documentation.

Component Resolution and Detail Helpers

The resolution flow begins at line 102 of packages/cli/api/component/component.mjs. After determining whether the component belongs to core or integration packages, the dispatcher calls loadComponentDoc and delegates to one of the detail helpers in packages/cli/api/component/detail/:

• componentDetail: Renders full documentation
• componentDetailProps: Displays prop tables
• componentDetailSource: Shows raw source code
• componentDetailShowcase: Renders showcase implementations
• componentDetailBlocks: Lists example blocks (showcase, examples, related)

Detail Command Examples

# Show full documentation for Button component

astryx component Button

# Output props table as JSON

astryx component Button --props --json

# Display raw source code

astryx component Button --source

# View showcase implementation

astryx component Button --showcase

# List all example blocks

astryx component Button --blocks

Command Architecture and Implementation Files

The component command follows a thin-client architecture where the CLI behavior is fully described by documentation objects and a shared programmatic API. This ensures consistency between interactive CLI output and the JSON envelope returned by astryx --json component.

Key implementation files include:

• packages/cli/clients/cli/commands/component.doc.mjs: Declares command flags, options, and examples.
• packages/cli/api/component/component.mjs: Main dispatcher that parses options and routes to list or detail leaves.
• packages/cli/api/component/list/list.mjs: Implements grouped component listing with category and detail filters.
• packages/cli/api/component/detail/*: Suite of formatting helpers for documentation output.

Summary

• The Astryx CLI component command supports two primary modes: listing all components with --list or viewing specific component documentation by name.
• List operations are handled by componentList in packages/cli/api/component/list/list.mjs, supporting category filters and three detail levels (compact, full, brief).
• Detail operations resolve component ownership and load .doc.mjs files via helpers in packages/cli/api/component/detail/.
• The architecture ensures CLI output matches programmatic JSON output through a unified envelope system.

Frequently Asked Questions

How do I filter components by category when listing?

Use the --category flag followed by the category name. For example, astryx component --category inputs displays only components tagged with the "inputs" category. The filtering logic processes the category parameter in packages/cli/api/component/list/list.mjs before building the grouped catalog.

What is the difference between the brief, compact, and full detail levels?

The --detail parameter controls output verbosity in list mode. brief shows minimal information, compact provides a balanced summary, and full displays comprehensive metadata including descriptions and prop counts. These levels are processed during the catalog construction phase in the list implementation.

Can I output component documentation as JSON for programmatic use?

Yes. Append the --json flag to any component command. For example, astryx component Button --props --json returns the props table as a JSON envelope. This leverages the same underlying API that powers the interactive CLI display, ensuring data consistency across formats.

Where does the CLI look for component documentation files?

The dispatcher in packages/cli/api/component/component.mjs resolves component ownership (core vs integration) and then loads the corresponding .doc.mjs file using loadComponentDoc. These documentation files are co-located with their component implementations and define the metadata, props, and examples displayed in the CLI.

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