v4.0.12

Changes

• The CLI is now published as datocms instead of @datocms/cli. Going forward, install with: npm install -g datocms
• The binary name, commands, plugins, and on-disk config (~/.config/datocms/...) are unchanged. This is purely a package-name change — shorter to type, matches the binary, and plays nicely with npx datocms.
• @datocms/cli keeps working. It is now a thin alias that depends on datocms and re-exports its binary and programmatic API. Existing installs and code that does import { Client } from '@datocms/cli/lib/cma-client-node' continue to work unmodified.

Migrating

If you had the scoped package installed globally, uninstall it before installing the new one so they don't fight over the datocms binary:

npm uninstall -g @datocms/cli
npm install -g datocms

User-installed plugins and saved profiles are preserved — they live under ~/.config/datocms and are shared between both install paths.

Also in this release

• Upgraded @whatwg-node/fetch and external DatoCMS client dependencies to latest.

v4.0.9

Changes

• --allow-primary flag for migrations:run — The CLI previously refused any in-place migration run on the primary environment. The recommended workflow is still to fork → run → promote, but that flow has real cost when a migration is strictly additive (e.g. adding an optional field, creating a new model). You can now opt in with --allow-primary to run the migration directly against primary.
• The guardrail error now surfaces both the recommended fork+promote workflow and the --allow-primary escape hatch via oclif suggestions, so the way out is discoverable the first time you hit it.
• Using --allow-primary prints a runtime warning: an in-place run has no automatic rollback, so a failure partway through leaves primary in a partially-migrated state. Only use this flag for migrations you've verified to be safe and additive.

Examples

# Recommended: fork, migrate, promote
datocms migrations:run --source=main
datocms environments:promote main-post-migrations

# New: in-place on primary (additive migrations only)
datocms migrations:run --source=main --in-place --allow-primary

v4.0.8

Changes

• cma:script now accepts a positional file argument — Most TS runners (tsx, node, bun) take the script path as a positional, so datocms cma:script /tmp/x.ts was a natural thing to try. Both the positional and -f/--file are accepted; the command errors out if they disagree.

Examples

# Both forms are now equivalent
datocms cma:script /tmp/my-script.ts
datocms cma:script -f /tmp/my-script.ts

v4.0.7

Changes

• New projects:list command — OAuth-only command that enumerates projects the logged-in account can reach across personal and organization workspaces, with optional fuzzy filtering by name/domain. Enables non-interactive agents to discover a siteId before invoking link --site-id.
• Non-interactive friendly link command — Detects non-TTY environments and either errors out with actionable guidance (when an interactive prompt would be needed) or falls back to sensible defaults for optional inputs. Unblocks the agent flow that discovers a siteId via projects:list and then runs link --site-id.

Examples

# Discover available projects
datocms projects:list

# Filter by name/domain
datocms projects:list --query my-blog

# Link non-interactively using a known site id
datocms link --site-id <siteId>

v4.0.6

Changes

• New cma:script command — Run one-off TypeScript scripts against the DatoCMS CMA. Accepts either a default-export async function (client: Client) => Promise<void> (portable, migrations-compatible) or plain top-level-await code with client and Schema available as ambient globals. Scripts run in an isolated workspace with live-generated project schema types and tsc type-checking, with stdout piped directly through (so output works with jq and other tools).
• Credentials moved to platform config dirs — credentials.json now lives under env-paths('datocms-cli') for platform-correct config locations.

Examples

# Run a script that uses the typed client
datocms cma:script -f ./my-script.ts

# Pipe output to jq
datocms cma:script -f ./list-items.ts | jq '.[] | .id'

v4.0.5

Changes

• New cma:docs command — Browse the DatoCMS Content Management API reference documentation directly from the terminal. List resources, describe actions, and expand details sections without leaving the CLI.

Examples

# List all available resources
datocms cma:docs

# Describe a specific resource and its actions
datocms cma:docs items

# Describe a specific action with examples
datocms cma:docs items create

# Expand a collapsed details section
datocms cma:docs items create --expand "Example: Basic example"

v4.0.4

Changes

• Revoke OAuth token on logout — datocms logout now revokes the OAuth token remotely before deleting local credentials
• Detect revoked tokens — When a stored OAuth token has been revoked (e.g. from account settings), the CLI now shows a clear error message instead of a generic "could not access project" error

v4.0.3

Changes

• Hide inaccessible projects in link command — Projects where the user doesn't have access permissions are no longer shown in the project selection list during datocms link

v4.0.2

Changes

• Allow re-login without requiring logout first — Running datocms login when already authenticated now replaces existing credentials instead of blocking
• Improve OAuth token resolution — Linked projects (via datocms link) now take priority over the DATOCMS_API_TOKEN environment variable, so OAuth-based authentication is not silently overridden
• Improve error messages — Better error message when a linked project cannot be accessed, mentioning possible OAuth permission changes

v4.0.1

Changes

• Hide empty workspaces in link command — Workspaces with no projects are filtered out before presenting the selection prompt, removing options the user can't meaningfully pick.
• Credentials path change — Internal change to where credentials are stored.