{"id":17066,"library":"storyblok","title":"Storyblok CLI","description":"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.","status":"active","version":"4.16.9","language":"javascript","source_language":"en","source_url":"https://github.com/storyblok/monoblok","tags":["javascript","storyblok","cli","node","typescript"],"install":[{"cmd":"npm install storyblok","lang":"bash","label":"npm"},{"cmd":"yarn add storyblok","lang":"bash","label":"yarn"},{"cmd":"pnpm add storyblok","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { storyblok } from 'storyblok'","symbol":"storyblok","correct":"storyblok <command> [options]"},{"note":"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.","wrong":"require('storyblok')().run()","symbol":"npx storyblok","correct":"npx storyblok <command> [options]"},{"note":"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.","wrong":"import { MyComponentType } from 'storyblok'","symbol":"Generated Component Types","correct":"import { MyComponentType } from './.storyblok/components'"}],"quickstart":{"code":"npm install -g storyblok\nstoryblok login\n# Follow the prompts to enter your personal access token\n\n# Pull all component schemas from your space\nstoryblok pull-components --space=<YOUR_SPACE_ID> --path=./src/storyblok/components\n\n# Generate TypeScript types for your components\nstoryblok generate-types --path=./src/storyblok/types.d.ts\n\n# Run a simple migration (example: rename a field)\n# First, create a migration file, e.g., 'storyblok/migrations/001-rename-field.js'\n// storyblok/migrations/001-rename-field.js\nmodule.exports = { \n  up: async (api) => {\n    console.log('Running migration: Rename old_field to new_field');\n    // Example: Find a component and rename a field\n    // await api.put('spaces/YOUR_SPACE_ID/components/COMPONENT_ID', { component: { schema: { new_field: { type: 'text' } } } });\n  },\n  down: async (api) => {},\n};\nstoryblok migrate --space=<YOUR_SPACE_ID> --path=./storyblok/migrations --dry-run\nstoryblok migrate --space=<YOUR_SPACE_ID> --path=./storyblok/migrations","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Node.js 18.0.0 or higher is required. Older versions may lead to installation failures or runtime errors.","severity":"breaking","affected_versions":"<=4.x"},{"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.","message":"A Storyblok Personal Access Token is mandatory for authentication. Without it, most CLI commands interacting with your space will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.16.9"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the CLI globally using `npm install -g storyblok` or execute commands using `npx storyblok <command>`.","cause":"The Storyblok CLI package has not been installed globally or is not in your system's PATH.","error":"command not found: storyblok"},{"fix":"Run `storyblok login` and provide your Storyblok Personal Access Token to authenticate your CLI session.","cause":"The CLI requires authentication to interact with your Storyblok space, and you have not logged in or your session has expired.","error":"Unauthorized: Please login first."},{"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.","cause":"Your current Node.js version is older than the minimum requirement for the Storyblok CLI.","error":"Error: Minimum Node.js version 18.0.0 is required."}],"ecosystem":"npm","meta_description":null}