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

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.

# 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 (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:

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

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

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