Kontent CLI is, as the name suggests, a command line interface to execute migration scripts within your Kentico Kontent projects. These migration scripts contain instructions to perform a set of updates on both object types and content items. In this article I will explain how you can leverage the Kontent CLI to automate the roll-out of content updates via targeted environments.

What would you use it for?

When you talk about content migration you often think about transferring data from one system to another. In many cases this will also be the case. A legitimate question 🤷‍♂️ is whether the amount of development effort outweighs e.g. the hiring of working students, who would manually migrate the data.

With the help of a tool, such as the Kontent CLI, a migration becomes a lot easier. 😍 The tool is specifically developed for these types of scenarios. This is different compared to writing a piece of code using available API's to perform a migration where workarounds to get the job done are often unavoidable.

Looking at the Kontent CLI, a typical scenario would be to bulk update data. Consider an application in production that requires object definition updates that should take place. How sour 😓 would it be if you had to manually adjust all thousands of content items manually in the CMS? With the help of the Kontent CLI this is a piece of cake 🍰.

How does it work?

Before I explain how the command line interface works, it is good to realize that it uses the Content Management API from Kentico Kontent. The Content Management API is available from the Business Plan and above. It is also advisable to create Dev and Test environments in Kentico Kontent so that you can test changes extensively before they are rolled out to Production.

The Kontent CLI becomes available by installing it via npm:

npm install rxjs --save
npm install -g @kentico/kontent-cli

Note taken from the documentation: The Kontent CLI requires Node 10+ and npm 6+, and uses the Kontent Management SDK to manipulate content in your projects. The SDK has a peer dependency on rxjs, which you need to install as well.

An alternative approach is to use the Kontent CLI boilerplate. This boilerplate contains a number of sample scripts (handy!) and automatically transpiles TypeScript into JavaScript files. This is extra useful because TypeScript is not standard supported by the Kontent CLI.

The next step is to register the environments using the following command:

kontent environment add --name <Enviroment> --api-key <Api key> --project-id <Project ID>

The Project ID and Api key are stored in the .environments.json file. Be extra careful and make sure you don't accidentally check this sensitive data into source control.

As mentioned, the Kontent CLI boilerplate contains sample scripts that clearly show how you can create, edit and publish content. To create a new migration file simply execute the following command:

kontent migration add --name <migration name>

You can directly create TypeScript files 💯 by specifying the template type:

kontent migration add --name <migration name> --template-type "typescript"

To keep things clear, I recommended to create separate scripts for each action. The order of execution can be determined via the order property, that can be specified within the migration script:

const migration: MigrationModule = {
    order: 1,
    run: async apiClient => {
        await apiClient
            .addContentType()
            .withData(BuildBlogPostTypeData)
            .toPromise();
    }
};

The scripts are executed sequentially based on the specified order and the status (successful / unsuccessful) is logged in a file called: status.json. Successfully executed scripts will no longer be executed in subsequent runs.

Tip: you can override the excution and force executed scripts to run again by passing in the --force parameter.

To run the migration execute the following command:

kontent migration run --environment <Enviroment>

Or in case of TypeScript and the Kontent CLI boilerplate:

npm run migrate:all

This command does basically the same but adds the command to convert TypeScript to JavaScript.

How did I expect it to work?

After I first heard about the plans to release the Kontent CLI about a year ago, I had the expectation that it would provide a way to develop the Information Architecture of projects using a code first approach. It soon became clear to me that this was not the primary goal of the Kontent CLI.

Therefore it is important to emphasize that the Kontent CLI is especially suitable for migrations but also scenarios such as the backup and restore of a Kentico Kontent project. See the Kontent backup manager for more info.

How could it work? 😄

After following the documentation I came up with the idea to put the migration scripts in source control and have them automatically executed via e.g. GitHub Actions after every commit. The process then looks like this:

1. A developer creates a new migration script and commits his change
2. The commit, after pull request review, triggers the GitHub Action workflow which runs the migration in Kentico Kontent

Although all this is just a fantasy, I am very enthusiastic about the potential of the Kontent CLI and I can't wait to use it in future projects. 😊