# How to Search Across Astryx Components, Hooks, and Docs Using the CLI > Easily search Astryx components, hooks, and docs via the CLI with astryx search . Discover relevant results with built-in scoring and filtering. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: how-to-guide - Published: 2026-07-02 --- **Run `astryx search ` to search across components, hooks, documentation, and templates with built-in relevance scoring and filtering options.** The Astryx design system from Meta provides a unified CLI command to help you discover components, hooks, and documentation without leaving your terminal. Learning how to search across Astryx components, hooks, and docs using the CLI accelerates your development workflow by surfacing relevant resources with fuzzy matching and type filtering. This guide covers the command syntax, underlying scoring algorithm, and practical examples based on the facebook/astryx source code. ## Command Syntax and Options The search functionality is registered in `packages/cli/src/commands/search.mjs`, which defines the command entry point and handles argument parsing around lines 31-38. ### Basic Usage To execute a search, run `astryx search` followed by your query term. The command scans all indexed domains—components, hooks, documentation topics, and templates—by default. ```bash npx astryx search button ``` ### Filtering by Resource Type Use the `--type` flag to narrow results to a specific category. Valid options include `component`, `hook`, `doc`, and `template`. This filtering is processed early in the command handler to reduce the candidate pool before scoring. ```bash npx astryx search modal --type component npx astryx search useForm --type hook ``` ### Limiting Results Control the number of returned items with the `--limit` flag. The command accepts an integer value and is processed in the argument parsing logic at lines 11-18 of the command file. ```bash npx astryx search dashboard --limit 5 ``` ## How the Search Algorithm Works The core implementation resides in `packages/cli/src/api/search.mjs`. This module gathers candidates from each domain, calculates relevance scores, and returns ranked results. The scoring algorithm at lines 19-28 evaluates matches using four weighted criteria: - **Exact name matches** receive highest priority for precise queries - **Keyword matches** in metadata tags and categories - **Fuzzy Levenshtein distance** calculations for typo tolerance and partial matches - **Prose matches** within descriptions and documentation content The candidate collection logic gathers resources from components, hooks, docs, and templates between lines 33-57, then applies the composite scoring table to determine result ranking. ## Output Formats and JSON API By default, the CLI prints human-readable results with match reasons and import paths. For detailed metadata including file paths, add the `--detail` flag. For programmatic consumption, add the `--json` flag. The JSON output follows a typed envelope structure generated at lines 63-66 of the command handler: ```json { "type": "search", "data": { "query": "chart", "results": [...] } } ``` This format is stable and designed for integration with build scripts, IDE extensions, and AI agents. ## Practical CLI Examples Here are common search patterns for daily development workflows: ```bash # Search across all domains npx astryx search button # Find components with detailed metadata npx astryx search form --detail # Get machine-readable output for scripts npx astryx search chart --json # Restrict to documentation only npx astryx search accessibility --type doc # Limit to top 3 results npx astryx search table --limit 3 ``` All commands automatically detect your project root and load local `astryx` configuration, enabling workspace-specific results. ## Key Source Files Understanding the architecture helps when extending or debugging the search functionality: - **packages/cli/src/commands/search.mjs** – CLI command registration, argument parsing, and output formatting (lines 31-38) - **packages/cli/src/api/search.mjs** – Core search implementation including candidate gathering, scoring logic, and the Levenshtein-based fuzzy matcher (lines 19-57) - **packages/cli/src/lib/json.mjs** – Utilities for standardized JSON output generation - **packages/cli/src/lib/manifest.mjs** – Command metadata definitions for the auto-generated manifest ## Summary - Use `astryx search ` to find resources across components, hooks, docs, and templates in a single command - Filter by resource type using `--type` with valid values: `component`, `hook`, `doc`, or `template` - The scoring algorithm ranks results by exact name matching, keyword tags, fuzzy Levenshtein distance, and prose content analysis - Enable `--json` for programmatic access to search results via a typed JSON envelope - Implementation is split between the command handler in `packages/cli/src/commands/search.mjs` and the scoring engine in `packages/cli/src/api/search.mjs` ## Frequently Asked Questions ### How do I search only for components in Astryx? Pass the `--type component` flag to restrict results to UI components only. According to the implementation in `packages/cli/src/commands/search.mjs`, this filters the candidate pool before the scoring algorithm runs, improving both performance and result relevance by excluding hooks, documentation, and templates from the query. ### What scoring algorithm does the Astryx search command use? The implementation in `packages/cli/src/api/search.mjs` uses a multi-tier relevance system. It weights exact name matches highest, followed by keyword tag matches, fuzzy Levenshtein distance calculations for typo tolerance, and prose content analysis. Each factor contributes to a composite score that determines the final result ranking returned to the CLI. ### Can I consume search results programmatically? Yes. Add the `--json` flag to receive a typed JSON envelope containing the query string and results array. This output format, generated at lines 63-66 of the command file, is stable and designed specifically for integration with build scripts, IDE extensions, and AI tooling that requires structured data rather than human-readable text. ### Where is the search command implemented? The CLI entry point resides in `packages/cli/src/commands/search.mjs`, which handles argument parsing, flag processing, and output formatting. The actual search logic, including candidate gathering from all domains and the relevance scoring algorithm, is implemented in `packages/cli/src/api/search.mjs`.