Today we are excited to announce the stable v1.0 release of
d2, the DHIS2 CLI!
d2 is a modular, standardized, and consolidated tool to make developing in the DHIS2 ecosystem as painless as possible.
What can you do with d2?
There’s quite a lot here, and more features coming soon!
I’ll dive deeper into some advanced
d2 features in another post, but here’s a quick sampling of what you might want to do with it today.
d2 utils uid generate- this replaces the one function of the old
dhis2-clitool, if you don’t know what that is you probably don’t need it.
d2 cluster up dev --seed- Create a local docker cluster including a DHIS2 core instance (the latest dev version), an NGINX gateway, and a Postgres database seeded with the Sierra Leone demodb This requires Docker running locally for now. See d2-cluster for details, or stay tuned for another post!
d2 create cli my-cli-module- Create a new CLI module. This module can be published and run stand-alone, or included as a sub-module of
Explore! You can run
d2 --helpto list all the commands and namespaces available, then
d2 style --helpand all the way down to
d2 style js install --help.
How do you install it?
> yarn global add @dhis2/cli > d2 --help d2 <command> Commands: d2 app Front-end application and library commands d2 cluster Manage DHIS2 Docker clusters [aliases: c] d2 create <type> [name] Create various DHIS2 components from templates d2 style DHIS2 programmatic style for commit msgs/code [aliases: s] d2 utils Utils for miscellaneous operations d2 debug Debug local d2 installation Options: --version Show version number [boolean] --config Path to JSON config file -h, --help Show help [boolean]
If you just want to run a single command without installing
d2 globally, you can use
npx, for instance both commands above are equivalent to
npx @dhis2/cli --help
NB installation with
npm install -g @dhis2/cli should also work but yarn is recommended.
NB there is an open issue tracking support for zero-dependency binary executables (which wouldn’t require
node be pre-installed).
If either installing
npm or just by downloading an executable appeals to you, please indicate your support on issue #34 in the
What about other command-line utilites?
The goal of
@dhis2/cli is to consolidate and standardize the various fragmented command-line utilities in the
dhis2 ecosystem. If possible, other tools which can be implemented as Node.js scripts should be ported to
d2 namespaces moving forward.
As an initial example of this transition, the code-style and packages tools introduced by @varl in an earlier post are now deprecated in favor of their
d2 equivalents (
d2 style instead of
code-style. Yarn workspaces should be used instead of
packages for simple mono-repo support, and
d2 utils release replaces
packages release, although this should only need to run in CI environments like travis)
packages exec which multiplexes commands across a mono-repo has not yet been ported to
d2, so you might still need to use
packages to run i.e.
packages exec yarn build
Contributing and building your own CLI modules
Please contribute! The CLI is modular in design, so it’s built to be easily extensible and repurposed. Here’s how you can help
d2, and how
d2 can help you:
- If you find a bug, report it or help fix it!
- If you are familiar with command-line tools used in the DHIS2 ecosystem, particularly in development environments, and you think it might belong in the DHIS2 cli please let us know
- If you’d like to contribute to CLI development yourself, check it out on GitHub
- If you want to build a DHIS2 command-line tool with Node, whether or not it fits as a command or namespace in
d2, you can use the
d2 create clitoo which will bootstrap a simple CLI module project. This module will include the dependency @dhis2/cli-helpers-engine
cli-helpers-engine (for curious technical folks)
This helper library provides low-level primitives like:
namespacefor declaring groups of commands
makeEntryPointfor turning a command or namespace into an executable program
reporterwhich supports console output to stderr and stdout at different log levels, including support for
cachewhich is a bit more complex but supports local caching of downloaded files and archives for use in the CLI program. See
d2 debug cache --helpto manage your local cache and the d2 cluster source for an example of the cache in action.