# search

Search for artifacts in registries

Canonical URL: https://docs.paradoc.dev/cli/commands/search/

Searches for artifacts in a registry.

## Usage

```bash
paradoc search [query] [options]
```

## Arguments

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| `query`  | Search query (matches name, title, or description) |

## Options

| Option                   | Description                                                          |
| ------------------------ | -------------------------------------------------------------------- |
| `--registry <namespace>` | Registry namespace to search (default: the only configured registry) |
| `--kind <kind>`          | Filter by artifact kind: `form`, `document`, `checklist`, `bundle`   |
| `--tags <tags>`          | Filter by tags (comma-separated)                                     |
| `--json`                 | Output as JSON                                                       |

## Description

The `search` command queries a registry's index to find matching artifacts. You can filter results by kind, tags, or a text query that matches against artifact names, titles, and descriptions. Each result shows the release you get by default, and the editions and versions the registry lists for the artifact. To install one of them, see the reference forms in [add](/cli/commands/add).

There is no default registry. Without `--registry`, it searches the one registry you have configured. With no registry configured, it fails and tells you to pass `--registry` or run [`paradoc registry add`](/cli/commands/registry/add). With several configured, it fails and lists them so you can pick one with `--registry`.

A namespace must be configured first with `paradoc registry add`; an unconfigured one fails and prints the command to run. `@paradoc` is reserved for the Paradoc registry, which is not available yet. When the registry host cannot be reached, the command fails and names it.

## Examples

Search all artifacts:

```bash
paradoc search
```

Search with a query:

```bash
paradoc search "lease agreement"
```

Filter by kind:

```bash
paradoc search --kind form
```

Filter by tags:

```bash
paradoc search --tags legal,real-estate
```

Search a specific registry:

```bash
paradoc search --registry @acme "tax"
```

Output as JSON:

```bash
paradoc search --json
```

## Output

```
Found 3 artifacts:

@acme/pet-policy v1.1.0
  Pet Policy
  Rules for keeping pets in a rental unit
  form
  Versions: 1.1.0 (latest), 2.0.0-beta.1, 1.0.0

@acme/residential-lease v1.0.0
  Residential Lease Agreement
  Standard residential property lease agreement between landlord and tenant
  form · #lease #residential #rental #agreement · 2 layers
  Versions: 1.0.0 (latest)

@acme/w4 2024 v1.1.0
  Employee's Withholding Certificate
  form · #irs #tax #payroll
  Editions:
    2024 (current)  2024: 1.1.0 (latest), 1.0.0
    2025  2025: 1.0.0 (latest)

Run paradoc add @acme/<name> to install an artifact, or @acme/<name>/<edition>@<version> for one release.
```

The first line of a result is the release you get by default. An artifact that has editions lists each one with its key, the issuer's label, and its versions.

## See also

* [add](/cli/commands/add) - Install an artifact
* [registry](/cli/commands/registry) - Manage registry configurations

Use `--no-cache` to bypass cached registry search results.