Command line interface tool that can be used for generating and runningKontent.ai migration scripts
npm install @kontent-ai/clish
npm install -g @kontent-ai/cli
`
🌟 Migration example
The current version of the CLI is useful for creating and running migration templates. Let's go through creating your first migration for a Kontent.ai project.
$3
When you need to add new features to your project and app, it's better to verify the changes in a separate non-production environment. In Kontent.ai, clone your project from the list of your projects.
$3
To improve the learning curve of our new CLI, we've prepared a Kontent.ai CLI boilerplate with examples on how to use the CLI. Clone the boilerplate GitHub repository on your drive. In the next step, you'll run a migration script from the boilerplate's Migrations directory.
$3
Open a command line and navigate to the root of the boilerplate folder (should be migrations-boilerplate) and execute the following commands:
`sh
Navigates to the root of the Kontent.ai CLI boilerplate folder.
cd ./migrations-boilerplate
npm install
Registers an environment (a pair of two keys, a environment ID and API key used to manage the environment) for migrations.
kontent environment add --name DEV --api-key --environment-id (Use the copy of your production project from the first step)
Runs a specific migration.
npm run migrate 01_sample_init_createBlogType
`
Kontent.ai CLI supports only running JavaScript migration files so in case you want to write in TypesScript, CoffeScript or in any other language you have to transpile your code before running.
In the case of TypeScript, you may use this example from Kontent.ai CLI boilerplate
That's it! You've run your first Kontent.ai migration. This migration created a content type called Blog that contains three text elements named Title, Author and Text. The sample migration is written in TypeScript.
The boilerplate is configured to transpile TypeScript migrations into plain JavaScript so that the Kontent.ai CLI can execute the migrations. Note that if you don't want to use TypeScript for your migrations, it's fine to write the migrations directly in JavaScript.
$3
You should now be able to go through the other boilerplate sample migrations. The migration scripts in the Migrations directory all focus on one scenario – replacing a piece of text from the Author text element with Author content items, which contain more information about the author. This way you can replace the texts within your items by more complex objects containing, for example, images and rich text.
You can use similar approach for your own specific scenarios. For example, imagine you need to add display information to the images inserted in your articles. You may want to specify relative size or caption for each image. To do this, you would need to open each article and replace every image with a component that would contain the image and a few elements for image metadata. You'd create small migration scripts for separate parts of the scenario (such as creating a new type, updating the articles, and so on) and the migrations will take care of the process for all articles within your environment.
Usage
Use the --help parameter to display the help section for CLI tool.
`sh
kontent --help
`
Combine the --help parameter with a specific command to learn more about that command.
`sh
kontent migration add --help
`
$3
The supported commands are divided into groups according to their target, at this first version there are just to spaces "migration" and "environment" containing following commands:
* environment add – Store information about the environment locally.
* The environment is defined as a named pair of values. For example, "DEV" environment can be defined as a pair of a specific environment ID and Management API key. This named pair of values is stored within your local repository in a configuration file named .environments.json.
* You can specify a named pair of environment ID and Management API key using these options: --environment-id .
* migration add --name – Generates a script file (in JavaScript or TypeScript) for running a migration on a Kontent.ai environment.
* The file is stored in the Migrations directory within the root of your repository.
* Add your migration script in the body of the run function using the Kontent.ai Management SDK that was injected via the apiClient parameter.
* Add your rollback script in the body of the rollback function using the Kontent.ai Management SDK that was injected via the apiClient parameter.
* To choose between JavaScript and TypeScript when generating the script file, use the --template-type option, such as --template-type "javascript".
* The migration template contains an order property that is used to run a batch of migrations (range or all) in the specified order. Order can be one of the two types - number or date.
* Ordering by number has a higher priority. The order must be a unique positive integer or zero. There may be gaps between migrations, for example, the following sequence is perfectly fine 0,3,4,5,10
* Ordering by date has a lower priority. To add date ordering use the switch option -d. The CLI will generate a new file which name consists of the date in UTC and the name you have specified. Moreover, the property order inside the file will be set to the Date accordingly.
* Executing all migrations will firstly migrate migrations with orders specified by number and only then migrations with order specified by date.
* By specifying range you can migrate either number-ordered migrations or date-numbered migrations. They can't be combined.
`typescript
// Example migration template
import {MigrationModule} from "@kontent-ai/cli";
const migration: MigrationModule = {
order: 1,
run: async (apiClient) => {
// TODO: Your migration code.
},
};
export default migration;
`
* migration run - Runs a migration script specified by file name (option --name ), or runs multiple migration scripts in the order specified in the migration files (options --all or --range).
* By adding --range you need to add value in form of number:number in case of number ordering or in the format of Tyyyy-mm-dd-hh-mm-ss:yyyy-mm-dd-hh-mm-ss in case of date order.
> When using the range with dates, only the year value is mandatory and all other values are optional. It is fine to have a range specified like T2023-01:2023-02. It will take all migrations created in January of 2023. Notice the T at the beginning of the Date range. It helps to separate date ordering from number order.
* You can execute a migration against a specific environment (options --environment ) or environment stored in the local configuration file (option --environment ).
* To execute your rollback scripts instead of run scripts, use the switch option --rollback or shortly -b.
* After each run of a migration script, the CLI logs the execution into a status file. This file holds data for the next run to prevent running the same migration script more than once. You can choose to override this behavior, for example for debugging purposes, by using the --force parameter.
> Note: For every migration there is only one record in the status file. Calling run/rollback continuously overrides the that record with new data.
* You can choose whether you want to keep executing the migration scripts even if one migration script fails (option --continue-on-error) or whether you want to get additional information logged by HttpService into the console (option --log-http-service-errors-to-console).
* backup --action [backup|restore|clean] - This command enables you to use Kontent.ai backup manager
* The purpose of this tool is to backup & restore Kontent.ai projects. This project uses CM API to both get & restore data.
$3
You might want to implement your way to store information about migrations status. For instance, you would like to save it into DB such as MongoDB, Firebase, etc,... and not use the default JSON file. Therefore, we provide you with an option to implement functions readStatus and saveStatus. To do so, create a new file called plugins.js at the root of your migrations project, and implement mentioned functions there. To fit into the required declarations, you can use the template below:
`js
//plugins.js
exports.saveStatus = async (data) => {}
exports.readStatus = async () => {}
`
> Note: Both functions must be implemented.
It is also possible to use Typescript. We have prepared types SaveStatusType and ReadStatusType to typesafe your functions. To create plugins in Typescript, create a file plugins.ts and implement your functions there. We suggest using and implementing the template below:
`ts
//plugins.ts
import type { ReadStatusType, SaveStatusType } from "@kontent-ai/cli";
export const saveStatus: SaveStatusType = async (data: string) => {}
export const readStatus: ReadStatusType = async () => {}
`
> Note: Don't forget to transpile plugins.ts into plugins.js otherwise your plugins will not work.
$3
By default, we do not provide any additional logs from the HttpService. If you require these logs, you can change this behavior by using (option --log-http-service-errors-to-console).
If you come across an error and you're not sure how to fix it, execute your migration script as follows and setup your debugger to the specified port.
`sh
node --inspect .\node_modules\@kontent-ai\cli\lib\index.js migration run -n 07_sample_migration_publish -e DEV
``