Contentful export tool

Contentful provides a content infrastructure for digital teams to power content in websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.

This is a command line tool (CLI) that help you backup your published Content Model, Content and Assets or move them to a new Contentful space. It will support Editor Interfaces, Webhooks and Roles & Permissions in a future version.

To import your exported data, please refer to the contentful-import repository.

Installation

We recommend the installation of this CLI via npm:

npm install -g contentful-export

Usage and examples

Usage: contentful-export [options]

Options:
  --version               Show version number                          [boolean]

  --space-id              ID of Space with source data       [string] [required]

  --management-token      Contentful management API token for the space to be
                          exported                           [string] [required]

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

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

  --download-assets       With this flag assets will also be downloaded
                                                                       [boolean]

  --max-allowed-limit     How many items per page per request
                                                        [number] [default: 1000]

  --management-host       Management API host
                                        [string] [default: "api.contentful.com"]

  --proxy                 Proxy configuration in HTTP auth format: host:port or
                          user:password@host:port                       [string]

  --error-log-file        Full path to the error log file               [string]

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

  --save-file           Save the export as a json file [boolean] [default: true]

  --config              An optional configuration JSON file containing all the
                        options for a single run

The --management-token parameter allows you to specify a token used for both spaces. If you request a token from here and your user account has access to both spaces, this should be enough.

Check the example-config.json file for an example of what a configuration file looks like. If you use the configuration file, you don't need to specify the other options for tokens and space ids.

Example

Basic Usage

contentful-export \
  --space-id spaceID \
  --management-token managementToken

contentful-export --config example-config.json

You can create your own configuration file based on the example-config.json file.

Querying

To scope your export, you are able to pass query parameters. All search parameters of our API are supported as documented in our API documentation.

contentful-export \
  --space-id spaceID \
  --management-token managementToken
  --query-entries 'content_type=contentTypeId'

The Export tool also support multiple inline queries.

contentful-export \
  --space-id spaceID \
  --management-token managementToken
  --query-entries 'content_type=contentTypeId'
  --query-entries 'sys.id=<entry-id>'

--query-assets uses the same syntax as --query-entries

Exported data

This is an overview of the exported data:

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

Usage as a library

While this tool is intended for use as a command line tool, you can also use it as a Node library:

var spaceExport = require('contentful-export')
var options = {
  spaceId: '{space_id}',
  managementToken: '{content_management_api_key}',
  maxAllowedItems: 100,
  errorLogFile: 'filename',
  saveFile: false
  ...
}
spaceExport(options)
.then((output) => {
  console.log('Your space data:', output)
})
.catch((err) => {
  console.log('Oh no! Some errors occurred!', err)
})

The options object can contain any of the CLI options, but written with a camelCase pattern instead and no dashes. For example --space-id would become spaceId.

Limitations

This tool currently does not support the export of space memberships.
Exported webhooks with credentials will be exported as normal webhooks. Credentials should be added manually afterwards.
If you have custom UI extensions, you need to reinstall them manually in the new space.

Changelog

Read the releases page for more information.

License

This project is licensed under MIT license

christineywang / contentful-export