CLI and upgrades

npx rdloom init              # set up rdloom.json, tokens and utils
npx rdloom add <name...>      # copy components (add --install for npm packages)
npx rdloom list               # what's available and installed
npx rdloom diff [--patch]     # your changes vs upstream's, per file
npx rdloom upgrade --dry-run  # what an upgrade would do
npx rdloom upgrade [name...]  # apply it

Components from GitHub

Install from any GitHub repository that publishes an rdloom registry, including private ones. The lock file pins each item to a commit, and upgrade merges new commits into your edits.

npx rdloom add acme/design-system/auth-kit       # default branch
npx rdloom add acme/design-system/auth-kit#v2    # a branch, tag or commit
npx rdloom add @acme/auth-kit                    # with "registries": { "@acme": "acme/design-system" } in rdloom.json

Private repositories work when GH_TOKEN or GITHUB_TOKEN is set, or you're logged in with gh auth login. The token is only sent to api.github.com. To publish your own, list items in rdloom-registry.json and run npx rdloom registry build.

Monorepos

Commands work from any directory: rdloom looks for rdloom.json where you are and then upwards, so a command run deep inside an app still finds it. The lock file and merge bases sit next to that config. Pick one of two layouts:

# One copy per app
npx rdloom init --cwd apps/web

# One shared copy for every app: run at the repo root
npx rdloom init --components-dir packages/ui/src/rdloom --tokens-css packages/ui/src/rdloom.css

The shared layout keeps a single lock file at the root, so one rdloom upgrade updates every app at once. Components import each other with relative paths, so they work unchanged inside a workspace package. Each app imports the tokens CSS once and adds @source for the shared folder so Tailwind scans it.

With other registry clients

Every component is also published in the common registry format, so a registry client can add rdloom components instead of this CLI. Files land in components/rdloom/ under your components alias, the npm packages are installed, and the colour tokens are added to your global CSS, with dark values on the .dark class.

npx shadcn@latest add https://rdloom.vimalbhatt.com/r/data-grid.json

Those clients don't track what they installed, so rdloom diff and rdloom upgrade can't merge later changes into your edits. For upgrades, use npx rdloom add instead.

How upgrades merge

For each file, upgrade compares three versions: as shipped, yours, and the new one. It merges them the way git does.

add never overwrites a file you've edited, new versions only print npm packages you don't have yet, and your line endings are kept.