---
title: assets push
description: Pushes assets and asset metadata from a local directory or uploads single assets (local files or remote URLs) to a Storyblok space.
url: https://www.storyblok.com/docs/tooling/cli/assets-push
---

# 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

```bash
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](#shared-asset-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](/docs/api/management/assets/the-asset-object) for available options. |
| `--asset-token` | string | _Optional._ Provide an asset token to access [private assets](/docs/concepts/assets#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.

```bash
# 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:

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

See the [asset object reference](/docs/api/management/assets/the-asset-object) 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](/docs/concepts/assets#shared-asset-libraries) and [manual](/docs/manuals/assets#shared-asset-libraries).

## Pagination

-   [Previous: assets pull](/docs/tooling/cli/assets-pull)
-   [Next: components pull](/docs/tooling/cli/components-pull)