Importing and Exporting Content

Overview

Exporting and importing content are an importants aspects of 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

Exporting, importing, and the execution of migration scripts can all be done via the Contentful CLI. Install it with the following command:

npm install -g contentful-cli

Exporting content

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

The possible options are:

Options:
  -h, --help              Show help                                    [boolean]
  --space-id              ID of Space with source data                  [string]
  --environment-id        ID of Environment with source data
                                                    [string] [default: "master"]
  --export-dir            Defines the path for storing the export json file
                          (default path is the current directory)       [string]
  --include-drafts        Include drafts in the exported entries
                                                      [boolean] [default: false]
  --skip-content-model    Skip exporting content models
                                                      [boolean] [default: false]
  --skip-content          Skip exporting assets and entries
                                                      [boolean] [default: false]
  --skip-roles            Skip exporting roles and permissions
                                                      [boolean] [default: false]
  --skip-webhooks         Skip exporting webhooks     [boolean] [default: false]
  --content-only          only export entries and assets
                                                      [boolean] [default: false]
  --download-assets       With this flags assets will also be downloaded
                                                                       [boolean]
  --max-allowed-limit     How many items per page per request
                                                        [number] [default: 1000]
  --host                  Management API host
                                        [string] [default: "api.contentful.com"]
  --proxy                 Proxy configuration in HTTP auth format:
                          [http|https]://host:port or
                          [http|https]://user:password@host:port        [string]
  --error-log-file        Full path to the error log file               [string]
  --query-entries         Exports only entries that matches these queries[array]
  --query-assets          Exports only assets that matches these queries [array]
  --content-file          The filename for the exported data            [string]
  --save-file             Save the export as a json file
                                                       [boolean] [default: true]
  --use-verbose-renderer  Display progress in new lines instead of displaying a
                          busy spinner and the status in the same line. Useful
                          for CI.                     [boolean] [default: false]
  --config                An optional configuration JSON file containing all the
                          options for a single run

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 space 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 UI extensions please use the Contentful CLI.

Importing content

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

The possible options are:

  -h, --help                 Show help                                 [boolean]
  --space-id                 ID of the destination space                [string]
  --environment-id           ID the environment in the destination space
                                                    [string] [default: "master"]
  --content-file             JSON file that contains data to be import to your
                             space                           [string] [required]
  --content-model-only       Import only content types[boolean] [default: false]
  --skip-content-model       Skip importing content types and locales
                                                      [boolean] [default: false]
  --skip-locales             Skip importing locales   [boolean] [default: false]
  --skip-content-publishing  Skips content publishing. Creates content but does
                             not publish it           [boolean] [default: false]
  --no-update                Skips updating entries if they already exist
                                                      [boolean] [default: false]
  --error-log-file           Full path to the error log file            [string]
  --management-host          Management API host
                                        [string] [default: "api.contentful.com"]
  --proxy                    Proxy configuration in HTTP auth format:
                             [http|https]://host:port or
                             [http|https]://user:password@host:port     [string]
  --config                   An optional configuration JSON file containing all
                             the options for a single run

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 space 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.