---
title: Set Up the CLI
description: Install Storyblok’s CLI and configure default values for command flags.
url: https://www.storyblok.com/docs/tooling/cli/setup
---

# 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

```bash
# 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:
    
    ```js
    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`:
    
    ```bash
    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:

```text
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

```js
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

```js
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

```js
// 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

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

## Pagination

-   [Previous: Introduction](/docs/tooling/cli)
-   [Next: Global options](/docs/tooling/cli/global-options)
