DatoCMS CLI

Authenticate with an API token

Use an API token to authenticate the CLI when OAuth isn't an option, typically in CI/CD pipelines where there is no browser. The CLI resolves authentication in this order:

--api-token flag on the command
linked project via OAuth (when datocms.config.json is present and you are logged in)
environment variable (DATOCMS_API_TOKEN for the default profile).

The API token must have access to the Content Management API (can_access_cma: true). The exact set of role permissions you need depends on what you do with the CLI: schema migrations need permissions on models/fields, environment commands need environment management, maintenance mode needs the maintenance toggle, and so on.

You can pass the token as a parameter to every command:

$ 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 or .env.local file, so you can place the token there. Make sure not to commit the file to your repo:

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