Migrate content to other environments

Migrate your content and assets

Once your environments are synced, you’re ready to migrate content items (language variants) and assets using the migrate-content command. This command is ideal for:

• Restoring content and assets between environments.
• Promoting content from staging to production.
• Copying content from production to test or transitional environments.

Prepare which content to migrate 

Before migrating content, it’s important to plan and understand your migration options. A few minutes of preparation can save hours of post-migration cleanup. The migrate-content command offers flexible parameters to help you scope the migration according to your needs.  To run the command, the minimal required parameters are:

• Environment IDs: Required to identify both source and target environments.
• Management API key: Required for both source and target environments, with read/write permissions.
• Language: Define which language to include in the migration.

Define your parameters, which are mutually exclusive. 

• Use items when you know the exact codenames of the content items you want to migrate.
  • Codenames for items can be found in More actions > Codename.
• Use the filter parameter to apply custom Delivery API filters and narrow down which items are migrated. 
• Apply the depth parameter to control how many levels of linked items are included.
• Choose the byTypesCodenames parameter to filter content items by their content type.

For a complete list of available parameters and their usage, refer to the documentation in GitHub.

Choose a migration approach

To run a successful content migration, choose an approach that best suits your needs. You can either create a snapshot or run the migration directly.

• Snapshot: Creates a ZIP file containing selected content items and assets. You can preview which items will be affected without making any changes. Snapshots are useful for versioning, auditing, testing, storing content offline, and preparing content for external processing or transformation.
• Direct migration: Executes the migration immediately and applies changes to the target environment. It’s best used when you‘re confident in the migration setup and ready to migrate content. 

What gets migrated? 

Only content items and assets are migrated. However, if the target environment already contains any of the entities listed below, they will remain unchanged. The migration process performs a patch operation—it updates existing content rather than replacing it entirely. Entities excluded from the migration:

• Assignees
• Content item history 
•  Workflows
• Tasks, notes, and comments

Run the migration

Before you start the migration, double-check:

• Environment IDs
• API keys
• Any filters you’ve applied.

These details help ensure the command targets the right content and destination. Before executing the migration, the CLI prints a list of content item codenames that will be affected. Review this list carefully to ensure only the intended items are included. This helps avoid accidental overwrites or updates.  After running the command, review the logs for errors and confirm that the expected content and assets appear in the target environment. It’s also a good practice to spot-check key items and run automated tests if you have them. This helps to make sure that everything is transferred correctly and is working as expected.

Considerations