Import Content Using the CLI

After exporting content from a source stack, unzip the exported file and then use the Contentstack CLI to import it into the destination stack.

This guide covers how to use the cm:stacks:import command with:

• Authentication via CLI login or a management token
• Content import using a configuration file or CLI parameters

Prerequisites

• Contentstack account
• Contentstack CLI installed
• CLI authenticated
• Configured management token (optional)
• Exported content extracted (unzipped) in a local folder

Supported Modules

• Assets
• Locales
• Environments
• Stacks (CLI supports Stacks from v1.43.0)
• Extensions
• Marketplace Apps
• Webhooks
• Global Fields (CLI supports Nested Global Fields from v1.42.0)
• Content Types
• Entries
• Labels
• Workflows
• Custom Roles
• Taxonomies
• Personalize
• Studio

Note: Imported content gets published to the same environment and locale as in the source stack. Unpublished content in the source stack remains unpublished after import.

Commands

The cm:stacks:import command lets you import content into your destination stack.

Note: By default, an audit fix is performed on the exported content before import. This helps identify and address potential issues in the exported data.

Usage

csdx cm:stacks:import -k <<stack_ApiKey>> --data-dir <<path_of_folder_where_content_is_stored>>

Options

Use the following options with any applicable import command:

Module-wise Import

Use the --module flag in the import command to import individual modules into the target stack. If you do not use the flag, the import command includes all available modules by default.

Importing an Export Produced by an Older CLI Version

Two behaviours differ when the folder you pass to --data-dir was produced by CLI V1 rather than V2. Both fail quietly, so check for them before you rely on the result.

The cause is a change in file layout. The V2 importer reads one file per UID and ignores the aggregate files that V1 wrote:

To resolve it, re-export the source stack with the current CLI before importing.

The second difference affects multi-branch V1 exports. V1 wrote a branches.json file at the export root and the V1 importer used it to navigate into the correct branch subfolder automatically. The current importer does not do this. Point --data-dir at the branch subfolder yourself:

csdx cm:stacks:import --stack-api-key bltxxxxxx --data-dir ./my-v1-export/main

Pointing it at the export root instead finds no content files there, and the command completes and reports success having imported nothing.

Dependency Order

Some modules depend on others. When importing modules individually, follow this sequence to avoid errors:

Locales → Environments → Assets → Taxonomies → Extensions → Marketplace Apps → Webhooks → Global Fields → Content Types → Workflows → Entries → Labels → Custom Roles → Publishing Rules → Personalize → Composable Studio.

Note: Before importing a module, ensure all its dependencies have been imported.

Example:

• To import only locales:
  csdx cm:stacks:import --stack-api-key bltxxxxxx --data-dir "C:\Users\Name\Desktop\cli\content" --module locales

Use of --backup-dir Flag

When importing modules individually with the import command, include the --backup-dir flag to prevent errors caused by inter-module dependencies. This flag stores mapping files that are required by dependent modules in future imports.

csdx cm:stacks:import --stack-api-key <<stack_ApiKey>> --data-dir <<path_of_folder_where_content_is_stored>> --module <<module>> --backup-dir <<backup_dir>>

During each module import, the system saves updated mapping files in the specified backup folder. These mappings are reused by dependent modules to ensure consistent and successful imports.

Note: The parent backup folder created during the initial import can be reused for subsequent module imports. To avoid errors, always include the --backup-dir flag when importing modules one at a time.

Examples

• To import assets into a stack:
  csdx cm:stacks:import --stack-api-key bltxxxxxx --data-dir "C:\Users\Name\Desktop\cli\content" --module assets
• To import entries into a stack with backup mapping:
  csdx cm:stacks:import --stack-api-key bltxxxxxx --data-dir "C:\Users\Name\Desktop\cli\content" --module entries --backup-dir <backup_dir>

Using Configuration File

You can also import content using a configuration file that stores all required parameters and values.

To get started, follow the steps below:

• Download the configuration file.
• Add your values.
• Save the file and note its path.

Usage

csdx cm:stacks:import -c <<config_file_path>>

Example

• To import content using a configuration file:
  csdx cm:stacks:import -c "C:\Users\Name\Desktop\cli\config.json"

Using a configuration file simplifies the import process by storing all required parameters and values in one place. This removes the need to enter each option manually and is helpful for repeated or complex imports.

Import Content Using Management Token

Use a management token to import content into a stack when you prefer token-based authentication instead of CLI login. You can pass the token directly through the command line or reference it from a configuration file.

Usage

csdx cm:stacks:import -a <<alias>>

Optional Parameters:

• --data-dir <path_of_folder_where_content_is_stored>: Specify the folder where the content is located.
• -c <config_file_path>: Use a configuration file that contains all import parameters.

Examples:

• To import content from a specific folder:
  csdx cm:stacks:import --alias mytoken --data-dir "C:\Users\Name\Desktop\cli\import-folder"
• To import content using a configuration file:
  csdx cm:stacks:import --alias mytoken -c "C:\Users\Name\Desktop\cli\config.json"

Import Overwrite Feature

Use the --replace-existing flag in the import command to overwrite the existing content in the target stack. This prevents import failures caused by module collisions and ensures that existing items are overwritten while new items are added.

When the import process detects a module that already exists in the target stack, the CLI replaces it instead of throwing an error. If the module does not exist, the CLI creates it as a new item.

Example:

csdx cm:stacks:import --replace-existing --backup-dir <backup-dir-path> --stack-api-key <value> --data-dir <content-dir-path>

For more details, refer Overwrite Existing Content using CLI Import document.

Toggle Between Console Logs and Progress Manager View (2.x.x-beta)

Contentstack CLI lets you toggle between the raw console logs and the visual Progress Manager UI during import or plugin workflows.

Default Usage:

csdx cm:stacks:import --data-dir "./export-data" --stack-api-key bltxxxxxx

Note: By default, the Progress Manager UI displays when you run the import command and does not require any configuration.

Example for Progress Manager View (Default Mode):

LOCALES:
   ├─ Master Locale        |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)
   ├─ Locales Create       |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (0/1)
   ├─ Locales Update       |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)

ENVIRONMENTS:
    └─ Environments        |████████████████████████████████████████| 100% | 2/2 | ✓ Complete (2/2)

STACK:
    └─ Stack               |██��█████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)

ASSETS:
   ├─ Folders              |████████████████████████████████████████| 100% | 2/2 | ✓ Complete (2/2)
   ├─ Upload               |████████████████████████████████████████| 100% | 12/12 | ✓ Complete (12/12)
   ├─ Publish              |████████████████████████████████████████| 100% | 12/12 | ✓ Complete (12/12)

TAXONOMIES:
    └─ Taxonomies          |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)

EXTENSIONS:
   ├─ Extensions Create    |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1)

Steps to Switch to Console Logs (Optional):

1. Run the following command to switch to console log mode:
   csdx config:set:log --show-console-logs

2. Run the import command:
   csdx cm:stacks:import --data-dir "./export-data" --stack-api-key bltxxxxxx

   The screen displays the console logs for the import operation.

   Tip: Use --show-console-logs for detailed debugging when troubleshooting import issues.

3. Run the following command to switch back to default mode:
   csdx config:set:log --no-show-console-logs

Options:

Example for Console Log Mode:

[2025-09-10 19:19:02] INFO: Audit process completed
[2025-09-10 19:19:03] INFO: Starting to import content version 2
[2025-09-10 19:19:03] INFO: Starting import of locales module
[2025-09-10 19:19:05] INFO: Created locale: 'fr-fr'
[2025-09-10 19:19:07] INFO: Updated locale: 'fr-fr'
[2025-09-10 19:19:07] SUCCESS: Languages have been imported successfully!
[2025-09-10 19:19:07] INFO: Starting import of environments module

Limitations

• Only the latest version of published entries or assets is imported.
• Workflow imports do not include admins or workflow stage users.
• To resolve maxContentLength and maxBodyLength errors, include these parameters in the configuration JSON with values in bytes. The default limit is 100MB. For implementation details, refer to the example configuration file.
• To manage API request timing and prevent concurrency issues, add the delayMs parameter to your configuration JSON.
  Example: delayMs: 1000 (adds a 1-second delay between API requests).
• The following modules cannot be imported through CLI:
  • Users
  • Releases

Additional Resource: Learn more about the CLI-supported import operations in the Support for CLI-Based Stack Import Operations document.