Available Commands in the Astryx CLI: Complete Reference Guide

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

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

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