What Is the Purpose of the CLI Astryx Package? A Complete Guide to @astryxdesign/cli

The @astryxdesign/cli package serves as the command-line interface for the Astryx design system, exposing three distinct access surfaces—human-friendly terminal commands, a typed JSON API for CI automation, and a programmatic JavaScript/TypeScript API for direct code integration.

The @astryxdesign/cli package is the primary entry point for the Astryx design system in the facebook/astryx repository. It enables developers, CI pipelines, and AI agents to browse components, compile themes, scaffold projects, and run diagnostics through a unified command-line interface. Understanding the purpose of the cli Astryx package reveals how it bridges design tokens, component libraries, and automated workflows through a self-describing, machine-readable architecture.

Three Access Surfaces of the Astryx CLI

The CLI is engineered as a multi-modal tool that accommodates interactive development, automation scripts, and direct programmatic access.

Human-Friendly Terminal Commands

The CLI provides intuitive commands for daily development workflows, implemented in packages/cli/bin/astryx.mjs using the Commander.js framework. These commands allow users to browse component documentation, search across the design system, and manage project themes without leaving the terminal.

# View full documentation for a component

npx astryx component Button

# Display only the props table

npx astryx component Button --props

# Generate a page template in your project

npx astryx template BannerCollapsibleContent ./src/pages/Banner.jsx

Typed JSON API for Automation

Every command supports a --json flag that returns a stable, typed envelope with the structure {type, data} and deterministic exit codes. This surface enables CI pipelines and scripts to consume Astryx data programmatically without parsing human-readable output. The JSON validation utilities reside in packages/cli/src/json/**.

# Search with machine-readable output

npx astryx search button --detail compact --json

# Run health checks in CI with JSON output

npx astryx doctor --json

# Exit code 0 indicates success, non-zero indicates failure

Programmatic JavaScript/TypeScript API

The core logic powering the terminal commands is exported from @astryxdesign/cli/api, allowing direct function calls from Node.js or TypeScript code. This eliminates shell overhead when building custom tooling or integrating Astryx into existing applications.

// Programmatic usage in a Node script
import {component, docs, hook} from '@astryxdesign/cli/api';

const buttonDoc = await component('Button');
console.log(buttonDoc.type); // "component.detail"

const tokenList = await docs('tokens');
console.log(tokenList.data.title); // "Tokens"

Core Commands and Implementation

The CLI bundles specific capabilities for component discovery, theme management, and project maintenance, each backed by dedicated source modules.

Component Discovery and Documentation

The component() function and its CLI wrapper enable deep inspection of design system components. Located in packages/cli/src/api/**, these functions return metadata, prop definitions, and usage examples. The search functionality scans across components, hooks, templates, and documentation simultaneously.

Theme Compilation and Token Management

The astryx theme build command compiles design tokens into usable assets, utilizing helper functions from packages/cli/src/lib/theme.mjs. Developers can query token documentation via astryx docs tokens, which interfaces with the same API layer that powers the programmatic surface.

Project Scaffolding and Maintenance

Project-level utilities in packages/cli/src/lib/project.mjs handle configuration discovery and package location. The astryx init command bootstraps new projects, while astryx upgrade executes codemods stored in packages/cli/src/codemods/** to automate migrations between versions. Health diagnostics run via astryx doctor validate the integrity of the installation and configuration.

Self-Describing Capability Manifest

The astryx manifest --json command generates a machine-readable capability manifest that external packages and AI agents consume to understand available CLI features. This implementation resides in packages/cli/src/manifest.mjs and exposes the CLI's command set, parameters, and output schemas.

Key Source Files and Architecture

The @astryxdesign/cli package structure separates concerns between command wiring, API logic, and utility modules:

• packages/cli/README.md – Command reference, JSON API documentation, and usage examples.
• packages/cli/bin/astryx.mjs – Entry point that wires Commander CLI arguments to the underlying API.
• packages/cli/src/api/** – Exported functions (component, docs, template, hook, search, upgrade) that implement core business logic.
• packages/cli/src/manifest.mjs – Generates the self-describing capability manifest for AI integration.
• packages/cli/src/json/** – Types and utilities for parsing and validating the {type, data} JSON envelopes.
• packages/cli/src/lib/project.mjs – Project-level utilities for config discovery and package location.
• packages/cli/src/lib/theme.mjs – Theme compilation helpers used by astryx theme build.
• packages/cli/src/codemods/** – Automated transformation scripts invoked by astryx upgrade.

Summary

• The @astryxdesign/cli package provides three access surfaces: human-friendly terminal commands, a JSON API for automation, and a programmatic Node.js/TypeScript API.
• All commands support a --json flag returning typed envelopes with the {type, data} structure, enabling deterministic CI integration.
• Core capabilities include component documentation lookup, theme compilation via packages/cli/src/lib/theme.mjs, project scaffolding, and automated upgrades via codemods in packages/cli/src/codemods/**.
• The CLI is self-describing through the astryx manifest command, making it fully discoverable by AI agents and external tools.

Frequently Asked Questions

What is the difference between using the Astryx CLI and importing from @astryxdesign/cli/api?

The CLI provides a command-line interface optimized for interactive use and shell scripts, while the programmatic API allows direct function calls such as component() and docs() from Node.js code without spawning child processes. Both interfaces utilize the same underlying logic exported from packages/cli/src/api/**.

How does the Astryx CLI support CI/CD automation?

Every command supports a --json flag that returns output in a stable {type, data} envelope with deterministic exit codes. This enables CI pipelines to parse results programmatically, fail builds based on astryx doctor health checks, and integrate upgrade validations into deployment workflows.

Where are the upgrade codemods stored in the Astryx repository?

Automated migration scripts are located in packages/cli/src/codemods/** and are invoked by the astryx upgrade command. These codemods transform codebase patterns automatically when migrating between versions of the design system.

Can AI agents integrate with the Astryx CLI?

Yes, the CLI is fully machine-readable. The astryx manifest --json command generates a capability manifest describing all available commands, and the universal --json flag ensures that all output follows a predictable schema suitable for AI agent consumption and external tooling integration.

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