Importing and exporting content with the Contentful CLI

Learn how to export and import content and content models between spaces.

Requirements

• A (free) Contentful account.
• Locally installed contentful-cli.
• Authenticated with contentful-cli.

Export 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"]
  --management-token        Contentful management API token               [string]
  --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]
  --include-archived        Include archived entries 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-tags               Skip exporting tags         [boolean] [default: false]
  --skip-webhooks           Skip exporting webhooks     [boolean] [default: false]
  --skip-editor-interfaces  Skip exporting editor interfaces
                                                        [boolean] [default: false]
  --strip-tags              Untag assets and entries    [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]
  --raw-proxy               Pass proxy config to Axios instead of creating a
                            custom httpsAgent.                           [boolean]
  --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.

Import 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:

Options:
  -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"]
  --management-token, --mt   Contentful management API token            [string]
  --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]
  --error-log-file           Full path to the error log file            [string]
  --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]
  --rawProxy                 Pass proxy config to Axios instead of creating a
                             custom httpsAgent                         [boolean]
  --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. 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

Tips and limitations

When exporting/importing content, consider the following aspects:

• Content:
  • Entries must be in "Draft" or "Published" state. Entries in "Changed" state are automatically published.
  • Drafts are not included by default - set “include-drafts” to include them.
  • Required fields must have values when the content status is "Changed" or "Published".
  • The version history isn't migrated - will start fresh in the new space.
• Assets - Assets are migrated with content - no download is required.
• Default locale - The target space must have the same default locale as the source space.
• Releases, tasks, workflows - Scheduled releases, tasks, and workflows aren't migrated and must be scripted afterwards.
• Tags - Tags are migrated with content. However, the tags must be present in the target space under the Settings.
• Webhooks - For security reasons, webhooks are exported without the credentials. Credentials must be manually created in the destination space.
• Space memberships - Export/import of space memberships isn't supported. They must be manually created in the destination space.
• CMA Token / Personal Access Token (PAT) - When importing content with the CLI, all entries are recreated using the CMA token or Personal Access Token (PAT) of the user running the script. This means the imported content will appear as if it was created by the token owner, resulting in the loss of author history.
• Apps / UI extensions - Custom apps or UI extensions aren't exported and must be reinstalled 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 many options to allow you to specify your migration in a granular way. You can learn about this through our migration examples.