# How the Astryx CLI Manifest Command Generates Component Manifests for IDE Integration

> Learn how the Astryx CLI manifest command generates component manifests for seamless IDE integration. Discover how it extracts command metadata to enhance your development workflow.

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

---

**The Astryx CLI `manifest` command programmatically walks the Commander program tree, extracts command metadata, and emits a structured JSON document that IDEs consume to understand the CLI's full surface area.**

The `astryx manifest` command produces a self-describing **capability manifest** that powers IDE autocomplete, documentation, and seamless integration with Astryx components. This article explains the complete generation pipeline as implemented in the `facebook/astryx` repository, from entry point to final JSON output.

## Entry Point: Invoking the Manifest Command

The manifest command is registered in the CLI's Commander configuration. When invoked with the `--json` flag, it triggers the `buildManifest` function located in `packages/cli/clients/cli/lib/manifest.mjs`.

```bash

# Generate human-readable manifest

astryx manifest

# Emit JSON for IDE consumption

astryx manifest --json > .astryx/manifest.json

```

The `--json` flag signals the CLI to produce machine-readable output rather than formatted terminal text.

## Deriving Command Information from the Program Tree

The `buildManifest` function accepts the live `program` object, which already contains all subcommands and global options defined across the CLI—including component, template, and theme commands.

According to `facebook/astryx` source code, `buildManifest` iterates over `program.commands` and extracts for each:

- **name** — the command identifier
- **description** — human-readable purpose
- **arguments** — positional parameters
- **options** — flags and their configurations
- **response types** — supported output formats (JSON, HTML, etc.) for commands that support structured responses

This extraction happens dynamically at runtime, ensuring the manifest always reflects the current CLI state.

## Collecting Component-Specific Data

The manifest extends beyond command metadata to include **components**, **templates**, and **codemods** defined in the project configuration. This process involves two key resolution steps.

First, `packages/cli/foundation/config/project.mjs` resolves paths from the user's [`astryx.config.js`](https://github.com/facebook/astryx/blob/main/astryx.config.js) (or default locations). Second, `packages/cli/foundation/integrations/integrations.mjs` loads the corresponding **integration manifest** if present.

From these integration manifests, the CLI extracts:

- Root directories for components, templates, and codemods
- Optional metadata such as `issuesUrl` for package-level integration

The `packages/cli/foundation/discovery/component-discovery.mjs` module then correlates discovered component source files with manifest entries, enabling IDEs to map commands to actual implementation files.

## Flattening the Command Hierarchy for IDE Consumption

IDEs and other tooling often require a deterministic, flat structure rather than a nested tree. The `flatten` helper—defined in the same `manifest.mjs` module—transforms the command hierarchy into fully-qualified names.

For example, the nested `create` subcommand under `component` becomes `component create` in the flattened output. This guarantees predictable indexing for autocomplete engines and command palettes.

## Embedding the Manifest in Standard CLI Output

Beyond the dedicated `astryx manifest --json` endpoint, the capability manifest is also embedded in the generic `astryx --json` output. This dual exposure preserves backward compatibility while making the manifest accessible without invoking a separate command.

The test suite in `packages/cli/clients/cli/lib/manifest.test.mjs` validates this embedding, verifying that the manifest appears under `parsed.data.manifest` when running the bare CLI with `--json`.

## Output Format and Schema

The final JSON envelope follows a consistent schema with these top-level fields:

```json
{
  "name": "astryx",
  "apiVersion": "1.2.3",
  "description": "Astryx CLI capability manifest",
  "globalOptions": [...],
  "commands": [
    {
      "name": "component create",
      "description": "Create a new component",
      "arguments": [...],
      "options": [...],
      "responseTypes": ["json", "html"]
    }
  ]
}

```

Each command object includes `responseTypes` to indicate which output formats the IDE should expect for structured parsing.

## Programmatic Manifest Generation

You can generate manifests programmatically for custom tooling or testing:

```javascript
// Programmatic use inside a custom script
import {buildManifest} from '@astryxdesign/cli/lib/manifest.mjs';
import {program} from '@astryxdesign/cli/clients/cli/index.mjs';

const manifest = buildManifest(program, {
  jsonSupported: true,
  version: '1.2.3',
});
console.log(JSON.stringify(manifest, null, 2));

```

This approach accepts configuration options for JSON support and version stamping, matching the behavior of the CLI flag.

## Key Source Files

| File | Role |
|------|------|
| `packages/cli/clients/cli/lib/manifest.mjs` | Core `buildManifest` implementation; extracts Commander metadata and assembles the JSON envelope |
| `packages/cli/foundation/config/project.mjs` | Resolves project-level integration manifests for components, templates, and codemods |
| `packages/cli/foundation/integrations/integrations.mjs` | Loads and validates conventional root manifests adjacent to [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) |
| `packages/cli/foundation/discovery/component-discovery.mjs` | Discovers component source files and correlates them with manifest entries |
| `packages/cli/clients/cli/lib/manifest.test.mjs` | Test suite enforcing drift-guard correctness and JSON output validation |

## Summary

- The **Astryx CLI manifest command** generates a capability manifest by walking the live Commander program structure
- **`buildManifest`** in `packages/cli/clients/cli/lib/manifest.mjs` serves as the central orchestration function
- Component metadata flows through **`project.mjs`** and **`integrations.mjs`** from user configuration files
- The **flatten** helper transforms nested commands into fully-qualified names for IDE consumption
- The manifest appears both via **dedicated command** and **embedded in base CLI output** for compatibility
- JSON output enables autocomplete, documentation lookup, and integrated component workflows in IDEs

## Frequently Asked Questions

### What is the purpose of the Astryx CLI manifest command?

The `astryx manifest` command produces a machine-readable JSON document that describes every command, option, and component available in the CLI. IDEs consume this manifest to provide autocomplete suggestions, inline documentation, and seamless navigation to component source code.

### How does the manifest include component-specific information?

The CLI resolves component paths through `packages/cli/foundation/config/project.mjs`, loads integration manifests via `packages/cli/foundation/integrations/integrations.mjs`, and discovers actual component files using `packages/cli/foundation/discovery/component-discovery.mjs`. This pipeline connects declared configuration to filesystem locations.

### Can I generate the manifest programmatically without using the CLI?

Yes. Import `buildManifest` from `@astryxdesign/cli/lib/manifest.mjs` and pass a Commander program instance along with configuration options for JSON support and versioning. This enables custom tooling, testing, or CI pipelines to generate manifests without shelling out to the CLI.

### Where is the manifest schema validated and tested?

The test suite in `packages/cli/clients/cli/lib/manifest.test.mjs` enforces drift-guard correctness, validates JSON structure, and verifies that `astryx --json` correctly embeds the manifest under `parsed.data.manifest`. These tests ensure the manifest format remains stable for IDE integrations.