---
title: Storyblok CLI
description: The Storyblok CLI enables developers to manage spaces via the Management API with tools for migrations, components, and schema type generation.
url: https://storyblok.com/docs/libraries/storyblok-cli
---

# Storyblok CLI

The `storyblok` CLI scaffolds Storyblok projects and facilitates Management API requests, such as pushing and pulling content and schemas.

Run `storyblok --help` to see available commands.

## Requirements

-   **Node.js** LTS (version 22.x or higher is recommended)

## Installation

```bash
# Global installation
npm install -g storyblok@latest
# Local installation (per project)
npm install -D storyblok@latest
```

## Configuration

The CLI can be configured via configuration files, setting default values within a given context. This avoids having to pass the same flags repeatedly for every command.

> [!TIP]
> Using a configuration file is _optional_, and the CLI will fall back to built-in defaults for all settings if no configuration file is found. However, using a configuration file is recommended for a better experience and to unlock the full potential of the CLI.

### Quick start

1.  Create a `storyblok.config.ts` file in the project root.
    
2.  Export a configuration object using `defineConfig` and apply the desired settings. For example:
    
    ```js
    import { defineConfig } from "storyblok/config";
    
    export default defineConfig({
      space: "123456",
    });
    ```
    
3.  Run any command, and the CLI will automatically apply the detected configuration settings. For example, the following command will automatically pull components from the space with the ID `123456`:
    
    ```bash
    storyblok components pull
    ```
    

### File locations and layers

A configuration file must adhere to the naming convention `{storyblok.}config.{ext}`. Supported file extensions are `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`, `.json`, .`json5`, `.jsonc`, `.yaml`, `.yml`, `.toml`.

#### Configuration layers

The CLI uses a layered configuration system that merges multiple config files, with more specific locations overriding more general ones. This allows for flexible configuration at different levels, such as globally for all projects, per workspace, or per individual project.

The CLI detects and merges configuration files at different levels. The resolution order is as follows:

1.  Home directory: `~/.storyblok/config.*`
2.  Workspace: `<workspace>/.storyblok/config.*`
3.  Project root: `<project>/storyblok.config.*`

Note that configuration files placed inside a `.storyblok` folder should be named `config.*`, while configuration files placed in other locations (e.g., project root) should be named `storyblok.config.*` to be detected by the CLI.

Settings from all layers are merged, allowing for a combination of settings across layers. Conflicting settings are resolved based on the precedence rules outlined below.

#### Precedence rules

Values from higher layers override lower layers:

```plaintext
flags > project > workspace > home directory > built-in defaults
```

### Complete example

storyblok.config.ts

```js
// storyblok.config.ts
import { defineConfig } from "storyblok/config";

export default defineConfig({
  // General settings
  region: "eu", // Storyblok region: 'eu', 'us', 'ap', 'ca', 'cn'
  verbose: false, // Enable verbose output

  space: "123456", // Default space ID for commands that require it
  path: ".storyblok", // Base directory

  // UI configuration
  ui: {
    enabled: true, // Enable UI output
  },

  // API configuration
  api: {
    maxRetries: 3, // Maximum retry attempts for failed requests
    maxConcurrency: 6, // Maximum concurrent API requests
  },

  // Logging configuration
  log: {
    console: {
      enabled: false, // Enable console logging
      level: "info", // Log level: 'info', 'warn', 'error', 'debug'
    },
    file: {
      enabled: true, // Enable file logging
      level: "info", // File log level
      maxFiles: 10, // Maximum log files to keep
    },
  },

  // Report configuration
  report: {
    enabled: true, // Enable report generation
    maxFiles: 10, // Maximum report files to keep
  },

  // Module-specific configuration
  modules: {
    components: {
      pull: {
        separateFiles: false, // Separate output per component
        filename: "components", // Filename for exports
      },
      push: {
        dryRun: false, // Preview changes without pushing
      },
    },
    datasources: {
      pull: {
        separateFiles: false,
      },
      push: {
        dryRun: false,
      },
    },
    migrations: {
      run: {
        dryRun: false,
      },
    },
    types: {
      generate: {
        output: "storyblok-component-types.d.ts",
      },
    },
  },
});
```

### Environment variables

Any configuration file runs in Node, and the CLI loads environment variables via `dotenv`. Access environment variables using `process.env` as follows.

Example config using environment variables

```js
export default defineConfig({
  region: process.env.STORYBLOK_REGION ?? "eu",
  space: process.env.STORYBLOK_SPACE_ID,
  api: {
    maxRetries: Number(process.env.STORYBLOK_MAX_RETRIES ?? 5),
  },
});
```

## Global options

| Flag | Config | Type | Description |
| --- | --- | --- | --- |
| `--api-max-concurrency` | `api.maxConcurrency` | integer | Maximum number of concurrent API requests. |
| `--api-max-retries` | `api.maxRetries` | integer | Maximum number of retry attempts for failed HTTP requests. |
| `--log-console-enabled`, `--no-log-console-enabled` | `log.console.enabled` | boolean | Enable or disable logging output to the console. |
| `--log-console-level` | `log.console.level` | string | Minimum log level for console output (`info`, `warn`, `error`). Defaults to `info`. |
| `--log-file-enabled`, `--no-log-file-enabled` | `log.file.enabled` | boolean | Enable or disable log generation. |
| `--log-file-level` | `log.file.level` | string | Minimum log level for file-based logs (`info`, `warn`, `error`). Defaults to `info`. |
| `--log-file-max-files` | `log.file.maxFiles` | integer | Maximum number of log files retained on disk. |
| `--path` | `path` | string | The path to use for any local operations. |
| `--region` | `region` | string | The region to use for API requests. |
| `--report-enabled`, `--no-report-enabled` | `report.enabled` | boolean | Enable or disable report generation. |
| `--report-max-files` | `report.maxFiles` | integer | Maximum number of report files retained on disk. |
| `--space` | `space` | integer | The space ID to use. |
| `--ui-enabled`, `--no-ui-enabled` | `ui.enabled` | boolean | Enable or disable interactive UI output. |
| `--verbose` | `verbose` | boolean | Enable verbose output for additional diagnostic information. |

## Commands

### `assets pull`

Downloads assets, asset metadata, and asset folders 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.

```bash
.storyblok/
└── assets/
    └── <space-id>/
        ├── <asset>.jpg
        └── manifest.jsonl
        └── folders/
            ├── <folder>.json
            └── manifest.jsonl
```

#### Usage

```bash
storyblok assets pull [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` `-s` | integer | _Required._ The ID of the Storyblok space to pull assets from. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for asset files. Defaults to `.storyblok/assets/<space-id>`. |
| `--asset-token` | string | _Optional._ Provide an asset token to access [private assets](/docs/concepts/assets#private-assets). |
| `--query`, `-q` | string | _Optional._ Filter assets using [query parameters](/docs/api/management/assets/retrieve-multiple-assets#query-parameters). |
| `--dry-run`, `-d` | boolean | _Optional._ Preview changes without applying them to the local directory. |

#### Examples

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

```bash
# Pull all assets from a space
storyblok assets pull
# Pull all assets from a space using an asset token to access private assets
storyblok assets pull --asset-token ASSET_TOKEN
# Pull all assets from a space, filtering by query and previewing changes without applying them
storyblok assets pull --query "search=my-file.jpg&with_tags=tag1,tag2"
```

### `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. |
| `--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
```

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.

### `components pull`

Fetches components schemas, component groups, component presents, 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.

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

#### Usage

```bash
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. |
| `--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>`. |

#### Examples

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

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

### `components push`

Pushes components schemas, component groups, component presents, and component tags, component whitelists, and datasources (excluding datasource entries) from a local directory to a Storyblok space.

#### Prerequisites

-   The command expects schemas that have previously been pulled from a space using `components pull`.
-   For components with fields that depend on datasources, first pull the datasources from the origin space and push them to the target space using `datasources pull` and `datasources push`.
-   Any flags used with `components pull` prior (such as `--suffix` or `--separate-files`) need to be applied with the same values when pushing to ensure the files are found correctly.

#### Usage

```bash
storyblok components push [arguments] [flags]
```

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Component name | string | _Optional._ The technical name of a single component to push. If not provided, all components will be pushed. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to push components to. |
| `--from`, `-f` | integer | _Optional._ The ID of the source space from which the components were originally pulled. If not provided, the origin space equals the target space specified via `--space`. |
| `--filter`, `-fi` | string | _Optional._ Glob pattern to filter components by their name (e.g., `hero*` will match all components starting with `hero`). |
| `--separate-files`, `-sf` | boolean | _Optional._ Read components from individual files, rather than a consolidated `components.json` 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>`. |

> [!TIP]
> To sync components between spaces, `pull` them from the origin space and then `push` them with `--space` set to the target space and `--from` set to the origin space.

#### Examples

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

```bash
# Push all components to a space
storyblok components push --from 654321
# Push a single component to a space
storyblok components push hero-section --from 654321
# Push all components to a space, reading each from a separate file with a custom suffix
storyblok components push --from 654321 --separate-files --suffix dev
# Push all components to a space, filtering by component name
storyblok components push --filter "hero-*"
```

### `create`

Scaffolds a new project using Storyblok with your preferred technology. Automatically generates the project structure, creates a Storyblok space, configures environment variables, integrates the project with Storyblok, and opens the new space in the browser.

If your account is associated with multiple [organizations](/docs/manuals/organizations), you will be prompted to select the target organization for the new space.

#### Prerequisites

-   Write access to the target directory
-   Space creation permissions in your Storyblok account

#### Usage

```bash
storyblok create [arguments] [flags]
```

> [!TIP]
> Run the command without any arguments or flags to start an interactive setup process.

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Project path | string | _Optional._ Specify a custom path for the project. If not provided, the current working directory is used. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--template` | string | _Optional._ Select a template in your preferred technology. Possible values are `react`, `vue`, `svelte`, `astro`, `nuxt`, `next`, `eleventy`. Supported templates correspond to all [core blueprints](/docs/concepts/blueprints#core-blueprints). |
| `--skip-space` | boolean | _Optional._ Skip the creation of a new space. Defaults to `false`. If no `--token` is provided, none will be added to the `.env` file. |
| `--token` | string | _Optional._ Specify the preview access token of an existing space. To be used in conjunction with the `--skip-space` flag. |

> [!TIP]
> To learn more about project configuration and development, see the Storyblok [technology guides](/docs/guides).

#### Examples

```bash
# Interactive project creation
storyblok create
# Create a Next.js project in the specified path and skip space creation
storyblok create ./my-nextjs-project --template nextjs --skip-space
# Create an Astro project in the specified path, skip space creation, and use the preview access token of an existing space
storyblok create ./my-astro-project --template astro --skip-space --token EXAMPLE_TOKEN
```

### `datasources delete`

Deletes a datasource from a Storyblok space by name or ID. Asks for confirmation before deleting.

#### Usage

```bash
storyblok datasources delete [arguments] [flags]
```

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Datasource name | string | _Required._ The name of a single datasource to delete. Note that the actual name (including upper/lower case) is used, as opposed to the slug. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to delete the datasource from. |
| `--id` | integer | _Optional._ The ID of the Storyblok datasource to delete. If provided, the datasource ID takes priority over the datasource name. |

#### Examples

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

```bash
# Delete a datasource by name
storyblok datasources delete colors
# Delete a datasource by ID
storyblok datasources delete --id 140731465546051
```

### `datasources pull`

Downloads datasources and their entries from a Storyblok space, recursively creates a folder structure if it doesn’t exist, 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.

```plaintext
.storyblok/
└── datasources/
    └── <space-id>/
        ├── <datasource-name>.json
```

#### Usage

```bash
storyblok datasources pull [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to pull datasources from. |
| `--filename`, `-f` | string | _Optional._ Specify a custom filename. Defaults to `datasources.json`. Ignored when `--separate-files` is used. |
| `--separate-files`, `-sf` | boolean | _Optional._ Save each datasource to a separate file. |
| `--suffix`, `-su` | string | _Optional._ Specify a custom suffix for datasource files. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for datasource files. Defaults to `.storyblok/datasources/<space-id>`. |

#### Examples

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

```bash
# Pull all datasources from a space
storyblok datasources pull
# Pull all datasources from a space, saving each to a separate file with a custom suffix
storyblok datasources pull --separate-files --suffix dev
# Pull all datasources from a space, saving with a custom filename
storyblok datasources pull --filename my-datasources
```

### `datasources push`

Uploads datasources and their entries from a local directory to a Storyblok space. The command will create new datasources and entries or update existing ones based on name matching.

#### Prerequisites

-   The command expects datasources that have previously been pulled from a space using `datasources pull`.
-   Any flags used with `datasources pull` prior (such as `--suffix` or `--separate-files`) need to be applied with the same values when pushing to ensure the files are found correctly.

#### Usage

```bash
storyblok datasources push [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to push datasources to. |
| `--from`, `-f` | integer | _Optional._ The ID of the source space from which the datasources were originally pulled. If not provided, the origin space equals the target space specified via `--space`. |
| `--filter`, `-fi` | string | _Optional._ Glob pattern to filter datasources by their name (e.g., `colors*` will match all datasources starting with `colors`). |
| `--separate-files`, `-sf` | boolean | _Optional._ Read datasources from individual files, rather than a consolidated `datasources.json` file. |
| `--suffix`, `-su` | string | _Optional._ Specify a custom suffix for datasource files. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for datasource files. Defaults to `.storyblok/datasources/<space-id>`. |

> [!TIP]
> To sync datasources between spaces, `pull` them from the origin space and then `push` them with `--space` set to the target space and `--from` set to the origin space.

#### Examples

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

```bash
# Push all datasources to a space
storyblok datasources push --from 654321
# Push all datasources to a space, reading each from a separate file with a custom suffix
storyblok datasources push --from 654321 --separate-files --suffix dev
# Push all datasources to a space, filtering by datasource name
storyblok datasources push --filter "colors-*"
```

### `languages pull`

Downloads the list of used languages from a Storyblok space, recursively creates a folder structure, and saves the data to a local directory. The list includes the default language and the language code, display name, and AI translation code for each language.

#### Usage

```bash
storyblok languages pull [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to pull languages from. |
| `--filename`, `-f` | string | _Optional._ Specify a custom filename. Defaults to `languages.json`. |
| `--suffix`, `-su` | string | _Optional._ Specify a custom suffix for language files. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for language files. Defaults to `.storyblok/languages/<space-id>`. |

#### Examples

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

```bash
# Pull languages from a space
storyblok languages pull
# Pull languages from a space, saving with a custom filename
storyblok languages pull --filename my-languages
```

### `login`

Authenticates a Storyblok user by email and password (supporting two-factor authentication) or [personal access token](/docs/concepts/access-tokens#personal-access-token) and stores their credentials in `~/.storyblok/credentials.json`. Using a personal access token is _recommended_ for CI/CD environments and _required_ for accounts using SSO.

#### Usage

```bash
storyblok login
```

> [!TIP]
> Run the command without any arguments or flags to start an interactive login process.

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--token` | string | _Optional._ A [personal access token](/docs/concepts/access-tokens#personal-access-token). |
| `--region` | string | _Optional._ The region of the Storyblok space. Possible values are ‘eu’, ‘us’, ‘ca’, ‘au’, and ‘cn’. Must match the space region. Once logged in, the same region setting is used for all subsequent CLI commands. |

### `logout`

Securely removes stored credentials and clear the current session to deauthenticate the logged-in Storyblok user.

#### Usage

```bash
storyblok logout
```

### `logs list`

Lists all logs for CLI operations performed per Storyblok space. Logs are stored locally under `.storyblok/logs/<space-id>/` (or at the location specified in the `--path` flag of a command that is logged) and include details such as the command executed, timestamp, and basic metadata.

To disable logging, use the `--no-log-file-enabled` flag when running the command, or change the global CLI configuration.

#### Usage

```bash
storyblok logs list [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to list logs for. |

### `logs prune`

Deletes old logs for CLI operations performed per Storyblok space.

#### Usage

```bash
storyblok logs prune [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to list logs for. |
| `--keep` | integer | _Optional._ The number of most recent logs to keep. If not specified, all logs are deleted. |

### `migrations generate`

Creates migration files for specific components of a Storyblok space. Migrations are useful for making changes to existing stories in a Storyblok space, such as updating component structures or content.

> [!NOTE]
> A “migration” is a change to the content in a space matching a change to the underlying schema. For example, if the name of the `title` field changes to `headline`, a migration would reassign all the content of the `title` field to the new `headline` field. This is different from a [CMS migration](/docs/concepts/cms-migration).

The command will recursively generate a folder structure and migration file for the specified component:

```plaintext
.storyblok/
└── migrations/
    └── <space-id>/
        └── <component-name>[.<suffix>].js
```

The generated migration file contains a template function with examples for common transformations. The function receives a `block` parameter that contains the components data. The function should return the updated block.

#### Usage

```bash
storyblok migrations generate <component-name> --space <source-space-id> [--suffix <suffix>]
```

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Component name | string | _Required._ The technical name of a single component to generate a migration for. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space that contains the component to generate a migration for. |
| `--path` | string | _Optional._ Specify a custom path for migration files. Defaults to `.storyblok/migrations/<space-id>`. |
| `--suffix` | string | _Optional._ Specify a custom suffix for migration files. |

#### Examples

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

```bash
# Generate a migration for the "hero-section" component in the specified space
storyblok migrations generate hero-section
# Generate a migration for the "hero-section" component in the specified space, saving with a custom suffix
storyblok migrations generate hero-section --suffix dev
```

### `migrations rollback`

Reverts a previous migration that was executed with `migrations run`, restoring affected stories in a Storyblok space based on a snapshot saved by `migrations run`.

#### Prerequisites

-   A snapshot file generated by `migrations run` is required to perform the rollback.

#### Usage

```bash
storyblok migrations rollback [arguments] [flags]
```

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Snapshot file | string | _Required._ The full name of the snapshot file generated by `migrations run`. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to perform the rollback for. |
| `--path` | string | _Optional._ Specify a custom path for snapshot files. Defaults to `.storyblok/migrations/<space-id>`. |

#### Examples

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

```bash
# Rollback a migration in the specified space
storyblok migrations rollback hero-section.1770129788914.js
```

### `migrations run`

Executes migration files for specific components in a Storyblok space, updating stories that use those components based on the defined migrations. Generates a component-specific snapshot of the space before applying the migrations to allow for rollback if needed.

#### Prerequisites

-   Migration files generated by `migrations generate` and updated with the desired changes must be present in the expected directory.

#### Usage

```bash
storyblok migrations run [arguments] [flags]
```

#### Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Component name | string | _Optional._ The technical name of a single component to run the migration for. If omitted, all migrations found in the specified path are run in the space. |

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space`, `-s` | integer | _Required._ The ID of the Storyblok space to run migrations for. |
| `--filter`, `-fi` | string | _Optional._ Glob pattern to filter stories by their component name (e.g., `hero*` will match all stories starting with `hero`). |
| `--dry-run`, `-d` | boolean | _Optional._ Preview changes without applying them. |
| `--query`, `-q` | string | _Optional._ Filter stories using [query parameters](/docs/api/management/stories/retrieve-multiple-stories#query-parameters). |
| `--starts-with`, `-sw` | string | _Optional._ A path prefix to filter stories to migrate. |
| `--publish` | string | _Optional._ Specify a publication mode: `all` (publish all stories), `published` (only publish stories that were already published), or `published-with-changes` (only publish stories that have unpublished changes). |
| `--path`, `-p` | string | _Optional._ Specify a custom path for migration files. Defaults to `.storyblok/migrations/<space-id>`. |

#### Examples

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

```bash
# Run migration for the "hero-section" component in the specified space
storyblok migrations run hero-section
# Run all migrations in the specified space, filtering by component name and previewing changes without applying them
storyblok migrations run --filter "hero-*" --dry-run
# Run all migrations in the specified space, filtering by query and publishing stories that were already published
storyblok migrations run --publish published --query "[highlighted][in]=true"
```

### `reports list`

Lists reports logs for CLI operations performed per Storyblok space. Logs are stored locally under `.storyblok/logs/<space-id>/` (or at the location specified in the `--path` flag of a command that is logged) and include details such as the command executed, timestamp, and detailed metadata (such as the applied configuration and aggregated results).

To disable reports, use the `--no-report-enabled` flag when running the command, or change the global CLI configuration.

#### Usage

```bash
storyblok reports list [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to list reports for. |

### `reports prune`

Deletes old reports for CLI operations performed per Storyblok space.

#### Usage

```bash
storyblok reports prune [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to list reports for. |
| `--keep` | integer | _Optional._ The number of most recent reports to keep. If not specified, all reports are deleted. |

### `signup`

Opens the Storyblok signup page in the browser. After signing up, run `login` to authenticate.

##### Usage

```bash
storyblok signup
```

### `stories pull`

Downloads stories 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. All stories are saved as individual JSON files (`{slug}_{UUID}.json`).

```bash
.storyblok/
└── stories/
    └── <space-id>/
        └── <story>.json
```

#### Usage

```bash
storyblok stories pull [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` `-s` | integer | _Required._ The ID of the Storyblok space to pull stories from. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for story files. Defaults to `.storyblok/stories/<space-id>`. |
| `--query`, `-q` | string | _Optional._ Filter stories using [query parameters](/docs/api/management/stories/retrieve-multiple-stories#query-parameters). |
| `--dry-run`, `-d` | boolean | _Optional._ Preview changes without applying them to the local directory. |
| `--starts-with`, `-sw` | string | _Optional._ A path prefix to filter stories to pull. |

#### Examples

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

```bash
# Pull stories from a space
storyblok stories pull
# Pull stories from a space, filtering by query and previewing changes without applying them to the local directory
storyblok stories pull --query "[highlighted][in]=true" --dry-run
# Pull stories from a space, filtering by path prefix
storyblok stories pull --starts-with "blog/"
```

### `stories push`

Pushes stories from a local directory to a Storyblok space.

#### Prerequisites

-   The command expects stories that have previously been pulled from a space using `stories pull`.
-   Run `components pull` to keep component schemas up-to-date, allowing for references to be resolved correctly.

#### Usage

```bash
storyblok stories push [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` `-s` | integer | _Required._ The ID of the Storyblok space to push stories to. |
| `--from`, `-f` | integer | _Optional._ The ID of the source space from which the stories were originally pulled. If not provided, the origin space equals the target space specified via `--space`. |
| `--path`, `-p` | string | _Optional._ Specify a custom path for story files. Defaults to `.storyblok/stories/<space-id>`. |
| `--dry-run`, `-d` | boolean | _Optional._ Preview changes without applying them to Storyblok. |
| `--cleanup` | boolean | _Optional._ Delete local stories after a successful push. |
| `--publish` | boolean | _Optional._ Publish stories after a successful push. |

#### Examples

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

```bash
# Push stories to a space
storyblok stories push
# Push stories to a space previewing changes without applying them to Storyblok
storyblok stories push --dry-run
```

#### Story manifest

The command creates a manifest file to keep track of story changes and references when pushing stories (stored under `.storyblok/stories/<space-id>/manifest.jsonl`). Specifically, it maps source IDs and filenames to target asset IDs and filenames. This serves the following purposes:

-   Idempotency: Prevent duplicate uploads of the same story when running `stories push` multiple times, recognizing existing stories and updating them instead.
-   Incremental workflows: As the relation between source and target stories is persisted, users can pull, modify, and push single or multiple stories 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.

### `types generate`

Generates TypeScript type definitions (`.d.ts` files) for Storyblok components that have been generated with the `components pull` command. `types generate` must include any flags used when running `components pull` to ensure components are matched correctly.

By default, the command generates two files:

-   `.storyblok/types/storyblok.d.ts`: Base Storyblok types
-   `.storyblok/types/<space-id>/storyblok-component.d.ts`: Space-specific component types

The command also creates types for any datasources that are referenced in the components’ schemas.

#### Prerequisites

-   The command relies on the presence of component files generated by `components pull` to create accurate type definitions.

#### Usage

```bash
types generate [flags]
```

#### Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space` | integer | _Required._ The ID of the Storyblok space to generate types for. |
| `--strict` | boolean | _Optional._ Enable strict mode for type generation, creating types that are more precise. |
| `--type-prefix` | string | _Optional._ Prepend a prefix to the generated types. |
| `--filename` | string | _Optional._ Specify a custom filename. Defaults to `storyblok-components.d.ts`. Ignored when `--separate-files` is used. |
| `--separate-files`, `-sf` | boolean | _Optional._ Save component type definitions as separate file, plus a `datasource-types.d.ts` containing all datasource type definitions as well as a `content-types.d.ts` containing all content type type definitions. |
| `--suffix` | string | _Optional._ Specify a custom suffix for type definition files. |
| `--path` | string | _Optional._ Specify a custom path for type definitions. Defaults to `.storyblok/types/<space-id>`. |
| `--compiler-options` | string | _Optional._ Specify a path to compiler options from `json-schema-to-typescript`. |
| `--custom-fields-parser` | string | _Optional._ Specify a path to a parser for custom field types. |

#### Examples

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

```bash
# Generate types for all components from a space
storyblok types generate
# Generate types for all components from a space with strict mode enabled
storyblok types generate --strict
# Generate types for all components from a space, reading each from a separate file with a custom suffix
storyblok types generate --separate-files --suffix dev
# Generate types for all components from a space, saving with a custom filename
storyblok types generate --filename my-types
```

### `user`

Checks if a user is currently logged in and, if so, displays information about the authenticated Storyblok account, including the friendly name, email address, and active region.

#### Usage

```bash
storyblok user
```

## Pagination

-   [Previous: Introduction](/docs/libraries)
-   [Next: Universal API Client](/docs/libraries/js/universal-api-client)