DatoCMS CLI

Profiles and multi-project setup

A profile is a named configuration block inside datocms.config.json that points the CLI at a specific DatoCMS project. When your repo only talks to one project, the default profile (created automatically by datocms link) is all you need. When your repo talks to multiple DatoCMS projects (for example, a blueprint project and several client projects), you create additional profiles, and select which one each command operates on.

Profiles vs environments

Profiles are about separating different projects or authentication contexts, not different environments of the same project. To target a sandbox environment of an already-selected project, use the --environment flag instead.

Creating an additional profile

Run link again, passing a profile name:

npx datocms link --profile=client_a

This appends a new profile block to datocms.config.json:

1
{
2
  "profiles": {
3
    "default": {
4
      "siteId": "12345",
5
      "organizationId": "67890",
6
      // ...
7
    },
8
    "client_a": {
9
      "siteId": "99999",
10
      "organizationId": "88888",
11
      // ...
12
    }
13
  }
14
}

Selecting the active profile

When you run a command, the CLI picks the active profile in this order:

--profile=<id> flag on the command
DATOCMS_PROFILE=<id> environment variable
default profile in datocms.config.json

So these two commands are equivalent:

npx datocms migrations:run --profile=client_a
DATOCMS_PROFILE=client_a npx datocms migrations:run

Token resolution per profile

When the CLI needs an API token for the active profile, it looks for one in this order:

--api-token flag on the command
The linked project's OAuth credentials (for profiles created via datocms login + datocms link)
An environment variable, named after the profile: - the default profile reads from DATOCMS_API_TOKEN - a client_a profile reads from DATOCMS_CLIENT_A_PROFILE_API_TOKEN - any other profile follows the same DATOCMS_<PROFILE>_PROFILE_API_TOKEN convention

If you want a custom environment variable name for a profile (for example because your CI provider already has a token under a different name), set the apiTokenEnvName property on the profile:

{
  "profiles": {
    "client_a": {
      "siteId": "99999",
      "apiTokenEnvName": "CLIENT_A_TOKEN"
    }
  }
}

CDA tokens don't work with the CLI

The CLI talks to the Content Management API, so the token must have CMA access (can_access_cma: true). Read-only CDA tokens like DATOCMS_READONLY_API_TOKEN or NEXT_PUBLIC_DATOCMS_API_TOKEN won't work.

Other profile-level configuration

Beyond siteId and apiTokenEnvName, every profile accepts a few additional properties:

organizationId: the DatoCMS organization the project belongs to
logLevel: NONE, BASIC, BODY, or BODY_AND_HEADERS (verbosity of CLI output)
logMode: stdout, file, or directory
baseUrl: for self-hosted or staging DatoCMS instances
migrations.directory: path where migration scripts live
migrations.modelApiKey: the API key of the DatoCMS model used to track applied migrations
migrations.template: path to a custom migration template file
migrations.tsconfig: path to a custom tsconfig.json for migrations

Use case: keeping multiple projects in sync

A common reason to use profiles is the blueprint → client workflow: you maintain a "blueprint" DatoCMS project where you evolve the schema, and you propagate the same migrations to multiple client projects. See Keeping multiple DatoCMS projects in sync for the full workflow.

Removing a profile

To remove a profile from datocms.config.json:

npx datocms unlink --profile=client_a