Configuring the CLI

First of all, you need to install the DatoCMS CLI with the following command:

npm install @datocms/cli

You can verify that everything is correctly installed by running the help command of the CLI:

npx datocms --help

Setting up a CLI profile

Although not strictly necessary, we strongly suggest generating a datocms.config.js configuration file in the root of your website/app project to avoid having to repeat a number of options for every command you run.

You can configure the profile with the profile:set command — and re-run the same command at a later time if you need to make some changes:

$ npx datocms profile:set
Requested to configure profile "default"
Config file already has profile "default", existing settings will be overridden

✔ * Level of logging to use for the profile (NONE, BASIC, BODY, BODY_AND_HEADERS) NONE
✔ * Directory where script migrations will be stored ./migrations
✔ * API key of the DatoCMS model used to store migration data schema_migration
✔ * Path of the file to use as migration script template (optional)
✔ * Path of the tsconfig.json to use to run TS migration scripts (optional)
Writing "datocms.config.json"... done

The generated datocms.config.json file will look similar to this:

1
{
2
  "profiles": {
3
    "default": {
4
      "logLevel": "NONE", // See https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients#logging-request-responses
5
      "migrations": {
6
        "directory": "./migrations", // Where the autogenerated migration files are saved
7
        "modelApiKey": "schema_migration", // In the CMS, the API key of the model that will be created to save migration progress metadata
8
        "template": "", // You can provide your own template if you'd like. See https://github.com/datocms/cli/blob/main/packages/cli/src/commands/migrations/new.ts#L11-L88 for the default template
9
        "tsconfig": "" // Path to a custom tsconfig to use when running migration scripts. Only use if your dev env needs it.
10
      }
11
    }
12
  }
13
}

Most of the time, you can just simply confirm the default values suggested by the CLI.

Once done, add the config file to your Git repository:

git add datocms.config.json
git commit -m "Add datocms.config.json file"

Specify a DatoCMS API token

Before working with migrations, you also need to set up the API token to use to perform all the operations. The API token's associated role needs at least these permissions on all the environments you want to migrate from or to:

• Customize content navigation bar

• Create/edit models and plugins

• Create/edit workflows

• Create/edit shared filters

You can pass the API token as a parameter to every command, e.g.:

$ npx datocms migrations:run --api-token=<YOUR-API-TOKEN> [...]

Or expose it as an environment variable:

$ export DATOCMS_API_TOKEN=<YOUR-API-TOKEN>
$ npx datocms migrations:run [...]

The CLI also loads environment variables from a .env file, so you can also place the token there — but make sure not to commit the file to your repo!

$ echo '.env' >> .gitignore
$ echo 'DATOCMS_API_TOKEN=<YOUR-API-TOKEN>' >> .env