# Astryx XDS CLI Commands: Complete Usage Guide and Reference > Master Astryx XDS CLI commands with this complete usage guide. Explore 17+ sub-commands for documentation, theming, scaffolding, and diagnostics. Integrate programmatically with JSON API support. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: how-to-guide - Published: 2026-07-02 --- **The Astryx XDS CLI (`astryx`) provides 17+ sub-commands for component documentation, theme management, project scaffolding, and diagnostic checks, with full JSON API support for programmatic integration.** The **Astryx XDS CLI** is the primary interface for working with Meta's Astryx design system. Built on top of Commander.js and maintained in the `facebook/astryx` repository, it exposes both human-readable outputs and typed JSON envelopes for AI agents and CI pipelines. All commands are lazily registered in `packages/cli/src/index.mjs` and support standardized global flags for locale and formatting control. ## Command Architecture and Registration All CLI commands are declared lazily in `packages/cli/src/index.mjs` to optimize startup performance. The entry point maintains a `JSON_SUPPORTED` Set that enumerates exactly which sub-commands can emit machine-readable JSON envelopes instead of human-readable text. ```javascript // packages/cli/src/index.mjs (lines 53-71) export const JSON_SUPPORTED = new Set([ 'component', 'docs', 'discover', 'search', 'swizzle', 'template', 'hook', 'theme build', 'theme list', 'theme add', 'upgrade', 'manifest', 'doctor', 'validate‑integration', 'layout expand', 'layout check', 'layout grammar', ]); ``` Concrete implementations reside under `packages/cli/src/commands/`, where each module registers its own sub-commands via the `commands` array. When invoking the CLI with `--json`, the entry point validates the sub-command against this Set before executing any side-effects, aborting early if the command lacks JSON support. ## Available CLI Commands The Astryx CLI organizes functionality into four primary domains: documentation browsing, theme management, project scaffolding, and diagnostics. ### Documentation and Discovery - **`component `** – Displays detailed documentation for a specific component, including props, variants, and usage examples. - **`docs `** – Renders token references and general design system documentation. - **`hook `** – Shows documentation for React hooks within the system. - **`search `** – Performs a global search across components, hooks, tokens, and documentation. - **`discover`** – Lists available capabilities and recently added components. ### Theme and Layout Management - **`theme build `** – Compiles a TypeScript theme file into CSS and JavaScript runtime helpers. - **`theme list`** – Enumerates installed theme packages and their versions. - **`theme add `** – Installs a new theme package from the registry. - **`layout expand`**, **`layout check`**, **`layout grammar`** – Layout system utilities for validating and expanding layout definitions. ### Project Scaffolding and Maintenance - **`init`** – Bootstraps a new project, installing packages and generating AI-ready documentation. - **`template `** – Injects pre-built page templates or component patterns into your codebase. - **`swizzle`** – Transform existing components to match new API patterns (codemod utility). - **`upgrade`** – Applies automated migration scripts; use `--list` to preview and `--apply` to execute. ### Diagnostics and Validation - **`doctor`** – Runs a health-check against the project configuration, exiting with code `0` on success and `1` on failure for CI compatibility. - **`manifest --json`** – Generates a complete capability manifest describing all available commands and their schemas. - **`validate-integration`** – Checks third-party integrations against Astryx compatibility rules. ## Global Options and JSON Mode The root `program` object in `packages/cli/src/index.mjs` defines global flags that apply to every sub-command: | Flag | Description | |------|-------------| | `--json` | Emits a typed JSON envelope (`{type, data}`) suitable for programmatic parsing. | | `--zh` | Renders documentation in Simplified Chinese. | | `--dense` | Outputs a token-efficient format optimized for AI agents. | | `--lang ` | Specifies locale explicitly (`en`, `zh`, or `dense`). | | `--detail ` | Controls information density: `full`, `compact`, or `brief`. | When `--json` is passed, the CLI validates that the invoked command exists in the `JSON_SUPPORTED` Set. If unsupported, the process exits before side-effects occur. JSON response shapes are defined in `packages/cli/src/lib/manifest.mjs` and consumed via the `@astryxdesign/cli/api` programmatic interface. ## Practical Usage Examples ### Display Component Documentation View human-readable documentation for the Button component: ```bash npx astryx component Button ``` Retrieve the same content as a typed JSON envelope for integration with AI agents: ```bash npx astryx component Button --json ``` Example output structure: ```json { "type": "component.detail", "data": { "name": "Button", "description": "Button triggers an action when clicked …", "props": [] } } ``` ### Search with Compact Output Search across all domains while limiting output detail: ```bash npx astryx search button --detail compact ``` ### Compile Theme Files Build a theme file and receive compiled assets via JSON: ```bash npx astryx theme build src/theme.ts --json ``` Response format: ```json { "type": "theme.build", "data": { "css": "...compiled CSS...", "js": "...runtime helper..." } } ``` ### CI Health Checks Integrate the diagnostic tool into GitHub Actions workflows: ```yaml # .github/workflows/ci.yml - run: npx astryx doctor ``` The `doctor` command returns exit code `0` for healthy projects and `1` when configuration errors are detected, making it ideal for automated quality gates. ## Summary - **17 commands** support JSON output mode, enabling both human and machine consumption via the `JSON_SUPPORTED` registry in `packages/cli/src/index.mjs`. - **Global flags** (`--json`, `--dense`, `--lang`) apply universally across all sub-commands for consistent localization and formatting. - **Theme compilation** converts TypeScript theme definitions into production CSS and JS through `astryx theme build`. - **Health diagnostics** via `astryx doctor` provide CI-friendly exit codes and detailed project validation. - **Programmatic API** access is available through `@astryxdesign/cli/api` for embedded tooling and automation scripts. ## Frequently Asked Questions ### What is the difference between `--json` and `--dense` mode? **`--json`** outputs a complete typed envelope with metadata headers suitable for API integration, while **`--dense`** produces a token-efficient format that minimizes character count for AI agent contexts. Both are machine-readable, but `--dense` strips whitespace and verbose property names to reduce context window usage. ### Can I use the Astryx CLI programmatically instead of via the terminal? Yes. The `@astryxdesign/cli/api` package exposes the same command set as a JavaScript API. Import the package and invoke commands to receive the same JSON envelopes without spawning subprocesses, as implemented in `packages/cli/src/lib/json.mjs`. ### How do I validate my project setup before deploying? Run `npx astryx doctor` to execute a comprehensive health check. This command verifies configuration files, dependency versions, and theme compilation status. In CI environments, it exits with code `1` on failure, automatically failing the build pipeline if the project does not meet Astryx standards. ### Which commands support the `--json` flag for automation? The CLI supports JSON output for 17 specific commands enumerated in the `JSON_SUPPORTED` Set within `packages/cli/src/index.mjs`. These include `component`, `docs`, `search`, `theme build`, `theme list`, `doctor`, `manifest`, and all `layout` sub-commands. Commands not in this Set will abort if invoked with `--json` to prevent incompatible output formats.