# Dynamic Search

How the CLI searches a registry, and what a large registry can do.

Source: https://webjs.dev/ui/docs/registry/dynamic-search

`search` is another name for `list`. It fetches your registry's `index.json` and filters the items locally. This works for any registry and requires nothing more than a static file.

Search runs in the CLI.

The CLI filters the index it fetched, so every registry gets search from a static `index.json`, with nothing to implement on the server.

## How It Works

When you run `search`, the CLI requests the index once and filters what comes back:

```bash
npx @webjsdev/ui search button --registry https://acme.com/r
```

```txt
GET https://acme.com/r/index.json
```

The index must be a JSON array of registry items. The CLI keeps the items typed `registry:ui` and `registry:block`, applies the filters below, and prints them in groups, Components then Blocks.

## Filters

Every filter runs in the CLI, against the index it fetched.

| Filter | Description |
| --- | --- |
| `[filter]` | Keeps the items whose name contains this substring. |
| `--type <type>` | `ui`, `block`, `chart` or `all` (the default). A chart is a `registry:block` item with the `chart` category. |
| `--category <name>` | Keeps the blocks and charts whose `categories` include this name. |
| `--json` | Prints one compact JSON array of `{ name, type, categories, description }`, for a script or an agent. |

```bash
npx @webjsdev/ui list --type block --category login --json --registry https://acme.com/r
```

## Response Format

Serve the whole index as a JSON array. `webjsui build` writes one with each item's `name`, `type` and `description`, which keeps it small however large the registry grows, since no file contents are in it.

```json title="index.json"
[
  { "name": "brand-button", "type": "registry:ui", "description": "A button in the Acme brand colors." },
  { "name": "login-01", "type": "registry:block", "description": "A simple login form." }
]
```

The `--category` filter reads each entry's `categories`, which the index `build` writes leaves out. A registry that wants category filtering serves an index whose entries carry `categories`, from its own route or script.

## Large Registries

For a registry with thousands of items, keep the index lean: names, types, descriptions and categories, never contents. The CLI downloads it once per command. Each item's full JSON is fetched only when someone views or installs that item.

## Testing

Test your index with `curl`:

```bash
curl https://acme.com/r/index.json
```

Then verify with the CLI:

```bash
npx @webjsdev/ui search button --registry https://acme.com/r
```
