@servicecmd/cli

Monitor and manage docker-compose stacks easily. This CLI enables the user to proxy commands to multiple docker-compose stacks.

Usage no npm install needed!

<script type="module">
  import servicecmdCli from 'https://cdn.skypack.dev/@servicecmd/cli';
</script>

README

@servicecmd/cli

Build Status Version Downloads/week Dependencies semantic-release

Demo

This is the base of the @servicecmd. All other features will extend the capabilities of the default CLI.

This CLI enables the user to proxy commands to multiple docker-compose stacks.

Install

$ npm install -g @servicecmd/cli
$ servicecmd COMMAND
running command...
$ servicecmd (-v|--version|version)
@servicecmd/cli/1.0.0 linux-x64 node-v16.9.1
$ servicecmd --help [COMMAND]
USAGE
  $ servicecmd COMMAND
...

Initial Setup

Usage

Proxying Commands to Groups

There is important flags you want to keep an eye on.

Run [-r] [--run]

  • Will run a certain command for the set of services.

    These commands coincide withs the naming scheme of docker-compose cli and can be:

    • up
    • down
    • restart
    • logs
    • kill
    • stop
    • exec
    • pull
    • build
    • ls -> shows the services inside docker-compose stack
    • ps
    • rm
    • top
    • stats -> filters docker stats with the containers specified

  • Some of these commands have their unique flags required but the CLI will throw out an error requesting them if it is missing.

  • Some of these commands also have their specific flags which it will pass them to the docker-compose CLI.

  • I have used flags instead of positional arguments since I sometimes prefer to add the command to end and change it on different runs and sometimes I prefer to add the command to the beginning and change the other parameters.

Examples
  • Run a command servicecmd docker -r up

Group [-g] [--group]

  • Will limit the task to certain group which is the designated name while defining the set of docker-compose stacks in servicecmd config docker.
  • Can be multiple for running the command in multiple groups.
  • Will default to all which will run for all services defined in the configuration file.
Examples
  • Run for all groups: servicecmd docker ...
  • Run for specific group: servicecmd docker -g some-other-group ...
  • Run for multiple specific groups: servicecmd docker -g some-group -g some-other-group ...

Limit [-l] [--limit]

  • Will filter the services depending on their absolute path after all the regular expressions in the configuration has been evaluated.

    Example for your configuration of group:

    { path: '/docker/**', depth: 0 }

    Where you have services after being evaluated:

    /docker/service1/docker-compose.yml
/docker/service2/docker-compose.yml
/docker/service3/docker-compose.yml
/docker/other/docker-compose.yml

    Limit is essentially a JavaScript regular expression so

    • -l "service.?" or -l service will resolve to all 3 services with name service on them.
    • -l service3 will resolve to only service3.

  • Can be multiple arguments.

Examples
  • Run for a single service: servicecmd docker -l service/
  • Run for multiple service with regular expressions: servicecmd docker -l "service.?/"
  • Run for multiple services imperatively: servicecmd doker -l service1/ -l service2/ -l service3/

Ignore [-i] [--ignore]

  • Ignore is the same with limit flag but the other way around limitting the services that should be run.
  • Ignore will run after every service is parsed so it also takes in hand your group and limit flags.
Examples
  • Run for everything except a single service: servicecmd docker -i service/
  • Run for everything except multiple service with regular expressions: servicecmd docker -i "service.?/"
  • Run for everything except multiple services imperatively: servicecmd doker -i service1/ -i service2/ -l service3/

Prompt [-p] [--prompt]

  • This will parse the command and create a yes/no prompt with what command it will apply to and for which targets.

Target [-t] [--target]

  • For some commands you can target the container name directly.
  • The argument might be required depending on the run command.
  • This is a docker-compose specific argument which only works for given set of run commands. servicecmd docker --help will list the commands it works with.
Examples
  • Run logs for only single container named mysql in your docker-compose stack that resides in /docker/some-container: servicecmd docker -l some-container -t mysql -r logs

Args [-a] [--args]

  • You can add any argument and this flag will append it to the end of the command.
  • The argument might be required depending on the run command.
  • This is a docker-compose specific argument which only works for given set of run commands. servicecmd docker --help will list the commands it works with.
Examples
  • Drop in to bash session of container named mysql in your docker-compose stack that resides in /docker/some-container: servicecmd docker -l some-container -t mysql -r exec -a bash
  • Add abort-on-container-exit flag to up run command: servicecmd docker -l some-container -r up -a "--abort-on-container-exit"

Docker-Compose Specific Arguments

  • Some of the docker-compose arguments have their proxy in this CLI to have easy access.
  • Certain arguments work with certain run commands. servicecmd docker --help will list the commands it works with.

Configuration Files

  • Configuration files are in yml format to make it easier to manage it with automation tools like Ansible, Puppet or Chef.
  • Configuration files are stored in the ${HOME}/.config/servicecmd folder.

Adding a new configuration

  • Run servicecmd config docker.

  • An interactive prompt will appear. Select "add" option.

  • Fill the generated prompt.

    • Path is the option where you define the service root.

      The service root can be:

      • Absolute folder of the docker-compose stack.

      • Single or multiple regular expressions in gitignore format. Multiple expressions should be seperated by ":".

        Regular expressions will also prompt for the depth that it should search for files. The default is 1 which is directly that folder. But you can designate it as 0 to disable this limit or throw in a integer value to limit the depth.

    • Name will be the alias of the designated group where it is used to address it in other command. It will default to the folder name itself.

    • File can be multiple expressions seperated by ":". If you want to run other named docker-compose files like "docker-compose.production.yml" it will be useful for that. Defaults to "docker-compose.yml".

Managing an existing configuration

Command Description
Show Show the current configuration.
Add Will add a new group to the current configuration.
Edit Edit an existing entry.
Remove Remove one or more entries in the configuration file.
Delete Delete the local configuration file compeletely.
Import Import a configuration from a local file or HTTP.

Commands

servicecmd autocomplete [SHELL]

display autocomplete installation instructions

USAGE
  $ servicecmd autocomplete [SHELL]

ARGUMENTS
  SHELL  shell type

OPTIONS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

EXAMPLES
  $ servicecmd autocomplete
  $ servicecmd autocomplete bash
  $ servicecmd autocomplete zsh
  $ servicecmd autocomplete --refresh-cache

See code: @oclif/plugin-autocomplete

servicecmd config

Manipulate the configuration options for this CLI.

USAGE
  $ servicecmd config

See code: dist/commands/config/index.ts

servicecmd config:docker

Edit services that is managed by this CLI.

USAGE
  $ servicecmd config docker

DESCRIPTION
  - Path can be a absolute value or a regular expression in gitignore format seperated by ":".
  - Name is a alias to group the specific set of services.
  - Regular expressions can have a depth to limit their recursive iteration over folders. "0" will disable this limit.

See code: dist/commands/config/docker.ts

servicecmd docker

Runs the designated command over the the intended services.

USAGE
  $ servicecmd docker

OPTIONS
  -a, --args=args                                                              Always adds this as the last argument.
                                                                               Works with commands: "up, down, restart,
                                                                               logs, kill, stop, exec, pull, build, ls,
                                                                               ps, rm, top"

  -g, --group=group                                                            [default: all] Limit the task with
                                                                               service group name.

  -i, --ignore=ignore                                                          Ignore a service utilizing JavaScript
                                                                               regex pattern depending on the final
                                                                               folder location.

  -l, --limit=limit                                                            Limit a service utilizing JavaScript
                                                                               regex pattern depending on the final
                                                                               folder location.

  -p, --prompt                                                                 Prompt user before doing something.

  -r, --run=up|down|restart|logs|kill|stop|exec|pull|build|ls|ps|rm|top|stats  (required) Execute the given command.

  -t, --target=target                                                          Target a container directly in
                                                                               docker-compose file. Works with commands:
                                                                               "logs, kill, stop, exec"

  --force-rm                                                                   Always remove intermediate containers.
                                                                               Works with commands: "build"

  --no-cache                                                                   Use no cache. Works with commands:
                                                                               "build"

  --parallel                                                                   Run Docker tasks in parallel. Works with
                                                                               commands: "build"

  --privileged                                                                 Give extended privileges to the process.
                                                                               Works with commands: "exec"

  --pull                                                                       Always pull fresh image. Works with
                                                                               commands: "build"

  --remove-orphans                                                             Remove containers for services not
                                                                               defined in the compose file. Works with
                                                                               commands: "up, down"

  --rmi=all|local                                                              Remove containers for services not
                                                                               defined in the compose file. Works with
                                                                               commands: "down"

See code: dist/commands/docker/index.ts

servicecmd help [COMMAND]

display help for servicecmd

USAGE
  $ servicecmd help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

servicecmd plugins

list installed plugins

USAGE
  $ servicecmd plugins

OPTIONS
  --core  show core plugins

EXAMPLE
  $ servicecmd plugins

See code: @oclif/plugin-plugins

servicecmd plugins:inspect PLUGIN...

displays installation properties of a plugin

USAGE
  $ servicecmd plugins:inspect PLUGIN...

ARGUMENTS
  PLUGIN  [default: .] plugin to inspect

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

EXAMPLE
  $ servicecmd plugins:inspect myplugin

See code: @oclif/plugin-plugins

servicecmd plugins:install PLUGIN...

installs a plugin into the CLI

USAGE
  $ servicecmd plugins:install PLUGIN...

ARGUMENTS
  PLUGIN  plugin to install

OPTIONS
  -f, --force    yarn install with force flag
  -h, --help     show CLI help
  -v, --verbose

DESCRIPTION
  Can be installed from npm or a git url.

  Installation of a user-installed plugin will override a core plugin.

  e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command 
  will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in 
  the CLI without the need to patch and update the whole CLI.

ALIASES
  $ servicecmd plugins add

EXAMPLES
  $ servicecmd plugins:install myplugin 
  $ servicecmd plugins:install https://github.com/someuser/someplugin
  $ servicecmd plugins:install someuser/someplugin

See code: @oclif/plugin-plugins

servicecmd plugins:link PLUGIN

links a plugin into the CLI for development

USAGE
  $ servicecmd plugins:link PLUGIN

ARGUMENTS
  PATH  [default: .] path to plugin

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

DESCRIPTION
  Installation of a linked plugin will override a user-installed or core plugin.

  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello' 
  command will override the user-installed or core plugin implementation. This is useful for development work.

EXAMPLE
  $ servicecmd plugins:link myplugin

See code: @oclif/plugin-plugins

servicecmd plugins:uninstall PLUGIN...

removes a plugin from the CLI

USAGE
  $ servicecmd plugins:uninstall PLUGIN...

ARGUMENTS
  PLUGIN  plugin to uninstall

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

ALIASES
  $ servicecmd plugins unlink
  $ servicecmd plugins remove

See code: @oclif/plugin-plugins

servicecmd plugins:update

update installed plugins

USAGE
  $ servicecmd plugins update

OPTIONS
  -h, --help     show CLI help
  -v, --verbose

See code: @oclif/plugin-plugins