Environment, migration and maintenance commands

This chapter is a command reference for three groups of CLI commands that, together, form the lifecycle of a DatoCMS project: environments let you create isolated sandboxes, migrations evolve the schema in a controlled way, and maintenance mode locks the primary environment while sensitive changes go through.

The end-to-end deploy workflow that uses these commands (fork → migrate → maintenance:on → promote → maintenance:off) is documented in Apply migrations to primary environment, with rationale, edge cases, and CI patterns. This page just lists what each command does and the flags that matter.

Environment commands

DatoCMS lets you fork any environment into a new sandbox, work on it in isolation, and then promote it back to primary when ready. Five CLI commands cover the lifecycle:

npx datocms environments:list
npx datocms environments:fork <SOURCE_ENV> <NEW_ENV>
npx datocms environments:promote <ENV_ID>
npx datocms environments:rename <ENV_ID> <NEW_ENV_ID>
npx datocms environments:destroy <ENV_ID>

• environments:list: list every environment in the project (primary plus sandboxes).

• environments:fork: create a sandbox from an existing environment. Add --fast to skip the data copy when you only care about the schema, or --force to overwrite an existing environment with the same name.

• environments:promote: promote a sandbox to primary. The previous primary becomes a sandbox.

• environments:rename: rename an environment.

• environments:destroy: delete a sandbox.

For the underlying concept (primary vs sandbox environments, when to fork, how promotion works) see Primary and sandbox environments. For the recommended workflow when applying changes (fork → migrate → promote) see Safe iterations using environments.

Migration commands

Migrations are versioned scripts that evolve your project's schema. The CLI exposes two commands:

npx datocms migrations:new <NAME>
npx datocms migrations:run

• migrations:new: scaffold a new migration script. Defaults to TypeScript when a tsconfig.json is present; pass --js to force JavaScript. Add --autogenerate=<env> to generate a script that diffs the current project against another environment, or --schema=Article,Author to inline the TypeScript schema of selected models into the new script.

• migrations:run: apply all pending migrations. By default, it forks the primary environment into a sandbox called <primary>-post-migrations, runs the migrations there, and stops (it does not promote). Key flags:

  • --source and --destination: the environment to fork and the name of the new sandbox. Defaults: source is primary, destination is <source>-post-migrations.

  • --in-place: run migrations in the --source environment directly, without forking. Mutually exclusive with --destination.

  • --allow-primary: required when --in-place would target the primary environment. Use only for strictly additive migrations: there is no rollback if the run fails partway through. The recommended workflow remains fork, migrate, promote.

  • --dry-run: simulate the run without writing anything to the project.

  • --fast-fork: use a fast (schema-only) fork instead of a full one. The source is locked to writes while the fork is in progress. --force lets the fast fork start even when there are active editing sessions on the source.

  For config overrides (--migrations-dir, --migrations-model, --migrations-tsconfig) and the full flag list, run npx datocms migrations:run --help.

For everything migration-related (writing migration scripts, the recommended workflow, applying to primary), see the Scripting Migrations section. In particular: Write and test migration scripts and Apply migrations to primary environment.

Maintenance mode commands

Maintenance mode prevents content changes to the primary environment, both via the Content Management API and from collaborators editing in the dashboard. Use it during deploys, schema promotions, or any operation where concurrent writes would be unsafe.

npx datocms maintenance:on
npx datocms maintenance:off

• maintenance:on: enable maintenance mode. Pass --force to enable it even when other users are currently editing.

• maintenance:off: disable maintenance mode.

Maintenance mode is typically wrapped around an environments:promote, so that no editor can write to primary while the promotion is in progress.