add

Last updated on

Adds an artifact from a registry into your project, or one or more document components and blocks from the Paradoc component registry.

Usage

paradoc add <targets...> [options]

Arguments

Options

Description

The add command fetches an artifact from a configured registry and saves it to your project's artifacts directory. The artifact is validated before being saved, and a lock file entry is created to track the installation.

A reference can name an edition, a version, or both: @namespace/name[/edition][@version]. Without an edition, you get the artifact's current edition. Without a version, you get the latest version. current and latest name the same defaults. The registry's publisher states both defaults in its manifest. See Editions and versions.

A reference to an edition or version that the registry does not list fails, and the error says which ones it does list. The CLI checks the downloaded file against the SHA-256 in the manifest, and checks that the file's own name, version and edition are the ones you asked for. A mismatch fails the install and nothing is written. The lock file entry records the version and, when the artifact has editions, the edition. A project holds one release of an artifact: adding another edition or version replaces the installed one.

By default, only the artifact definition is downloaded. Use --layers to also download associated files like PDFs or templates.

Content reference files (instructions, agentInstructions) that use kind: "file" are downloaded automatically — no --layers flag needed. These are typically small text files essential for the artifact to function correctly. Every downloaded file requires a checksum; a missing checksum or requested layer fails the install without writing the artifact or lock entry.

A direct URL fetches that exact JSON or YAML resource without requesting a registry manifest. No manifest means no checksum and no identity check for the artifact file: you get what the URL serves. --output ts writes the TypeScript module and keeps a JSON source for other Paradoc commands; the lock points to that JSON source.

When called with just a namespace (@namespace), the command enters browse mode and lets you interactively select artifacts to install.

Document components

A bare name is a document component rather than an artifact: an artifact reference always carries a namespace or is a URL, so the two cannot be confused. An artifact always names its namespace. A bare name that is not a component, such as paradoc add w9, fails and asks for the registry: paradoc add @registry/w9. The built-in @paradoc namespace needs no configuration; any other namespace must be added with paradoc registry add @<ns> <url> first (see Namespaces).

paradoc add field

Name several components to install them in one call. Each one reports its own result:

paradoc add field image

That writes the @paradoc namespace into the project's components.json if it is not already there, then runs npx shadcn@4 add @paradoc/field. The shadcn major is pinned rather than latest, because the registry's install proof runs that major. The component's source lands in components/paradoc/ and is yours to edit; see Components for the full list and what stays in @paradoc/react.

A block installs the same way and is one of these names too. It brings a whole document rather than one component, so paradoc add purchase-order lands the artifact, its sample data and the composition that binds them; the composition goes to components/paradoc/ and the other two to artifacts/paradoc/.

Only a name the registry ships is read as a component. Any other bare argument is reported as an invalid artifact reference, listing both forms, rather than being sent to the shadcn CLI to fail on a missing item.

The command needs a shadcn project: run npx shadcn@latest init first if there is no components.json. A @paradoc namespace already pointing at a different registry is left alone and reported, so a project running its own mirror is not silently repointed.

Examples

Add an artifact:

paradoc add @acme/residential-lease

Add one edition and version:

paradoc add @acme/w-9/2024-03@1.0.0

Add with all layers:

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

Add specific layers:

paradoc add @acme/residential-lease --layers pdf,markdown

Add with a specific output format:

paradoc add @acme/residential-lease --output yaml

Add as a TypeScript module:

paradoc add @acme/residential-lease --output ts

Browse all artifacts in a namespace:

paradoc add @acme

Add from a direct URL:

paradoc add https://registry.example.com/r/my-form.json

Add from a URL with authentication:

paradoc add https://registry.example.com/r/my-form.json --header "Authorization: Bearer token123"

Add a document component:

paradoc add field

Output

✔ Registry: https://registry.acme.com
✔ Found residential-lease v1.0.0
✔ Verified layer "legal": residential-lease-legal.md
✔ Written: artifacts/@acme/residential-lease.json

✓ Added @acme/residential-lease v1.0.0

Format: json
  → artifacts/@acme/residential-lease.json
Layers: legal

An artifact that has editions shows the edition before the version:

✔ Registry: https://registry.acme.com
✔ Found w4 2025 v1.0.0
✔ Written: artifacts/@acme/w4.json

✓ Added @acme/w4 2025 v1.0.0

Format: json
  → artifacts/@acme/w4.json

A reference to an edition or version the registry does not list:

✖ Failed to resolve @acme/w4/2023
w4 has no edition 2023. Its editions: 2024, 2025 (current: 2024).
Registry: https://registry.acme.com

See also

• search - Find artifacts in registries
• list - List installed artifacts
• show - View artifact details
• Components - The document component registry paradoc add <name> installs from

A conflicting registry mapping stops installation without writing files. Correct or remove the mapping, then retry. Component installation invokes the package runner with --yes.