Set Up the CLI

Install the storyblok CLI globally on your device or as a dependency of a specific project.

Requirements

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

Installation

# Global installation
npm install -g storyblok@latest

# Local installation (per project)
npm install -D storyblok@latest

Configuration files

Use configuration files to define default values for specific contexts and avoid retyping flags. The CLI applies these values to the relevant commands.

While optional, configuration files provide a better developer experience, especially in multi-command workflows.

Quickstart

1. In the project root, create a storyblok.config.ts file.

2. Export a configuration object using defineConfig and define the default value. For example:

   import { defineConfig } from "storyblok/config";
   
   export default defineConfig({
     space: "123456",
   });

3. Run any command, and the CLI applies the relevant settings. For example, the following command pulls components from the space with the ID 123456:

   storyblok components pull

Naming patterns and file types

A configuration file must follow the naming pattern {storyblok.}config.{ext}. The CLI supports the following file types, in this order: .js, .ts, .mjs, .cjs, .mts, .cts, .json, .jsonc, .json5, .yaml, .yml, .toml.

Keep one configuration file per location. If a directory contains more than one, the CLI loads only the first match in the order above.

Configuration file locations

The CLI reads configuration files from three locations and merges them. Two of these locations depend on the current working directory (<cwd>), the directory where you run the command:

Context	Directory	File
Home	~/.storyblok	config.*
Project	<cwd>/.storyblok	config.*
Project root	<cwd>	storyblok.config.*

The CLI checks only these three locations and ignores configuration files in parent directories.

When settings conflict, the CLI applies them in the following order, from highest to lowest priority:

flags > <cwd>/storyblok.config.* > <cwd>/.storyblok/config.* > ~/.storyblok/config.* > built-in defaults

The CLI merges settings key by key. A file overrides only the settings it defines, and every other setting keeps its value from a lower-priority source.

Workspaces with multiple projects

In a workspace with multiple projects, the CLI applies the configuration of the directory where the command runs. Run commands from the project directory, or use a workspace command such as npm run --workspace <project>, which also runs in the project directory.

To share settings across projects, define them in a configuration file in the workspace root:

storyblok.config.ts

import { defineConfig } from "storyblok/config";

export default defineConfig({
  region: "eu",
  api: {
    maxRetries: 5,
  },
});

Then extend that file from each project’s configuration file and add the project-specific settings:

apps/website/storyblok.config.ts

import { defineConfig } from "storyblok/config";

export default defineConfig({
  extends: ["../../storyblok.config.ts"],
  space: "123456",
});

Settings in the project file override the matching settings in the extended file.

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
    rateLimit: 6, // Maximum Management API requests per second
  },

  // 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: {
        filename: "storyblok-component-types",
      },
    },
  },
});

Environment variables

The CLI loads environment variables with dotenv. In JavaScript and TypeScript configuration files, use process.env to access them:

storyblok.config.ts

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