README
@servicecmd/cli
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
- Run
servicecmd docker
with flags.
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
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
- Run
servicecmd config docker
. - The interactive menu will appear with certain set of tasks.
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]
servicecmd config
servicecmd config:docker
servicecmd docker
servicecmd help [COMMAND]
servicecmd plugins
servicecmd plugins:inspect PLUGIN...
servicecmd plugins:install PLUGIN...
servicecmd plugins:link PLUGIN
servicecmd plugins:uninstall PLUGIN...
servicecmd plugins:update
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