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.

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"]
  --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.

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:

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

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 many options to allow you to specify your migration in a granular way. You can learn about this through our migration examples.