Data-ops is a CLI tool for managing data in your Kontent.ai projects. It runs in Node.js with ESM support (lts).
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.
Use `-h` or `--help` anytime to get information about available commands and their options.
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 <command> --help
# you can also install the package globally, or locally
npm i @kontent-ai/data-ops -g
# with the package installed, you can call the tool as follows
data-ops --help
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 @kontent-ai/data-ops ...
)
The tool usage is based on commands provided in the following format:
npx @kontent-ai/data-ops@latest <command-name> <command-options>
The instructions for individual commands are provided in the README.md files located in each command's respective folder (./src/commands). Data-ops supports the following commands:
- import & export
- clean
- sync-model
- sync-content
- migrations
npm ci
to install packagesnpm run build
to compile the toolnode build/src/index.js --help
to run (ornpm run start -- --help
)
The tool is transpiled into the build
folder.
TypeScript in tests is handled by ts-jest.
npm run test:unit
to run unit testsnpm run test:integration
to run integration tests (these create temporary Kontent.ai environments and delete them afterwards, interrupting the tests while they're running may lead to orphaned environments in your project)npm run test:advancedDiff
compares generated advanced diff with a test baseline. Part of integration tests.
The configuration is only necessary to run the integration tests.
- Copy the
.env.template
into.env
(cp .env.template .env
) - Fill in the values (each value is explained in comments in the template)
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 MAPI key for successful execution.
You can use the withTestEnvironment
function to provide the tests with a new empty environment.
Please note that creation and removal of new environments takes some time, therefore try to keep the number of environment-dependent tests to a minimum.