# How to Use the Astryx Command-Line Interface: A Complete Guide

> Master the Astryx command-line interface with our comprehensive guide. Learn to browse components, generate templates, eject code, and run codemods using npx astryx.

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

---

**The Astryx CLI is a Node-based tool in `packages/cli` that provides sub-commands for browsing components, generating templates, ejecting source code, and running upgrade codemods, accessible via `npx astryx` or direct path execution.**

This guide explores the **Astryx command-line interface** from its architecture to daily workflows, based on the source code in the `facebook/astryx` repository. Whether you're inspecting component APIs or scaffolding new pages, the CLI serves as the bridge between Astryx's design system and your development environment.

## Installing and Running the Astryx CLI

The CLI package exposes its entry point through **[`package.json`](https://github.com/facebook/astryx/blob/main/package.json)**'s `bin` field, making the `astryx` command available once installed.

### Direct execution methods

- **Via npx (recommended):** `npx @astryxdesign/cli`
- **Via node directly:** `node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs`
- **Via npm script alias:** Add to your [`package.json`](https://github.com/facebook/astryx/blob/main/package.json):

```json
{
  "scripts": {
    "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
  }
}

```

With the script alias, run commands as `npm run astryx -- component --list` (note the `--` separator for passing arguments).

## CLI Architecture and Bootstrap Process

When **`bin/astryx.mjs`** starts, it performs three initialization steps:

1. **Loads agent documentation** — Pulls design-system knowledge from doc files that power both CLI and UI tools
2. **Creates command registry** — Dynamically discovers modules in `packages/cli/clients/cli/commands/*.mjs`
3. **Installs JSON error boundary** — Wraps execution in `lib/json-shim.mjs` for machine-parseable failure output

This "single-binary → sub-command" pattern produces the following command tree:

| Command | File | Purpose |
|---------|------|---------|
| `docs` | `commands/docs.mjs` | List and display documentation topics |
| `component` | `commands/component.mjs` | Browse component library and APIs |
| `template` | `commands/template.mjs` | Generate page templates and skeletons |
| `swizzle` | `commands/swizzle.mjs` | Eject component source for customization |
| `upgrade` | `commands/upgrade.mjs` | Apply version migration codemods |

## Core Commands Explained

### Browse documentation with `astryx docs`

The **`docs`** command surfaces design-system knowledge stored in `.doc.mjs` files throughout the repository.

```bash

# List all available documentation topics

astryx docs

# Get concise, structured output for a specific topic

astryx docs principles --dense

```

The **`--dense`** flag outputs JSON-structured content suitable for programmatic consumption or AI tooling.

### Inspect components with `astryx component`

The **`component`** command in `commands/component.mjs` is the primary way to explore Astryx's component library without leaving the terminal.

```bash

# Enumerate all components grouped by category

astryx component --list

# Get detailed API documentation for a specific component

astryx component Button --dense

```

The **dense output** includes a complete **ComponentDoc** object containing props, variants, usage patterns, and anatomical structure — all parsed from `packages/core/src/Button/Button.doc.mjs`. This format enables automated code generation and IDE integrations.

### Generate templates with `astryx template`

The **`template`** command in `commands/template.mjs` emits ready-to-use page source code.

```bash

# List available page templates

astryx template --list

# Generate full page source for "LandingPage"

astryx template LandingPage > src/pages/LandingPage.tsx

# Generate only the layout skeleton (no content components)

astryx template LandingPage --skeleton > src/pages/LandingPage.skel.tsx

```

Use **`--skeleton`** when you want structural markup without pre-populated content components.

### Eject components with `astryx swizzle`

The **`swizzle`** command in `commands/swizzle.mjs` copies a component's source from `node_modules` into your repository for deep customization.

```bash

# Eject the Button component for modification

astryx swizzle Button

```

This creates a local copy of the Button implementation that overrides the distributed version, following the pattern established in `commands/swizzle.mjs`.

### Run migrations with `astryx upgrade`

The **`upgrade`** command in `commands/upgrade.mjs` applies automated codemods when updating Astryx core versions.

```bash

# Preview available migrations

astryx upgrade

# Apply all pending codemods

astryx upgrade --apply

```

Codemods are discovered through the CLI integration system documented in `cli-integrations.doc.mjs`.

## Environment Variables and Automation

The Astryx CLI respects several environment variables for customized behavior:

- **`$ASTRYX`** — Used for update notifications (see `lib/update-check.mjs`)
- Standard Node variables for `NODE_ENV` and path resolution

The CLI is **automation-safe** by design: all output supports JSON formatting, errors are shimmed to structured objects via `lib/json-shim.mjs`, and the source enforces no raw `console.log` statements through ESLint rules.

## Complete Workflow Example

Here's a typical daily workflow combining multiple commands:

```bash

# 1. Check available commands

astryx help

# 2. Review design principles before implementing

astryx docs principles --dense

# 3. Find the right component for a feature

astryx component --list | grep -i "input"

# 4. Inspect its API details

astryx component TextInput --dense > textinput-api.json

# 5. Generate a new page using a template

astryx template DashboardPage > src/pages/Dashboard.tsx

# 6. Eject a component that needs customization

astryx swizzle DataTable

# 7. Apply any pending migrations

astryx upgrade --apply

```

## Summary

- **Entry point:** `packages/cli/clients/cli/bin/astryx.mjs` bootstraps the CLI and registers sub-commands
- **Command structure:** Five main commands (`docs`, `component`, `template`, `swizzle`, `upgrade`) implemented in separate `*.mjs` modules
- **Automation-ready:** JSON-shimmed errors, dense output mode, and no unstructured logging
- **Integration model:** Components, templates, and codemods are discovered through `.doc.mjs` files per `cli-integrations.doc.mjs`

## Frequently Asked Questions

### How do I add the Astryx CLI to an existing project?

Install the `@astryxdesign/cli` package and add the script alias to your [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) as shown in the repository's README snippet: `"astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"`. Then run with `npm run astryx -- <command>`.

### What does the `--dense` flag do in Astryx CLI commands?

The **`--dense`** flag outputs structured JSON instead of human-readable text, making the output suitable for scripting, CI pipelines, and AI agent consumption. It works with `docs`, `component`, and other commands that return structured data.

### Where does `astryx swizzle` put the ejected component files?

The `swizzle` command copies source files from the distributed package into your project's local directory structure, typically mirroring the path under `packages/core/src/`. The exact destination logic is implemented in `commands/swizzle.mjs`.

### How does Astryx CLI handle errors in automated environments?

All commands wrap execution in `lib/json-shim.mjs`, which catches uncaught exceptions and reformats them as JSON objects with consistent error codes. This guarantees that CI systems can parse failures without regex-matching human-readable output.