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.

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)

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

• Export a stack or content:
  1

  csdx cm:stacks:export

• Import content into a stack:
  1

  csdx cm:stacks:import

• Export specific content only:
  1

  csdx cm:stacks:export-query

• Audit schema and entries:
  1

  csdx cm:stacks:audit

• Set up mapping and dependencies before import:
  1

  csdx cm:stacks:import-setup

• Run custom content transformations:
  1

  csdx cm:stacks:migration

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.

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

NoteDisabling 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

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

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

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

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.

• 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

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.

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

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.

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

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"]
    }
  }
}

Use this configuration to import content and stack metadata into a target stack, typically after an export or as part of a migration workflow. This section describes the root-level and module-specific options that control how content is imported and published.

Command: csdx cm:stacks:import

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

Note The target_stack and data fields are required unless they are provided through CLI flags or a management token alias.

Recommended starting point: Start by tuning importConcurrency, which controls overall import parallelism. Use module-level overrides for targeted optimization, and treat fetchConcurrency and writeConcurrency as advanced tuning options.

Additional Resource Refer to the Configuration Precedence section for a detailed explanation and examples.

Assets Module

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

Default folderValidKeys: ["name", "parent_uid"]

Note Folder hierarchy during import follows folders.json, not modules.assets.importSameStructure. The importSameStructure setting (default: true) only controls asset replace or skip behavior.

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

Note limit and assetBatchLimit are defined in config but not actively used in the entries import code.

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

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', 'multiple', '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,
  "skipPrivateAppRecreationIfExist": 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": {
      "limit": 50,
      "assetBatchLimit": 5
    },
    "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"
      }
    }
  }
}

Follow these best practices for Contentstack CLI imports:

• Set branchName or branchAlias for non-default branch imports. Verify the branch exists (or the alias resolves). The CLI does not create branches, so the import fails if the branch is missing.
• Backup your export data using one of these methods:
  • Create a new backup: Set createBackupDir to a dedicated path in the config. If that path already exists, the CLI removes it before creating the backup directory and copying your export data.
  • Reuse an existing backup: Pass the --backup-dir flag or set useBackedupDir in the config.

  Note After each run, the CLI logs the actual backupDir used. Setting backupDir in the config alone does not control the backup location. Use createBackupDir or useBackedupDir (or --backup-dir) to define it.

• Verify content publishing behavior before import using entriesPublish, skipEntriesPublish, and skipAssetsPublish.

Warning skipExisting and replaceExisting are high-impact flags that control whether content is skipped or overwritten.

Use the Audit configuration to analyze stack schemas and entries for structural or data-related issues. Audit identifies inconsistencies and provides a summary of potential problems across supported modules.

Follow this workflow to ensure a safe and predictable migration:

• Export: Export stack content with the CLI into the expected folder layout.
• Audit: Run csdx cm:stacks:audit against that folder (read-only; reports under audit-report).
• Fix (optional): Run csdx cm:stacks:audit:fix only when you want to modify files; use --copy-dir or --copy-path to keep a safe copy.
• Import / migrate: Import or migrate using the cleaned export in a separate step.

Note Audit does not export or import data. Always point --data-dir or basePath to the root of your export.

Command: csdx cm:stacks:audit

Default Configuration: Refer to the default audit configuration file in the CLI repository to understand included modules, supported fixes, and reporting behavior.

Limit audit modules to shorten runs on large exports, skip unnecessary areas, or narrow testing. The modules array defines these audit pipelines.

Supported modules:

• content-types
• entries
• assets

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"
}

Follow these practices when using the Audit plugin:

• Use CLI export data in the expected layout. Review the default audit configuration for details. Older or non-CLI exports might lack matching module paths and filenames.
• Set --data-dir or basePath to the root of the exported data. For branch-enabled stacks, point directly to the branch folder inside the export and not to a parent directory.
• Use --copy-dir with cm:stacks:audit:fix to back up the export before writing fixes. Use --copy-path to specify a custom backup location. Avoid applying fixes directly to your main copy.
• Split large audits using --modules or the modules config to reduce memory usage and isolate issues. The entries module is typically the most resource-intensive.
• Increase Node.js memory (for example, NODE_OPTIONS=--max-old-space-size=4096) if audit runs fail on very large datasets.
• Use --fix-only for targeted fixes instead of applying all supported fix types.
• Use skipConfirm: true in non-interactive environments to apply fixes without prompts. Always maintain a backup or version-controlled copy before running fixes.

Use this configuration when you need to export a subset of stack content that matches a specific query, rather than exporting the entire stack. A successful run creates an export directory containing the matched content and a query metadata file describing the export.

A successful query export creates the specified exportDir containing the exported modules and a _query-meta.json file that describes the export.

Command: csdx cm:stacks:export-query

Note The exportDir and stackApiKey fields are required unless they are provided through CLI flags or a management token alias.

The query field supports two formats based on where it is defined: CLI input (string) and config file (object).

CLI (--query as a string)

Pass the query as either a file path or inline JSON:

• If the value contains .json, /, or \, the CLI treats it as a file path and loads the JSON.
• Otherwise, it parses the value using JSON.parse, so it must be valid JSON.

Config file (as an object)

Define module-specific filters under query.modules.<moduleName>:

• Do not use a flat query object for filtering.
• Each module filter is merged into the corresponding module API request.

For entries:

• The filter is applied inside the nested query object used by the Content Management API.
• Supports Mongo-style operators such as $regex.

Example:

{
 "query": {
   "modules": {
     "entries": {
       "title": { "$regex": "blog" }
     }
   }
 }
}

You can set these modules.* keys in any order in your JSON file. The modules.exportOrder key controls the runtime sequence of the export. Keep the default setting unless you understand module dependencies, such as exporting stacks and locales before content types and entries.

Warning Arbitrary reordering can break or omit data.

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.

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

Use this configuration to prepare module dependencies and mappings required for a successful import. Import-Setup is typically run before the Import command to ensure dependent modules are created in the correct order.

Command: csdx cm:stacks:import-setup

Each module can specify dependencies that must be imported first.
Dependencies define the order in which modules are imported. The CLI uses them to automatically import required modules first, avoiding reference or schema errors.

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

Use Migration Configuration to run user-defined scripts during CLI execution for advanced schema or content changes beyond export and import.
Running a migration executes the specified script against the target stack.

• Script controls all changes: The script fully determines all content and schema changes. The CLI does not validate, restrict, or preview the resulting operations.
• Permissions define impact: Migrations run with the configured management token or session, so the scope of changes depends entirely on that credential’s permissions. The CLI does not add restrictions. Use least-privilege tokens to limit risk.
• No built-in safety checks: The CLI does not prompt before destructive or bulk actions (for example, deleting a content type). Add safeguards in your script, such as prompts, environment checks, or conditional logic.

Note Migration behavior depends on the logic defined in the migration script. Test migrations in non-production environments before applying them to production stacks.

Command: csdx cm:stacks:migration

Migration uses either an inline configuration or external JSON files.

Inline Configuration

Use the --config flag with key-value pairs:

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

Replace the placeholders with keys expected by your script.

External Configuration File

Use the --config-file flag with a JSON file:

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

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

• Export Content Using CLI
• Import Content Using CLI
• Overwrite Existing Content using CLI Import