# Registries

Consuming and creating Paradoc artifact registries

Canonical URL: https://docs.paradoc.dev/concepts/registries/

A registry is a hosted collection of Paradoc artifacts. Registries can be public or private. You find an artifact in a registry, install it into your project, and fill and render it there. The [CLI](/cli) and the [AI tools](/ai-tools/get-registry) both read registries; the examples on this page use the CLI.

## Using registries

### Namespaces

Every artifact reference names a registry namespace, as in `@acme/residential-lease`.

* **There is no default registry.** The CLI resolves a namespace only through your configuration. An unconfigured namespace fails with a message that names it and tells you to run `paradoc registry add @<ns> <url>`.
* **`@paradoc` is reserved.** It is kept for the Paradoc registry, which is not available yet. Using it fails with `The Paradoc registry is not available yet`. `paradoc registry add @paradoc <url>` is refused, and a global or project config that sets a URL for `@paradoc` is an error.
* **Every other namespace is yours to add.** Anyone can host a registry and give it any other namespace.

For example, `https://public.paradoc.dev` is a demo registry you can add under any namespace:

```bash
paradoc registry add @demo https://public.paradoc.dev --global
paradoc search --registry @demo
```

### Adding a registry

Add a registry to your project by editing `paradoc.json`:

```json
{
  "registries": {
    "@acme": "https://registry.acme.com"
  }
}
```

Or add one globally so it's available across all projects:

```bash
paradoc registry add @acme https://registry.acme.com --global
```

For registries that require authentication, use the extended format:

```json
{
  "registries": {
    "@private": {
      "url": "https://registry.example.com",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

| Field       | Description                                      |
| ----------- | ------------------------------------------------ |
| `url`       | Registry base URL                                |
| `headers`   | Custom headers (supports `${ENV_VAR}` expansion) |
| `cache.ttl` | Per-registry cache TTL override in seconds       |

### Searching for artifacts

Use [`paradoc search`](/cli/commands/search) to query a registry. Without `--registry` it searches your one configured registry; with none or several configured, pass `--registry`:

```bash
paradoc search lease
paradoc search --kind form --tags legal
paradoc search --registry @acme "tax"
```

The query matches against artifact names, titles, and descriptions. Filter by `--kind` or `--tags` to narrow results.

### Installing artifacts

Use [`paradoc add`](/cli/commands/add) to install an artifact. The CLI resolves the namespace to a registry, downloads the definition, writes it to your artifacts directory, and updates the lock file:

```bash
paradoc add @acme/residential-lease
```

Download layers alongside the definition:

```bash
paradoc add @acme/residential-lease --layers all
```

### Viewing artifact details

View metadata for an installed artifact:

```bash
paradoc registry view @acme/residential-lease
```

### Direct URL installs

Install from a URL directly, bypassing namespace resolution:

```bash
paradoc add https://example.com/artifacts/my-form.yaml
```

### Private registries

For private registries, configure authentication headers with environment variable tokens:

```json
{
  "registries": {
    "@private": {
      "url": "https://registry.example.com",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

```bash
export REGISTRY_TOKEN="your-token-here"
paradoc add @private/internal-form
```

Local development registries may use HTTP:

```json
{
  "registries": {
    "@local": {
      "url": "http://localhost:4567"
    }
  }
}
```

### Managing registries

List all configured registries (project and global). The built-in `@paradoc` is not listed, because it is never configured:

```bash
paradoc registry list
```

Remove a registry. Without a namespace, the command lets you pick from a list. `--global` or `--project` limits the list to that config:

```bash
paradoc registry remove @acme --global
paradoc registry remove --project
```

See the [`registry`](/cli/commands/registry) command reference for all subcommands.

***

## Creating registries

### Registry structure

A registry is a directory containing a `registry.json` index file and individual artifact files:

```
my-registry/
├── registry.json           # Registry index
└── artifacts/
    ├── residential-lease/
    │   ├── artifact.yaml   # Artifact definition
    │   └── lease.pdf       # Layer files
    └── w9/
        ├── artifact.yaml
        └── w9.pdf
```

### Registry index

The `registry.json` file lists all available artifacts:

```json
{
  "$schema": "https://schema.paradoc.dev/registry.json",
  "name": "acme",
  "description": "Official forms and documents for Acme Corp",
  "homepage": "https://acme.com/forms",
  "items": [
    {
      "name": "residential-lease",
      "version": "1.0.0",
      "kind": "form",
      "title": "Residential Lease Agreement",
      "description": "Standard residential lease agreement",
      "tags": ["legal", "real-estate", "lease"],
      "path": "artifacts/residential-lease/artifact.yaml"
    }
  ]
}
```

#### Index fields

| Field           | Type   | Required | Description                                    |
| --------------- | ------ | -------- | ---------------------------------------------- |
| `$schema`       | string | No       | JSON schema URL                                |
| `name`          | string | Yes      | Registry name, a lowercase slug (e.g., `acme`) |
| `description`   | string | No       | Registry description                           |
| `homepage`      | string | No       | Registry homepage URL                          |
| `artifactsPath` | string | No       | Path prefix for artifact URLs (e.g., `/r`)     |
| `items`         | array  | Yes      | List of artifact entries                       |

#### Artifact entry fields

| Field         | Type   | Required | Description                                                                                          |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | Artifact identifier (slug)                                                                           |
| `version`     | string | Yes      | Semantic version                                                                                     |
| `kind`        | string | Yes      | Artifact type: `form`, `checklist`, `document`, `bundle`                                             |
| `title`       | string | No       | Human-readable name                                                                                  |
| `description` | string | No       | Artifact description                                                                                 |
| `layers`      | array  | No       | Layer keys the artifact provides                                                                     |
| `tags`        | array  | No       | Searchable tags                                                                                      |
| `path`        | string | No       | Path to the artifact file, relative to the registry URL plus `artifactsPath`. Default: `<name>.json` |

### Workflow

The CLI provides commands to scaffold and manage a registry:

1. **Create the registry** — [`paradoc registry make`](/cli/commands/registry/make) generates a `registry.json` with your registry name and metadata.

2. **Add artifacts to the catalog** — [`paradoc registry catalog`](/cli/commands/registry/catalog) manages the artifacts listed in the index.

3. **Compile** — [`paradoc registry compile`](/cli/commands/registry/compile) validates all artifacts and prepares the registry for publishing.

```bash
paradoc registry make --name acme --description "Official forms and documents for Acme Corp"
paradoc registry catalog add ./artifacts/residential-lease/artifact.yaml
paradoc registry compile
```

### Hosting

A registry is just static files served over HTTPS. Any hosting provider or web server works:

* **GitHub Pages** — free for public repositories
* **Netlify / Vercel** — deploy from a Git repository
* **AWS S3 + CloudFront** — scalable, cost-effective
* **nginx / Apache** — self-hosted

For local development, serve the directory with a static file server:

```bash
npx serve my-registry -l 4567
```

Then configure the local registry:

```json
{
  "registries": {
    "@local": {
      "url": "http://localhost:4567"
    }
  }
}
```

### Example: GitHub Pages

1. Create a repository with your registry structure (`registry.json` + `artifacts/`)
2. Enable GitHub Pages in repository settings (serve from the root or `docs/` folder)
3. Configure the registry in your project:

```json
{
  "registries": {
    "@myorg": "https://myorg.github.io/paradoc-registry"
  }
}
```

The CLI fetches `https://myorg.github.io/paradoc-registry/registry.json` to discover available artifacts.

### Best practices

1. **Version your artifacts** — use semantic versioning for all artifacts
2. **Add descriptive tags** — help users discover artifacts through search
3. **Include descriptions** — add descriptions to the registry, artifacts, and fields
4. **Validate before publishing** — run `paradoc validate` on all artifacts before compiling
5. **Use HTTPS** — always use HTTPS in production (HTTP only for local development)