# 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](https://www.datocms.com/docs/scripting-migrations/apply-migrations-to-primary-environment.md), 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: Terminal window ```bash npx datocms environments:list npx datocms environments:fork npx datocms environments:promote npx datocms environments:rename npx datocms environments:destroy ``` - `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](https://www.datocms.com/docs/general-concepts/primary-and-sandbox-environments.md). For the recommended workflow when applying changes (fork → migrate → promote) see [Safe iterations using environments](https://www.datocms.com/docs/scripting-migrations/safe-iterations-using-environments.md). > [!NOTE] Automating environments in CI > Environment commands are commonly automated. Typical patterns: forking a per-PR preview environment when a pull request opens, and destroying it when the pull request closes. Combine `environments:fork` with `--force` and `--fast` to make them re-runnable in a CI step. ## Migration commands Migrations are versioned scripts that evolve your project's schema. The CLI exposes two commands: Terminal window ```bash npx datocms migrations:new 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=` 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 `-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 `-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](https://www.datocms.com/docs/scripting-migrations/introduction.md). In particular: [Write and test migration scripts](https://www.datocms.com/docs/scripting-migrations/scripting-migrations-with-the-datocms-cli.md) and [Apply migrations to primary environment](https://www.datocms.com/docs/scripting-migrations/apply-migrations-to-primary-environment.md). ## 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. Terminal window ```bash 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. ## Related content in "DatoCMS CLI" - [CLI Overview](https://www.datocms.com/docs/cli.md) - [Environment, migration and maintenance commands](https://www.datocms.com/docs/cli/environment-migration-and-maintenance-commands.md) - [Generating TypeScript types from your schema](https://www.datocms.com/docs/cli/generating-typescript-schema.md) - [Importing content from other CMSs](https://www.datocms.com/docs/cli/importing-from-other-cms.md) - [CLI for AI coding agents](https://www.datocms.com/docs/cli/cli-commands-for-ai-coding-agents.md) - [Authenticate with an API token](https://www.datocms.com/docs/cli/authenticate-with-api-token.md) - [Profiles and multi-project setup](https://www.datocms.com/docs/cli/profiles-and-multi-project-setup.md)