Introducing the new DatoCMS CLI

Following our recent release of the new TypeScript API client, we're happy to also announce an improved CLI to interact with DatoCMS!

The biggest advantages it offers compared to the previous CLI?

• Migration scripts can now be written in TypeScript;

• You can easily setup tab auto-completion for Bash and zsh shells;

• Profile files can be used to store and share a set of sane defaults with other developers in your team;

• An extensible architecture: the CLI is split into a number of modules that you can install separately when needed, and everybody can contribute creating and sharing new custom modules;

• Every command offers a --json option that will output the result as JSON, so that it can be easily parsable by other CLI tools like jq;

• It warns the user if a newer version of the CLI is available to install;

• More coherent conventions around command names/flags/arguments, etc.

Basic usage

You can install the new CLI using npm:

$ npm -g install @datocms/cli@latest

The commands exposed by the CLI are grouped into topics/namespaces:

$ datocms --help
CLI to interact with DatoCMS APIs
VERSION
  @datocms/cli/1.0.0 darwin-x64 node-v14.19.1
USAGE
  $ datocms [COMMAND]
TOPICS
  environments  Manage primary/sandbox environments of a project
  maintenance   Enable/disable maintenance mode for a project
  migrations    Create a new migration script
  plugins       List installed plugins.
  profile       Remove a profile from DatoCMS config file

Each topic holds a number of commands, which you can inspect with the --help flag:

$ datocms environments --help
Manage primary/sandbox environments of a project
USAGE
  $ datocms environments:COMMAND
COMMANDS
  environments:destroy  Destroys a sandbox environment
  environments:fork     Creates a new sandbox environment by forking an existing one
  environments:index    Lists primary/sandbox environments of a project
  environments:list     Lists primary/sandbox environments of a project
  environments:primary  Returns the name the primary environment of a project
  environments:promote  Promotes a sandbox environment to primary

Shell auto-completion

The CLI comes with auto-completion ready for your shell! You can read the setup instructions with the command:

$ datocms autocomplete

Once configured, every command and flag is one tab away from you!

Config file and profiles

The new CLI can read from (and write to) a configuration file called datocms.config.json, which is meant to be stored in your projects root directory. The config file can be safely added to your Git repository (it doesn't contain secrets) and it is very useful to share a set of sane defaults with other developers in your team, or to simply stop repeating yourself with the same flag options every time you run a command.

A single config file can also hold different profiles, each with different preferences. This allows your projects to work with multiple DatoCMS projects at the same time, if needed.

You can configure a profile with the profile:set command (and re-run the same command at a later time if you need to make some changes):

$ datocms profile:set 
Config file not present in "datocms.config.json", will be created from scratch
Requested to configure profile "default"
* Level of logging to use for the profile (NONE, BASIC, BODY, BODY_AND_HEADERS) [NONE]: 
* Directory where script migrations will be stored [./migrations]: 
* API key of the DatoCMS model used to store migration data [schema_migration]: 
* Path of the file to use as migration script template (optional): 
Writing "datocms.config.json"... done

The name of the profile in this case will be "default", but if you want a different name you can just specify it as an argument:

$ datocms profile:set custom_name

By default the CLI will load the settings of the "default" profile, but you can pass an explicit --profile flag to a command (or expose a DATOCMS_PROFILE environment variable) to use a different profile instead.

Specifying your project API token

Most of the commands of the CLI interact with a specific DatoCMS project, so a valid DatoCMS API token is often required as a parameter.

There are multiple ways to pass this information. You can either use the --api-token flag on every command you run, ie.:

$ datocms migrations:run --api-token=<YOUR-API-TOKEN> [...]

Or expose it as an environment variable:

$ export DATOCMS_API_TOKEN=<YOUR-API-TOKEN>
$ datocms migrations:run [...]

To specify the API token related to a profile different than the default one, the environment variable name will be DATOCMS_<UPPERCASE_PROFILE_NAME>_PROFILE_API_TOKEN.

Store API tokens in an .env file

The CLI also reads environment variables from a local .env file, so you can place the token there — just make sure not to commit the file to your repo!

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

Migration scripts in TypeScript

One of the most common uses for the CLI is running migration scripts. The new CLI works in conjunction with our recently released TypeScript client, so this means that you can finally write your migration scripts in TypeScript!

The command to generate a new script is migrations:new, which will automatically generate a TypeScript script file if your project contains a tsconfig.json file:

$ datocms migrations:new 'create article model'
Created migrations/1591173668_createArticleModel.ts

The documentation about Sandbox Environments and Migration Scripts is already updated, so make sure to read it!

How to migrate old migration scripts?

There's no need for that! 😃 If you have existing migration scripts written for the legacy datocms-client CLI, simply move them to a legacyClient directory, and the CLI will take care of passing them the legacy API client instead of the new one:

mkdir migrations/legacyClient
mv migrations/*.js migrations/legacyClient

Additional modules: WordPress/Contentful importer

To keep the CLI lightweight, we decided to split some less frequently used functionality into separate modules that can be installed at a later time.

You can always take a look at all the official additional modules with the plugins:available command:

$ datocms plugins:available
package                       description                          installed
───────────────────────────── ──────────────────────────────────── ─────────
@datocms/cli-plugin-wordpress Import a WordPress site into DatoCMS true
[...]

As an example, if you need our Wordpress to DatoCMS importer, you can install it with this command:

$ datocms plugins:install @datocms/cli-plugin-wordpress

And a new wordpress:import command will appear:

$ datocms wordpress:import --help
Imports a WordPress site into a DatoCMS project
USAGE
  $ datocms wordpress:import --wp-username <value> --wp-password <value> [--json] [--config-file <value>] [--profile <value>]
    [--api-token <value>] [--log-level NONE|BASIC|BODY|BODY_AND_HEADERS] [--wp-json-api-url <value> | --wp-url <value>]
    [--autoconfirm] [--ignore-errors] [--concurrency <value>]

Wrap up: with a solid foundation, the future is bright!

At this time, the new CLI is merely a rewrite of the previous one, without much additional functionality. But it is a rewrite that gives us the confidence to extend it with many more commands in the near future. We're really happy about the final result, and we hope you'll like it too.

As always, please let us know what you think in our Community! 🙏♥️

P.S. The legacy CLI will be only maintained to apply periodic security updates. All the new development efforts will be focused on this new project, so we strongly suggest to move to the new CLI when you find the time!