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

npm install -g storyblok@latest

Options

Check the command definition to see which options the command accepts.

For some options, the effect of the option depends on whether the command pulls data to the local machine or pushes data to Storyblok. For example, in pull commands, --space refers to the origin space, while in push commands it refers to the target space.

Caution

When uploading schemas or content (with push and migrations commands), the command must include all flags present when pulling to ensure the CLI correctly identifies the files.

--compiler-options <options>

Path to compiler options from json-schema-to-typescript.

--custom-fields-parser <path>

Path to parser file for custom field types.

--dry-run

• Alias: -d
• Default: false

Whether to preview changes before applying them to the Storyblok space when pushing.

--filename

• Alias: -f

Custom name for files written (for pull commands) or read (for push commands). Ignored with --separate-files.

--filter <glob-pattern>

• Alias: -fi

Glob pattern to match components by filename when pushing.

--from <source-space-id>

• Alias: -f
• Default: <space-id>

When pushing components, the ID of the space from which the data was originally pulled.

--id <item-id>

ID of the affected item. Only works with datasources delete.

--template <blueprint-template>

The blueprint template for creating a new Storyblok project.

--path

• Alias: -p
• Default: .storyblok

The path of the parent folder, which will contain a space folder (with the name <space-id>) that contains the schemas.

--publish <mode>

Which stories to publish when pushing: all (all stories), published (stories that have already been published), or published-with-changes (only stories that have unpublished changes).

--query <query>

• Alias: -q

A query filter to to select content by Storyblok content attributes (e.g., --query "[highlighted][in]=true").

--region <region>

The region of a space’s server (one of eu, us, cn, or au).

--separate-files

• Alias: -sf
• Default: false

Whether to use separate files when writing data (for pull commands) or reading data (for push commands).

--space <space-id>

• Alias: -s

The ID of the source space (for pull commands) or target space (for push commands).

--starts-with <path>

A filter to include only Stories with a path that starts with a given string (e.g. /en/blog).

--suffix <suffix>

• Alias: --su

A suffix to include before the extension in filenames in the format <file-name>[.<suffix>].<json>.

--token <personal-access-token>

A personal access token from the Storyblok account dashboard.

--type-prefix <prefix>

Prefix to prepend to type names generated by types generate.

--verbose

• Alias: -v
• Default: false

Whether to enable verbose output.

Commands

components push

storyblok components push <component-name> --space <space-id> [--from | -f <source-space-id>] [--filter | --fi <filter>] [--separate-files | --sf] [--suffix | --su <suffix>] [--path | -p <path>]

components push sends components schemas --- along with any components, component groups, component presets, component tags, component whitelists, and datasources that they depend on --- from a local directory to a Storyblok space. The command expects content that has previously been pulled from a Storyblok space.

The --space option is required. --separate-files will read the components from individual files, rather than a consolidated components.json file.

By default, the command uploads all components and dependencies from .storyblok/components/<source-space-id>/components.json. The folder structure can be customized based on the following template:

<path>/
└── components/
    └── <space-id>/
        └── components.json

<path> defaults to .storyblok, and <space-id> is defined by the --space option.

With --separate-files, the command will read files from the following folder structure:

<path>/
└── components/
    └── <space-id>/
        ├── <componentName1>[.<suffix>].json
        ├── <componentName1>.presets.json
        ├── <componentName2>[.<suffix>].json
        ├── <componentName2>.presets.json
        └── ...

The following command will push all components from the space with the ID 12345 using default settings:

storyblok components push --space 12345

components pull

storyblok components pull [<component-name>] --space <space-id> [--filename | -f <filename>] [--separate-files | -sf] [--suffix | --su <suffix>] [--path | -p <path>]

components pull fetches components schemas, along with any components and datasources they depend on, from a Storyblok space, recursively creates a folder structure if it doesn’t exist, and saves the schemas to a local directory.

The --space option is required. --filename will default to components.json or be ignored if --separate-files is true, in which case files will be saved to <component-name>.json.

The command downloads all components, component groups, component presents, and component tags, and (with default configuration) saves them to the following structure:

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

With the --path <path>, --filename <filename>, and --suffix <suffix> options, the structure can be customized as follows:

<path>/
└── components/
    └── <space-id>/
        ├── <filename>[.<suffix>].json
        ├── groups.json
        ├── presets.json
        └── tags.json

With --separate-files, a list of component files will replace the components and presets files:

<path>/
└── components/
    └── <space-id>/
        ├── <componentName1>[.<suffix>].json
        ├── <componentName1>.presets.json
        ├── <componentName2>[.<suffix>].json
        ├── <componentName2>.presets.json
        ├── ...
        ├── groups.json
        └── tags.json

With the <component-name> parameter, the command will pull a single component and its dependencies:

storyblok components pull hero --space 12345

The single-component command will save files to the following structure:

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

For example, the following configurations:

storyblok components pull --space 12345 --suffix dev --filename my-components --path ./backup

Would generate these files:

backup/
└── components/
    └── 12345/
        ├── my-components.dev.json
        ├── groups.json
        ├── presets.json
        └── tags.json

create

storyblok create [<project-path>] [--template <blueprint-template>] [--skip-space] [--token <personal-access-token>]

The create command scaffolds a new project using Storyblok with your preferred technology stack. It automatically generates the project structure, creates a Storyblok space, configures environment variables, and opens your new space in the browser.

The CLI will request a technology stack and, if not provided, a project path. Then, it will launch a project in four steps:

1. Scaffold a new project using your selected blueprint
2. Create a new Storyblok space for your project
3. Generate a .env file with your space’s access token
4. Open your new space in the browser

Blueprints are templates for Storyblok projects. The CLI includes seven blueprint options:

• react
• vue
• svelte
• astro
• nuxt
• next
• eleventy

The command requires the user to be authenticated with Storyblok in the CLI. If this is not the case, run the login command:

storyblok login

The authenticated account must have write access to the target directory, space creation permissions, and a valid authentication token; otherwise, the CLI throw errors.

The create command scaffolds a complete project structure based on your chosen blueprint, including:

• Project scaffolding with the selected technology
• Storyblok integration setup
• Example components and pages
• Development server configuration

Caution

Note that the create command does not install dependencies.

With the --token <STORYBLOK_DELIVERY_API_TOKEN> option, the CLI will skip space generation and only create the local project files. And use the provided token in the generated .env file. With the --skip-space option, the CLI will skip space generation and only create the local project files.

Without --skip-space or --token, the command will create a new Storyblok space in the user’s region with the following configurations:

• A name matching the project name
• Settings for the chosen technology
• A preview token for local development

The command automatically creates a .env file in your project root with:

STORYBLOK_ACCESS_TOKEN=<space-token>

After creation, the command will open the Storyblok space in the default browser, displaying next steps.

The <project-path> must meet multiple requirements:

• At least one character long
• Containing only letters, numbers, hyphens, and underscores
• Relative or absolute

For example, my-project, my_project_123, ./projects/awesome-app, and /Users/admin/Documents/my-app would all work, while my project and @pp would fail.

First-time users should use the command with no options:

storyblok create

This will walk the user through an interactive setup process.

Experienced users can directly define the blueprint and space in the command:

storyblok create ./projects/my-project --template vue --skip-space

Tip

To learn more about project configuration and development, see the Storyblok technology guides.

datasources delete

storyblok datasources delete <datasource-name> --space <space-id> [--id <datasource-id>]

datasources delete deletes a datasource from your Storyblok space by name or ID.

The <space-id> is required. If both <datasource-name> and <datasource-id> are provided, the ID will take priority.

The following command will delete the datasource named colors from the Space with the ID 12345:

storyblok datasources delete colors --space 12345

datasources pull

storyblok datasources pull --space <space-id> [--filename | -f <filename>] [--separate-files]

datasources pull downloads datasources and their entries from a Storyblok space, recursively creates a folder structure if it doesn’t exist, and saves the schemas to a local directory.

The --space option is required.

By default, datasources will be saved to the following directory structure:

<path>/
└── datasources/
    └── <space-id>/
        └── <filename>[.<suffix>].json

Or, with --separate-files:

<path>/
└── datasources/
    └── <space-id>/
        ├── <first-datasource-name>[.<suffix>].json
        └── <second-datasource-name>[.<suffix>].json

datasources push

storyblok datasources push --space <space-id> [--filename | -f <filename>] [--separate-files]

datasources push uploads datasources and their entries to a Storyblok space. The command works with datasources that have previously been pulled from Storyblok, and must be executed with the same options used when pulling.

The --space option is required. The --from option will default to the <space-id> of the folder containing the datasources (<path>/datasources/<space-id>/). The --filename option defaults to datasources.

The --filter option will select only datasources whose filename match the string passed to filter.

The command will create new datasources and entries or update existing ones based on name matching. Each datasource file contains the datasource metadata (id, name, slug, dimensions, timestamps) and an array of entries (id, name, value, dimension_value).

Here’s an example datasources file:

{
  "id": 1,
  "name": "colors",
  "slug": "colors",
  "dimensions": [],
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z",
  "entries": [
    {
      "id": 101,
      "name": "blue",
      "value": "#0000ff",
      "dimension_value": "",
      "datasource_id": 1
    }
  ]
}

To copy 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. Cross-space pushes will match datasources by name and entries by datasource and name. ids are ignored, as they are automatically generated and vary between spaces). If a datasource is uploaded multiple times with different names, it will create a new datasource each time.

The command reads from the following folder structure:

<path>/
└── datasources/
    └── <space-id>/
        └── <file-name>[.<suffix>].json

Or, with --separate-files:

<path>/
└── datasources/
    └── <space-id>/
        ├── <first-datasource-name>[.<suffix>].json
        └── <second-datasource-name>[.<suffix>].json

languages pull

storyblok languages pull --space <space-id>

languages pull downloads a list of 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. This command is useful for version control and backups.

The --space option is required.

The command saves the files to the following folder structure:

<path>/
└── languages/
    └── <space-id>/
        └── <filename>[.<suffix>].json

login

storyblok login [--token <personal-access-token>] [--region <region>]

login authenticates a Storyblok user and stores their credentials in ~/.storyblok/credentials.json.

The <region> option must match the Space region _ one of eu, us, cn, and au.

logout

storyblok logout

logout securely removes stored credentials from ~/.storyblok/credentials.json and clear the current session to deauthenticate the logged-in Storyblok user.

migrations

The migrations module provides tools to manage and execute migrations for your Storyblok components. 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 the all from the content of the title field to the new headline field. This is different from a platform migration, when a team changes their CMS.

Migrations have three steps:

1. generate the migration file
2. run the migration
3. rollback changes if necessary

Migrations use the following file structure:

.storyblok/
└── migrations/
    └── <space-id>/
        ├── <first-component>.js
        ├── <second-component>.js
        └── ...

Use --dry-run to preview changes before applying them.

migrations generate

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

The migrations generate command allows you to create a migration file for a specific component in your Storyblok space. The component-name parameter and --space option are required.

By default, the command will recursively generate a folder structure and migration file for the specified component:

<path>/
└── 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.

export default function (block) {
  // Example to change a string to boolean
  block.example_boolean_field = !!block.example_text_field;

  // Example to transfer content from other field
  block.example_field_two = block.example_field_one;

  // Example to transform an array
  block.example_array_field = block.example_array_field.map((item) => ({ ...item, new_prop: "value" }));

  // Example to combine fields
  block.example_full_name = `${block.first_name} ${block.last_name}`;

  return block;
}

migrations rollback

storyblok migrations rollback <migration-file> --space <space-id>

migrations rollback reverts a previous migration that was executed with migrations run. The migrations run command saves a snapshot to <path>/migrations/<space-id>/rollbacks. migrations rollback uses that snapshot to revert a migration. If the snapshot is not available, the reversion will fail.

The command will restore the stories from the snapshot, updating the Storyblok space.

The migration-file parameter and --space option are required. migration-file is the name of the snapshot file generated by migrations run.

The command will search for a snapshot in the following directory structure:

.storyblok/
└── migrations/
    └── <space-id>/
        └── rollbacks/
            └── <migration-file>.json

The following command would read from .storyblok/migrations/12345/rollbacks/migration-component.1746452866186.json:

storyblok migrations rollback migration-component.1746452866186.json --space 12345

migrations run

storyblok migrations run [<component-name>] --space <space-id> [--filter <glob-pattern>] [--dry-run] [--query <query>] [--starts-with <path>] [--publish <mode>]

migrations run uploads content that has been exported with migrations generate. The command also generates a pre-upload snapshot of the space and saves it to .storyblok/migrations/<space-id>/rollbacks, so that the content can be restored with migrations rollback.

By default, the command reads the migration files, finds all stories that use the components, applies the migrations, updates the stories in Storyblok, and creates a snapshot.

The --space option is required.

By default, the command will run all migrations found in <path>/migrations/<space-id>/. With the <component-name> parameter, the command will only migrate the provided component.

The --dry-run option will preview changes without applying them. The --filter, --query, and --starts-with options filter the content to migrate. The --publish option sets the publication behavior.

The following command runs all migrations:

storyblok migrations run --space 12345

The following command will migrate all components with names that start with “hero” and preview the changes without applying them.

storyblok migrations run --space 12345 --filter "hero*" --dry-run

The following command will migrate all stories that match the provided filter and publish stories that have already been published.

storyblok migrations run --space 12345 --publish published --query "[highlighted][in]=true"

signup

storyblok signup

signup opens the Storyblok signup page in the default browser. After signing up, run login to authenticate.

types generate

storyblok types generate --space <space-id> [--separate-files] [--strict] [--filename <name>] [--type-prefix <prefix>] [--suffix <suffix>] [--custom-fields-parser <path>] [--compiler-options <options>] [--path <path>]

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.

Caution

types generate must run after components pull.

By default, the command generates two files:

• <path>/types/storyblok.d.ts: Base Storyblok types
• <path>/types/<space-id>/storyblok-component.d.ts: Component types

The --space option is required. --strict will disable loose typing, creating types that are more precise (and which may require more explicit type handling). --type-prefix will prepend a prefix to the generated types. --custom-fields-parser accepts a path to a parser for custom field types. --compiler-options accepts a path to compiler options from json-schema-to-typescript.

The command generates the following folder structure:

<path>/
└── types/
    ├── storyblok.d.ts
    └── <space-id>/
        └── storyblok-components.d.ts

The following command will generate types for all components from the space with the ID 12345:

storyblok types generate --space 12345

The following command will generate types with strict mode, prepending them with “Storyblok”:

storyblok types generate --space 12345 --strict --type-prefix Storyblok

user

storyblok user

user displays information about the authenticated Storyblok account, including the friendly name, email address, and logged-in region.