The expert path: migrate with CLI commands

The expert path gives you direct control over each migration step. Use it to inspect intermediate output, script the migration, or run a subset of the steps. The commands come from the same @contentstack/cli-external-migrate plugin the guided path uses.

What you'll learn

• How to run the whole content migration in one command

• How to run the export, convert, audit, and import steps separately

• Which flags control each step

• How to check migration progress with a manifest

Run the whole migration in one command

The migrate:create command exports the Contentful space, converts it to a Contentstack bundle, creates a new stack in your organization, and imports the content:

csdx migrate:create \  --source contentful \  --org <your-org-uid> \  --space-id <your-space-id> \  --download-assets \  --output ./migration-workspace \  --workspace ./migration-workspace

Useful flags:

• --source contentful declares the migration source. Contentful is the only supported source today.

• --org is the Contentstack organization UID where the new stack is created. If you omit it, the command prompts with a list.

• --space-id is the Contentful space to export.

• --download-assets includes asset binaries in the export.

• --include-drafts and --include-archived widen the export beyond published entries.

• --affix sets a content-type UID prefix (default CS).

• --output is the parent directory; the bundle is written to <output>/bundle (default ./output-dir).

• -y skips the import confirmation prompt (on by default; pass --no-yes to keep the prompt).

Provide your Contentful management token through the CONTENTFUL_MANAGEMENT_TOKEN environment variable, or pass it with --source-token. Prefer the environment variable so the token stays out of your shell history.

By default the command invites the Contentful space members into the new stack with their mapped roles, which sends invite emails. Pass --no-invite-users to skip the emails and only write the users-mapping.json report. To migrate every space a token can reach in one run, use --cf-org-id <contentful-org-id> instead of --space-id, which creates one stack per space.

Run the steps separately

If you want to inspect or modify the bundle between steps, run the discrete commands instead. They share a workspace directory so the manifest can track progress across them. These subcommands do not appear in csdx migrate --help, which lists only migrate:create, but they ship with the plugin and run normally.

Export from Contentful

Export the space to an export.json in your workspace:

csdx migrate:export \  --legacy contentful \  --space-id <your-space-id> \  --download-assets \  --output ./migration-workspace

The --include-drafts and --include-archived flags work here too. Prefer the CONTENTFUL_MANAGEMENT_TOKEN environment variable over passing the token as a flag.

Convert to a Contentstack bundle

Convert the export into a Contentstack import bundle:

csdx migrate:convert \  --legacy contentful \  --input ./migration-workspace/export.json \  --output ./contentstack-import \  --master-locale en-us

The bundle is written to <output>/bundle and contains content types, entries, assets, references, and a mapper.json recording the field-UID mapping. Inspect the converted content types before importing:

ls ./contentstack-import/bundle/content_types/
cat ./contentstack-import/bundle/mapper.json

Audit the bundle

The audit step wraps the existing Contentstack audit tooling to validate the bundle before import:

csdx migrate:audit \  --data-dir ./contentstack-import/bundle \  --report-path ./audit-reports

Review the report, and if the audit surfaces fixable issues, you can run csdx cm:stacks:audit:fix against the bundle before importing.

Import into a stack

Import into an existing stack by API key:

csdx migrate:import \  --stack-api-key <your-stack-api-key> \  --data-dir ./contentstack-import/bundle \  -y

To create a new stack during import instead, pass --org <your-org-uid> rather than --stack-api-key, and optionally --stack-name to name it. The import target stack must be empty.

Check progress

The migration writes a migration-manifest.json to the workspace. Check the status of each step at any time:

csdx migrate:status --workspace ./migration-workspace

Key takeaways

• migrate:create runs export, convert, create stack, and import in one command.

• migrate:export, migrate:convert, migrate:audit, and migrate:import run the same steps discretely.

• The convert step produces a bundle and a mapper.json you can inspect before import.

• The import target stack must be empty, or let the command create a new one with --org.

• migrate:status reports progress from the workspace manifest.