Visual Builder CLI

A command-line interface for managing Contentstack Visual Builder configurations.

Installation

Install globally via npm:

npm install -g @contentstack/visual-builder-cli

Usage

Prerequisites

1. This CLI is designed to work with Contentstack Visual Builder projects
2. You need to have a configs.json file with your configurations
3. You must set the config file location before using other commands

Getting Started

1. First, set your config file location

visual-builder set "path/to/your/configs.json"

The config file should follow this format:

{
  "configs": {
    "config-name-1": {
      "API_KEY": "your-api-key",
      "DELIVERY_TOKEN": "your-delivery-token",
      "ENVIRONMENT": "development",
      "API_HOST": "your-api-host",
      "PREVIEW_TOKEN": "your-preview-token",
      "APP_HOST": "your-app-host",
      "TARGET_APP_URL": "http://localhost:3006",
      "STACK_NAME": "Your Stack Name",
      "ORG_UID": "your-org-uid",
      "BRANCH": "main"
    },
    "config-name-2": {
      // ... another configuration
    }
  }
}

2. Then use other commands from your Visual Builder project directory

Commands

Set config file location

visual-builder set <config-file-path>

Set the path to your configs.json file. This can be a relative or absolute path.

Examples:

visual-builder set "data/configs.json"
visual-builder set "/absolute/path/to/configs.json"
visual-builder set "../shared/configs.json"

List all available configurations

visual-builder csr list

Shows all available configurations with:

• A marker indicating the current active config (●) vs inactive (○)
• Stack name, environment, and API host for each config

Switch to a specific configuration

visual-builder csr use "config-name"

Examples:

visual-builder csr use "manual testing"
visual-builder csr use "idontknow"
visual-builder csr use "visual builder automation"
visual-builder csr use "manual testing (dev22)"

Show current active configuration

visual-builder csr current

Displays all the configuration values for the currently active config.

Show help

visual-builder --help

Configuration Management

How it works

1. The CLI reads from a centralized configs.json file containing all available configurations
2. When you select a config, it generates a new config.ts file in your project
3. Your Visual Builder application reads from this generated config.ts file
4. The CLI can detect which configuration is currently active by comparing values

Project Structure

The CLI expects your project to have this structure:

your-project/
├── test-resources/
│   └── csr/
│       └── src/
│           └── config.ts  (generated by this CLI)

Adding New Configurations

To add new configurations:

1. Edit your configs.json file (the one you set with visual-builder set)
2. Add your new configuration following this format:

{
  "configs": {
    "your-config-name": {
      "API_KEY": "your-api-key",
      "DELIVERY_TOKEN": "your-delivery-token", 
      "ENVIRONMENT": "development",
      "API_HOST": "your-api-host",
      "PREVIEW_TOKEN": "your-preview-token",
      "APP_HOST": "your-app-host",
      "TARGET_APP_URL": "http://localhost:3006",
      "STACK_NAME": "Your Stack Name",
      "ORG_UID": "your-org-uid",
      "BRANCH": "main"
    }
  }
}

Examples

# Install the CLI globally
npm install -g @contentstack/visual-builder-cli

# Set your config file location (do this once)
visual-builder set "data/configs.json"

# Navigate to your Visual Builder project
cd /path/to/your/visual-builder-project

# List available configurations
visual-builder csr list

# Switch to a specific configuration
visual-builder csr use "manual testing"

# Check what's currently active
visual-builder csr current

Color Coding

• 🟢 Green: Current active configuration
• 🟡 Yellow: Available configurations
• 🔵 Blue: Information text
• 🔴 Red: Error messages

Requirements

• Node.js >= 14.0.0
• npm or yarn

License

MIT

Support

For issues and questions, please visit the GitHub repository.