Looking up components

astryx component accepts exact selectors as a variadic positional argument. With no selector it browses the catalog. With one selector it keeps the normal single-component response. With two or more it prints one complete ordered batch receipt.

bash
astryx component Button Badge Text
astryx --json component Button Badge Text

Every selector gets one row in input order. Duplicate selectors stay duplicate rows. A missing or ambiguous component does not hide successful neighbors or stop later selectors from resolving.

A batch accepts at most 100 selectors, including duplicates, in every projection mode. A larger request returns a top-level ERR_INVALID_ARGUMENT before any component resolves. It emits no component.batch receipt and no partial results.

Focused component controls apply to every found row. Use the same control you use for one component:

bash
astryx --json component Button Card --props
astryx component Button Card --source
astryx component Button Card --showcase
astryx component Button Card --blocks
astryx component Button Card --detail compact
astryx component Button Card --lang dense
astryx component Button Card --package @astryxdesign/core

A selector is an exact component identity, not free-text search. Use one of these forms:

• Button for an unqualified component name.
• widgets/Button for a component in an unscoped package.
• @acme/widgets/Button for a component in a scoped package.
• @acme/widgets@1.2.3/Button to require that exact installed package version.

A version qualifies the package, never the component. The lookup does not fall through to another installed version. An unqualified name owned by several installed packages is ambiguous and lists every candidate. Use a package-qualified selector or --package to choose one.

astryx discover remains free-text package discovery. Its words form one query; they are not component batch selectors.

JSON uses component.batch with {count, results}. Each row echoes selector and has one status: found, not_found, ambiguous, or error. A found row carries the normal single-component {type, data} under result. Failed rows carry code and error, plus suggestions or candidates when available.

bash
astryx --json component Button Badge                 # all found, exit 0
astryx --json component Button MissingWidget         # mixed, exit 1
astryx --json component MissingWidget MissingPanel   # all failed, exit 1
astryx --json component Button Button                # two ordered rows, exit 0

bash
astryx --json component MissingWidget MissingPanel

json
{
  "apiVersion": 1,
  "type": "component.batch",
  "data": {
    "count": 2,
    "results": [
      {
        "selector": "MissingWidget",
        "status": "not_found",
        "code": "ERR_UNKNOWN_COMPONENT",
        "error": "No component named \"MissingWidget\""
      },
      {
        "selector": "MissingPanel",
        "status": "not_found",
        "code": "ERR_UNKNOWN_COMPONENT",
        "error": "No component named \"MissingPanel\""
      }
    ]
  }
}

text
Component batch
​
count: 2
​
Results
​
MissingWidget
​
selector: MissingWidget
status:   not_found
code:     ERR_UNKNOWN_COMPONENT
error:    No component named "MissingWidget"
​
MissingPanel
​
selector: MissingPanel
status:   not_found
code:     ERR_UNKNOWN_COMPONENT
error:    No component named "MissingPanel"

The CLI emits every row first, then exits 1 when any row is not found. This includes mixed receipts and receipts where every row failed. JSON and text use the same exit status. A batch where every row is found exits 0.

The argument shape chooses the response shape. Omit the argument for the catalog, pass a string for the existing single-component response, and pass an array for component.batch. An array always means batch, including empty and one-item arrays, so filtering a selector list cannot silently change the response type. The published ComponentBatchResponse specializes the shared BatchResponse and BatchRow types.

javascript
import {component} from '@astryxdesign/cli/api';
​
const catalog = await component(); // component.list
const button = await component('Button'); // component.detail
const empty = await component([]); // component.batch, count 0
const oneRow = await component(['Button']); // component.batch, count 1
const batch = await component(['Button', 'Badge']); // component.batch, count 2
await component(Array(101).fill('Button')); // ERR_INVALID_ARGUMENT before lookup

json
{
  "type": "component.batch",
  "data": {
    "count": 0,
    "results": []
  }
}

javascript
const receipt = await component(['Button', 'MissingWidget']);
​
for (const row of receipt.data.results) {
  if (row.status === 'found') {
    useComponentDoc(row.selector, row.result);
  } else if (row.status === 'ambiguous') {
    choosePackage(row.selector, row.candidates);
  } else {
    reportLookupFailure(row.selector, row.code, row.error);
  }
}