contentful-cli-export

Contentful Export Tool

This tool simplifies exporting data from Contentful to a local json file. It's easier to use than the actual Contentful CLI export and can also be easily integrated into a CI/CD pipeline such as GitLab or GitHub.

Note: This is NOT the official Contentful CLI Export tool. That can be found on GitHub 🔗 or NpmJS 🔗

Sponsored by Atida

✨ Features · 💡 Installation · 📟 Example · 🎹 Usage · 📅 ToDo · 👾 Contributors · 🎩 Acknowledgments· 📚 Collection · 📄 License

✨ Features

• Ease of Use: Compared to the actual Contentful CLI, this tool requires less manual configuration and is more straightforward to use.
• CI/CD Pipeline Integration: It is designed to be used as part of a CI/CD pipeline, like GitLab or GitHub. Differently from the official Contentful CLI, it doesn't require a global installation, making it portable and easy to run in various environments.
• Command Line Parameters: All necessary parameters can be passed via command line arguments, making it flexible for different use cases. These include management-token, space-id and environment-id, making it even more suitable for being integrated into a release pipeline.
• ZIP Compression: This tool provides an option to compress the result into a ZIP file. This is particularly useful when exporting large amounts of data or assets, helping to save storage space.
• Consistent Naming: The naming of the output files (.json, .zip, and .log) are consistent and predictable, making it easier to manage the exported data (current date + space-id + environment-id).

💡 Installation

To use this cli script, you must have Node.js 🔗 and npm 🔗 installed.

To install it, simply run:

npm install contentful-cli-export --save

Or, if using yarn 🔗:

yarn add contentful-cli-export

Similarly, if you are using Bun 🔗, just run:

bun add contentful-cli-release

Requirements

• node >= 18.20.0
• npm >= 10.5.0
• contentful-management >= 11.31.7
• contentful-export >= 7.19.146
• contentful-lib-helpers >= 0.4.0

Set-up

• To better use the Contentful CLI Export, it is recommended to put the following values in your .env/.env.local file:

  CMS_MANAGEMENT_TOKEN=<management-token>
  CMS_SPACE_ID=<space-id>
  CMS_MAX_ALLOWED_LIMIT=100
  CMS_EXPORT_DIR=export/
  

  However, these values could also be passed as parameters during execution.

• You will need to create the CMS_EXPORT_DIR folder, that will contain all the exports. This folder should stay preferably in the root of your project. If no folder is specified, a folder export/ will be created automatically if missing.

📟 Example

The basic command should contain the from environment we want to export from:

npx contentful-cli-export --from "<environment-id>"

A more complex export command could be

npx contentful-cli-export --from "<environment-id>" --space-id"<space-id>" --management-token "<management-token>" --compress

This will export data from the specified environment-id, space-id, and management token, and compress the result into a ZIP file.

🎹 Usage

This script can be used from the command line and accepts various arguments for customization:

• --from or --environment-id [MANDATORY]: The environment id from which data will be exported.
• --space-id: The Contentful space id.
• --management-token or --mt: The Contentful Management Token.
• --only-published: To include only published data.
• --download-assets: To include assets in the exported data.
• --verbose: Display the progress in new lines, instead of animated UI (useful in CI).
• --compress: To compress the result into a ZIP file.
• --export-dir: To specify a custom directory for the exported data (default is subdirectory CMS_EXPORT_DIR or export/ in your project root). The script will exit if this custom folder doesn't exist.
• --max-allowed-limit: Number of entries to fetch at each iteration. Max: 1000 - Recommended: 100 (lower values fire more API calls, but avoid 'Response too big' error).

📅 Todo

• Add compatibility with official Contentful Export env/settings.
• Improve Logging (+ Colors).
• Add Tests.

👾 Contributors

@fciacchi

@psyvic

@aalduz

@leslyto

Contributions

Feel free to open issues or pull requests in our GitHub Repository if you have suggestions or improvements to propose.

🎩 Acknowledgements

I would like to express my gratitude to the following parties:

• Atida 🔗, the company that has allowed these scripts to be open sourced. Atida is an e-commerce platform that sells beauty and medical products. Their support for open source is greatly appreciated. A special thank to Shaya Pourmirza that has been a great promoter and supporter of this initiative inside the company.
• Contentful 🔗, for creating their excellent content management platform and the JavaScript CMA SDK that this library is built on. Without their work, this project would not be possible.

Thank you to everyone involved!

📚 Other Scripts in the same collection

We produce a bunch of interesting packages for Contentful. You might want to check them out:

• Contentful Lib Helpers (GitHub and NpmJS): Utility Library for Contentful Management API.
• Contentful CLI Export (GitHub and NpmJS): Simplifies backup of your Contentful Environment.
• Contentful CLI Migrations (GitHub and NpmJS): Tool to automate and scale Contentful Migrations.
• Contentful CLI Release (GitHub and NpmJS): Release utilities to deploy Contentful in a CI/CD.

📄 License

This project is licensed under the MIT License