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
--jsonoption that will output the result as JSON, so that it can be easily parsable by other CLI tools likejq;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@latestThe 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 fileEach 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 primaryShell auto-completion
The CLI comes with auto-completion ready for your shell! You can read the setup instructions with the command:
$ datocms autocompleteOnce 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"... doneThe 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_nameBy 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>' >> .envMigration 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.tsThe 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/legacyClientmv migrations/*.js migrations/legacyClientAdditional 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-wordpressAnd 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!