Updating

See what changed in the patterns you installed, and update them without losing your edits.

Every item in the registry has a version. When a pattern changes, its version goes up, and the change is recorded as steps you can follow by hand, such as "h-8 → h-9 on Button" or "--radius: 0.625rem → 0.5rem". The steps still apply after you've edited the file.

The lock file

gaudi-ui add and gaudi-ui init write gaudi-lock.json at the project root. It records the version of each item you installed and a hash of every file as it was written. Keep it in git alongside your code, so everyone on the project checks for updates against the same versions.

gaudi-lock.json

{
  "lockVersion": 1,
  "items": {
    "button-default": {
      "version": 2,
      "files": {
        "src/components/button/button-default.tsx": "sha256-9d11…"
      }
    }
  }
}

A file whose hash no longer matches has been edited. The CLI uses this to warn you before an update would overwrite your edits.

Check for updates

npx gaudi-ui@latest outdated
  button-default  1 → 2
  theme           1 → 2  edited

See what changed

npx gaudi-ui@latest changes
button-default 1 → 2
  v2 2026-10-09  Taller default button with a light shadow.
    - components/button/button-default.tsx · Button: h-8 → h-9; add shadow-xs

theme 1 → 2
  v2 2026-10-09  Smaller corner radius.
    - styles/theme.css · :root: --radius: 0.625rem → 0.5rem

Name items to see only those, and add --diff for the line-by-line diff. --from <version> shows changes since any version, even for items you haven't installed.

StepWhat to do
ClassesOn the named element, swap (→), add or remove the listed classes
PropsSet or remove attributes on the named element
CSSAdd, change or remove one declaration in the named block
ElementAn element was added or removed; read the diff
FileChanges the steps above don't describe, such as logic; read the diff
Packages/itemsInstall or remove npm packages, or add the Gaudi UI items it now requires

Update

npx gaudi-ui@latest update

Nothing is replaced without your confirmation. For each outdated item, the CLI shows its changes and asks what to do:

Update theme?
  1. Replace with v2. Your edits to src/styles/theme.css are lost
  2. Show the diff
  3. Skip: I'll apply the changes by hand

If you skip an item, apply its steps yourself or ask your agent, then record the new version:

npx gaudi-ui@latest update --applied theme

Outside a terminal, such as in a script, update only prints the changes. To replace items there, name them and confirm with --yes. Edited items also need --overwrite:

npx gaudi-ui@latest update button-default --yes

With an agent

The MCP server's get_updates tool reads your lock file and returns the same steps as JSON, with the diff when a step needs it. Ask your agent:

  • "Update my Gaudi UI patterns, keeping my changes."
  • "What changed in Gaudi UI's button since I installed it?"

The JSON is also available without the server: gaudi-ui changes --json, or /r/changes/<name>.json in the registry.