Summary

keepcli is a command line tool used primarily for issuing search and aggregate queries. Additional verbs are added to the environment from time to time.

Prerequisites

keepcli is installed as a .NET Core Global Tool from our NuGet repository It runs on Windows, Mac and Linux environments using the .Net Core 3.0 SDK, which must be installed prior to installing and running keepcli. Download the SDK for your specific operating system from https://dotnet.microsoft.com/download

Confirm the .NET Core SDK is installed

dotnet --info
.NET Core SDK (reflecting any global.json):
 Version:   3.0.100
 Commit:    04339c3a26

Installation

dotnet tool install --global --add-source http://nuget.feenics.com/nuget keepcli

If keepcli is already installed it can be updated with

dotnet tool update --global --add-source http://nuget.feenics.com/nuget keepcli

Configuration

keepcli stores credential information in the folder Feenics/KeepCli within the system folder identified using System.Environment.GetFolderPath(System.SpecialFolder.LocalApplicationData)(see MSDN docs). This folder is varies by operating environment. On MacOS and Linux the path will be ~/.local/share and on Windows the path will be %HOMEDRIVE%%HOMEPATH%\AppData\Local.

keepcli supports multiple configurations. Each configuration is stored as a unique file with .json extension inside the configuration folder. Use the -@ option to name a configuration. If missing default is assumed.

These configuration files are unencrypted, and only as secure as the workstation & user profile on which they reside

keepcli configure \
    -a https://dev-api.feenicsdev.com \
    -i *yourinstance* -u *yourusername* \
    -p *yourpassword*

After setting the default configuration, try it out with the test verb.

keepcli test
Connected to *your instance commonName* (yourInstanceFQDN) on https://dev-api.feenicsdev.com version x.x.x.xxx

Verbs

The first argument for keepcli must be one of the defined verbs. Use the --help option to get a list of verb with descriptions for each verb.

keepcli --help
Copyright (C) 2019 KeepCli

  configure                Supply Configuration information to be saved to disk...
  test                     Test saved configuration
  list                     Test saved configuration
  get                      Get object by Key
  search                   Search
  command                  Command Mercury Readers
  aggregate                Execute an Aggregate Query
  getinfotemplate          Get object by Key
  message                  Send a message to a person
  renameFqdn               Rename an FQDN for an existing instance
  remove                   Remove saved configuration
  subscribe                Subscribe to events
  controller-changetype    Change the type of a Controller from Ep to Lp or Lp to Ep
  help                     Display more information on a specific command.
  version                  Display version information.

Use the --help option with a verb to get the set of options specific for that verb.

keepcli configure --help
KeepCli 1.0.32
Copyright (C) 2019 KeepCli

  -a, --ApiAddress        URL of the Keep Server to connect to.  For example https://api.feenicshosting.com for US customers
  -i, --Instance          The login name of the instance.  The same value that is supplied when logging in using the Windows, Web, or Mobile Clients
  -u, --Username          The username name to connect with.  May be proceeded with an different instance name in the system hierarchy
  -p, --Password          The password to be used for this user to connect.
  -r, --Replace           Update exisitng configuration with new values
  -c, --Copy              Copy this existing configuration
  -e, --EventPublisher    Url of the MQTT Event Publisher for this API Service
  -@, --Profile           (Default: default) Saved Profile Name
  --help                  Display this help screen.
  --version               Display version information.

Using KeepCli with cUrl

There are number of circumstances when making a cUrl call to the Keep by Feenics API is necessary as part of application development and testing. To make a curl call to the API, a valid access token is required. keepcli can be used to get an access_token as well as other necessary information.

#!/bin/bash
INSTANCE=$(keepcli test -j)
BASEADDRESS=$(echo $INSTANCE | jq -r .BaseAddress)
TOKEN=$(echo $INSTANCE | jq -r .Token)

curl -s -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" ${BASEADDRESS}/api | jq '{Cn:.CommonName, Fqdn:.FullyQualifiedDomainName, Key:.Key}'

This script uses the -j option on the test verb to return a JSON value similar to:

{
  "CommonName": "Really Good Software Company",
  "FullyQualifiedDomainName": "rgsc",
  "BaseAddress": "https://dev-api.feenicsdev.com",
  "Key": "5d81127e8ea1b00001393e9d",
  "Version": "2.0.4.139",
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6InJhbHBoIiwic3ViIjoiNWQ4MTEyODM4ZWExYjAwMDAxMzkzZWE2IiwiaW5zdGFuY2UiOiI1ZDgxMTI3ZThlYTFiMDAwMDEzOTNlOWQiLCJuYmYiOjE1NzA2NDc0NTMsImV4cCI6MTU3MDczMzg1MywiaWF0IjoxNTcwNjQ3NDUzfQ.Xxp4sVy2zvDFOso0JMffTV8VDVu5Q-OX7HY2CrrG_wk"
}

This JSON value is stored in the environment variable INSTANCE and from it the BASEADDRESS and TOKEN values are extracted using jq

the curl command in this case simply returns the InstanceInfo object for the logged in user

Search examples

The Keep by Feenics API offers a search facility that leverages the MongoDB search syntax. For example to find the zero or more people with a given name (first name) of Ralph use:

keepcli search -s '{"GivenName":"Ralph"}' -r | jq .

This will return one more PersonInfo objects. Use jq to filter out only specific fields. NB: the -r option forces a search across the hierarchy of folders/instances using the configured instance as a starting point.

keepcli search -s '{"GivenName":"Ralph"}' | jq '{cn:.CommonName, cards:[ .CardAssignments[]|.DisplayCardNumber]|join(",") }'

Subscribe to Events examples

The keepcli is able to subscribe to events in real time. Use the -t option to provide a template for the event output in human readable format. More typical use case is to transform the published event message into something more concise. Event subscription runs over a separate web socket from a separate service independent to the API Server. This service end point must be added to the configuration.

keepcli configure -r -e wss://dev-events.feenicsdev.com

Once configured use the subscribe verb to establish a connection to the event publisher. The event messages produced are an extension to the EventMessageData. keepcli adds the property EventData to the message, which is the JSON rendering of the EventDataBsonBase64 string that is also included. The EventData property of the event message is free-form and it’s contents will vary depending on the event type. Use the -d option to change the duration of the subscription, or the -l to limit the total number of events reported. Also note that DateTime properties such as PublishedOn, and OccurredOn are returned as Unix Epoch (milliseconds since 1970-01-01). Also all DateTime values are UTC.

{
  "PublishedOn":{"$date":1567596623176}
}

For example, the following command will subscribe to all events for a period of 1 hours (3600 seconds) and use jq to format the output to include only the PublishedOn date, MessageLong value, and all EventData.

keepcli subscribe -d 3600 | jq -c '{d:.PublishedOn."$date"| (. / 1000 | todate),m:.MessageLong,meta:.EventData}'

{
  "d": "2019-09-04T11:37:28Z",
  "m": "Login attempted by user System Administrator.  Outcome: Passed",
  "meta": {
    "Outcome": "Passed",
    "User": {
      "CommonName": "System Administrator"
    }
  }
}

Last updated: 09 Oct 19 15:16 EDT