Use the CLI

This is a guide to getting started with using the Cortex CLI. This is the comprehensive SENSA Fabric CLI Reference Guide

The cortex command-line interface (CLI) helps you perform many Cortex tasks from your terminal, including:

• Generating and deploying skills
• Invoking agent services
• Configuring actions and connections
• Managing Campaigns
• Running Impact Assessments
• And many other common developer tasks

See the Install the Cortex Tools page to install the CLI.

Configure the CLI

Use the Cortex CLI cortex configure command to authenticate your Fabric CLI installation and to set up profiles.

To authenticate to the CLI, you must first obtain your personal access token:

• Login to Fabric Console and at the top right click the Settings icon(gear).; your personal access token is displayed.
• Either copy the token or download it to a local file. The CLI accepts both.

info

If your SENSA Fabric instance uses self-signed certificates, you'll need to get access to a Certificate bundle (.crt) file to set extra environment variables that will allow the Cortex CLI to authenticate and communicate with the SENSA Fabric instance successfully.

Please talk to your IT administrator or Devops team to get access to the appropriate Certificate bundle file. Once you have the file you need to set the following additional environment variable in any terminal that uses the Cortex CLI to talk to the Fabric instance.

export NODE_EXTRA_CA_CERTS=/path/to/your/ca.crt

Use a token file

In your terminal run:

cortex configure --file /personal/access/token.json --project defaultProject

Where:

• /personal/access/token.json is the location on your local drive of the token file that you downloaded from the Settings page in Console.
• defaultProject is the projectId of the Fabric project you want to work with. Setting a default project is optional but recommended. You can obtain Project IDs (names) by opening the Project List page in the Fabric Console.

Use a token string

1. In your terminal run:

   cortex configure --project defaultProject

   Where:

   • defaultProject is the projectId of the Fabric project you want to work with. Setting a default project is optional but recommended. You can obtain Project IDs (names) by opening the Project List page in the Fabric Console

2. The following is then displayed and you paste your token where indicated:

   Cortex Personal Access Token: <paste access token>

Use command line arguments

You can configure your user-profile using command line arguments:

cortex configure \
--file /personal/access/token.json \
--project defaultProject

note

When your token expires, you may get a 403 authorization error when running commands. You must go to Settings (top right gear icon) to obtain a new token and re-run cortex configure to reauthenticate.

Configure TTL for your auth Token

When you authenticate to Cortex, you can optionally set a time-to-live before the token is refreshed. This prevents being logged out for long running jobs if your browser does not support token refresh. You may set the TTL to milliseconds (ms), seconds (s), minutes (m), hours (h), days (d), weeks (w), months (M), or years (y). Include both an integer and the abbreviation for the scale.

To set the token TTL run:

cortex configure token --ttl <int> <ms, s, m, h, d, w, M, or y>

Example

cortex configure token --ttl 7200 s

Projects in the CLI

All activity in SENSA Fabric is Project-scoped. In other words, the system must know which Project you are working in. You are assigned to Projects by a system administrator.

When you authenticate to the CLI, you may optionally set a default Project (as in the example above). All commands following authentication will be carried out in the context of that default project setting unless you append the command with --project <project-name-not-default>

If you opt to NOT set a default project, you must append all CLI commands during the session with --project <project-name>.

Example You authenticate by running: cortex configure --file /personal/access/token.json --project myDefaultProject

To get a list of agents from the Project myDefaultProject run:cortex agents list. (You do not need to specify a project name.)

To get a list of agents from the Project myOtherProject without re-authenticating run: cortex agents list --project myOtherProject.

If you authenticate without specifying a default project for the session all commands must include a project name.

Configure user-profiles

In addition to the default user-profile, the CLI supports usage of named user-profiles. Multiple user-profiles can be configured to run the CLI against different Cortex deployments. This option is useful, for example, if you are working with different projects at the same time, so that you can easily switch between them.

To configure an additional user-profile, add --profile new-profile-name to cortex configure then enter the required information to authenticate.

Example:

cortex configure --project defaultProject --profile new-profile-name

Where:

• /personal/access/token.json is the location on your local drive of the token file that you downloaded from Settings (top right gear icon) in Console.
• defaultProject is the projectId of the Fabric project you want to work with. You can obtain Project IDs (names) by opening the Project List page in the Fabric Console
• new-profile-name is the name for the user-profile you want associated with this token.

After creating a new user-profile, it is set as the active user-profile. To view all of your configured user-profiles and to see which user-profile is active, run the command below. The active user-profile is highlighted in the response.

cortex configure list

To set which user-profile is active:

cortex configure set-profile profile-name

To use a different user-profile without changing the active user-profile, add the --profile option to your command. The example below lists agents for the profile2 account:

cortex agents list --profile profile2

Update the CLI

The CLI includes an automatic compatibility check that notifies you if you are required to update the CLI or if a newer version is available. The check is performed when you issue commands with the CLI.

A message is displayed if a newer version of the CLI is available or required.

If you receive this or a similar message, run the following command to update the CLI to the latest or the required version:

npm i -g cortex-cli@<latest-or-required-version>

where:

• -g indicates that the Cortex CLI is installed globally (recommended)
• <latest-version> is the latest Cortex CLI version, which is displayed in the update notification.

Query and filter CLI responses

Many of the Cortex CLI commands support a --json option to query JSON responses.

Values to the --json option use JMESPath to filter JSON documents, which is similar to the popular JQ tool and supported by Amazon AWS and other notable services.

The JMESPath documentation provides several query examples, however a few CLI-specific examples have been included below to help you get started.

Only valid JSON queries with the whitelisted parameters are allowed; error messages are provided that list issues by option.

You can also use Mongo-style queries as shown in Example 3 below.

Example 1: return limited data

This example lists all agents but filters the response to only return the name and title of each.

Command:

cortex agents list --json "[].{name: name, title: title}"

Response:

[
{
  "name": "tutorial/movie_recommendation",
  "title": "Movie Recommendation Agent"
},
{
  "name": "default/trading-insights-agent",
  "title": "Trading Insights Agent"
},
{
  "name": "default/client-complaints-agent",
  "title": "Client Complaints Agent"
}
]

Example 2: return limited data

This example lists all actions deployed in the project, supported by the create time, and only returns the name and creation date of the actions.

Command:

cortex actions list --json "sort_by([], &createdAt)[*].{Name: name, Created: createdAt}"

Response:

[
{
  "Name": "cortex/generate_insights",
  "Created": "2018-04-26T13:51:54.035Z"
},
{
  "Name": "cortex/optical_character_recognition",
  "Created": "2018-05-02T22:41:02.224Z"
},
{
  "Name": "nf/news_filter",
  "Created": "2018-05-21T21:15:32.907Z"
},
{
  "Name": "na/news_articles",
  "Created": "2018-06-04T19:35:30.796Z"
}
]

Example 3 - Comparison between Mongo-style query and JMESPath query to return limited data

EXAMPLE: CONNECTION MONGO-STYLE FILTER

cortex connections list --filter '{"name": {"$regex": "^hello"}}'

EXAMPLE: CONNECTION JMESPATH QUERY

cortex connections list --json '[*].[name,title]'

Sorting and modifying lists

You can also return lists that:

• limit the number of results:

  cortex connections list --project projectName --limit 10

• skip a specified number of records:

  cortex connections list --project projectName --skip 2

  (Limit and skip must be expressed as an integer.)

• sort the results (uses a Mongo-style query):

  cortex connections list --project projectName --sort  ‘{“createdBy”: 1}’

  The example above sorts the connections list in ascending order of createdBy date/time.

info

Skip is applied after sort; limit is applied after skip. The order of operations is sort, skip, limit.

CLI formatting with quotes

Some CLI commands require the use of quotes when passing complex string encoded objects as options. If you encounter issues running commands, check to make sure your quotes are properly escaped.

Example CLI command option --cmd with quotes:

cortex actions deploy \
  --actionType daemon \
  --docker example/image:daemon \
  --port 5000 \
  --project example \
  --cmd '["java","-jar","./libs/api-server.jar"]'

To avoid formatting issue use files-as-command. (described below)

Using Files as Commands

For some CLI commands, you can optionally create a .json or .yaml file that specifies the parameters and options in a file saved to a local drive.

JSON file example

{
"docker": "image-name:daemonTest",
"port": "5000",
"actionType": "daemon",
"name": "c12e/daemon-test"
}

YAML file example

docker: image-name:daemonTest
port: 5000
actionType: daemon
name: c12e/daemon-test

To call the file simply provide the command and the file path.

JSON file command example

cortex actions deploy  <path-to-json-file>

YAML file command Example

cortex action deploy --yaml <path-to-yaml-file>

Using files as commands for complex commands especially in Windows is a recommended best practice in SENSA Fabric.

Cortex CLI on Windows

While most of the prerequisites and set-up for Cortex CLI are the same across operating systems, Windows 10 occasionally exhibits issues when running cortex commands. Most of these issues can be fixed by changing a couple of node environment variables.

Node environment variables

1. Open PowerShell, then enter node to start node.

2. Add the following variable.

   NODE_PATH = %AppData%\npm\node_modules

3. In the System Variables section, append the PATH variable with %AppData%\npm.

Best practices

Use the following best practices when working with CLI on Windows 10:

• Use PowerShell as your command line application. PowerShell exhibits fewer issues with Cortex CLI than Windows Command Prompt.
• In PowerShell, make sure to set your Execution Policy to Unrestricted. Enter Set-ExecutionPolicy Unrestricted -Scope CurrentUser -Force -Verbose.
• For Windows use the file-as-command option described above for all CLI commands with complex arguments to avoid "bad format" or "bad request errors".