CLI & source ownership

Source ownership means BeeUI component source lives in your repository: you read it, edit it, review its diffs, and decide when to take upstream changes. The public CLI is @beemvp/beeui-cli; see the release status above for the current release candidate.

Prerequisites: a Node.js project with npx/pnpm dlx available, and @beemvp/beeui-core installed for the copied imports to resolve against (see Start).

Run the public RC CLI

npx @beemvp/beeui-cli@next --help
npx @beemvp/beeui-cli@next init
npx @beemvp/beeui-cli@next list
npx @beemvp/beeui-cli@next add --dry-run button
npx @beemvp/beeui-cli@next add button
npx @beemvp/beeui-cli@next doctor
npx @beemvp/beeui-cli@next diff
npx @beemvp/beeui-cli@next update

Pin @0.86.2-rc.3 instead of @next when you need an immutable CLI version in automation.

The CLI resolves the project from the current working directory, so run it from the consumer project you want it to modify.

Command contract

Command	Behavior
help	Print usage text.
version	Print the CLI package name and version.
init	Create the config file without overwriting an existing one.
list	List supported public Registry items in stable order.
add <items...>	Preflight and copy source plus transitive BeeUI dependencies.
doctor	Validate Registry integrity and the local source-ownership state.
verify	Alias for doctor.
diff [items...]	Compare previously added source against the bundled Registry; never mutates.
update [items...]	Re-sync previously added files whose upstream source changed.

Option	Applies to	Behavior
--all	add	Add the complete stable Registry surface.
--dry-run	add, update	Print the deterministic plan without filesystem mutation.
--overwrite	add	Explicitly replace differing destination files after preflight.
--force	update	Overwrite files where both local and upstream changed, discarding the local edit.

Exit code 0 means success; usage, validation and runtime errors exit 1 with the reason on stderr.

Source ownership versus package consumption

	Package boundary	Source ownership
What lands in your repo	Dependency declarations	Actual component/theme source files
Who edits component implementation	Upstream BeeUI package	Your project
Upgrade	Bump package version/tag	Review diff, then update deliberately
Version identity	npm package version	Per-file content digest + bundled Registry version
Public RC today	@beemvp/beeui-*@next	npx @beemvp/beeui-cli@next …

The models are not mutually exclusive: a project can consume BeeUI packages centrally while owning a small number of customized components.

Registry behavior

• Requested items are normalized and dependency closure is resolved deterministically.
• Registry metadata is JSON, not executable code.
• Every copied file is checked against the bundled Registry and expected digest.
• add preflights the full operation before writing.
• diff is read-only.
• update refuses destructive overwrite unless the appropriate explicit option is present.
• Source ownership changes file ownership, not BeeUI’s accessibility/token/behavior contracts.

Repository-local maintainer mode

When developing BeeUI itself, maintainers can still run the workspace CLI from the BeeUI checkout:

pnpm beeui list
pnpm beeui add --dry-run button
pnpm beeui doctor
pnpm beeui diff
pnpm beeui update

That repository-local path is a maintainer/development convenience. External consumers should use the published CLI RC.

Release channel

The current release candidate is a prerelease published under next — see the release status above. During the 0.86.2 prerelease line latest follows the newest complete, verified RC only after the owner moves it for all four packages, so it can lag next; the last observed latest target is recorded in docs/dist-tag-policy.md. Documentation and automation must therefore keep using @next or the exact RC version.

See the repository authority docs/dist-tag-policy.md for channel rules and docs/registry-cli.md for the full Registry/source-ownership contract.