@tool3/nicli v3.3.15

                                                 ___
                                      __        /\_ \   __
                                 ___ /\_\    ___\//\ \ /\_\
                               /  __ \/\ \  / ___\\ \ \\/\ \
                               /\ \/\ \ \ \/\ \__/ \_\ \\ \ \
                               \ \_\ \_\ \_\ \____\/\____\ \_\
                                \/_/\/_/\/_/\/____/\/____/\/_/

                                    multi monorepo manager

install

install nicli globally using: npm install -g @tool3/nicli

quick start

see setup steps below or simply setup a new workspace

platform dependencies

given you are working with the following platform dependencies, nicli can be a great fit for your workflow:

• npm
• lerna
• ts-node
• pm2
• mongo
• docker docker-compose
• cucumber for e2e tests

naming system

given you are working with microservices in monorepo git structure. nicli creates a short name map (for microservices with longs names this saves a lot of typing).

you can provide different structures per monorepo in .niclirc.
to see all available shorthands that nicli creates from your filesystem on the fly: run nicli map -a.

it creates a shorthand from the microservice name, splitting at - as a delimeter.
for names with no dashes, nicli takes the first 3 letters as a shorthand.
if a shorthand name already exists under that monorepo - the full name will be used.

config

nicli creates a default config file under your home directory named: .niclirc.json, with the following structure:

{
  "workingDirectory": string,
  "stdout": boolean,
  "lerna": {
     "scope": string,
     "prefix": string
  },
  "mongo": {
    "dir": string,
    "collection": string,
    "ports": {  
       "db1": number,
       "db2": number.
       "router": number,
       "config": number
    },
  },
  "structure": string,
  "env": object,
  "prefix": string,
  "repositories": array<object>
}

workingDirectory

nicli's workingDirectory is the master directory, under which all monorepos will cloned and hosted. to setup a working directory, run the following commands:

# <path-to-dir> is the root directory which will have all of the monorepos.
mkdir <path-to-dir>

# configure nicli to use it as a workspace directory.
nicli config set workingDirectory <path-to-dir>

Running nicli config get workingDirectory - will return the configured working directory.

you can export NICLI_WORKING_DIR as an environment variable and use that as nicli's working directory.

stdout

by default, nicli will wrap the results in a spinner and show the final status once completed (✔ or ✘). In order to always allow stdout across allnicli's commands - change this config to true.

lerna

nicli was built on mananging several monorepos which already has a lerna.json - but it can also work with npm only.

• scope: the scope of the packages\microservices in a given monorepo (overrideable).

  Note that the value given in the config will be wrapped with @ - so given "scope": "sample" will be @sample.

• prefix: sometimes it's useful to prefix packages\microservices names with some prefix for better management - nicli supports this - leave blank for no prefix - overrideable.

mongo

nicli runs a mongo cluster locally in pm2, with a single router, single config, and 2 shards.

use this section in .niclirc to customize ports and collection name, or provide an alternative mongoOptions json config for nicli run

by default, nicli will create the data/db and data/config directories under nicli's root working directory.

change this by providing a dir key to the mongo section in .niclirc

structure

structure represents the path to the microservices directory in your monorepo:

server/
  ├──package.json
  └──packages/
       └──services/
           ├─some-microservice-name
           |   └─package.json
           └─some-microservice-name
               └─package.json        

you can configure a structure at the top level of .niclirc or override with a specific structure in the repository object of the repositories section in .niclirc.

env

the env section in .niclirc is a json key-value object which will be available as process.env in all of the microservices running in pm2.

prefix

if you are managing your monorepo using lerna - and you have a prefixed name for each microservice under a certain monorepo - nicli supports it and will prepend this prefix to the service name so it could tell lerna about the service(s) needed for the current command.

leave an empty string to not use a prefix.

repositories

the repositories in .niclirc are a collection of a repository json object which represents a monorepo:

{
  // repo name - must match name in filesystem under the root directory
  "name": "some-repo", 
  // alias will become a flag for this repo
  "alias": "s", 
  // repo http url - use --http to use this url
  "http": "http://url-to-repo",
  // repo ssh url - default
  "ssh": "ssh@url-to-repo",
  // overrides top-level structure configuniclition
  "structure": "Server/packages/services" 
  // default services runs in pm2 by default
  "defaults": ["some-service"], 
  // lerna config
  "lerna": { 
    "scope": "sample"
    "prefix": "service"
  } 
}

default services

specify default services per monorepo in the defaults section of the repo config. defaults expects an array of strings which are the microservices names on the file system.

config commands

get key

# get config file
nicli config get

# get config key
nicli config get workingDirectory

set

# set config key
nicli config set workingDirectory ~/projects

delete

# delete config key
nicli config delete workingDirectory ~/projects

use

# use alternative config file
# config file will be saved under ~/.niclirc.json
nicli config use /path/to/config.json

revert config

In order to revert to default config, run:

rm ~/.niclirc.json

and then simply nicli config set workingDirectory <path-to-dir> this will recreate the config file using the default config file under nicli's root project repo (~/.niclirc.json)

experimental (macos only)

try nicli verify to check platform and npm dependencies.
run with nicli verify --fix if your on macos, this will use brew to install the missing dependencies.
Otherwise, follow manual steps below.

clone

after settings a config dir, run nicli clone -a.

Note: if you wish to only clone the repos relevant to your projects - see flags

commands

see all available nicli commands using nicli or nicli --help

run

run runs services in pm2. run can accept a repo flag, services shorthands or services full name. nicli run <repo-alias> run all of that repo services in pm2

{
    ...
    "alias": "p"
    ...
}

the above example repo alias, will result in the ability to do:

# following commands will run on all services under the repo aliased with 'p'
$ nicli run -p
$ nicli test -p
$ nicli build -p

bootstrap

alias: bs
bootstrap runs lerna bootstrap for an entire repo or specific services.

usage:

# bootstrap repo
$ nicli bootstrap -r 

# bootstrap specific services using shorthands
$ nicli bootstrap rec cv

# boottstniclip specific services using full-names
$ nicli bootstrap client-views receiver

install

install runs npm install in a given repo/specific services.

usage:

# install help
$ nicli install --help

# npm install repo
$ nicli install -r

# npm install specific services
$ nicli install cv rec

build

build runs lerna run build in a given repo/specific services.

usage:

# build help
$ nicli build --help

# build repo
$ nicli build -r

# build specific services
$ nicli build cv rec

test

test runs lerna test for a repo or specific services.

usage:

# test help
$ nicli test --help

# test repo
$ nicli test -r

# test specific services
$ nicli test cv rec

ct

ct runs e2es for a given repo/feature path/directory.

run nicli ct -${repo-alias} <feature-path>.
ommiting the <feature-path> will run all e2e tests under that repo.

map

map creates a services shorthand on-the-fly each time you run a command. You can see all of the service shorthand map with nicli map -a, or specific repo by their respective flag. run nicli map --help for help.

usage:

# map help
$ nicli map --help

# show all repos shorthands
$ nicli map -a

# show a specific repos' shorthands
$ nicli map -z

NOTE some services don't have a shortcut - that's because the shorthand already exists under that repo.

changed

changed returns the names of services which files have changed in the relevant repo's last commit HEAD.

usage:

# changed help
$ nicli changed --help

# run build only for the services that changed under that repo
$ nicli build $(nicli changed -r)

# show changed services\libs under that repo
$ echo $(nicli changed -l)

exec

exec runs a custom command in a given repo/specific services.

usage:

# exec help
$ nicli exec --help

# exec command in repo and don't show result
$ nicli exec "npm install --save ts-node" -r

# exec command in repo and show result
$ nicli exec "echo `pwd`" -rs 

# exec command in repo and each of it's services
$ nicli exec "echo `pwd`" -res

cd

cd returns a given repo/specific services paths.

usage:

# get path for a repo
$ nicli cd -z

# get path for a specific service
$ nicli cd cv

# change to a repo directory
$ cd $(nicli cd -z)

# change to a specific service directory
$ cd $(nicli cd cv)

git commands

run git commands across all projects. This is useful when building cross services features.

status

runs git status in a given repo/specific services.

usage:

# git status for a repo directory
$ nicli status -z

# git status for all repos
$ nicli status -a

clone

runs git clone for a given repo/specific services.

usage:

# git clone a repo
$ nicli clone -r

# git clone all repos
$ nicli clone -a

pull

runs git pull for a given repo/specific services.

usage:

# git pull a repo
$ nicli pull -r

# git pull all repos
$ nicli pull -a

checkout

runs git checkout for a given repo/specific services.

usage:

# git checkout a branch in a specific repo
$ nicli checkout master -r

# git checkout changes (remove changes) in a specific repo
$ nicli checkout . -r

# git checkout qa branch across all repos
$ nicli checkout qa -a

# git checkout to a new branch in a specific repo
$ nicli checkout -b new_branch -z

# git checkout a new branch in all repos
$ nicli checkout -b new_branch -a

command help

Note that running any command with --help will reveal that command’s specific help menu and special options.

specific services and dynamic run

You can use nicli to run specific services along with the default ones and containers.
For example: running nicli run cv - will run client views and the default services and containers.
You can than add services dynamically by repeating the same run command with other services instead.
So running nicli run sec - will run site-events-consumer while not interfering with the running containers and services.

ci/cd

You can use nicli as a CI tool - by combining flags, for example:
nicli build $(nicli changed -z) - will build ONLY the analytics services,that changed in the last git HEAD.

this can be useful when we only want to test services who's code changed in the last commit HEAD:

#will only build services under repo aliased with '-z'
$ nicli build $(nicli changed -z) 

new workspace

setting up a new workspace is easy with nicli.
the time it takes for these commands to complete varies between machines and commands.

# install nicli globally
npm install -g @tool3/nicli  

# create a workspace directory
mkdir ~/projects                              

# configure working directory
nicli config set workingDirectory ~/projects  

# clone all repos configured in ~/.niclirc.json
nicli clone -a                                

# lerna bootstrap in all repos
nicli bootstrap -a

# see available commands
nicli --help                                  

nicli in docker

⚠️ WORK IN PROGRESS ⚠️