PrimeUI CLI

Command line tools for inspecting PrimeUI projects and managing PrimeUI assistant plugins.

pnpm dlx @primeui/cli@rc info --json
pnpm dlx @primeui/cli@rc info --cwd ./my-app --json

primeui info reports detected PrimeVue, PrimeNG, or PrimeReact packages, application environment, theme configuration, and PrimeReact variant signals. It does not modify the project.

Components

The component router validates the package-local PrimeUIPro registry and installs from package-owned bytes:

pnpm dlx @primeui/cli@rc component list
pnpm dlx @primeui/cli@rc component list --json
pnpm dlx @primeui/cli@rc add texteditor --framework vue --ui tailwind --output-dir src/components --dry-run
pnpm dlx @primeui/cli@rc --framework vue add scheduler --ui primeone --json
pnpm dlx @primeui/cli@rc component status texteditor --output-dir src/components --json
pnpm dlx @primeui/cli@rc component update texteditor --output-dir src/components --dry-run --json
pnpm dlx @primeui/cli@rc component remove texteditor --output-dir src/components --dry-run --json

primeui component list renders human or versioned JSON output from the same validated package-local registry used by add. The current released inventory is exactly:

• Scheduler for Vue with PrimeOne or Tailwind
• TaskBoard for Vue with PrimeOne or Tailwind
• TextEditor for Vue with PrimeOne or Tailwind

Vue is the current released component framework. Angular, React, and Lit component payloads are not released, and Chart, Diagram, and PDF Viewer are not available from this inventory. --framework may be omitted only when project package.json metadata proves exactly one framework and the chosen component/UI combination exists in the registry. An explicit framework that conflicts with detected package metadata is rejected.

--ui selects the PrimeOne or Tailwind implementation of a component. It defaults to primeone for add.

--output-dir must be a normalized relative path. The final destination preserves <output-dir>/<component> semantics and is reported without exposing the private absolute project path. Dry-run performs the same registry, path, symlink, hash, and conflict preflight as a real install while making zero target writes.

Missing files are created, byte-identical files are unchanged no-ops, and different files fail before all writes. Pass --overwrite to approve replacement of only the planned conflicts. Installation stages and verifies every changed file before activation, backs up only approved replacements, rolls back all completed changes on failure, and leaves unrelated files untouched.

Every successful add also writes a deterministic .primeui-managed.json inside the final component destination. The versioned record contains the @primeui/cli package identity and version, registry provenance, component/framework/UI identity, normalized destination, the sorted path/hash inventory, managed directory evidence, and an integrity hash. It contains no timestamps, credentials, environment values, absolute paths, or source-checkout paths. A first add can adopt byte-identical registry files by recording only those exact files; unrelated files remain unowned. Identical reruns preserve byte-identical payload and manifest bytes.

component status derives the framework and UI from the verified ownership record and partitions every owned path as unchanged, modified, missing, or unsafe without writing. component update loads that same component identity from the package registry. It refuses missing, unsafe, tampered, and unowned evidence; modified owned files require --overwrite, which approves only the planned owned replacements. component remove is stricter: every owned file must still be a byte-identical regular file. It deletes only those files and the verified manifest, then removes only recorded managed directories that are empty. Unrelated files and nonempty directories are preserved.

Update and remove support --dry-run, which performs the full ownership, registry, path, hash, parent, symlink, and transaction preflight and reports the exact plan with zero writes. Payload and ownership bytes share one sibling-staged transaction, including backup, activation verification, reverse rollback, and cleanup. Component ownership is independent of assistant-plugin ownership records.

Add plans include conservative compatibility and setup diagnostics from the selected registry payload. Required packages are partitioned as present, missing, incompatible, or unknown: a declaration is present only when its supported semver range intersects the registry requirement, and it is incompatible only when recognized ranges are provably disjoint. Conflicting declarations, unresolved workspace or catalog forms, tags, URLs, git/file/link specifications, malformed metadata, and other incomplete evidence remain unknown. These findings never install packages or change package manifests or lockfiles.

The same versioned plan reports stable setup checks for payload import aliases, TypeScript, declared styles or Tailwind processing, and Vue framework setup. A category is not-applicable when the payload bytes and registry metadata do not require it. Setup evidence is limited to bounded, explicit regular project files; symlinks, malformed configuration, unsupported forms, and ambiguous evidence remain unknown. Diagnostics are guidance only and never change tsconfig.json, jsconfig.json, stylesheet entrypoints, framework configuration, package metadata, or lockfiles.

The canonical component registry is vendored as byte-identical, package-owned data through an explicit local sync boundary:

corepack pnpm --filter @primeui/cli registry:sync -- --source /absolute/path/to/registry.json
corepack pnpm --filter @primeui/cli registry:check

The sync source path is always explicit. Registry checks, normal builds, tests, packed execution, and runtime read only registry/registry.json from @primeui/cli.

Debug timings and performance evidence

All commands accept --debug before or after the command and command options. In human mode, diagnostics are written only to stderr. With --json, the complete normal result gains only a top-level timings object and no debug prose is written to stderr. The versioned schema uses a monotonic clock, stable phase ordering, bounded millisecond durations, and not_run for inapplicable phases; it never includes arguments, environment values, command output, error text, or private paths. When a phase is measured repeatedly, its duration is the deterministic sum of every attempt, attempts records the count, and any failed attempt makes the aggregate phase status failed.

If parsing or command execution throws before a normal JSON result exists, safe timing diagnostics are written to stderr and the original error and exit behavior are preserved.

The committed project-inspection benchmark uses four minimal framework fixtures, three warmups, eleven process samples, and same-environment medians:

corepack pnpm --filter @primeui/cli build
corepack pnpm --filter @primeui/cli benchmark

Its budgets compare only against the recorded same-machine baseline and are not cross-machine performance claims. Host lifecycle and MCP work are intentionally outside this fixture benchmark and are reported separately by debug phases when those commands run.

Assistant plugins

PrimeUI assistant plugins are distributed from the public primefaces/primeui-plugins repository. Each library plugin installs one matching skill and MCP server without loading the other libraries.

Install a plugin for a specific assistant and library:

pnpm dlx @primeui/cli@rc plugin install --tool claude --library primevue
pnpm dlx @primeui/cli@rc plugin install --tool codex --library primeng
pnpm dlx @primeui/cli@rc plugin install --tool copilot --library primevue
pnpm dlx @primeui/cli@rc plugin install --tool gemini --library primereact

Inside a project with exactly one supported PrimeUI library, --library is optional:

pnpm dlx @primeui/cli@rc plugin install --tool codex

Use the same command group to inspect, update, or remove the selected plugin:

pnpm dlx @primeui/cli@rc plugin status --tool codex --library primevue
pnpm dlx @primeui/cli@rc plugin update --tool codex --library primevue
pnpm dlx @primeui/cli@rc plugin remove --tool codex --library primevue

plugin status --json returns one versioned, host-neutral result for Claude Code, Codex, GitHub Copilot, Gemini CLI, and Cursor. It reports the selected tool and library, detected project and PrimeReact variant context, plugin/skill/MCP states, the exact MCP package reference when the host exposes it, normalized checks, source, and summary. States are explicit: installed, missing, disabled, manual, unsupported, or error. Host command output and profile configuration are not included.

Human-readable status is rendered from that same normalized result. Claude Code and Codex currently expose plugin state through their list commands; fields those surfaces do not prove, such as physical skill or MCP discovery, are reported as unsupported rather than inferred from a successful command exit. GitHub Copilot status verifies the selected native install under ~/.copilot/installed-plugins/primeui, including its manifest, skills, MCP identity, and provenance. Gemini exposes extension skill and MCP details. Cursor status physically verifies the selected managed local plugin, manifest, skill, MCP identity, provenance, and deterministic payload hash.

Doctor

Run the supported end-to-end diagnostic after selecting an assistant and library:

pnpm dlx @primeui/cli@rc doctor --tool codex --library primevue
pnpm dlx @primeui/cli@rc doctor --tool gemini --library primereact --variant tailwind --json

--library may be omitted only when --cwd detects exactly one PrimeUI library. Doctor also works outside a project when --library is explicit. --variant is PrimeReact-only and accepts styled, tailwind, primitive, or headless; a conflicting explicit and detected variant fails before host inspection.

Doctor returns versioned structured JSON, and human output is derived from the same checks. For Claude Code, Codex, GitHub Copilot, and Gemini it verifies the selected plugin and physical installed payload where the host exposes a safe contract. Claude and Gemini paths come from their list JSON and must remain inside their effective plugin or extension roots. Codex derives the physical cache path from CODEX_HOME, the selected library, and the plugin version because its plugin list JSON does not expose an install path. Copilot uses its documented installed-plugin directory and reports marketplace registration as unsupported rather than parsing human output. Every payload path is canonicalized before its manifest, skill, MCP identity, command, arguments, and exact selected-library package pin are trusted.

Codex direct MCP inspection uses the confirmed mcp list --json transport contract. Claude Code and Gemini currently have no confirmed machine-readable direct-MCP surface, so only that check is reported as unsupported instead of parsing human output or invented JSON. A matching Codex direct/plugin command and exact pin is a warning; a malformed entry or conflicting command, arguments, package, or pin is a failure. Doctor also checks stdio startup, the exact eight-tool surface, Button documentation, source-backed variant-specific valid Button usage, and rejection of a made-up property. Primitive and headless usage smoke is reported as unsupported until a current source-backed snippet is available.

Check states are pass, warning, failure, unsupported, manual, or blocked. Exit code 0 means all required checks passed (possibly with warnings), 1 means an actionable failure, and 2 is reserved for a supported manual or externally blocked check. Host output, credentials, environment values, unrelated plugins, and unnecessary profile or project paths are not included.

Claude Code, Codex, and GitHub Copilot use their native marketplace commands. Copilot CLI installs are also discovered by VS Code. Gemini and Cursor use a persistent checkout under ~/.primeui/plugin-sources/primeui-plugins. Set PRIMEUI_HOME to relocate this managed checkout.

Cursor install and update copy only plugins/<library> from the verified managed checkout into ~/.cursor/plugins/local/<library>. The install is physical and atomically activated from a sibling staging directory. .primeui-managed.json records the source commit, manifest version, deterministic payload hash, and install time. Update and remove refuse unowned, symlinked, malformed, corrupted, or mismatched destinations; unrelated Cursor plugins and configuration are never changed. Direct Cursor MCP registration inspection remains unsupported because Cursor does not currently expose a confirmed machine-readable surface.

Preview any lifecycle operation without changing assistant state:

pnpm dlx @primeui/cli@rc plugin install --tool claude --library primevue --dry-run
pnpm dlx @primeui/cli@rc plugin install --tool claude --library primevue --dry-run --json

Shared options

• --cwd <dir>: inspect another project directory.
• --json: print machine-readable output.

Plugin options

• --tool <tool>: required; claude, codex, copilot, cursor, or gemini.
• --library <library>: primevue, primeng, or primereact; optional only when one library is detected from --cwd.
• --dry-run: print the exact lifecycle plan without running host commands.

PrimeReact variants do not need a CLI option. The single PrimeReact plugin supports styled, Tailwind, primitive, and headless guidance and selects the relevant path from project context.

License

Licensed under the PrimeUI License - Copyright (c) PrimeTek Informatics