qcli is command line interface for management of quark services.

This overview covers qcli syntax, describes the command operations and provides common examples.

Installation

1. download latest release: qcli-windows-amd64-0.1.0-beta.5
2. add downloaded binary to PATH
3. open console and enter command:

qcli version

if everything is ok, you should get response similar to this:

Version: 0.1.0-beta.5

Configuration

As qcli is esentially a client for chost management API and it can manage multiple quark hosts, some settings for those managed hosts must be configured:

Execute following command:

qcli hosts

If this is the first time qcli is started response like this may come as a result:

 NAME | URI | DESCRIPTION | DEFAULT

showing that there are no configured console hosts.

Let’s assume that we have two running console hosts somewhere:

• first one, reachable at http://192.168.10.11:5000 (default console host management API port).
• second, reachable at http://171.55.33.223:12000 (custom port).

To add informations about hosts, we are using qcli hosts add command. To see how to use the command, type:

qcli help hosts add

and some basic usage help should be displayed:

kosta@ZEHN:/$ qcli help hosts add
Add host to list

Usage:
  qcli hosts add <NAME> <URI> [flags]

Examples:
qcli hosts add somename http://localhost:5000" - add server at http://localhost:5000 to a list of managed hosts with nam
e "somename"

Flags:
  -d, --default              set host as default (default=false)
  -D, --description string   set description
  -h, --help                 help for add

Global Flags:
  -v, --verbose   show verbose info
kosta@ZEHN:/$

As it turns out qcli hosts add <NAME> <URI> is the path to follow - we want to store uris of console host processes for future management. As it is usually easier to remember names then ip based uri’s, we can (actually we must) name that host instance, also.

Looking at the help above we can see few flags that can be set, and for now, let’s look at the “-D” flag: description. Not a mandatory info, but it also can be of help in certain situations.

Finally, we will try to add host at http://192.168.10.11:5000 aptly named host-1 with additional description Host in the sky with diamonds by executing following command:

qcli hosts add host-1 http://192.168.10.11:5000 --description "Host in the sky with diamonds"

Response should be:

Host name:host-1, uri:http://192.168.10.11:5000 added to list

So far, so good. To be sure that host name is stored use command: qcli hosts list or qcli hosts or even shorter version qcli h:

   NAME  |            URI            |          DESCRIPTION          | DEFAULT
  host-1 | http://192.168.10.11:5000 | Host in the sky with diamonds | true

We can see that host-1 is name for the host listening at http://192.168.10.11:5000 described as a host in the sky with diamonds, and also that it is the default host.

What does “default” mean? To answer that question, we should add another host to manage. Same principles applied, final command to be executed is:

qcli hosts add host-2 http://171.55.33.223:12000 --description "Abbey Road host"

Another qcli hosts reveals that host-2 info is accurate, but it is not default. This looks reasonably enough, only one of those should be default at last:

   NAME  |            URI             |          DESCRIPTION          | DEFAULT
  host-1 | http://192.168.10.11:5000  | Host in the sky with diamonds | true
  host-2 | http://171.55.33.223:12000 | Abbey Road host               | false

Host settings (and all other settings for that matter) are stored in $HOME/.qcli folder, so removing content should get you to a fresh start if needed.

Host management

Properties of registered hosts can be retreived or changed using command qcli manage:

Manage single quark console host

Usage:
  qcli manage [command]

Examples:
Set description for default host:
        qcli manage set description "Some description"

Set description for host named "server-name":
        qcli manage set description "Some description" --server server-name

Get description for host named "server-name":
        qcli manage get description  --server server-name

Get uri for default host:
        qcli manage get uri


Available Commands:
  get         Get host properties
  set         Set host properties

Flags:
  -h, --help          help for manage
  -s, --host string   set host name (default "host-2")

Global Flags:
  -v, --verbose   show verbose info

Use "qcli manage [command] --help" for more information about a command.

Usage

List hosted services

After setting up host configuration, we should be able to query hosts for services they contain and run. Command allowing us to do so is qcli services or qcli service or qcli srv or shortest one: qcli q. Go ahead and execute

qcli services

and result will be something like this:

          NAME         |  STATE
  allegro              | running
  assonoPublisher      | stopped
  cargoList            | stopped
  core112              | stopped
  eCall                | stopped
  smsPeeker            | stopped
  plk                  | stopped
  podZir               | stopped
  radioSniffer         | stopped
  remoteGIS            | stopped
  inSGW                | stopped
  mediatorSGW          | stopped
  outSGW               | stopped
  smsRest              | stopped
  spin                 | stopped
  spinExternalListener | stopped
  statKlicLogger       | stopped

What we got back is a list of loaded quark modules and their states. As it can be seen, only running quark service is allegro, rest of them are happily stopped.

Remember that we have two hosts defined? host-1 and host-2 both have some quark services installed and running, hopefully, so what services are we getting back? Answer is quite expected: from default host, of course.

To inspect it in more details, execute following command:

qcli services -v

-v is a global flag and it will make qcli display more verbose informations. Result might look like this:

Using server name:host-1, uri:http://192.168.10.11:5000, description:Host in the sky with diamonds
Show services:all
          NAME         |  STATE
  allegro              | running
  assonoPublisher      | stopped
  cargoList            | stopped
  core112              | stopped
  eCall                | stopped
  smsPeeker            | stopped
  plk                  | stopped
  podZir               | stopped
  radioSniffer         | stopped
  remoteGIS            | stopped
  inSGW                | stopped
  mediatorSGW          | stopped
  outSGW               | stopped
  smsRest              | stopped
  spin                 | stopped
  spinExternalListener | stopped
  statKlicLogger       | stopped

Seems nice, true that, but what if we had to query “the other” host? qcli help services has some hints again:

Manage quark services

Usage:
  qcli services [flags]
  qcli services [command]

Aliases:
  services, service, srv, q

Available Commands:
  config      Manage service configurations
  list        List services hosted within the selected host
  restart     Restarts service <NAME>
  start       Starts service <NAME>
  status      Get service status
  stop        Stop service <NAME>

Flags:
  -h, --help          help for services
  -s, --host string   set host name (default "host-1")
  -t, --type string   list services of type 'all','running','stopped' (default "all")

Global Flags:
  -v, --verbose   show verbose info

Use "qcli services [command] --help" for more information about a command.

There is a --host or -s (shorthand) flag allowing us to specify the host we would like our command to be executed on. Therefore, to see what is happening on our second quark host, command would be:

qcli services -s host-2 -v

meaning “we want to list services on host-2 and we would like some verbose informations”:

Using server name:host-2, uri:http://171.55.33.223:12000, description:Abbey Road host
Show services:all
          NAME         |  STATE
  allegro              | running
  assonoPublisher      | stopped
  cargoList            | running
  core112              | running
  eCall                | running
  smsPeeker            | stopped
  plk                  | running
  podZir               | running
  radioSniffer         | stopped
  remoteGIS            | running
  inSGW                | running
  mediatorSGW          | running
  outSGW               | running
  smsRest              | running
  spin                 | running
  spinExternalListener | running
  statKlicLogger       | stopped

Here we can see that more quark services are running. Flag --type allows us to filter services by their state:

qcli services -s host-2 -v -t running

yields this:

Using server name:host-2, uri:http://localhost:5000, description:Abbey Road host
Show services:running
          NAME         |  STATE
  allegro              | running
  cargoList            | running
  core112              | running
  eCall                | running
  plk                  | running
  podZir               | running
  remoteGIS            | running
  inSGW                | running
  mediatorSGW          | running
  outSGW               | running
  smsRest              | running
  spin                 | running
  spinExternalListener | running

--type all is default flag value and it will display all services. --type stopped will display only stopped services, of course, and unknown type (--type foobar, for example) is considered as “all”

Service management

Services can be started, stopped and restarted using qcli:

• to get a single service status on a default server: qcli services status spin
• to start a single service on a default server: qcli services start spin
• to stop a single service on a default server: qcli services stop spin
• to restart a single service on a default server: qcli services restart spin

each of those commands will return informations about executed operation:

  NAME |  STATE  |       MESSAGE
  spin | running | Service spin started

Service configuration management

Quark service configurations are managed using command qcli services config. Help is always welcome source of informations: qcli help services config explains:

Manage service configurations

Usage:
  qcli services config [command]

Aliases:
  config, c, configuration, cfg

Available Commands:
  export      Export running services configuration
  get         Get service configuration
  set         Set service configuration

Flags:
  -f, --file string   use file for input or output
  -h, --help          help for config

Global Flags:
  -s, --host string   set host name (default "host-2")
  -v, --verbose       show verbose info

Use "qcli services config [command] --help" for more information about a command.

Take a closer look at Aliases section in the text above. Aliases for config command are c, configuration and cfg. We will sometimes use the shortest alias c in following examples. (almost every command has an alias, feel free to check help)

Get service configuration

To get service configuration, use get command: qcli s c get -h:

Read running service configuration

Usage:
  qcli services config get <NAME> [flags]

Aliases:
  get, g

Flags:
  -h, --help   help for get

Global Flags:
  -f, --file string   use file for input or output
  -s, --host string   set host name (default "host-2")
  -v, --verbose       show verbose info

Using this command you can query console host for quark service configuration:

• qcli services config get spin will display “spin” service config:

  {
  "active": 1,
  "endpointName": "PLKServiceSoap",
  "location": "",
  "plkEndpointUri": "http://branko.logos.si/SPINWS/PLKService.asmx",
  "siPodEndpointUri": "http://branko.logos.si/SPINWS/SiPodService.asmx",
  "spinPassword": "",
  "spinUsername": "",
  "subsystem": ""
  }
  

• qcli services config get spin -f spin-config.json will save spin quark config to a file spin-config.json

Get all services configuration

Composite settings can be displayed / exported to file

qcli services config export

should display configurations for all loaded services. (loaded = present in “modules” folder of the quark service host). Exporting to file can be done in a same way as for single config, adding --file settings.json as a flag to command above.

Set service configuration

Service configuration can be set, either completely or partially using command qcli services config set:

Set service configuration

Updates service configuration: configuration data may be supplied to this command from pipe or specified as
a flag -f

Usage:
  qcli services config set <NAME> [<property> <value>] [flags]

Aliases:
  set, s

Examples:
read standard input stream and set configuration for service named "metrics":
        qcli services config set metrics

read configuration from file "metric-config.json" and set configuration for "metrics" service:
        qcli services config set metrics --file metric-config.json

set configuration param "textReportPath" to "somereport.txt":
        qcli services config set metrics textReportPath somereport.txt


Flags:
  -h, --help   help for set

Global Flags:
  -f, --file string   use file for input or output
  -s, --host string   set host name (default "host-2")
  -v, --verbose       show verbose info

• settings can be imported from json file:

  qcli services config set spin -f spin-config.json

  or piped from stdin:

  cat spin-config.json | qcli services config set spin

• settings can be set individually, using qcli s c set <service-name> <property> <value> syntax: qcli services config set metrics textReportPath somereport.txt should set value of the textReportPath property for metrics quark service to value of somereport.txt

Every set command should return updated configuration as a result. Last command, for example, should result in something like this:

service:metrics, param:textReportPath, value:somereport.txt
Configuration for service metrics is set
{
  "appPerformanceMeters": true,
  "influxDbUri": "http://localhost:8086?db=mydb",
  "intervalToSend": 10,
  "sysPerformanceMeters": true,
  "tag": {
    "application": null,
    "host": null,
    "region": null
  },
  "textReportPath": "somereport.txt"
}

Get service configuration templates

Template for each service can be retrieved using qcli generate cfg <service-name> command. Executing qcli generate cfg metrics will get configuration template for metrics service:

{
  "metrics": {
    "active": 0,
    "appPerformanceMeters": false,
    "influxDbUri": null,
    "intervalToSend": null,
    "sysPerformanceMeters": false,
    "tag": {
      "application": null,
      "host": null,
      "region": null
    },
    "textReportPath": null
  }
}

Next steps

qcli help is your friend, and there is also browsable reference here.