# add Add an artifact from a registry, or document components and blocks Canonical URL: https://docs.paradoc.dev/cli/commands/add/ Adds an artifact from a registry into your project, or one or more document components and blocks from the [Paradoc component registry](/components). ## Usage ```bash paradoc add [options] ``` ## Arguments | Argument | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `targets` | Artifact reference (`@namespace/name`, with an optional `/edition` and `@version`), namespace (`@namespace`), direct URL, or one or more document component or block names (`field`). Several targets must all be component or block names; add artifacts one at a time. | ## Options | Option | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--layers ` | Layers to download (comma-separated, or `"all"`) | | `--output ` | Output format: `json`, `yaml`, `typed` (json + .d.ts), or `ts` (TypeScript module). Default: `artifacts.output` in `paradoc.json`, then `defaults.output` in global config, then `json` | | `--header
` | HTTP header for direct URL auth (format: `"Name: Value"`). Can be used multiple times. A malformed header fails the command. | | `--cache-ttl ` | Cache TTL in seconds (`0` = no cache, default: use config) | | `--no-cache` | Skip cache and fetch fresh | | `--registry ` | Component registry URL template for `@paradoc` (must contain `{name}`) | | `--dry-run` | For a component, print the install command instead of running it | ## 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](/concepts/registries#editions-and-versions). | Reference | Meaning | | ------------------------- | ------------------------------------------------------------------------------ | | `@acme/w-9` | The current edition, latest version | | `@acme/w-9/2024-03` | The latest version of edition `2024-03` | | `@acme/w-9@1.0.0` | Version `1.0.0` of the current edition, or of an artifact that has no editions | | `@acme/w-9/2024-03@1.0.0` | One edition and one version | 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 @ ` first (see [Namespaces](/concepts/registries#namespaces)). ```bash paradoc add field ``` Name several components to install them in one call. Each one reports its own result: ```bash 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](/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: ```bash paradoc add @acme/residential-lease ``` Add one edition and version: ```bash paradoc add @acme/w-9/2024-03@1.0.0 ``` Add with all layers: ```bash paradoc add @acme/residential-lease --layers all ``` Add specific layers: ```bash paradoc add @acme/residential-lease --layers pdf,markdown ``` Add with a specific output format: ```bash paradoc add @acme/residential-lease --output yaml ``` Add as a TypeScript module: ```bash paradoc add @acme/residential-lease --output ts ``` Browse all artifacts in a namespace: ```bash paradoc add @acme ``` Add from a direct URL: ```bash paradoc add https://registry.example.com/r/my-form.json ``` Add from a URL with authentication: ```bash paradoc add https://registry.example.com/r/my-form.json --header "Authorization: Bearer token123" ``` Add a document component: ```bash 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](/cli/commands/search) - Find artifacts in registries * [list](/cli/commands/list) - List installed artifacts * [show](/cli/commands/show) - View artifact details * [Components](/components) - The document component registry `paradoc add ` 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`.