components pull

Fetches component schemas, component groups, component presets, and component tags from a Storyblok space and saves them to a local directory.

The command saves to the following folder structure and recursively creates it if it doesn’t exist yet.

.storyblok/
└── components/
    └── <space-id>/
        ├── components.json
        ├── groups.json
        ├── presets.json
        └── tags.json

Usage

storyblok components [arguments] [flags]

Arguments

Argument	Type	Description
Component name	string	Optional. The technical name of a single component to pull. If not provided, all components will be pulled.

Flags

Flag	Type	Description
--space	integer	Required. The ID of the Storyblok space to pull components from.
--filter, -fi	string	Optional. Glob pattern to select components by name (for example, hero* matches all components whose name starts with hero).
--group, -gr	string	Optional. Select components assigned to a component group, by name (for example, Checkout) or by a slash-separated path of nested group names (for example, Checkout/Payment) to disambiguate. Repeatable; includes descendant groups.
--tag, -tg	string	Optional. Select components carrying a tag. Repeatable and comma-separated.
--filename, -f	string	Optional. Specify a custom filename. Defaults to components.json. Ignored when --separate-files is used.
--separate-files, -sf	boolean	Optional. Save each component and each preset to a separate file.
--suffix, -su	string	Optional. Specify a custom suffix for component files.
--path, -p	string	Optional. Specify a custom path for component files. Defaults to .storyblok/components/<space-id>.

Selective pull

Use --filter, --group, and --tag to pull a subset of a space’s components instead of all of them. This is useful when several teams share a single space and each team only wants to sync the components it owns.

Multiple values for the same selector combine with OR (a component matches if it satisfies any of them), while different selectors combine with AND (a component must match every selector you provide). For example, --group Checkout --tag beta selects components that are in the Checkout group tree and carry the beta tag, while --tag a --tag b selects components carrying either tag.

A selective pull always includes each matched component’s dependencies: its assigned groups (with their ancestor groups), its assigned tags, its presets, and any groups or tags referenced by its own field whitelists. Sibling components referenced through a component whitelist are not pulled in, because that reference is name-based and resolves on its own once the referenced component exists in the target space.

Examples

The following examples assume that a space has been defined in a configuration file.

# Pull all components from a space
storyblok components pull
# Pull a single component from a space
storyblok components pull hero-section
# Pull all components from a space, saving each to a separate file with a custom suffix
storyblok components pull --separate-files --suffix dev
# Pull all components from a space, saving with a custom filename
storyblok components pull --filename my-components
# Pull only components whose name matches a glob
storyblok components pull --filter "checkout-*"
# Pull only components in the Checkout group (and its nested groups)
storyblok components pull --group Checkout
# Disambiguate a nested group by its path
storyblok components pull --group "Checkout/Payment"
# Pull only components carrying the beta tag
storyblok components pull --tag beta
# Combine selectors: components in the Checkout group tree that also carry the beta tag
storyblok components pull --group Checkout --tag beta