Skip to main content
Our docs redesign is live!
Guide: Migrating from Contentful to Contentstack in depth

Prerequisites and setup

•
2 min read
cliautomation
tim-hero.png
AuthorTim Benniks

The migration runs from your machine and talks to both Contentful and Contentstack. Set up the prerequisites once before either path.

What you'll learn

  • Which tools and versions you need

  • How to install the Contentstack CLI and the migration plugin

  • How to authenticate against both platforms

  • What inputs you need before you start

Required tools

Confirm your environment before installing anything:

node --version    # must be 20 or higher

Node 20 or higher is required. If you run several Node versions through nvm or Homebrew, make sure the version on your PATH is 20 or higher, because a non-interactive shell sometimes resolves an older one.

Install the CLI and plugin

Install the Contentstack CLI globally, then install the migration plugin:

npm install -g @contentstack/cli
csdx plugins:install @contentstack/cli-external-migrate

Verify the plugin is available:

csdx migrate --help

The output lists the migrate:create command. If it is missing, reinstall the plugin and check csdx plugins for a duplicate or stale migrate plugin.

Set the destination region

Contentstack runs in several regions. Set the region that matches your destination stack before you log in:

csdx config:set:region AWS-EU

The supported region codes are AWS-NA, AWS-EU, AWS-AU, AZURE-NA, AZURE-EU, GCP-NA, and GCP-EU.

Authenticate against both platforms

Log in to Contentstack with OAuth. The command opens your browser and detects when you finish:

csdx auth:login --oauth

Log in to Contentful with its CLI. This step is interactive and prompts you to open a browser and paste your management token:

npx contentful-cli login

Your Contentful management token is a secret. Do not paste it into files, commit it, or share it in chat. The migration reads it from the Contentful CLI's stored session.

Gather your inputs

Before you start, have these ready:

  • Your Contentful space ID, which you can list with npx contentful-cli space list.

  • Your Contentstack organization UID, which is the org where the new stack will be created. if you use OAuth to log into Contentstack, we can derive the Org UID from your session.

  • The local path to the application code you want to migrate, if you plan to migrate code.

Key takeaways

  • Node 20 or higher is required, and the version on your PATH must match.

  • Install the CLI, then the @contentstack/cli-external-migrate plugin.

  • Set the destination region before logging in.

  • Authenticate against both Contentstack (OAuth) and Contentful (CLI login).

  • Treat the Contentful management token as a secret.

Frequently asked questions

  • What Node.js version is required for the migration setup?

    Node.js 20 or higher is required. Ensure the Node version on your PATH is 20+ to avoid non-interactive shells picking an older version.

  • How do I install the Contentstack CLI and the external migrate plugin?

    Install the CLI globally with npm, then install the plugin via `csdx plugins:install @contentstack/cli-external-migrate`. Verify with `csdx migrate --help`.

  • Why do I need to set the Contentstack region before logging in?

    Contentstack stacks are region-specific. Setting the correct region ensures authentication and subsequent operations target the destination stack’s region.

  • How do I authenticate to both Contentstack and Contentful for the migration?

    Authenticate to Contentstack using `csdx auth:login --oauth`. Authenticate to Contentful using `npx contentful-cli login`, which stores a session used by the migration.

  • What inputs should I gather before starting the migration?

    Have your Contentful space ID, your Contentstack organization UID (often derivable from the OAuth session), and the local path to any application code you plan to migrate.