Astryx XDS CLI Commands: Complete Usage Guide and Reference

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.

// 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 <name> – Displays detailed documentation for a specific component, including props, variants, and usage examples.
• docs <topic> – Renders token references and general design system documentation.
• hook <name> – Shows documentation for React hooks within the system.
• search <query> – Performs a global search across components, hooks, tokens, and documentation.
• discover – Lists available capabilities and recently added components.

Theme and Layout Management

• theme build <file> – Compiles a TypeScript theme file into CSS and JavaScript runtime helpers.
• theme list – Enumerates installed theme packages and their versions.
• theme add <package> – 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 <name> – 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 <locale>	Specifies locale explicitly (en, zh, or dense).
--detail <level>	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:

npx astryx component Button

Retrieve the same content as a typed JSON envelope for integration with AI agents:

npx astryx component Button --json

Example output structure:

{
  "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:

npx astryx search button --detail compact

Compile Theme Files

Build a theme file and receive compiled assets via JSON:

npx astryx theme build src/theme.ts --json

Response format:

{
  "type": "theme.build",
  "data": {
    "css": "...compiled CSS...",
    "js": "...runtime helper..."
  }
}

CI Health Checks

Integrate the diagnostic tool into GitHub Actions workflows:

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

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