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 like
It warns the user if a newer version of the CLI is available to install;
More coherent conventions around command names/flags/arguments, etc.
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 --helpCLI to interact with DatoCMS APIsVERSION@datocms/cli/1.0.0 darwin-x64 node-v14.19.1USAGE$ datocms [COMMAND]TOPICSenvironments Manage primary/sandbox environments of a projectmaintenance Enable/disable maintenance mode for a projectmigrations Create a new migration scriptplugins List installed plugins.profile Remove a profile from DatoCMS config file
Each topic holds a number of commands, which you can inspect with the
$ datocms environments --helpManage primary/sandbox environments of a projectUSAGE$ datocms environments:COMMANDCOMMANDSenvironments:destroy Destroys a sandbox environmentenvironments:fork Creates a new sandbox environment by forking an existing oneenvironments:index Lists primary/sandbox environments of a projectenvironments:list Lists primary/sandbox environments of a projectenvironments:primary Returns the name the primary environment of a projectenvironments:promote Promotes a sandbox environment to primary
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:setConfig file not present in "datocms.config.json", will be created from scratchRequested 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
Store API tokens in an
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
$ 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/legacyClientmv 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
$ datocms plugins:availablepackage 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 --helpImports a WordPress site into a DatoCMS projectUSAGE$ 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!