assets push

Pushes assets and asset metadata from a local directory or uploads single assets (local files or remote URLs) to a Storyblok space.

Usage

storyblok assets push [arguments] [flags]

Arguments

Argument	Type	Description
Asset path	string	Optional. The path to a single local file or remote URL to upload. If not provided, all assets from the local .storyblok/assets/<space-id>/ directory will be pushed.

Flags

Flag	Type	Description
--space	integer	Required. The ID of the Storyblok space to push or upload assets to.
--target	string	Optional. Select the destination: space (the space), shared (the organization’s shared libraries), or auto (route each local asset to its origin — the space plus every writable shared library). Defaults to space for a single asset and auto for a bulk push. A single-asset push accepts only space or shared.
--library	integer	Optional. The ID of the destination shared library. Required when pushing a single asset with --target shared.
--path, -p	string	Optional. Specify a custom path for asset files. Defaults to .storyblok/assets/<space-id>.
--from, -f	integer	Optional. The ID of the source space from which the assets were originally pulled. If not provided, the origin space equals the target space specified via --space.
--dry-run, -d	boolean	Optional. Preview changes without applying them to the Storyblok space.
--short-filename	string	Optional. Override the filename of the uploaded asset.
--folder	string	Optional. The ID of the folder to upload the asset to.
--cleanup	boolean	Optional. Delete local assets and metadata after a successful push.
--update-stories	boolean	Optional. Update stories that reference the uploaded asset.
--data	string	Optional. Provide inline metadata. See the asset object for available options.
--asset-token	string	Optional. Provide an asset token to access private assets. The asset token is needed for comparing the local assets with remote assets that are private.

Examples

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

# Push assets from .storyblok/assets/<space>
storyblok assets push
# Push a single asset
storyblok assets push ./path/to/image.png
# Upload a single remote URL
storyblok assets push https://example.com/assets/image.png
# Upload a single local file
storyblok assets push ./path/to/image.png
# Upload a single local file with inline metadata to a folder and override the filename
storyblok assets push ./path/to/image.png \
  --data='{"meta_data":{"alt":"Hero image"}}' \
  --short-filename="hero.png" \
  --folder=654321
# Update a single existing file and stories referencing it
storyblok assets push ./path/to/image.png --update-stories
# Push a single asset into a shared library the space can write to
storyblok assets push ./path/to/image.png --target shared --library 789

When uploading a single asset (local file or remote URL), the command supports an optional sidecar JSON file (with the same basename) to provide additional metadata, such as alt text and tags. For example, ./path/to/image.png can have a sidecar file ./path/to/image.json with the following content:

{
  "meta_data": {
    "alt": "Hero image",
    "title": "Homepage hero"
  }
}

See the asset object reference for all available metadata options.

Note

When updating a single asset, the filename cannot be changed. Only the actual file and metadata are updated.

Tip

For bulk updates or migrations, it is significantly more performant to run assets push followed by stories push than using asset push for an individual asset and combined with the --update-stories flag. The stories command automatically resolves and updates asset references using the asset manifest file.

Asset manifest

The command creates manifest files to keep track of asset changes and references when pushing assets (stored under .storyblok/assets/<space-id>/manifest.jsonl and .storyblok/assets/<space-id>/folders/manifest.jsonl). Specifically, they map source IDs and filenames to target asset IDs and filenames. This serves the following purposes:

• Idempotency: Prevent duplicate uploads of the same asset when running assets push multiple times, recognizing existing assets and updating them instead.
• Incremental workflows: As the relation between source and target assets is persisted, users can pull, modify, and push single or multiple assets incrementally.
• Migration: Mapping source and target IDs is crucial for space-to-space migrations in Storyblok as well as CMS migrations from third-party systems to Storyblok.

Shared asset libraries

Organizations can maintain shared asset libraries: top-level asset folders that several spaces reuse, each with per-space read or write access. The assets pull and assets push commands work with these libraries through the --target flag.

• Pull shared library assets alongside or instead of the space with --target with-referenced, --target all, or --target shared.
• Push local assets to the libraries the space can write to with --target shared or --target auto (which also pushes the space’s own assets). When pushing a single asset, identify the destination library with --library <library-id>.

The CLI stores shared library assets under .storyblok/assets/shared/<library-id>/, parallel to the space subtree at .storyblok/assets/<space-id>/, each with its own manifest.jsonl and folders/ metadata.

Note

A space can pull from the libraries it can read and push to the libraries it can write to. Pushing to a library the space cannot write to fails with a 403 response.

Tip

For background on shared asset libraries, refer to the Assets developer concept and manual.