Environment, migration and maintenance commands

Three groups of commands that together form the lifecycle of a DatoCMS project: environments let you create isolated sandboxes, migrations let you evolve the schema in a controlled way, and maintenance mode lets you safely apply changes to the primary environment. They are commonly used together. For example, a typical deploy looks like fork → run migrations → maintenance:on → promote → maintenance:off.

This chapter lists the CLI commands in each group. For the underlying concepts and the recommended workflows, follow the cross-links to the dedicated sections.

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 NEW
npx datocms environments:promote ENV_ID
npx datocms environments:rename ENV_ID NEW_ID
npx datocms environments:destroy ENV_ID

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

• environments:fork SOURCE NEW: 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 ENV_ID: promote a sandbox to primary. The previous primary becomes a sandbox.

• environments:rename ENV_ID NEW_ID: rename an environment.

• environments:destroy ENV_ID: 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 NAME: 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. Key flags: --source and --destination for the environments to operate on, --dry-run to preview without applying, --fast-fork for a faster schema-only copy, --in-place to run on an existing environment instead of forking, --force to overwrite an existing destination, and --allow-primary to operate directly on the primary environment (typically used together with maintenance mode).

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.