# Available Commands in the Astryx CLI: Complete Reference Guide

> Explore over 15 Astryx CLI commands like init, component, search, and more. Discover a comprehensive reference guide for all available Astryx CLI functionalities.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: api-reference
- Published: 2026-07-15

---

**The Astryx CLI ships with 15+ commands—including `init`, `component`, `search`, `docs`, `template`, `hook`, `swizzle`, `upgrade`, `theme build`, `discover`, `doctor`, `manifest`, `validate-integration`, and layout utilities—all defined in `packages/cli/src/commands/` and discoverable via a self-describing capability manifest.**

The `facebook/astryx` repository provides a single-purpose command-line interface for managing design-system artefacts. Understanding the available commands in the Astryx CLI is essential for developers who need to bootstrap projects, inspect components, or run automated migrations. Every command is implemented as a modular ES module in the CLI package and exposed through a unified Commander-based entry point.

## Core Development Commands

The primary workflow commands enable project initialization, component inspection, and content generation.

**`init`** – Bootstraps a new project with Astryx packages, theming configuration, and optional AI-agent documentation. This is typically the first command run in a new codebase.

**`component`** – Lists registered components or displays detailed documentation for a specific component, including its props, source location, and interactive showcase. Implemented in `packages/cli/src/commands/component.mjs`.

**`search`** – Performs fuzzy searches across components, hooks, documentation, and templates. This command indexes the entire design system for rapid discovery.

**`docs`** – Prints reference documentation for design tokens, theme objects, color palettes, typography scales, and spacing systems. Use this to verify token values without opening source files.

**`template`** – Injects page-level or block-level templates into a specified directory. For example, you can scaffold a new dashboard page using a predefined layout template.

**`hook`** – Lists available React hooks or prints detailed documentation for a specific hook, including its parameters and return types.

## Component Customization and Migration

These commands handle advanced workflows like deep customization and version migration.

**`swizzle`** – Copies a component’s source code from the Astryx package into your consuming repository. This enables deep customization when wrapper components are insufficient. The command preserves the original file structure and dependencies.

**`upgrade`** – Runs automated codemods that migrate a project between Astryx versions. This command scans for breaking changes and applies transformations to keep your codebase current.

## Theme and Layout Operations

Specialized commands for visual design system compilation and layout validation.

**`theme build`** – Compiles a `defineTheme` configuration file into production-ready CSS and JavaScript. This command processes design tokens and generates the static assets required for runtime.

**`layout expand` / `layout check` / `layout grammar`** – Utilities for visual-layout authoring and validation. These subcommands, defined in `packages/cli/src/commands/layout.mjs`, help verify that layout compositions adhere to the design system’s grid and spacing constraints.

## Discovery and Validation Utilities

Commands for ecosystem integration and health monitoring.

**`discover`** – Finds external packages and components that advertise Astryx compatibility. This scans npm registries or local monorepos for packages containing the `astryx` keyword or manifest flag.

**`validate-integration`** – Verifies that an external package correctly integrates with Astryx conventions. Defined in `packages/cli/src/lib/manifest.mjs`, this command checks for required exports, metadata structure, and theme compatibility.

**`doctor`** – Runs a comprehensive health-check suite that diagnoses the project’s Astryx setup. It verifies configuration files, dependency versions, and theme compilation status. Implemented in `packages/cli/src/commands/doctor.mjs`.

**`manifest`** – Emits a **self-describing capability manifest** (similar to an OpenAPI specification) for AI agents. Running `astryx manifest --json` outputs a machine-readable schema of all available commands, their arguments, and response types.

## Global CLI Options and JSON Output

All commands support a **global set of options** defined in `packages/cli/src/index.mjs`:

- `--json` – Emits structured JSON output instead of human-readable text
- `--detail` – Increases verbosity of output
- `--lang` – Specifies language localization
- `--zh` – Shortcut for Chinese language output
- `--dense` – Condenses output for terminal constraints
- `--version` – Displays CLI version information

The `--json` flag is particularly important for automation. When enabled, commands like `component`, `docs`, `template`, `upgrade`, and `doctor` emit a typed envelope (`{type, data}`) that downstream tools can parse reliably. The manifest generation logic in `src/lib/manifest.mjs` tracks which commands support JSON output, ensuring documentation remains synchronized with implementation.

## Implementation Architecture

Command definitions reside in `packages/cli/src/commands/` as individual ES modules. For example, `src/commands/component.mjs` implements the component inspection logic, while `src/commands/upgrade.mjs` handles migration codemods.

The entry point at `src/index.mjs` wires the Commander program, registers global options, and dynamically loads command modules. This architecture ensures that adding new commands requires only creating a new file in the commands directory and registering it in the index.

The capability manifest system in `src/lib/manifest.mjs` derives the full command catalogue directly from the Commander configuration. This guarantees that AI agents consuming `astryx manifest --json` receive accurate, up-to-date metadata about the available commands in the Astryx CLI, including parameter types, option flags, and example invocations.

## Common Usage Examples

```bash

# Initialize a new Astryx project with theming

npx astryx init my-design-system

# Display Button component documentation with props as JSON

npx astryx component Button --props --json

# Search for spacing tokens and return machine-readable results

npx astryx search spacing --type token --json

# Generate a Dashboard page template in ./src/pages

npx astryx template Dashboard ./src/pages

# Swizzle the IconButton component for local customization

npx astryx swizzle IconButton

# Run health checks and output JSON for CI pipelines

npx astryx doctor --json

# Export the capability manifest for AI agent integration

npx astryx manifest --json > astryx-manifest.json

```

## Summary

- The Astryx CLI provides **15+ specialized commands** for design system management, from project initialization (`init`) to health diagnostics (`doctor`).
- All commands are implemented as modular ES modules in `packages/cli/src/commands/` and registered in `src/index.mjs`.
- **Global options** like `--json`, `--detail`, and `--version` are available across every command, enabling both human and machine-readable workflows.
- The **`manifest`** command emits a self-describing capability specification derived directly from the Commander configuration in `src/lib/manifest.mjs`.
- **Layout utilities** (`layout expand`, `layout check`, `layout grammar`) provide specialized validation for visual composition workflows.

## Frequently Asked Questions

### How do I list all available commands in the Astryx CLI?

Run `npx astryx --help` or `npx astryx --list` to see the complete command catalogue. For machine-readable output suitable for automation or AI agents, execute `npx astryx manifest --json`, which emits a structured schema of all commands, options, and examples defined in `packages/cli/src/lib/manifest.mjs`.

### Which Astryx CLI commands support JSON output?

According to the manifest definition in `src/lib/manifest.mjs`, commands including `component`, `docs`, `template`, `upgrade`, `doctor`, and `manifest` support the `--json` flag. When used, these commands emit a typed response envelope (`{type, data}`) instead of formatted text, enabling reliable parsing by downstream tools and CI pipelines.

### What is the difference between `swizzle` and `component` commands?

The **`component`** command (`src/commands/component.mjs`) inspects and displays documentation for components within the Astryx package, while **`swizzle`** copies the component's source code into your local repository for deep customization. Use `component` to explore available APIs, and `swizzle` when you need to modify internal implementation details that cannot be achieved through props or wrappers.

### Where are the Astryx CLI command implementations located?

Each command resides as a separate ES module in `packages/cli/src/commands/`. For example, `upgrade` logic is in `src/commands/upgrade.mjs`, `doctor` is in `src/commands/doctor.mjs`, and layout utilities are in `src/commands/layout.mjs`. The entry point at `src/index.mjs` registers these modules with Commander and applies global options like `--json` and `--version`.