Contentful migrations

On this page
  • Content & schema migrations

Content & schema migrations

For migrations you will need Contentful's command line interface tool.


  • Node LTS


Using homebrew:

brew install contentful-cli

Using npm:

npm install -g contentful-cli

Using yarn:

yarn global add contentful-cli


You will need to login to Contentful on your computer. Run contentful login and follow the prompts, see below for an example:

❯ contentful login
A browser window will open where you will log in (or sign up if you don’t have an account), authorize this CLI tool and paste your CMA token here:
? Open a browser window now? Yes
? Paste your token here: [hidden]
Great! Your CMA token is now stored on your system. (Located at /Users/zander/.contentfulrc.json)
You can always run contentful logout to remove it.

Create a new CMA token (personal access token) from this page.

Content modeling & migration scripts

Every time you need to modify a content model, a new migration script should be created. It needs to be carefully modeled so that you don't overwrite existing types and content.

For more information on how to model your content programmatically, see these docs

When editing existing fields, it can be useful to view the JSON representation of the content model to see what is there. e.g. app.contentful.com/spac...view

Useful links:

Migration scripts


Richtext field

const myRichTextCT = migration
nodes: {
'embedded-entry-block': [
size: {
min: 1,
max: 4,
linkContentType: ['markdownContentType'],
'embedded-entry-inline': [
size: {
min: 10,
max: 20,
'this is a custom error for number of embedded inline entries',
linkContentType: ['parent'],
message: 'we only accept parent',
enabledNodeTypes: [
'Only heading 1, heading 2, heading 3, heading 4, heading 5, ordered list, unordered list, horizontal rule, quote, block entry, asset, link to Url, link to entry, link to asset, and inline entry nodes are allowed',

Running the migration

It is a good idea to create a test environment that is a clone of master so that everything can be checked before running the migration script "for real".

contentful space migration --space-id a65gr7u3g09k --environment-id 'test' 01-add-article-cta-type.js
Edit this page
Want to make your own site like this?
Try gatsby-theme-code-notes by Zander Martineau.
Notes on code. My second brain, by Zander Martineau.