Contentstack CLI Configuration Reference

This reference outlines all configuration options available in Contentstack CLI plugins for export, import, audit, and content migrations tasks. It helps developers and administrators configure and manage CLI-based workflows across stacks.

Prerequisites

Before you begin, ensure that:

• The CLI is installed and authenticated
• You have stack access with the necessary permissions
• You understand how configuration values are loaded (via config files, environment variables, or CLI flags)

What You’ll Learn

After reading this reference, you can:

• Choose the correct CLI command and configuration for your task
• Understand how configuration values are resolved across environment variables, root settings, module overrides, and defaults
• Configure required and optional settings, including module-specific options
• Optimize performance and avoid common configuration errors

Quick Reference

• Export a stack or content:
  csdx cm:stacks:export

• Import content into a stack:
  csdx cm:stacks:import

• Export specific content only:
  csdx cm:stacks:export-query

• Audit schema and entries:
  csdx cm:stacks:audit

• Set up mapping and dependencies before import:
  csdx cm:stacks:import-setup

• Run custom content transformations:
  csdx cm:stacks:migration

Environment Variables

The CLI supports environment variables that override config files and defaults. This is especially useful for CI/CD pipelines, local overrides, and handling sensitive settings such as encryption keys.

Note: Environment variables have the highest priority in the configuration resolution order. Refer to the Configuration Precedence section for the complete hierarchy.

Supported CLI Configuration Environment Variables

Usage Examples

The following examples focus on environment variables that significantly impact CLI behavior or are commonly used in real-world workflows.

Change the default location for CLI log files

export CS_CLI_LOG_PATH="/path/to/logs"
csdx cm:stacks:export

Disable configuration file encryption

export ENCRYPT_CONF=false
csdx cm:stacks:import

Note: Disabling encryption is useful in CI environments where secrets are managed externally.

Use a custom directory for CLI configuration files

export CS_CLI_CONFIG_PATH="/path/to/config"
csdx cm:stacks:export

Configuration Precedence

Refer to this section when your CLI config includes both root and module-level values, and you need to understand which setting takes precedence.

Precedence Order

1. Module-specific configuration (highest priority)
2. Root-level configuration
3. Default values (lowest priority)

How It Works

The CLI uses a recursive merge strategy (merge.recursive()) when loading configuration files. This means:

• Module config overrides root config: If a key exists at both <module>.<key> and root-level <key>, the module-specific value is used.
• Root config acts as a fallback: If a key is not defined at the module level, the CLI uses the root-level value.
• Defaults are a last resort: If neither module nor root includes the key, the CLI falls back to default values.

Examples

Import Configuration Precedence

Example 1: importConcurrency for Entries Module

{
  "importConcurrency": 5,
  "modules": {
    "entries": {
      "importConcurrency": 10
    }
  }
}

Result: Entries module uses importConcurrency: 10 (module config), while other modules use importConcurrency: 5 (root config).

Code Reference: Refer to the entries.ts in the CLI repository.

Example 2: writeConcurrency for Content Types Module

{
  "writeConcurrency": 5,
  "modules": {
    "content-types": {
      "writeConcurrency": 8
    }
  }
}

Result: Content Types module uses writeConcurrency: 8 (module config), while other modules use writeConcurrency: 5 (root config).

Code Reference: See content-types.ts in the CLI repository.

Export Configuration Precedence

Example 3: chunkFileSize for Entries Module

{
  "modules": {
    "entries": {
      "chunkFileSize": 20
    }
  }
}

Result: Entries module uses chunkFileSize: 20 (module config). If not specified, it defaults to 10 (FsUtility default).

Example 4: fetchConcurrency for Assets Module

{
  "fetchConcurrency": 5,
  "modules": {
    "assets": {
      "fetchConcurrency": 10
    }
  }
}

Result: Assets module uses fetchConcurrency: 10 (module config), while other modules use fetchConcurrency: 5 (root config).

Common Keys with Precedence

The following table lists configuration keys that can be defined at both the root level and module level, along with their corresponding module override paths.

Best Practices

• Define shared configuration values at the root level to apply them consistently across all modules.
• Use module-specific configuration only when a module requires behavior that differs from the global defaults.
• Avoid repeating the same configuration value at both root and module levels unless different behavior is intentionally required.
• When validating or troubleshooting CLI behavior, review module-level configuration first.
• Be aware that environment variables override configuration file values and can affect CLI behavior across commands.

Example – Recommended Pattern:

The following example demonstrates a recommended configuration pattern that balances shared defaults with targeted module overrides.

{
  "fetchConcurrency": 5,
  "writeConcurrency": 5,
  "modules": {
    "entries": {
      "importConcurrency": 10,
      "chunkFileSize": 20
    },
    "assets": {
      "fetchConcurrency": 10
    }
  }
}

In this example:

• Most modules use fetchConcurrency: 5 and writeConcurrency: 5 from the root
• The Entries module uses importConcurrency: 10 and chunkFileSize: 20 (module-specific overrides)
• The Assets module overrides the root value with fetchConcurrency: 10

Export Configuration

Use this configuration to export stack content and metadata for backups, migrations, or moving content between stacks.

Command:

csdx cm:stacks:export

Default Configuration: See the default export configuration file in the CLI repository.

Basic Settings

Note: The source_stack and data fields are required unless they are provided through CLI flags or an alias.

Path & Directory Settings

Content Filtering

Performance Settings

Feature Flags

Authentication

Advanced Settings

Note: If a configuration value is defined at both the root level and a module level, the module-level value takes precedence for that module. See Configuration Precedence for more information.

Module-Specific Configuration

Assets Module

Entries Module

Default invalidKeys for Entry Module:

• stackHeaders
• content_type_uid
• urlPath
• created_at
• updated_at
• created_by
• updated_by
• _metadata
• published

Note: The downloadLimit is not used for entries export. It applies only to the assets module.

Precedence: Module-specific chunkFileSize, limit, and batchLimit are module-specific only and don't have root-level equivalents.

Content Types Module

Default validKeys for Content Type Module:

• title
• uid
• field_rules
• schema
• options
• singleton
• description

Precedence: modules.content-types.writeConcurrency takes precedence over root-level writeConcurrency. If not set, falls back to the root writeConcurrency (default: 5).

Global Fields Module

Default validKeys for Global Field Module:

• title
• uid
• schema
• options
• singleton
• description

Taxonomies Module

Default invalidKeys for Taxonomies Module:

• updated_at
• created_by
• updated_by
• stackHeaders
• urlPath
• created_at

Personalize Module

Base URLs by Region:

• AWS-NA: https://personalize-api.contentstack.com
• AWS-EU: https://eu-personalize-api.contentstack.com
• AWS-AU: https://au-personalize-api.contentstack.com
• AZURE-NA: https://azure-na-personalize-api.contentstack.com
• AZURE-EU: https://azure-eu-personalize-api.contentstack.com
• GCP-NA: https://gcp-na-personalize-api.contentstack.com
• GCP-EU: https://gcp-eu-personalize-api.contentstack.com

Locales Module

Default requiredKeys for Locales module:

• code
• uid
• name
• fallback_locale

Environments Module

Extensions Module

Stack Module

Webhooks Module

Workflows Module

Default invalidKeys for Workflows module:

• stackHeaders
• urlPath
• created_at
• updated_at
• created_by
• updated_by

Labels Module

Default invalidKeys for Labels module:

• stackHeaders
• urlPath
• created_at
• updated_at
• created_by
• updated_by

Complete Export Configuration Example

The following example shows a complete export configuration, including commonly used options and module-level overrides.

{
  "contentVersion": 2,
  "versioning": false,
  "host": "https://api.contentstack.io/v3",
  "preserveStackVersion": false,
  "master_locale": {
    "name": "English - United States",
    "code": "en-us"
  },
  "source_stack": "bltXXXXXXXXXX",
  "data": "./export-data",
  "branchName": "main",
  "moduleName": null,
  "contentTypes": [],
  "securedAssets": false,
  "fetchConcurrency": 5,
  "writeConcurrency": 5,
  "delayMs": 1000,
  "maxContentLength": 100000000,
  "maxBodyLength": 100000000,
  "personalizationEnabled": false,
  "skipStackSettings": false,
  "skipDependencies": false,
  "developerHubBaseUrl": "",
  "marketplaceAppEncryptionKey": "nF2ejRQcTv",
  "modules": {
    "assets": {
      "batchLimit": 20,
      "chunkFileSize": 1,
      "downloadLimit": 5,
      "fetchConcurrency": 5,
      "includeVersionedAssets": false,
      "securedAssets": false,
      "displayExecutionTime": false,
      "enableDownloadStatus": false,
      "assetsMetaKeys": ["uid", "url", "filename", "parent_uid"],
      "host": "https://images.contentstack.io"
    },
    "entries": {
      "limit": 100,
      "batchLimit": 20,
      "exportVersions": false,
      "chunkFileSize": 10
    },
    "content-types": {
      "limit": 100,
      "validKeys": ["title", "uid", "field_rules", "schema", "options", "singleton", "description"]
    },
    "global-fields": {
      "validKeys": ["title", "uid", "schema", "options", "singleton", "description"]
    },
    "taxonomies": {
      "limit": 100
    },
    "personalize": {
      "baseURL": {
        "AWS-NA": "https://personalize-api.contentstack.com",
        "AWS-EU": "https://eu-personalize-api.contentstack.com",
        "AWS-AU": "https://au-personalize-api.contentstack.com",
        "AZURE-NA": "https://azure-na-personalize-api.contentstack.com",
        "AZURE-EU": "https://azure-eu-personalize-api.contentstack.com",
        "GCP-NA": "https://gcp-na-personalize-api.contentstack.com",
        "GCP-EU": "https://gcp-eu-personalize-api.contentstack.com"
      },
      "exportOrder": ["attributes", "audiences", "events", "experiences"]
    }
  }
}