Distribution

These commands matter once your design system and your applications live in separate repos — or whenever you need to snapshot a contract and move it somewhere else.

Mental model

Sources are recorded in .specui-sources.yml at the project root, so update knows where things came from.

load — install a full SpecUI

cd my-app
npx specui load git+https://github.com/org/acme-ds.git --as acme
npx specui validate .specui --strict

Also supports:

• Local directory: specui load ../acme-ds --as acme
• npm package (packed SpecUI layout): specui load @scope/acme-ds --as acme

--force overwrites an existing .specui/.

link — symlink for development

When you're editing the design system and the app at the same time, copying gets tedious. Symlink instead:

npx specui link ../acme-ds --as acme
# edit files in ../acme-ds
cd my-app && npx specui update --name acme

And unlink when done:

npx specui unlink --name acme

push / pull — flat design-system repo

From a flat repo (SPEC.md at root, created with specui new):

npx specui push --remote origin --msg "chore: token updates"
npx specui pull --remote origin

push may git init if needed; it requires a configured remote or --remote-url.

import / export archive

Export a tarball:

npx specui export --format tarball --to ./acme-specui.tgz --from .specui

Import into an app:

npx specui import ./acme-specui.tgz --force

Export a directory tree (no compression):

npx specui export --format dir --to ./snapshot --from .specui

Interop formats (Tailwind, CSS, …) are covered in Interop.

update — refresh a consumed source

npx specui list sources
npx specui update --name acme
npx specui update --name acme --strict

Re-copies from the git or directory source, shows the token diff, and runs validate. Exits 1 if validate fails.

diff — token comparison

npx specui diff --from ./design-system --to ./my-app/.specui
npx specui diff --from ./v1 --to ./v2 --json

Useful before and after DS upgrades or fork merges — you'll know exactly which tokens changed before anything lands.

list sources

npx specui list sources

Shows installed and linked sources from .specui-sources.yml.

Choosing load vs get

See Registries.

Next steps

• Scenarios — flat repo
• Interop — export formats
• CLI reference