Setting up the CLI

Install the storyblok CLI once per machine, or per project to pin its version alongside the rest of your dependencies.

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