Registry and CLI

Quick start

1pnpm add -D @nerio-ui/registry@1.0.0-beta.1 @nerio-ui/cli@1.0.0-beta.1

1pnpm exec nerio init2pnpm exec nerio list3pnpm exec nerio info button4pnpm exec nerio add button --dry-run5pnpm exec nerio add button6pnpm exec nerio diff button7pnpm exec nerio update button --dry-run8pnpm exec nerio doctor

init creates configuration, doctor validates the manifest, and add writes the selected component and source dependencies. Use list to discover components, info to inspect metadata, and add --dry-run to review the initial install plan. Use diff and update --dry-run before applying an upstream source update.

For a one-off initialization or component install, invoke the real package name. Keep the local installation above as the default for repeatable lifecycle work.

1pnpm dlx @nerio-ui/cli@1.0.0-beta.1 init2pnpm dlx @nerio-ui/cli@1.0.0-beta.1 add button

Project configuration

1{2  "schemaVersion": "1.0.0",3  "registry": "@nerio-ui/registry/manifest.json",4  "components": "components/nerio"5}

The default package specifier resolves the immutable Registry shipped with the installed CLI-compatible release. Relative registry paths resolve from the target project. HTTPS manifests resolve every source file relative to the final manifest URL. Plain HTTP is rejected unless each command supplies --allow-insecure-http; reserve that opt-in for a trusted local Registry. Remote requests enforce a 10-second request/body timeout, a 2 MiB manifest limit, a 4 MiB per-source limit, at most three redirects, content-type handling, schema/path validation, and SHA-256 integrity.

Installed source lifecycle

A successful install writes nerio.lock.json beside nerio.json. The portable record contains Registry schema and release metadata, exact source revision, style contract version, requested items, dependency closure, installed paths, and original SHA-256 hashes and Registry integrity metadata. It contains no source content, secrets, or absolute machine paths.

• diff [component] reports unchanged, locally modified, upstream changed, added, removed, and combined conflict states.
• update [component] --dry-run prints the complete deterministic plan without writing.
• update [component] applies added and upstream-only changes, removes only unchanged obsolete files, and preserves local-only edits.
• When local and upstream changes overlap, the update stops before writing. Resolve the source manually or use --force only when intentional replacement is acceptable.
• Shared tokens and utilities are tracked independently from leaf components, so dependency closures update without duplicate files.
• Add and update fetch and validate the complete plan before writing, stage every change, commit source before lock metadata, and restore both source and lock state after any handled failure. A durable local journal recovers an interrupted process on the next state-sensitive command (add, diff, update, or doctor); already-committed source and lock state is retained. A project-local process lock serializes installs, updates, validation, and recovery so parallel commands cannot lose source ownership or lock metadata; list and info remain read-only inspection commands. An owner heartbeat also makes locks reclaimable after process death, restart, or PID reuse.

To adopt a pre-metadata alpha install, commit or back up local changes, point nerio.json at the intended release Registry, and rerun add <component>. Files that still match the release are adopted into the new metadata without replacement; customized token source remains local and is reported as drift. The CLI accepts the legacy nerio.json 0.1.0 schema during adoption and diagnoses the move to schema 1.0.0. Resolve other pre-existing differences explicitly before the first managed update. Use the same diff-first sequence for prerelease-to-prerelease and prerelease-to-1.0 migrations.

This page reads Registry 1.0.0-beta.1 (v1.0.0-beta.1) using schema 1.1.0 and style contract tailwind-v1. Initial add refuses to replace changed files by default. Use --overwrite only for intentional reinstall; normal upgrades use the non-destructive update workflow.

Registry contract

• Metadata declares dependencies, files, SHA-256 integrity, Base UI primitives, slots, and variants.
• Top-level metadata pins the Registry release, exact source revision, schema, and style contract.
• Server-safe form items such as form-group declare no Base UI primitive; interactive controls such as checkbox, radio-group, and switch declare their Base UI primitive contracts.
• Required tokens make styling dependencies explicit for products and AI agents.
• list prints component name, title, and category from the configured registry.
• info <component> prints dependencies, registry dependencies, files, tokens, and usage.
• Registry dependencies are traversed before the requested component is installed.
• --dry-run prints every target file without writing to the project.
• Target paths are constrained to the configured component directory.
• doctor distinguishes blocking version, schema, dependency, metadata, and setup errors from informational local source drift.