# contentful-export

> this tool allows you to export a space to a JSON dump

Latest version **8.5.0** (published 2026-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install contentful-export
pnpm add contentful-export
yarn add contentful-export
bun add contentful-export
```

Provides the command `contentful-export`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 8.5.0 |
| Published | 2026-09-10 |
| First published | 2016-06-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22 |
| Dependencies | 17 |
| Unpacked size | 80 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 172 |
| Author | Contentful |
| Maintainers | contentful-ecosystem |
| Keywords | contentful, contentful-export |

## Links

- npm: https://www.npmjs.com/package/contentful-export
- Repository: https://github.com/contentful/contentful-export
- Homepage: https://github.com/contentful/contentful-export#readme
- Issues: https://github.com/contentful/contentful-export/issues
- npm.io page: https://npm.io/package/contentful-export

## Dependencies (17)

- [bfj](https://npm.io/package/bfj.md) ^9.1.3
- [axios](https://npm.io/package/axios.md) ^1.13.5
- [listr](https://npm.io/package/listr.md) ^0.14.1
- [yargs](https://npm.io/package/yargs.md) ^18.0.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^2.0.0
- [figures](https://npm.io/package/figures.md) ^3.2.0
- [bluebird](https://npm.io/package/bluebird.md) ^3.3.3
- [date-fns](https://npm.io/package/date-fns.md) ^4.1.0
- [cli-table3](https://npm.io/package/cli-table3.md) ^0.6.0
- [contentful](https://npm.io/package/contentful.md) ^11.5.10
- [axios-retry](https://npm.io/package/axios-retry.md) ^4.5.0
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^9.0.0
- [lodash.startcase](https://npm.io/package/lodash.startcase.md) ^4.4.0
- [contentful-batch-libs](https://npm.io/package/contentful-batch-libs.md) ^12.0.0
- [contentful-management](https://npm.io/package/contentful-management.md) ^12.17.0
- [listr-update-renderer](https://npm.io/package/listr-update-renderer.md) ^0.5.0
- [listr-verbose-renderer](https://npm.io/package/listr-verbose-renderer.md) ^0.6.0

## Recent versions

- 8.5.0 (latest) — 2026-09-10
- 9.0.0-exo.4 (exo) — 2026-08-13
- 7.22.0-DX-541-gha-publishing.1 (dev) — 2025-11-12
- 7.19.161-beta.1 (beta) — 2024-11-07
- 7.2.0-beta1 (next) — 2018-07-18
- 8.4.0 — 2026-09-10
- 8.3.0 — 2026-08-28
- 8.2.2 — 2026-08-28
- 8.2.1 — 2026-08-25
- 8.2.0 — 2026-08-13
- 9.0.0 — 2026-08-13
- 9.0.0-exo.3 — 2026-08-13
- 8.1.3 — 2026-08-13
- 9.0.0-exo.2 — 2026-08-11
- 9.0.0-exo.1 — 2026-08-03
- … 640 more at https://npm.io/package/contentful-export/versions

## README

# Contentful export tool

[![CI](https://github.com/contentful/contentful-export/actions/workflows/main.yaml/badge.svg)](https://github.com/contentful/contentful-export/actions/workflows/main.yaml)
[![npm](https://img.shields.io/npm/v/contentful-export.svg)](https://www.npmjs.com/package/contentful-export) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

[Contentful](https://www.contentful.com) 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 library that helps you backup your Content Model, Content and Assets or move them to a new Contentful space. _It will support Roles & Permissions in a future version._

To import your exported data, please refer to the [contentful-import](https://github.com/contentful/contentful-import) repository.

## :exclamation: Usage as CLI

> We moved the CLI version of this tool into our [Contentful CLI](https://github.com/contentful/contentful-cli). This allows our users to use and install only one single CLI tool to get the full Contentful experience.
>
> Please have a look at the [Contentful CLI export command documentation](https://github.com/contentful/contentful-cli/tree/master/docs/space/export) to learn more about how to use this as command line tool.

## :cloud: Pre-requisites && Installation

### Pre-requisites

- Node LTS

### :cloud: Installation

```bash
npm install contentful-export
```

## :hand: Usage

### CommonJS

```javascript
const contentfulExport = require('contentful-export')

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  ...
}

contentfulExport(options)
  .then((result) => {
    console.log('Your space data:', result)
  })
  .catch((err) => {
    console.log('Oh no! Some errors occurred!', err)
  })
```

### ESM

```javascript
import contentfulExport from 'contentful-export'

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  ...
}

// contentfulExport returns a Promise so you can use async/await, etc.
await contentfulExport(options)
```

### 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](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters).

```javascript
const contentfulExport = require('contentful-export')

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  queryEntries: ['content_type=<content_type_id>']
}

contentfulExport(options)
...
```

The Export tool also support multiple inline queries.

```javascript
const contentfulExport = require('contentful-export')

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  queryEntries: [
    'content_type=<content_type_id>',
    'sys.id=<entry_id>'
  ]
}

contentfulExport(options)
...
```

`queryAssets` uses the same syntax as `queryEntries`

### Export an environment

```javascript
const contentfulExport = require('contentful-export')

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  environmentId: '<environment_id>'
}

contentfulExport(options)
...
```

## :gear: Configuration options

### Basics

#### `spaceId` [string] [required]

ID of the space with source data

#### `environmentId` [string] [default: 'master']

ID of the environment in the source space

#### `managementToken` [string] [required]

Contentful management API token for the space to be exported

#### `deliveryToken` [string]

Contentful Content Delivery API (CDA) token for the space to be exported.

Providing `deliveryToken` will export both entries and assets from the
Contentful Delivery API, instead of the Contentful Management API.
This may be useful if you want to export the latest _published_ versions,
as the management API always only exports the entirety of items, with the latest
unpublished content. So if you want to make sure only to see the latest
published changes, provide the `deliveryToken`.

Just to clarify: When Contentful Management API always returns the latest version (e.g. 50 in this case):

```
  "createdAt": "2020-01-06T12:00:00.000Z",
  "updatedAt": "2020-04-07T11:00:00.000Z",
  "publishedVersion": 23,
  "publishedAt": "2020-04-05T14:00:00.000Z",
  "publishedCounter": 1,
  "version": 50,
```

the Content Delivery API would return the `publishedVersion` (23). CDA responses don't include
version number.

Note: Tags are only available on the Contentful Management API, so they will not be exported if you provide a Contentful Delivery Token. Tags is a new feature that not all users have access to.

### Output

#### `exportDir` [string] [default: current process working directory]

Defines the path for storing the export JSON file

#### `saveFile` [boolean] [default: true]

Save the export as a JSON file

#### `contentFile` [string]

The filename for the exported data

### Filtering

#### `includeDrafts` [boolean] [default: false]

Include drafts in the exported entries.

The `deliveryToken` option is ignored
when `includeDrafts` has been set as `true`.
If you want to include drafts, there's no point of getting them through the
Content Delivery API.

#### `includeArchived` [boolean] [default: false]

Include archived entries and assets in the exported data. This option does not include archived Releases.

#### `skipContentModel` [boolean] [default: false]

Skip exporting content models

#### `skipEditorInterfaces` [boolean] [default: false]

Skip exporting editor interfaces

#### `skipContent` [boolean] [default: false]

Skip exporting assets and entries.

#### `skipRoles` [boolean] [default: false]

Skip exporting roles and permissions

#### `skipTags` [boolean] [default: false]

Skip exporting tags

#### `skipWebhooks` [boolean] [default: false]

Skip exporting webhooks

#### `skipReleases` [boolean] [default: false]

Skip exporting [Releases](https://www.contentful.com/help/releases/). See the "Releases" section below for what's exported when this is on.

#### `stripTags` [boolean] [default: false]

Untag assets and entries

#### `includeExperienceOrchestration` [boolean] [default: true]

Export Experience Orchestration (ExO) entities: Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences.

Requires the Organization to have the `exo_m1` entitlement. If the Organization is not entitled, the export will not throw — each ExO array will be empty and a warning will be logged.

See [docs/exo-export.md](./docs/exo-export.md) for full details.

#### `contentOnly` [boolean] [default: false]

Only export entries and assets

#### `queryEntries` [array]

Only export entries that match these queries

#### `queryAssets` [array]

Only export assets that match these queries

#### `downloadAssets` [boolean]

Download actual asset files

### Connection

#### `host` [string] [default: 'api.contentful.com']

The Management API host

#### `hostDelivery` [string] [default: 'cdn.contentful.com']

The Delivery API host

#### `proxy` [string]

Proxy configuration in HTTP auth format: `host:port` or `user:password@host:port`

#### `rawProxy` [boolean]

Pass proxy config to Axios instead of creating a custom httpsAgent

#### `maxAllowedLimit` [number] [default: 1000]

The number of items per page per request

#### `headers` [object]

Additional headers to attach to the requests.

### Other

#### `errorLogFile` [string]

Full path to the error log file

#### `useVerboseRenderer` [boolean] [default: false]

Display progress in new lines instead of displaying a busy spinner and the status in the same line. Useful for CI.

### Experience Orchestration

#### `includeExperienceOrchestration` [boolean] [default: true]

Flag controlling whether Experience Orchestration (ExO) entities — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — are exported when present in the source space. Requires the `exoM1` entitlement on the source space's organization. Set to `false` to opt out. See the "Experience Orchestration (ExO) entities" section below for what happens when the space isn't entitled.

## :rescue_worker_helmet: Troubleshooting

### Proxy

Unable to connect to Contentful through your proxy? Try to set the `rawProxy` option to `true`.

```javascript
contentfulExport({
  proxy: 'https://cat:dog@example.com:1234',
  rawProxy: true,
  ...
})
```

### Error: 400 - Bad Request - Response size too big.

Contentful response sizes are limited (find more info in our [technical limit docs](https://www.contentful.com/developers/docs/technical-limits/)). In order to resolve this issue, limit the amount of entities received within a single request by setting the [`maxAllowedLimit`](#maxallowedlimit-number-default-1000) option:

```javascript
contentfulExport({
  proxy: 'https://cat:dog@example.com:1234',
  rawProxy: true,
  maxAllowedLimit: 50
  ...
})
```

### Embargoed Assets

If a space is configured to use the [embargoed assets feature](https://www.contentful.com/help/media/embargoed-assets/), certain options will need to be set to use the export/import tooling. When exporting content, the `downloadAssets` option must be set to `true`. This will download the asset files to your local machine. Then, when importing content ([using `contentful-import`](https://github.com/contentful/contentful-import)), the `uploadAssets` option must be set to `true` and the `assetsDirectory` must be set to the directory that contains all of the exported asset folders.

```javascript
const contentfulExport = require("contentful-export");

const options = {
  spaceId: "<space_id>",
  managementToken: "<content_management_api_key>",
  downloadAssets: true,
};

contentfulExport(options);
```

## :card_file_box: Exported data structure

This is an overview of the exported data:

```json
{
  "contentTypes": [],
  "entries": [],
  "assets": [],
  "locales": [],
  "tags": [],
  "webhooks": [],
  "roles": [],
  "editorInterfaces": [],
  "releases": [],
  "designTokens": [],
  "components": [],
  "experienceTemplates": [],
  "dataAssemblies": [],
  "experienceFragments": [],
  "experiences": []
}
```

When `includeExperienceOrchestration: true` is set, six additional arrays are included:

```json
{
  "designTokens": [],
  "components": [],
  "experienceTemplates": [],
  "dataAssemblies": [],
  "experienceFragments": [],
  "experiences": []
}
```

_Note:_ Tags feature is not available for all users. If you do not have access to this feature, the tags array will always be empty.

_Note:_ `designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, and `experiences` are Experience Orchestration (ExO) entities — present by default; absent only if you explicitly set `includeExperienceOrchestration: false` — see the "Experience Orchestration (ExO) entities" section below.

_Note:_ `releases` is present by default; absent only if you explicitly set `skipReleases: true` — see the "Releases" section below. It's a separate, GA Contentful feature, not part of ExO.

## :test_tube: Experience Orchestration (ExO) entities

Experience Orchestration (ExO) is Contentful's system for composing and rendering structured page experiences. It sits above the traditional entry/content-type layer and provides six dedicated entity types — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — that together describe how content is fetched, assembled, and laid out.

> **Experimental:** ExO entities (`designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, `experiences`) are `@internal` and considered experimental. Their shape and export behavior are subject to change without notice.

ExO export is on by default (`includeExperienceOrchestration: true`) — for the CLI and the module API alike. Pass `includeExperienceOrchestration: false` (`--include-experience-orchestration=false` on the CLI) to opt out.

```javascript
import contentfulExport from 'contentful-export'

const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  includeExperienceOrchestration: false // opt out; omit to export ExO entities when present (the default)
}

await contentfulExport(options)
```

If the source space has no ExO entities, or lacks the `exoM1` entitlement, each ExO entity type logs a `Skipping <Entity> export` warning and exports as an empty array — it does not fail the export. Pass `includeExperienceOrchestration: false` if you want to avoid it.

Requires the `exoM1` entitlement on the source space's organization. [contentful-cli](https://github.com/contentful/contentful-cli)'s `space export` command doesn't expose this option at all yet, so ExO export isn't reachable through that separate CLI regardless of default.

### Optimization Variants

Experiences and Experience Fragments each support **Optimization Variants** — alternate versions used for personalization. Variants are a separate opt-in on top of `includeExperienceOrchestration`, defaulting to `false`:

```javascript
const options = {
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  includeExperienceOrchestration: true,
  includeExoVariants: true
}

await contentfulExport(options)
```

Unlike the six entity types above, variants are **not** exported as a seventh top-level array — they're nested onto their parent as `experience.optimizationVariants` / `experienceFragment.optimizationVariants`, because a variant has no globally-unique `sys.id` of its own (the API's variant response reuses the parent's `sys.id`; the variant is identified by `sys.variant`/`sys.variantType`/`sys.variantDimension` instead). When `includeExoVariants` is omitted or `false`, the `optimizationVariants` field is absent entirely — not an empty array — so default export output is unaffected. See [`docs/exo-export.md`](./docs/exo-export.md#optimization-variants) for the full shape, the ADR behind the nested-storage decision, and the corresponding `contentful-import` behavior.

### Round-tripping into `contentful-import`

The ExO entities exported here are designed to be fed directly into [`contentful-import`](https://github.com/contentful/contentful-import), which preserves source IDs, applies dependency ordering (a topological sort for Components and Experience Fragments, since either can reference others of the same type), and upgrades entities from older, pre-rename export files automatically. See `contentful-import`'s README "Experience Orchestration (ExO) entities" section for the import-side details.

## :package: Releases

[Releases](https://www.contentful.com/help/releases/) (Timeline) is a separate, GA Contentful feature — not part of Experience Orchestration, and gated by its own organization entitlement rather than `exoM1`.

Releases export is on by default (`skipReleases: false`) — for the CLI and the module API alike. Pass `skipReleases: true` (`--skip-releases` on the CLI) to opt out.

Only releases with `sys.schemaVersion: "Release.v2"` ("Releases") are fetched. `Release.v1` ("Launch") releases are excluded by the export query itself, since [`contentful-import`](https://github.com/contentful/contentful-import) only supports `Release.v2` on the import side.

Only active Releases are exported. Archived Releases are omitted, regardless of `includeArchived`, because that option currently applies only to entries and assets.

If the source space's organization lacks the Releases entitlement, or the fetch otherwise fails, a `Skipping Releases export` warning is logged and `releases` exports as an empty array — it does not fail the export.

Round-trips into [`contentful-import`](https://github.com/contentful/contentful-import), which imports each release found in the exported data. See `contentful-import`'s README "Releases" section for the import-side details, including a real limitation worth knowing before you rely on this for repeated imports: Releases have no ID-preserving create, so re-importing the same export creates additional releases rather than updating existing ones.

## :warning: 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.

## :memo: Changelog

Read the [releases](https://github.com/contentful/contentful-export/releases) page for more information.

## :scroll: License

This project is licensed under MIT license

## For AI Agents

<!-- Generated by seed-golden-context | Last updated: 2026-05-04 -->
If you are an AI coding agent working in this repository, read [AGENTS.md](./AGENTS.md) first. It tells you where to find architectural context, development setup, decision records, and repo-specific rules.

[1]: https://www.contentful.com

---
_Source: https://npm.io/package/contentful-export · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._