New release is coming soon! If you want to try out the latest features, simply run npm i -s moleculer@next. The docs for the latest version are available here.

Command Line Tool

moleculer-cli npm

This is a command-line tool for Moleculer to help developing & testing.

Install

$ npm i -g moleculer-cli

Commands

Init

The init command is used to scaffold a new Moleculer project.

$ moleculer init project my-project

The above command downloads the template from moleculerjs/moleculer-template-project, prompts some information and generates a new module to the ./my-project folder.

Answers from file

You can put the question answers into a JSON file and load it with the --answers argument. It can be useful to generate project programmatically.

$ moleculer init project my-project --answers ./answers.json

Disable installing dependencies

You can disable the automatic NPM dependency installation with --no-install argument. It can be useful to generate project programmatically.

$ moleculer init project my-project --answers ./answers.json --no-install

Official templates

  • project - Generate a common Moleculer-based project. Use it if you want to start a new project which is based on Moleculer framework
    • sample service (greeter)
    • official API Gateway (optional)
    • Docker & Docker Compose files
    • tests & coverage with Jest
    • lint with ESLint
  • nano - Minimal project template for one microservice. Use it if you want to create a microservice which connect to others via transporter
    • sample service (greeter)
    • Docker & Docker Compose files
    • tests & coverage with Jest
    • lint with ESLint
    • Minimal Docker file
  • module - Generate a new Moleculer module project (e.g.: moleculer-xyz). Use it if you want to create a module for Moleculer framework
    • empty service skeleton
    • examples skeleton
    • readme skeleton
    • tests & coverage with Jest
    • lint with ESLint

Custom templates

$ moleculer init username/repo my-project

Where username/repo is the GitHub repo shorthand for your fork.

The shorthand repo notation is passed to download-git-repo so it can be bitbucket:username/repo for a Bitbucket repo and username/repo#branch for tags or branches.

Local Templates

Instead of a GitHub repo, use a template from local filesystem:

$ moleculer init ./path/to-custom-template my-project

Template aliases

To simplify usage of custom templates (local and remote), it is possible to register an alias and use that afterwards instead of the whole repository url.

$ moleculer alias-template myAlias somegithubuser/reponame
$ moleculer alias-template otherAlias ./path/to/some-local/custom/template


$ moleculer init myAlias my-project

All registered template aliases are stored in the file ~/.moleculer-templates.json and can also be edited manually.

Creating Custom Templates

Moleculer templates consist of a meta.js file and a template directory.

meta.js

The meta.js file exports a function that returns an object defining the Moleculer CLI init interface. The function takes a parameter values that gives access to external values passed in from the CLI. The object has several keys which are explained below.

The questions property is an array of objects defining the questions asked in the init process. These objects are Inquirer.js objects. Data collected here is stored in the Metalsmith metadata object.

The metalsmith property allows custom code to be executed at different points in the transformation process. The before function executes before the transformation is run, the after function executes after the transformation is run, and the complete function executes after the transformation is run and the files are copied to the destination directory.

The metalsmith functions take an argument metalsmith which gives a reference to the Metalsmith object. A common use is to get the Metalsmith metadata by calling metalsmith.metadata() and then adding or mutating properties on the metadata object so it will be available for the rest of the transformation.

The filters object takes a set of keys matching a path and a value matching the name of a question variable. If the question variable’s value is false, the specified path will be ignored during the transformation and those files will not be added to the project being intialized.

The completeMessage property takes a multiline string that will be displayed after the initialization is completed.

template

The template directory contains files which will be transformed using Handlebars and then copied to the destination directory. Handlebars is given the metadata object from Metalsmith to be the source for string replacement.

Handlebars can also transform file names.

Start

This command starts a new ServiceBroker locally and switches to REPL mode.

$ moleculer start

Options

--version     Show version number                                    [boolean]
--help        Show help                                              [boolean]
--config, -c  Load configuration from a file            [string] [default: ""]
--ns          Namespace                                 [string] [default: ""]
--level       Logging level                         [string] [default: "info"]
--id          NodeID                                  [string] [default: null]
--hot, -h     Enable hot-reload                     [boolean] [default: false]
--commands    Custom REPL command file mask (e.g.: ./commands/*.js)
                                                      [string] [default: null]

Connect

This command starts a new ServiceBroker, connects to a transporter server and switches to REPL mode.

# Connect with TCP transporter
$ moleculer connect

# Connect to NATS
$ moleculer connect nats://localhost:4222

# Connect to Redis
$ moleculer connect redis://localhost

# Connect to MQTT
$ moleculer connect mqtt://localhost

# Connect to AMQP
$ moleculer connect amqp://localhost:5672

# Load all options from config file
$ moleculer connect --config ./moleculer.config.js

Options

--version     Show version number                                    [boolean]
--help        Show help                                              [boolean]
--config, -c  Load configuration from a file            [string] [default: ""]
--ns          Namespace                                 [string] [default: ""]
--level       Logging level                         [string] [default: "info"]
--id          NodeID                                  [string] [default: null]
--hot, -h     Enable hot-reload                     [boolean] [default: false]
--serializer  Serializer                              [string] [default: null]
--commands    Custom REPL command file mask (e.g.: ./commands/*.js)
                                                      [string] [default: null]

Call

The call command can be used establish a connection with a Moleculer project and call an action with parameters. The result (stringified JSON) will be printed to the console. This means that you can process the result with another tool. The calling parameters should start with @ prefix and the meta parameters should start with # prefix.

Options

--version          Show version number                               [boolean]
--help             Show help                                         [boolean]
--config, -c       Load configuration from a file       [string] [default: ""]
--transporter, -t  Transporter connection string (NATS, nats://127.0.0.1:4222,
                   ...etc)                            [string] [default: null]
--ns               Namespace                            [string] [default: ""]
--level            Logging level                  [string] [default: "silent"]
--id               NodeID                             [string] [default: null]
--serializer       Serializer                         [string] [default: null]

Example with params

moleculer call math.add --transporter NATS --@a 5 --@b 3

Example with params & meta

moleculer call math.add --transporter NATS --@a 5 --@b 3 --#meta-key MyMetaValue

Example with post processing the result with jq

moleculer call "\$node.health" | jq '.mem.free'

The transporter can be defined via TRANSPORTER environment variable, as well.

Example with transporter env var

TRANSPORTER=nats://localhost:42222 moleculer call math.add --@a 5 --@b 3

Emit

The emit command can be used establish a connection with a Moleculer project and emit an event with a payload. The calling parameters should start with @ prefix and the meta parameters should start with # prefix.

Options

--version          Show version number                               [boolean]
--help             Show help                                         [boolean]
--config, -c       Load configuration from a file       [string] [default: ""]
--transporter, -t  Transporter connection string (NATS, nats://127.0.0.1:4222,
                   ...etc)                            [string] [default: null]
--ns               Namespace                            [string] [default: ""]
--level            Logging level                  [string] [default: "silent"]
--id               NodeID                             [string] [default: null]
--serializer       Serializer                         [string] [default: null]
--broadcast, -b    Send broadcast event             [boolean] [default: false]
--group, -g        Event groups                       [string] [default: null]

Example with params

moleculer emit user.created --transporter NATS --@id 3 --@name John

Example with params & meta

moleculer emit math.add --transporter NATS --@id 3 --@name John --#meta-key MyMetaValue

Example with broadcast & groups

moleculer emit math.add --transporter NATS --broadcast --@id 3 --@name John --group accounts

Example with multi groups

moleculer emit math.add --transporter NATS --broadcast --@id 3 --@name John --group accounts --group mail

The transporter can be defined via TRANSPORTER environment variable, as well.

Example with transporter env var

TRANSPORTER=nats://localhost:42222 moleculer call math.add --@a 5 --@b 3