cs-icon.svg

Import Content using the CLI

Note: The Taxonomy feature is currently released as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.

Once you have exported the content from the source stack, the next step is to import it into the destination stack. To do this, you can use the import command in several ways.

Note: Before using the import command, make sure you have successfully unzipped the exported content located within the corresponding folder.

Content can be imported into a stack for the following modules:

Note: The imported content in the target or the destination stack will be automatically published to the environment and locale in which it was previously published in the source stack. If any exported content has not been published on any environment, that specific content will not be published to any environment upon import into the target stack.

Prerequisites

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 prior to executing the import operation. This helps in identifying and addressing any potential issues in the exported stack data.

Below we have listed down different ways in which you can use the cm:stacks:import command:

Let's discuss how you can import content into your stack in detail.

Note: If the export folder has branches, the path or location in your file system where you intend to import the content should point till the particular branch folder (absolute path). For example, -d "C:\Users\Name\Desktop\cli\content\branch_name".

Import Content Using Management Token and Parameters

This command lets you import content using a management token. For ease, you can pass several parameters/options to this command at once.

Usage

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

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

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

Options

  • -c--config=config: [optional] Path of config file.
  • -k--stack-api-key=stack-api-key: API key of the target stack.
  • -a, --alias: The management token of the destination stack where you will import the content.
  • -d, --data-dir=data-dir: The path or the location in your file system where the content, you intend to import, is stored. For example, -d "C:\Users\Name\Desktop\cli\content". If the export folder has branches involved, then the path should point till the particular branch. For example, -d "C:\Users\Name\Desktop\cli\content\branch_name".
  • --branch=branch: The name of the branch where you want to import your content. If you don’t mention the branch name, then by default the content will be imported to the main branch.
  • --module=module: (optional) Specify the module to import into the target stack. If not specified, the import command will import all the modules into the stack. The available modules are assets, content-types, entries, environments, extensions, marketplace-apps, global-fields, labels, localeswebhooks, custom-roles, workflows and taxonomies.
  • --backup-dir=backup-dir : (optional) Backup directory name when using specific module.
  • --import-webhook-status=disable: (default) This webhook state force-disables the destination stack webhooks.
  • --import-webhook-status=current: (optional) This webhook state keeps the same state of webhooks as the source stack.
  • --skip-audit: (optional) Skips the audit fix that occurs during an import operation.
  • -y, --yes: Force override all Marketplace prompts.

    Note: If the --yes flag is not passed, you are prompted to enter an encryption key while importing the Marketplace App for the app configurations. You have 3 attempts to enter the correct encryption key for the Marketplace App configurations while using the import command. You must start the import process from the beginning after 3 failed attempts.

After importing the first module, note the name of the backup folder that was created in the workspace or in the code editor’s CLI folder.

Note: The parent backup folder created after the first import can be used to save all the backups in a single folder as it gets updated after every import operation.

When importing modules using the import command, provide the backup flag --backup-dir along with the backup folder name as follows:

csdx cm:stacks:import -a <<alias>> -d <<path_of_folder_where_content_is_stored>> --module <<module>> --backup-dir <<backup_dir>>

Including the backup flag is essential when repeatedly using the single module import command. As these modules have inter-dependency, using the backup flag helps avoid any errors while importing. 

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

Examples

  • To import all modules into a stack:
    csdx cm:stacks:import -a mytoken  -d "C:\Users\Name\Desktop\cli\content"
    
  • To import all modules in a particular branch of your stack (For example: develop).
    csdx cm:stacks:import -a mytoken -d "C:\Users\Name\Desktop\cli\content" --branch develop
    
  • To import only locales into a stack:
    csdx cm:stacks:import -a mytoken  -d "C:\Users\Name\Desktop\cli\content" --module locales 
    
  • To import only entries into a stack:
    csdx cm:stacks:import -a mytoken  -d "C:\Users\Name\Desktop\cli\content" --module entries 
    
  • Including the backup flag to import only environments into a stack after your first module import.
    csdx cm:stacks:import -a mytoken -d "C:\Users\Name\Desktop\cli\content" --module environments --backup-dir _backup_123 
    
  • To import all modules into a stack by overriding any prompts:
    csdx cm:stacks:import -a mytoken  -d "C:\Users\Name\Desktop\cli\content" –y 
    

Note: - When importing modules individually, make sure you follow this module 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 have had imported assets, taxonomies, environments, locales, extensions, marketplace-apps, webhooks, global-fields, content-types, and workflows.
- You cannot import a single entry to a stack using CLI.

Import Content Using Management Token and Config file

This command lets you import content to your stack by using a management token and a configuration file that contains the parameters/options and the associated values.

To get started with this command, download this config file, add values to this file, and note down the path where you have saved this file.

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

Note:
  • Mac OS users must use "\" for paths in a JSON file.
  • Windows OS users must use "\\" for paths in a JSON file.

Usage

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

Options

  • -a, --alias: The management token of the destination stack where you will import the content.
  • -c, --config=config: The path of the JSON file containing all the options for a single run. You can refer to this example config file.

Example

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

Import Content Using Auth Token and Parameters

You can use this method to import content to your stack if you have logged in to the session using the Login command. Running the Login command generates an auth token, which is used in the command below.

Usage

Refer to the command below to add several parameters/options in a single line:

csdx cm:stacks:import -k <<stack_ApiKey>> -d <<path_of_folder_where_content_is_stored>>

Note: If the management token is not specified, by default import command uses Auth token.

Options

  • -k, --stack-api-key=stack-api-key: The API key of the target stack.
  • -d, --data-dir=data-dir: The path or the location in your file system where the content, you intend to import, is stored. For example, -d "C:\Users\Name\Desktop\cli\content". If the export folder has branches involved, then the path should point till the particular branch. For example, -d "C:\Users\Name\Desktop\cli\content\branch_name".
  • --branch=branch: The name of the branch where you want to import your content. If you don’t mention the branch name, then by default the content will be imported to the main branch.
  • --module=module: (optional) Specify the module to import into the target stack. If not specified, the import command will import all the modules into the stack. The available modules are assets, content-types, entries, environments, extensions, marketplace-apps, global-fields, labels, localeswebhooks, custom-roles, workflows, and taxonomies.
  • --skip-audit: (optional) Skips the audit fix that occurs during an import operation.
  • -y, --yes: Force override all Marketplace prompts.

    Note: If the --yes flag is not passed, you are prompted to enter an encryption key while importing the Marketplace App for the app configurations. You have 3 attempts to enter the correct encryption key for the Marketplace App configurations while using the import command. You must start the import process from the beginning after 3 failed attempts.

After importing the first module, note the name of the backup folder that was created in the workspace or in the code editor’s CLI folder.

Note: The parent backup folder created after the first import can be used to save all the backups in a single folder as it gets updated after every import operation.

When importing modules using the import command, provide the backup flag (b) along with the backup folder name as follows:

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

Including the backup flag is essential when repeatedly using the single module import command. As these modules have inter-dependency, using the backup flag helps avoid any errors while importing.

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

Examples

  • To import all modules into a stack:
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content"
    
  • To import all modules in a particular branch of your stack (For example: develop).
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --branch develop
    
  • To import only locales into a stack:
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module locales
    
  • To import only entries into a stack:
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module entries
    
  • Including the backup flag to import only environments into a stack after your first module import.
    csdx cm:stacks:import -k bltxxxxxx -d "C:\Users\Name\Desktop\cli\content" --module environments --backup-dir _backup_123
    
  • To import all modules into a stack by overriding any prompts:
    csdx cm:stacks:import -a mytoken  -d "C:\Users\Name\Desktop\cli\content" –y 
    

Note: - When importing modules individually, make sure you follow this module 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 have had imported assets, taxonomies, environments, locales, extensions, marketplace-apps, webhooks, global-fields, content-types, and workflows.
- You cannot import a single entry to a stack using CLI.

Import Content Using Auth Token and Config file

This command lets you import content to your stack by using auth token and a configuration file that contains the parameters/options and the associated values.

To get started with this command, download this config file, add values to this file, and note down the path where you have saved this file.

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

Note:
  • Mac OS users must use "\" for paths in a JSON file.
  • Windows OS users must use "\\" for paths in a JSON file.

Usage

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

Options

  • -c, --config: The path of the configuration JSON file containing all the options for a single run. You can refer to this example config file.

Example

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

Support for Marketplace Apps

You can import public and private Marketplace Apps to a stack using CLI commands.

Note:
  • You must be logged in to your Contentstack account to perform the import operation on Marketplace Apps.
  • You must have owner or admin rights to perform Marketplace Apps import.
  • The destination organization should have Marketplace Apps support enabled.
  • You can install only the latest version of a public or private Marketplace App via the CLI.
  • If you use a region other than NA, EU, Azure NA, Azure EU, or GCP-NA, you must provide the Developer Hub URL for the specific region when prompted.
  • To override the default Marketplace App Encryption Key you can replace the config.json file.

Public apps:

If an app with a configuration already exists in the destination organization, then while importing it from one organization to another, you can:

  • Update it with the new app configuration.
  • Skip updating the configuration (If you do not update the configuration, there may be some issues with the content which you import).
  • Exit to cancel the entire stack import process.

Private apps:

  1. If the imported app has the same name as any existing apps in the destination, you will be prompted to change the name of the imported app.

    Note: The app name must be 3-20 characters long.

  2. During the stack import process, if you acknowledge and confirm, the listed private app(s) will be re-created and installed.
  3. If you cancel the app re-creation, it may break the import process of entries/content types/global fields.
Note:
  • If an error occurs while importing a private or public app, you will be prompted to confirm whether or not you should proceed with the process. If you do not proceed, the import process stops. If you proceed, the entries/content types/global fields may be affected.
  • You cannot reuse any existing private apps during the import process.

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.

Note: This feature currently supports assets, extensionsglobal fields, content types, and entries.

Usage

csdx cm:stacks:import --replace-existing

or

csdx cm:stacks:import --skip-existing

Options

  • --replace-existing: Replace the existing module in the target stack.
  • --skip-existing: Skip the module exists warning messages.

Steps for Execution

Follow the steps below to perform overwrite operation on your target stack:

  1. Update the source stack modules that support the overwrite feature.
  2. Export the content of your source stack using the CLI export command.
  3. Import the content to your target stack using the CLI import command with the --replace-existing flag.
    csdx cm:stacks:import --replace-existing --module entries
    
  4. This overwrites the target stack with the updated modules.

Note: You can perform the Overwrite feature on branches as well.

Import Overwrite Limitation

Currently, we do not support a seamless replacement of existing assets. For now, we create a new root folder with the name Import- to import all assets when we use the --replace-existing flag with the import command. This distinguishes old and new assets.

Limitations

  • The import command will import only the latest version of a published entry/asset.
  • While importing workflows from one stack to another, admins and workflow stage users are not included. Therefore, admins and stage users of your workflows will not be migrated to the new stack.
  • Currently, you cannot import content for the following modules:

Additional Resources: Check out the Export Content documentation to learn how you can export content from your stack using CLI. 

Was this article helpful?
^