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.
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
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
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
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 Consolenew-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 --query
option to
filter JSON responses. You must include the --json
option when using --query
.
Queries 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 \
--query "[].{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 \
--query "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 --query '[*].[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.
Return a list based on a prefix:
cortex projects list --project projectName --prefix my
All projects starting with "my" are returned from the example above.
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
Open PowerShell, then enter
node
to start node.Add the following variable.
NODE_PATH = %AppData%\npm\node_modules
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
toUnrestricted
. EnterSet-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".