Contentstack CLI Configuration Reference

This document provides a comprehensive reference for all configuration options available across Contentstack CLI plugins.

The CLI supports several environment variables that can be used to configure behavior without modifying configuration files.

Set custom log path:

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

Disable configuration encryption:

export ENCRYPT_CONF=false
csdx cm:stacks:import

Use custom config directory:

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

Note Environment variables take precedence over configuration file settings and defaults.

When the same configuration key exists at both the root level and module level, the CLI follows a specific precedence order.

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

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

• Module config overrides root config: If a key exists in both modules.<module-name>.<key> and root-level <key>, the module-specific value is used.
• Root config is fallback: If a key doesn't exist in module config, the root-level value is used.
• Defaults are last resort: If neither module nor root config has the key, default values are used.

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: See 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).

The following keys can be set at both root and module levels:

Import:

• importConcurrency → modules.entries.importConcurrency
• fetchConcurrency → modules.<module>.fetchConcurrency
• writeConcurrency → modules.<module>.writeConcurrency
• chunkFileSize → modules.entries.chunkFileSize

Export:

• fetchConcurrency → modules.<module>.fetchConcurrency
• writeConcurrency → modules.<module>.writeConcurrency
• chunkFileSize → modules.entries.chunkFileSize
• limit → modules.<module>.limit
• batchLimit → modules.<module>.batchLimit

1. Use root-level config for global settings: Set common values at the root level to apply across all modules.
2. Override per module when needed: Use module-specific config to customize behavior for specific modules.
3. Avoid duplication: Don't repeat root-level values in module config unless you need different values.

Example - Recommended Pattern:

{
  "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 root
• Entries module uses importConcurrency: 10 and chunkFileSize: 20 (module-specific)
• Assets module uses fetchConcurrency: 10 (overrides root)

Command: csdx cm:stacks:export

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

*Required unless using CLI flags or management token alias

Note Use the --alias flag to specify a management token alias instead of providing credentials directly in the configuration file.

Important: When the same configuration key exists at both root level and module level, module-specific configuration takes precedence. For example, if you set fetchConcurrency: 5 at root and modules.assets.fetchConcurrency: 10, the assets module will use 10. See Configuration Precedence section for detailed explanation and examples.

Note If CS Assets is not active, the CLI ignores these options. They apply only when your region has CS Assets enabled and the branch has linked workspaces. See CLI for CS Assets.

Default invalidKeys: ['stackHeaders', 'content_type_uid', 'urlPath', 'created_at', 'updated_at', 'created_by', 'updated_by', '_metadata', 'published']

Note downloadLimit is not used for entries export (only applies to assets module).

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

Default validKeys: ["title", "uid", "field_rules", "schema", "options", "singleton", "description"]

Note Content Types module uses the root-level writeConcurrency setting. Module-specific writeConcurrency is not supported for this module.

Default validKeys: ["title", "uid", "schema", "options", "singleton", "description"]

Default invalidKeys: ['updated_at', 'created_by', 'updated_by', 'stackHeaders', 'urlPath', 'created_at']

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

Default requiredKeys: ['code', 'uid', 'name', 'fallback_locale']

Default invalidKeys: ['stackHeaders', 'urlPath', 'created_at', 'updated_at', 'created_by', 'updated_by']

Default invalidKeys: ['stackHeaders', 'urlPath', 'created_at', 'updated_at', 'created_by', 'updated_by']

{
  "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": [],
      "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"]
    }
  }
}

Command: csdx cm:stacks:import

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

*Required unless using CLI flags or management token alias

Note Use the --alias flag to specify a management token alias instead of providing credentials directly in the configuration file.

Important: When the same configuration key exists at both root level and module level, module-specific configuration takes precedence. For example, if you set importConcurrency: 5 at root and modules.entries.importConcurrency: 10, the entries module will use 10. See Configuration Precedence section for detailed explanation and examples.

Default validKeys: ["title", "parent_uid", "description", "tags"]
Default folderValidKeys: ["name", "parent_uid"]

Note modules.assets.fetchConcurrency can override root-level fetchConcurrency if specified.

Default invalidKeys: ['created_at', 'updated_at', 'created_by', 'updated_by', '_metadata', 'published']

Precedence: modules.entries.importConcurrency takes precedence over root-level importConcurrency. If not set, falls back to root importConcurrency (default: 5).

Note If CS Assets is not active, the CLI ignores these options. They apply only when the content directory contains a spaces/ directory exported using CS Assets mode. See CLI for CS Assets.

Default validKeys: ["title", "uid", "schema", "options", "singleton", "description"]

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

Default validKeys: ["title", "uid", "schema", "options", "singleton", "description"]

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

Default requiredKeys: ['code', 'uid', 'name', 'fallback_locale']

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

Precedence: modules.environments.fetchConcurrency takes precedence over root-level fetchConcurrency. If not set, falls back to root fetchConcurrency (default: 5), but the module default is 2.

Default validKeys: ['data_type', 'srcdoc', 'title', 'type', 'mutiple', 'config']

Base URLs: Same as Export configuration (see Export section above).

{
  "versioning": false,
  "host": "https://api.contentstack.io/v3",
  "extensionHost": "https://app.contentstack.com",
  "contentVersion": 2,
  "preserveStackVersion": false,
  "master_locale": {
    "name": "English - United States",
    "code": "en-us"
  },
  "target_stack": "bltXXXXXXXXXX",
  "data": "./import-data",
  "branchName": "main",
  "moduleName": null,
  "contentTypes": [],
  "skipAssetsPublish": false,
  "skipEntriesPublish": false,
  "entriesPublish": true,
  "concurrency": 1,
  "importConcurrency": 5,
  "fetchConcurrency": 5,
  "writeConcurrency": 5,
  "delayMs": 1000,
  "maxContentLength": 100000000,
  "maxBodyLength": 100000000,
  "skipAudit": false,
  "skipExisting": false,
  "replaceExisting": false,
  "importWebhookStatus": "disable",
  "personalizeProjectName": null,
  "exclude-global-modules": false,
  "backupDir": "./backup",
  "createBackupDir": "./temp",
  "cliLogsPath": "./logs",
  "developerHubBaseUrl": "",
  "marketplaceAppEncryptionKey": "nF2ejRQcTv",
  "getEncryptionKeyMaxRetry": 3,
  "auditConfig": {
    "noLog": false,
    "skipConfirm": true,
    "returnResponse": true,
    "noTerminalOutput": false,
    "config": {
      "basePath": ""
    }
  },
  "modules": {
    "apiConcurrency": 5,
    "assets": {
      "assetBatchLimit": 1,
      "uploadAssetsConcurrency": 2,
      "importFoldersConcurrency": 1,
      "importSameStructure": true,
      "includeVersionedAssets": false,
      "displayExecutionTime": false,
      "host": "https://api.contentstack.io",
      "validKeys": ["title", "parent_uid", "description", "tags"],
      "folderValidKeys": ["name", "parent_uid"]
    },
    "entries": {
      "importConcurrency": 5,
      "chunkFileSize": 10
    },
    "content-types": {
      "limit": 100,
      "validKeys": ["title", "uid", "schema", "options", "singleton", "description"]
    },
    "global-fields": {
      "limit": 100,
      "validKeys": ["title", "uid", "schema", "options", "singleton", "description"]
    },
    "taxonomies": {
      "dirName": "taxonomies",
      "fileName": "taxonomies.json"
    },
    "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"
      },
      "importData": true,
      "importOrder": ["attributes", "audiences", "events", "experiences"],
      "project_id": "",
      "experiences": {
        "thresholdTimer": 60000,
        "checkIntervalDuration": 10000
      }
    },
    "variantEntry": {
      "apiConcurrency": 5,
      "query": {
        "locale": "en-us"
      }
    }
  },
}

Command: csdx cm:stacks:audit

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

Default modules: ['content-types', 'global-fields', 'entries', 'extensions', 'workflows', 'custom-roles', 'assets', 'field-rules']

Default fix-fields: ['reference', 'global_field', 'json:rte', 'json:extension', 'blocks', 'group', 'content_types']
Default schema-fields-data-type: ['blocks', 'group', 'global_field']

Default systemKeys: ['uid', 'ACL', 'tags', 'locale', '_version', '_metadata', 'published', 'created_at', 'updated_at', 'created_by', 'updated_by', '_in_progress', '_restore_status', 'publish_details']

When using the --config flag with audit commands, you can pass external configuration options:

Example external config file:

{
  "noLog": false,
  "skipConfirm": true,
  "returnResponse": true,
  "noTerminalOutput": false,
  "basePath": "./export-data"
}

Command: csdx cm:stacks:export-query

*Required unless using CLI flags or management token alias

Default exportOrder: ['stack', 'locales', 'environments', 'content-types', 'global-fields', 'extensions', 'taxonomies', 'entries', 'assets']

Note The modules.dependent array includes marketplace-apps and personalize in addition to the listed modules.

Note Use the --alias flag to specify a management token alias instead of providing credentials directly in the configuration file.

{
  "host": "https://api.contentstack.io/v3",
  "exportDir": "./query-export-data",
  "stackApiKey": "bltXXXXXXXXXX",
  "branchName": "main",
  "query": {
    "title": {
      "$regex": "blog"
    }
  },
  "skipReferences": false,
  "skipDependencies": false,
  "skipStackSettings": false,
  "securedAssets": false,
  "fetchConcurrency": 5,
  "writeConcurrency": 5,
  "batchSize": 100,
  "personalizationEnabled": false,
  "maxCTReferenceDepth": 20,
  "queryConfig": {
    "maxRecursionDepth": 10,
    "batchSize": 100,
    "metadataFileName": "_query-meta.json",
    "validation": {
      "maxQueryDepth": 5,
      "maxArraySize": 1000,
      "allowedDateFormats": ["ISO8601", "YYYY-MM-DD", "MM/DD/YYYY"]
    }
  },
  "modules": {
    "general": ["stack", "locales", "environments"],
    "queryable": ["content-types"],
    "dependent": ["global-fields", "extensions", "marketplace-apps", "taxonomies", "personalize"],
    "content": ["entries", "assets"],
    "exportOrder": [
      "stack",
      "locales",
      "environments",
      "content-types",
      "global-fields",
      "extensions",
      "taxonomies",
      "entries",
      "assets"
    ]
  }
}

Command: csdx cm:stacks:import-setup

Each module can specify dependencies that must be imported first:

Default taxonomies invalidKeys: ['updated_at', 'created_by', 'updated_by', 'stackHeaders', 'urlPath', 'created_at', 'ancestors', 'update', 'delete', 'fetch', 'descendants', 'move', 'search']

Command: csdx cm:stacks:migration

Migration uses either inline configuration or external JSON files.

Use --config flag with key-value pairs:

csdx cm:migration --config key1:value1 key2:value2 --file-path <migration/script/file/path>

Use --config-file flag with JSON file:

{
  "apiKey": "your-api-key",
  "branch": "main",
  "customKey": "customValue"
}

Note Use the --alias flag to specify a management token alias instead of providing managementToken in the configuration file.

Note Migration configuration is script-specific and varies based on your migration requirements.

Performance Tuning

{
  "fetchConcurrency": 10,
  "writeConcurrency": 10,
  "delayMs": 500
}

Export Specific Content Types

{
  "contentTypes": ["blog_post", "author"],
  "moduleName": "entries"
}

Import with Backup

{
  "backupDir": "./backup",
  "createBackupDir": "./temp-backup"
}

1. Path Formatting:

   • Mac/Linux: Use forward slashes /
   • Windows: Use double backslashes \\\\ or forward slashes /

2. Authentication:

   • Always use --alias flag instead of hardcoding tokens
   • Never commit configuration files with credentials

3. Module Dependencies:

   • Import/export modules in correct order
   • CLI handles dependencies automatically for full imports/exports

4. Performance:

   • Adjust concurrency based on API rate limits
   • Use delayMs to avoid rate limiting
   • Monitor maxContentLength and maxBodyLength for large operations

5. Backup:

   • Always provide backupDir when importing modules individually
   • Maintain mapping files across multiple imports

Issue: Horizontal scrolling on tables
Solution: Use collapsible sections (details/summary tags) for module-specific configs

Issue: Configuration not being read
Solution:

• Verify JSON syntax is valid
• Check file path is correct
• Ensure required fields are present

Issue: Rate limiting errors
Solution:

• Reduce fetchConcurrency and writeConcurrency
• Increase delayMs between requests