Publish and checkout

Send catalog items, pages, tokens, and assets to a registry, and write registry content back into a workspace.

Publish

Terminal

npm run publish -- all

all publishes every kind in dependency order. To publish one kind:

Terminal

npm run publish -- catalog
npm run publish -- pages
npm run publish -- tokens
npm run publish -- assets

Add ids to publish only those entities: catalog item ids, page ids, token set ids, or asset collections.

Terminal

npm run publish -- catalog button card
npm run publish -- tokens foundation/colors

catalog covers components and patterns. Each declaration decides how the registry stores it.
publish builds first, using the build cache.
tokens and assets run the Figma pipeline first, so the Figma credentials must be available.
publish does not run while two catalog items share an id.
After a publish, reload the registry to see the change.

Option	Effect
`--dry-run`	Lists what a real publish would upload. Connects to no registry, so it needs no URL or token. The build still runs.
`--no-build`	Publishes the existing build output without building first
`-f, --force`	Re-uploads entities whose content is unchanged on the registry, which are skipped by default

Together, --dry-run --no-build leaves the workspace unchanged.

The transfer is content-addressed: publish asks the registry which blobs it already has and sends only the rest.

Since 2.1.0, publish uploads artifacts above 4.5 MB as blobs first, so large components and patterns publish. A registry older than 2.1.0 still stops at 4.5 MB.
Against an older registry, publish stops before the upload when a package is too large and names the largest files.
Asset blobs follow the asset storage upload paths.

checkout writes registry content into the workspace. It takes the same kinds and ids:

Terminal

npm run checkout -- all
npm run checkout -- catalog button
npm run checkout -- all --dry-run

--dry-run reads from the registry and lists the files a real checkout would create or overwrite. It writes nothing.
Overwriting an existing local file needs --force or a confirmation in the terminal.
Catalog items return to the directory they were published from. Before writing outside catalog.include, checkout asks.
Declarations are written in runtime.workspace.declarationFormat: ts (default), js, or cjs.
Previews keep their export order.

The push and pull commands still run, with a deprecation warning. Switch to the new commands.

They also accept components and patterns as the type, and accept options for features Handoff does not have, with a warning for each.