Storyblok CLI

4.16.9 · active · verified Wed Apr 22

The Storyblok CLI (Command Line Interface) is a powerful development tool designed to enhance the developer experience for projects integrating with the Storyblok Headless CMS. It provides a robust set of features for managing Storyblok spaces directly from the terminal, including generating TypeScript type definitions for components to ensure type safety in frontend applications. The current stable version is 4.16.9, released very recently, indicating an active development and release cadence, often as part of a monorepo that includes various Storyblok SDKs. Key differentiators include its comprehensive component management capabilities (pulling, pushing schemas, groups, presets, tags), a flexible migration system for content updates, secure authentication across regions, and advanced filtering options. It focuses on improving workflow efficiency with features like organized file structures, customizable paths, and a dry run mode for migrations.

Common errors

```
command not found: storyblok
```
cause The Storyblok CLI package has not been installed globally or is not in your system's PATH.

fix Install the CLI globally using `npm install -g storyblok` or execute commands using `npx storyblok <command>`.
```
Unauthorized: Please login first.
```
cause The CLI requires authentication to interact with your Storyblok space, and you have not logged in or your session has expired.

fix Run `storyblok login` and provide your Storyblok Personal Access Token to authenticate your CLI session.
```
Error: Minimum Node.js version 18.0.0 is required.
```
cause Your current Node.js version is older than the minimum requirement for the Storyblok CLI.

fix Update Node.js to version 18.0.0 or higher. Use `nvm install 18 && nvm use 18` or download the latest LTS version from nodejs.org.

Warnings

breaking Node.js 18.0.0 or higher is required. Older versions may lead to installation failures or runtime errors.
Fix: Upgrade your Node.js environment to version 18.0.0 or later using a tool like nvm or by downloading the latest LTS from nodejs.org.
gotcha A Storyblok Personal Access Token is mandatory for authentication. Without it, most CLI commands interacting with your space will fail.
Fix: Generate a Personal Access Token from your Storyblok account settings (https://app.storyblok.com/#/me/account?tab=token) and use `storyblok login` to authenticate before running commands.
gotcha Be cautious when using commands like `storyblok push-components` or `storyblok migrate` on production spaces. Always use `--dry-run` first for migrations, and consider version control for component schemas.
Fix: For destructive operations, always use `--dry-run` to preview changes and test on staging environments before applying to production. Implement a robust CI/CD pipeline that includes schema and content backups.
gotcha Path resolution for component and migration files can be tricky. Ensure the `--path` option is correctly specified relative to your current working directory or as an absolute path.
Fix: Since v4.16.9, path resolution has been improved, but always double-check your `--path` argument. Use absolute paths for clarity or ensure the relative path is correct from where you execute the CLI command.

Install

npm install storyblok npm
yarn add storyblok yarn
pnpm add storyblok pnpm

Imports

storyblok
wrong:
```
import { storyblok } from 'storyblok'
```
correct:
```
storyblok <command> [options]
```
The primary way to interact with this package is via its CLI. After global installation (`npm install -g storyblok`), the `storyblok` command is available in the terminal.
npx storyblok
wrong:
```
require('storyblok')().run()
```
correct:
```
npx storyblok <command> [options]
```
Using `npx` allows running the Storyblok CLI without a global installation, ensuring you use the latest available version or a specified one for one-off tasks or CI/CD pipelines.
Generated Component Types
wrong:
```
import { MyComponentType } from 'storyblok'
```
correct:
```
import { MyComponentType } from './.storyblok/components'
```
The Storyblok CLI generates TypeScript type definitions for your Storyblok components into a configurable local path (e.g., `.storyblok/components`). These types are then imported into your frontend project, not directly from the `storyblok` npm package itself.

Quickstart

This quickstart demonstrates how to install the Storyblok CLI globally, log in, pull component schemas, generate TypeScript types, and run a basic content migration with a dry run.

npm install -g storyblok
storyblok login
# Follow the prompts to enter your personal access token

# Pull all component schemas from your space
storyblok pull-components --space=<YOUR_SPACE_ID> --path=./src/storyblok/components

# Generate TypeScript types for your components
storyblok generate-types --path=./src/storyblok/types.d.ts

# Run a simple migration (example: rename a field)
# First, create a migration file, e.g., 'storyblok/migrations/001-rename-field.js'
// storyblok/migrations/001-rename-field.js
module.exports = { 
  up: async (api) => {
    console.log('Running migration: Rename old_field to new_field');
    // Example: Find a component and rename a field
    // await api.put('spaces/YOUR_SPACE_ID/components/COMPONENT_ID', { component: { schema: { new_field: { type: 'text' } } } });
  },
  down: async (api) => {},
};
storyblok migrate --space=<YOUR_SPACE_ID> --path=./storyblok/migrations --dry-run
storyblok migrate --space=<YOUR_SPACE_ID> --path=./storyblok/migrations

view raw JSON →