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

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

   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:

   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:

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

Complete example

storyblok.config.ts

// 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

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.

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

Usage

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.
--query, -q	string	Optional. Filter assets using 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.

# 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

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 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

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.

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.

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

# 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

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.

# 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, 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

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

Examples

# 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

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.

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

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

Usage

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.

# 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

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.

# 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

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.

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

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

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

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

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.

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

.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

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.

# 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

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.

# 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

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

# 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

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

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

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).

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

Usage

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

# 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

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.

# 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

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.

# 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

storyblok user