---
title: Setting up the CLI
description: Install the Storyblok CLI, and configure it so flags need not be repeated for every command.
url: https://www.storyblok.com/docs/tooling/cli/setup
---

# 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

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

```text
flags > project > workspace > home directory > built-in defaults
```

### 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
    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

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