{"id":13314660,"url":"https://github.com/kontent-ai/data-ops","last_synced_at":"2025-05-03T07:31:25.370Z","repository":{"id":206032630,"uuid":"715656354","full_name":"kontent-ai/data-ops","owner":"kontent-ai","description":"The Official CLI Tool for manipulating data in Kontent.ai","archived":false,"fork":false,"pushed_at":"2025-04-14T08:21:14.000Z","size":6632,"stargazers_count":13,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-20T01:14:54.117Z","etag":null,"topics":["kontent-ai","kontent-ai-export","kontent-ai-import","kontent-ai-import-export","kontent-ai-migration","kontent-ai-migrations","kontent-ai-sync","kontent-ai-tool"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kontent-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-07T15:16:48.000Z","updated_at":"2025-04-14T07:55:24.000Z","dependencies_parsed_at":"2024-11-05T15:20:19.728Z","dependency_job_id":"58f3f8e7-0fdc-4252-ba23-d04611ac0d03","html_url":"https://github.com/kontent-ai/data-ops","commit_stats":{"total_commits":411,"total_committers":11,"mean_commits":37.36363636363637,"dds":0.5766423357664234,"last_synced_commit":"9da88a5618749d31e88264297da2b27f700ca1fe"},"previous_names":["kontent-ai/data-ops"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdata-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdata-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdata-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kontent-ai%2Fdata-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kontent-ai","download_url":"https://codeload.github.com/kontent-ai/data-ops/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252156897,"owners_count":21703371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kontent-ai","kontent-ai-export","kontent-ai-import","kontent-ai-import-export","kontent-ai-migration","kontent-ai-migrations","kontent-ai-sync","kontent-ai-tool"],"created_at":"2024-07-29T18:11:53.195Z","updated_at":"2025-05-03T07:31:20.358Z","avatar_url":"https://github.com/kontent-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kontent.ai Data Ops: Control Your Infrastructure \u0026 Data (Backup, Restore, Sync, Migrate)\n\n[![NPM Version][npm-shield]][npm-url]\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n[![Discord][discord-shield]][discord-url]\n\nKontent.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:\n- **Environment Backup**: Export your project's data for backup or migration purposes.\n- **Environment Restore**: Easily recreate environments from your backups.\n- **Synchronizing and Migrating Data**: Keep content and content models in sync across different projects and environments.\n- **Executing Migration Scripts**: Apply changes incrementally using migration scripts and maintain a clear history of modifications.\n\nBy automating these processes, Data Ops helps maintain consistency, reduce manual effort, and accelerate your deployment workflows.\n\n---\n\n## Contents\n\n- [Prerequisites](#prerequisites)\n- [Getting Started](#getting-started)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n- [Commands](#commands)\n  - [Examples](#examples)\n- [Contributing](#contributing)\n  - [How to Contribute](#how-to-contribute)\n  - [Code of Conduct](#code-of-conduct)\n  - [Getting Started with Development](#getting-started-with-development)\n  - [Running Tests](#running-tests)\n  - [Prepare Your Testing Project](#prepare-your-testing-project)\n  - [Configuration for Testing](#configuration-for-testing)\n  - [Structure](#repository-structure)\n- [License](#license)\n- [Support](#support)\n- [Additional Resources](#additional-resources)\n\n---\n\n## Prerequisites\n\n- **Node.js**: Node.js with ESM support (lts).\n- **Kontent.ai Account**: Access to your Kontent.ai project with appropriate permissions.\n- **Management API Key**: Obtain a Management API key for your project.\n- **Preview Delivery API Key**: For Synchronizing content, Preview Delivery API key might be required. \n\n  \u003e **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.\n\n---\n\n## Getting Started\n\n### Installation\n\nWe 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.\n\n\n```bash\nnpx @kontent-ai/data-ops@latest \u003ccommand\u003e\n```\n\nAlternatively, you can install the package globally or locally:\n\n```bash\n# Global installation\nnpm install -g @kontent-ai/data-ops\n\n# Local installation\nnpm install @kontent-ai/data-ops\n```\n\n**Use `-h` or `--help` anytime to get information about available commands and their options.**\n\n```bash\nnpx @kontent-ai/data-ops@latest --help\n# or\nyarn dlx @kontent-ai/data-ops --help\n\n# Help for a specific command\nnpx @kontent-ai/data-ops@latest \u003ccommand\u003e --help\n\n# If installed globally\ndata-ops --help\n```\n\n\n### Configuration\n\nAll options (including options for commands) can be provided in three different ways:\n\n- **As command-line parameters** (e.g., `--environmentId xxx`)\n- **In a JSON configuration file** (e.g., `--configFile params.json`) - *We recommend this approach*\n- **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 ...`)\n\n\n## Commands\n\nThe tool usage is based on commands provided in the following format:\n\n```bash\nnpx @kontent-ai/data-ops@latest \u003ccommand-name\u003e \u003ccommand-options\u003e\n```\n\nBelow are the available commands:\n\n- **environment**:\n  - **[backup \u0026 restore](./src/commands/environment/backupRestore/README.md)**: Backup \u0026 restore your Kontent.ai environment.\n  - **[clean](./src/commands/environment/clean/README.md)**: Delete all data from your Kontent.ai environment.\n- **sync**:\n  - **[snapshot](./src/commands/sync/snapshot/README.md)**: Create a local snapshot from a Kontent.ai environment for the purpose of synchronization.\n  - **[diff](./src/commands/sync/diff/README.md)**: Compare two environments.\n  - **[run](./src/commands/sync/run/README.md)**: Synchronize content model and environment metadata changes between environments.\n- **migrate-content**:\n  - **[snapshot](./src/commands/migrateContent/snapshot/README.md)**: Create a local snapshot from selected content items and assets.\n  - **[run](./src/commands/migrateContent/run/README.md)**: Migrate content items across environments.\n- **[migrations](./src/commands/migrations/README.md)**:\n  - **add**: Add new migration scripts.\n  - **run**: Execute migration scripts.\n\n\u003e [!NOTE]\n\u003e All command functions are publicly exposed, making it easy to include them in your scripts. See the individual command readmes for more information.\n\n### Examples\n\n**Creating an Environment Backup including Content Items and Assets**\n\n```bash\nnpx @kontent-ai/data-ops@latest environment backup \\\n  --environmentId \u003cenvironment-id\u003e \\\n  --apiKey \u003cManagement-API-key\u003e \\\n  --include contentItems assets\n```\n\n**Cleaning an Environment Excluding Taxonomies and Languages**\n\n```bash\nnpx @kontent-ai/data-ops@latest environment clean \\\n  --environmentId \u003cenvironment-id\u003e \\\n  --apiKey \u003cManagement-API-key\u003e \\\n  --exclude taxonomies languages\n```\n\n**Synchronizing Content Types and Snippets Only**\n\n```bash\nnpx @kontent-ai/data-ops@latest sync run \\\n  --sourceEnvironmentId \u003csource-environment-id\u003e \\\n  --sourceApiKey \u003csource-api-key\u003e \\\n  --targetEnvironmentId \u003ctarget-environment-id\u003e \\\n  --targetApiKey \u003ctarget-api-key\u003e \\\n  --entities contentTypes contentTypeSnippets\n```\n\n\u003e[!Tip]\n\u003e\n\u003e - **Selective Operations**: Use the `--include` option to operate on a limited set of entities.\n\u003e - **Configuration Files**: For complex commands with multiple entities, consider using a configuration file with the `--configFile` option to manage your parameters more easily. \n\n---\n\n## Contributing\n\nWe welcome contributions to the Kontent.ai Data Ops tool!\n\n### How to Contribute\n\n- **Report Issues**: Use the [GitHub Issues](https://github.com/kontent-ai/data-ops/issues) to report bugs or request features.\n- **Fork the Repository**: Create a personal fork of the repository on GitHub.\n- **Create a Feature Branch**: Use a descriptive name for your branch.\n- **Submit a Pull Request**: Submit your changes for review.\n\nPlease read our [Contributing Guidelines](CONTRIBUTING.md) for more details.\n\n### Code of Conduct\n\nThis project adheres to a [Code of Conduct](https://github.com/kontent-ai/.github/blob/main/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.\n\n### Getting Started with Development\n\n- Run `npm ci` to install packages.\n- Run `npm run build` to compile the tool.\n- Run `node build/src/index.js --help` to run (or `npm run start -- --help`).\n\n### Running Tests\n\nWe have comprehensive test suites to ensure the reliability of the Data Ops tool.\n\n- **Unit Tests**: Run `npm run test:unit` to execute unit tests.\n- **Integration Tests**: Run `npm run test:integration` to execute integration tests.\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003e [!IMPORTANT]\n\u003e Run `npm run test:advancedDiff` to compare generated advanced diffs with test baselines.\n\n### Prepare Your Testing Project\n\nTo successfully execute integration tests, you must prepare a Kontent.ai project with corresponding environments. You can use the [environment restore](./src/commands/environment/backupRestore/README.md) command to import prepared zip files located at `tests/integration/\u003ctestName\u003e/data/\u003czipName\u003e.zip`.\n\n#### Exporting Test Environments\n\nAll Kontent.ai test environments are exported in `tests/integration/\u003ctestName\u003e/data/\u003czipName\u003e.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 `npm run export:testEnv`. 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 `npm run export:testEnv -- -s -t`.\n\n\u003e [!IMPORTANT]\n\u003e Creation and removal of new environments takes some time; therefore, try to keep the number of environment-dependent tests to a minimum.\n\n### Configuration for Testing\n\nThe configuration is only necessary to run the integration tests.\n\n- Copy the `.env.template` into `.env`:\n\n  ```bash\n  cp .env.template .env\n  ```\n\n- Fill in the values (each value is explained in comments in the template).\n\n### Repository Structure\n\nThe main part of the tool is located in the `src` folder. The project is structured around commands, with each command defined on the [yargs](https://yargs.js.org/) 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.\n\nTests 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.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details.\n\n---\n\n## Support\n\nIf you have any questions or need assistance, please reach out:\n\n- **Kontent.ai Support**: [Contact Support](https://kontent.ai/support/)\n\n---\n\n## Additional Resources\n\n- **Kontent.ai Official Documentation**: [Learn more about Kontent.ai](https://kontent.ai/learn/)\n\n---\n\n[contributors-shield]: https://img.shields.io/github/contributors/kontent-ai/data-ops.svg?style=for-the-badge\n[contributors-url]: https://github.com/kontent-ai/data-ops/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/kontent-ai/data-ops.svg?style=for-the-badge\n[forks-url]: https://github.com/kontent-ai/data-ops/network/members\n[stars-shield]: https://img.shields.io/github/stars/kontent-ai/data-ops.svg?style=for-the-badge\n[stars-url]: https://github.com/kontent-ai/data-ops/stargazers\n[issues-shield]: https://img.shields.io/github/issues/kontent-ai/data-ops.svg?style=for-the-badge\n[issues-url]: https://github.com/kontent-ai/data-ops/issues\n[license-shield]: https://img.shields.io/github/license/kontent-ai/data-ops.svg?style=for-the-badge\n[license-url]: https://github.com/kontent-ai/data-ops/blob/master/LICENSE.md\n[discord-shield]: https://img.shields.io/discord/821885171984891914?color=%237289DA\u0026label=Kontent.ai%20Discord\u0026logo=discord\u0026style=for-the-badge\n[discord-url]: https://discord.com/invite/SKCxwPtevJ\n[npm-url]: https://www.npmjs.com/package/@kontent-ai/data-ops\n[npm-shield]: https://img.shields.io/npm/v/%40kontent-ai%2Fdata-ops?style=for-the-badge\u0026logo=npm\u0026color=%23CB0000\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fdata-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkontent-ai%2Fdata-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkontent-ai%2Fdata-ops/lists"}