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

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

{
  "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.

# 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.

# 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.

# 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.

# 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.

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

# 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 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.

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