Registries

Last updated on

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 and the AI tools 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:

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:

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

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

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

For registries that require authentication, use the extended format:

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

Searching for artifacts

Use paradoc search to query a registry. Without --registry it searches your one configured registry; with none or several configured, pass --registry:

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

paradoc add @acme/residential-lease

Download layers alongside the definition:

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

Viewing artifact details

View metadata for an installed artifact:

paradoc registry view @acme/residential-lease

Direct URL installs

Install from a URL directly, bypassing namespace resolution:

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

Private registries

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

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

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

Local development registries may use HTTP:

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

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:

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

See the 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:

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

Artifact entry fields

Workflow

The CLI provides commands to scaffold and manage a registry:

1. Create the registry — paradoc registry make generates a registry.json with your registry name and metadata.

2. Add artifacts to the catalog — paradoc registry catalog manages the artifacts listed in the index.

3. Compile — paradoc registry compile validates all artifacts and prepares the registry for publishing.

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:

npx serve my-registry -l 4567

Then configure the local registry:

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

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