Join us Nov. 5 for our Fall Product Update
Contentstack
search
Changelog

Import Content Using the CLI

After exporting content from a source stack, use the Contentstack CLI to import it into a destination stack.

This guide explains how to use the cm:stacks:import command by logging in to CLI (or with a management token), using configuration files or direct CLI parameters.

Prerequisites

Supported Modules

Note: Imported content will be published to the same environment and locale as in the source stack. Unpublished content in the source stack will remain 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>> -d <<path_of_folder_where_content_is_stored>>

Options

Use the following options with any applicable import command:

  • -k, --stack-api-key=stack-api-key: API key of the target stack.
  • -a, --alias: Management token alias of the destination stack.
  • -d, --data-dir=data-dir: Absolute path to the folder with your exported content.
    Example: -d "C:\Users\Name\Desktop\cli\content".
    If using branches, include the branch folder in the path: -d "C:\Users\Name\Desktop\cli\content\branch_name"
  • --branch=branch: [default: main] Name of the branch to import content into.
  • --branch-alias=branch-alias: Alias of the branch to import content into.
  • --exclude-global-modules: Exclude branch-independent modules from the import operation.
  • --module=module: (optional) Export a specific module from the source stack. If not specified, all modules are exported.
    Available modules: assets, content-types, entries, environments, stacks, extensions, marketplace-apps, global-fields, labels, locales, webhooks, workflows, custom-roles, taxonomies, personalize.
  • --backup-dir=backup-dir : (optional) Backup directory name for a specific module.
  • --import-webhook-status=<option>: [default: disable] Maintain webhook state configuration from the source stack. <options: disable|current>
  • --skip-audit: (optional) Skip the audit fix that occurs during import.
  • --skip-app-recreation: (optional) Skip the recreation of private apps if they already exist.
  • --skip-assets-publish: Skip asset publishing during import.
  • --skip-entries-publish: Skip entry publishing during import.
  • -y, --yes: Force override all Marketplace prompts.
  • -c, --config=config: Path to the configuration JSON file containing all the options for a single run.

Note:

  • If you don’t use the --yes flag during import, you’ll be prompted to enter an encryption key for Marketplace App configurations. You can attempt up to three times to enter the correct key. After three failed attempts, the import process will stop and must be restarted from the beginning.
  • If you don’t use the --skip-audit flag, the audit step will remove all workflow branches except the one you're importing into. For example, if your source stack has main, development, and production branches, and you import into the development branch, the audit will remove the main and production branches from the workflow module to ensure a clean import.

Using Configuration File

You can also import content using a configuration file.

To get started, follow the steps below:

  1. Download the configuration file.
  2. Add your values.
  3. Note the path where the file is saved.

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"
Note:
  • Mac OS users must use "\" for paths in a JSON file.
  • Windows OS users must use "\\" for paths in a JSON file.

Import Content Using Management Token

You can also import content to your stack using a management token.

Usage

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

Alternatively, refer to the following command to add several parameters or options in a single line:

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

You can also import content by using a management token and a configuration file that contains the parameters or options and the associated values.

By doing so, you don’t need to separately provide parameters or options in the command.

Usage:

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

Example:

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

Module-wise Import

The --module flag in the import command allows module-specific imports into the target stack. Specify a module to import only that module. To import all modules, avoid using the flag.

Available modules include:

  • assets
  • content-types
  • entries
  • environments
  • stacks
  • extensions
  • marketplace-apps
  • global-fields
  • labels
  • locales
  • webhooks
  • workflows
  • custom-roles
  • taxonomies
  • personalize

This feature enhances control and efficiency in managing stack data.

Note: Before importing a module, ensure its dependent modules are imported first. When importing individually, follow this sequence:
Locales → Environments → Assets → Taxonomies → Extensions → Marketplace Apps → Webhooks → Global Fields → Content Types → Workflows → Entries → Labels → Custom Roles.
For example, before importing entries, you must first import locales, environments, assets, taxonomies, extensions, marketplace-apps, webhooks, global-fields, content-types, and workflows.

Example:

  • To import only locales:
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module locales

Use of --backup-dir Flag

Including the --backup-dir flag is essential when repeatedly using the single module import command. Due to module inter-dependencies, the backup flag helps avoid import errors.

csdx cm:stacks:import -k <<stack_ApiKey>> -d <<path_of_folder_where_content_is_stored>> --module <<module>> --backup-dir <<backup_dir>>

For every import module operation, all the latest mapping files are added to a single mapper folder. Dependent modules use the latest UIDs of the dependency for efficient mapping.

More Examples

To import assets into a stack:

csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module assets

To import entries into a stack:

csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module entries --backup-dir <<backup_dir>>

Note: The parent backup folder created during the initial import can be reused for subsequent module imports. To ensure a smooth import process, always provide this backup folder when importing modules individually.

Import Overwrite Feature

The Overwrite feature in the import command enhances the import process by allowing you to seamlessly update the existing content within a stack. By using this feature, you can prevent an import failure if an imported module already exists in the target stack.

Learn more in the Overwrite Existing Content using CLI Import guide.

Limitations

  • Only the latest version of a published entry or asset is imported.
  • When importing workflows, admins and workflow stage users are not included in the migration.
  • To resolve the maxContentLength and maxBodyLength errors, include these parameters in the configuration JSON with values specified in bytes. The default limit is 100 MB. For implementation details, refer to the example configuration file.
  • Currently, we import only the latest version of entries and assets.
  • Currently, the following modules cannot be imported:

Additional Resources: Learn more about the CLI-supported import operations in the CLI-Supported Features for Export, Import, and Clone Operations document.

More articles in "Contentstack CLI Core Commands"