Kontent.ai Data Ops: Control Your Infrastructure & Data (Backup, Restore, Sync, Migrate)

[![NPM Version][npm-shield]][npm-url]
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Discord][discord-shield]][discord-url]

Kontent.ai Data Ops is a powerful CLI tool designed to streamline data management in your Kontent.ai projects. It supports a wide variety of complex operations, including:
- Environment Backup: Export your project's data for backup or migration purposes.
- Environment Restore: Easily recreate environments from your backups.
- Synchronizing and Migrating Data: Keep content and content models in sync across different projects and environments.
- Executing Migration Scripts: Apply changes incrementally using migration scripts and maintain a clear history of modifications.

By automating these processes, Data Ops helps maintain consistency, reduce manual effort, and accelerate your deployment workflows.

---

Contents

- Prerequisites
- Getting Started
- Installation
- Configuration
- Commands
- Examples
- Contributing
- How to Contribute
- Code of Conduct
- Getting Started with Development
- Running Tests
- Prepare Your Testing Project
- Configuration for Testing
- Structure
- License
- Support
- Additional Resources

---

Prerequisites

- Node.js: Node.js with ESM support (lts).
- Kontent.ai Account: Access to your Kontent.ai project with appropriate permissions.
- Management API Key: Obtain a Management API key for your project.
- Preview Delivery API Key: For Synchronizing content, Preview Delivery API key might be required.

> Security Tip: Always store your Management API keys securely. Avoid hardcoding them in scripts or sharing them publicly. Use environment variables or secure credential storage solutions when possible.

---

Getting Started

$3

We recommend running data-ops with npx. Be aware that npx calls the cached version of the tool. Use @latest to ensure you're using the latest version.

``bash
npx @kontent-ai/data-ops@latest
`

Alternatively, you can install the package globally or locally:

`bash


Global installation

npm install -g @kontent-ai/data-ops

Local installation

npm install @kontent-ai/data-ops
`

Use -h or --help anytime to get information about available commands and their options.

`bash
npx @kontent-ai/data-ops@latest --help


or

yarn dlx @kontent-ai/data-ops --help

Help for a specific command

npx @kontent-ai/data-ops@latest --help

If installed globally

data-ops --help
`

$3

All options (including options for commands) can be provided in three different ways:

- As command-line parameters (e.g., --environmentId xxx)
- In a JSON configuration file (e.g., --configFile params.json) - We recommend this approach
- As environment variables with DATA_OPS_ prefix and transformed into UPPER_SNAKE_CASE (e.g., DATA_OPS_ENVIRONMENT_ID=xxx npx @kontent-ai/data-ops ...)




Commands

The tool usage is based on commands provided in the following format:

`bash
npx @kontent-ai/data-ops@latest
`

Below are the available commands:

- environment:
- backup & restore: Backup & restore your Kontent.ai environment.
- clean: Delete all data from your Kontent.ai environment.
- sync:
- snapshot: Create a local snapshot from a Kontent.ai environment for the purpose of synchronization.
- diff: Compare two environments.
- run: Synchronize content model and environment metadata changes between environments.
- migrate-content:
- snapshot: Create a local snapshot from selected content items and assets.
- run: Migrate content items across environments.
- migrations:
- add: Add new migration scripts.
- run: Execute migration scripts.
- export:
- markdown: Export content items as markdown files with YAML frontmatter.

> [!NOTE]
> All command functions are publicly exposed, making it easy to include them in your scripts. See the individual command readmes for more information.

$3

Creating an Environment Backup including Content Items and Assets

`bash
npx @kontent-ai/data-ops@latest environment backup \
--environmentId \
--apiKey \
--include contentItems assets
`

Cleaning an Environment Excluding Taxonomies and Languages

`bash
npx @kontent-ai/data-ops@latest environment clean \
--environmentId \
--apiKey \
--exclude taxonomies languages
`

Synchronizing Content Types and Snippets Only

`bash
npx @kontent-ai/data-ops@latest sync run \
--sourceEnvironmentId \
--sourceApiKey \
--targetEnvironmentId \
--targetApiKey \
--entities contentTypes contentTypeSnippets
`

>[!Tip]
>
> - Selective Operations: Use the --include option to operate on a limited set of entities.
> - Configuration Files: For complex commands with multiple entities, consider using a configuration file with the --configFile option to manage your parameters more easily.

---

Contributing

We welcome contributions to the Kontent.ai Data Ops tool!

$3

- Report Issues: Use the GitHub Issues to report bugs or request features.
- Fork the Repository: Create a personal fork of the repository on GitHub.
- Create a Feature Branch: Use a descriptive name for your branch.
- Submit a Pull Request: Submit your changes for review.

Please read our Contributing Guidelines for more details.

$3

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.

$3

- Run pnpm install to install packages.
- Run pnpm build to compile the tool.
- Run node build/src/index.js --help to run (or pnpm start -- --help).

$3

We have comprehensive test suites to ensure the reliability of the Data Ops tool.

- Unit Tests: Run pnpm test:unit to execute unit tests.
- Integration Tests: Run pnpm test:integration to execute integration tests.

> [!IMPORTANT]
> Integration tests require access to a Kontent.ai project and may create temporary environments. Interrupting tests may lead to orphaned environments. Always allow tests to be completed or clean up manually if necessary.

> [!IMPORTANT]
> Run pnpm test:advancedDiff to compare generated advanced diffs with test baselines.

$3

To successfully execute integration tests, you must prepare a Kontent.ai project with corresponding environments. You can use the environment restore command to import prepared zip files located at tests/integration//data/.zip.

#### Exporting Test Environments

All Kontent.ai test environments are exported in tests/integration//data/.zip. When you update any of these environments, you should also update the corresponding exported zip files. To streamline this process, we've provided a script called exportTestEnvironments.js. You can run it with the command pnpm export:testEnvs. If you need to export specific environments, you can use the following command parameters: -i for Import/Export test environment, -s for Sync Source Template environment, and -t for Sync Target Template environment. For instance, to export only the Sync Source and Sync Target environments, you would run pnpm export:testEnvs -- -s -t.

> [!IMPORTANT]
> Creation and removal of new environments takes some time; therefore, try to keep the number of environment-dependent tests to a minimum.

$3

The configuration is only necessary to run the integration tests.

- Copy the .env.template into .env:

`bash
cp .env.template .env
`

- Fill in the values (each value is explained in comments in the template).

$3

The main part of the tool is located in the src folder. The project is structured around commands, with each command defined on the yargs object in a folder of the same name within the src/commands folder. The exported register function (of type RegisterCommand) must be included in src/index.ts in the commandsToRegister array.

Tests can be found in tests/integration and tests/unit folders. Integration tests require Kontent.ai environments and a valid Management API key for successful execution. You can use the withTestEnvironment` function to provide the tests with a new empty environment.

---

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

---

Support

If you have any questions or need assistance, please reach out:

- Kontent.ai Support: Contact Support

---

Additional Resources

- Kontent.ai Official Documentation: Learn more about Kontent.ai

---

[contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/data-ops.svg?style=for-the-badge
[contributors-url]: https://github.com/kontent-ai/data-ops/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/kontent-ai/data-ops.svg?style=for-the-badge
[forks-url]: https://github.com/kontent-ai/data-ops/network/members
[stars-shield]: https://img.shields.io/github/stars/kontent-ai/data-ops.svg?style=for-the-badge
[stars-url]: https://github.com/kontent-ai/data-ops/stargazers
[issues-shield]: https://img.shields.io/github/issues/kontent-ai/data-ops.svg?style=for-the-badge
[issues-url]: https://github.com/kontent-ai/data-ops/issues
[license-shield]: https://img.shields.io/github/license/kontent-ai/data-ops.svg?style=for-the-badge
[license-url]: https://github.com/kontent-ai/data-ops/blob/master/LICENSE.md
[discord-shield]: https://img.shields.io/discord/821885171984891914?color=%237289DA&label=Kontent.ai%20Discord&logo=discord&style=for-the-badge
[discord-url]: https://discord.com/invite/SKCxwPtevJ
[npm-url]: https://www.npmjs.com/package/@kontent-ai/data-ops
[npm-shield]: https://img.shields.io/npm/v/%40kontent-ai%2Fdata-ops?style=for-the-badge&logo=npm&color=%23CB0000