Importing and Exporting Content

Overview

Exporting and importing content is an important tool in many content-workflow processes. By the end of this tutorial, you will be able to export and import content and content models between spaces.

The tools

Our export, import, and migration tooling are separated into different command-line tools that can be installed and used separately.

The rest of this tutorial will assume the tools to have been installed using the following commands.

npm install -g contentful-import
npm install -g contentful-export
npm install -g contentful-migration-cli

Exporting content

After you have the export CLI tool installed and at the command line, run contentful-export [options].

The possible options are:

Options:
  --version [bool]               Display the version number.

  --space-id [string]            The ID of the space containing data to export.

  --management-token [string]    Use the Contentful management API token for
                                 the space you want to export.

  --export-dir [string]          Define the path where you want to store the
                                 exported JSON file.
                                 By default, the path is the current directory.

  --include-drafts [bool]        Include drafts in the exported entries.

  --skip-content-model [bool]    Skip exporting content models.

  --skip-content [bool]          Skip exporting assets and entries.

  --skip-roles [bool]            Skip exporting roles and permissions.

  --skip-webhooks [bool]         Skip exporting webhooks.

  --download-assets [bool]       Download assets.

  --max-allowed-limit [number]   Set a maximum number of items per http request.

  --management-host [string]     Set the host to call for the management API.
                                 The default is api.contentful.com.

  --proxy [string]               Configure the HTTP proxy.
                                 Specify it in HTTP auth format:
                                 host:port or user:password@host:port

  --error-log-file [string]      Specify the dull path to the error log file.

  --use-verbose-renderer [bool]  Display progress in more detail,
                                 which can be useful for debugging.

  --save-file [bool]             Save the export in JSON format.

  --config                       Use a configuration JSON file that
                                 contains all of the options.

All of these options can be put in an external config.json file. You can find a reference config file here.

Next, run your export.

contentful-export --config example-config.json

The exported JSON file has the following structure:

{
  "contentTypes": [],
  "entries": [],
  "assets": [],
  "locales": [],
  "webhooks": [],
  "roles": [],
  "editorInterfaces": []
}

You can use this structure with the import tool to import content into another space.

Limitations

  • This tool does not support exporting space memberships. They have to be manually created in the destination space.
  • For security reasons, exported webhooks do not contain authentication information. Therefore, you need to manually create credentials within the destination space.
  • Custom UI extensions are not exported. For managing extensions please use the Contentful CLI.

Importing content

After you have the import CLI tool installed and at the command line, run contentful-import [options] from your command line.

The possible options are:

Options:
  --version [bool]                 Display version number.

  --space-id [string]              The ID of the space to import content to.

  --management-token [string]      Use the Contentful management API token
                                   for the space you want to import to.

  --content-file [string]          The JSON file that contains the data to be
                                   imported into your space.

  --content-model-only [bool]      Import only content types.

  --skip-content-model [bool]      Skip importing content types and locales.

  --skip-locales [bool]            Skip importing locales.

  --skip-content-publishing [bool] Skips content publishing.
                                   Creates content but does not publish it.

  --error-log-file [string]        Specify the full path to the error log file.

  --proxy [string]                 Configure the HTTP proxy.
                                   Specify it in HTTP auth format:
                                   host:port or user:password@host:port

  --config                         Use a configuration JSON file that
                                   contains all of the options.

Similar to the export tool these settings can be stored in an external json file. You can find a reference config file here.

Note that you also need to reference a JSON file that contains the exported content. The expected format is the same as the export format from the export tool above.

Next, run your import.

contentful-import --config example-config.json

Limitations

  • This tool does not support the import of space memberships.
  • This tool is expecting the target space to have the same default locale as your previously exported space.
  • Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards.
  • If you have custom UI extensions, you need to reinstall them manually using the Contentful CLI.

Migrations

Contentful also provides a tool for content migrations. A migration is different from a direct export/import in that it also allows you to define content model changes that should be applied to the target space. For example you could opt to add completely new fields, or split an existing field into two.

The migrations CLI tool has its own powerful DSL (Domain Specific Language) that contains a multitude of options to allow you to specify your migration granularly. It is best learnt by visiting our migration examples.

Note: The migrations tool is still in BETA.

Older tooling

Note: The tools listed in this section are no longer officially supported as of May 11th, 2017. You are free to use them, fork them and patch them to suit your own needs. Downloads from RubyGems will still be available.