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

> Discover the purpose of the @astryxdesign/cli package. This guide explores its terminal commands, JSON API for CI, and JS/TS API for seamless code integration.

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

---

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

```bash

# 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/**`.

```bash

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

```typescript
// 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`](https://github.com/facebook/astryx/blob/main/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.