Environments and migrations

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"

Need to manage multiple DatoCMS projects from the same repo?

You can set up additional profiles with the datocms profile:set <NEW_PROFILE_NAME> command.

When you have multiple profiles, you can specify the profile to use to run a command with the --profile flag (or by exposing a DATOCMS_PROFILE environment variable).

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.

You can either pass it as a flag 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