Cognigy Command Line Interface (CLI)

Cognigy CLI offers a series of tools and functionalities in order to interact with your Cognigy.AI virtual agent projects from the command line.

The CLI can only create Snapshots and Locales right now - no other resources. It is meant for changing already existing resources and manipulating their state.

Currently supported resources ():

- Flows (clone, restore, push, pull, diff, train)
- Lexicons (clone, restore, push, pull, diff)
- Endpoints (clone, restore, push, pull, diff)
- Snapshots (create)
- Extensions (pull)
- AI Agents (clone, push, pull)

For Endpoints, Transformers will be separately stores as TypeScript files

Installation

$3

We recommend to install the Cognigy.AI CLI globally to use wherever you like. In order to so, perform the following step.

npm install -g @cognigy/cognigy-cli

$3

Alternatively you can use a local copy by performing the following steps:

1. Clone the repo
2. Run npm ci
3. Run npm run build
4. Run node build/cognigy init
5. (optional) Run npm link to enable running cognigy globally

$3

The Cognigy CLI will respect the HTTP_PROXY/http_proxy and HTTPS_PROXY/https_proxy and NO_PROXY/no_proxy environment variables.

If you're behind a proxy, you might need to configure NPM separately to use it. You can do that using the commands below.

``
npm config set proxy http://usr:pwd@proxy.company.com:8080
npm config set https-proxy http://usr:pwd@proxy.company.com:8080
`

Configuration

Configuration can be provided via config.json file. The config.json can be created by executing cognigy init.

The Cognigy.AI CLI needs the following configuration:

| Key | Description | Environment Var |
| ---------------------- | ---------------------------------------------------- | ---------------------------- |
| baseUrl | The base URL of your Cognigy.AI environment API | CAI_BASEURL |
| apiKey | The Cognigy.AI API Key to use | CAI_APIKEY |
| agent | The ID of your agent project | CAI_AGENT |
| agentDir | The folder where you want to store the agent locally | CAI_AGENTDIR |
| playbookTimeoutSeconds | Timeout for checking playbook runs | CAI_PLAYBOOK_TIMEOUT_SECONDS |

NOTE: The API Base URL is the endpoint for accessing the Cognigy.AI OpenAPI.

Both environment configuration and file-based configuration can be used together. Environment configuration takes priority.

Commands

$3

#### Help

To get help on any command, use the -h flag.

cognigy -h or cognigy -h

#### Forcing configuration files

By default the CLI will use the ./config.json configuration file.
You can force the use of another configuration file by using the -c flag.

cognigy -c ./config2.json or cognigy --config ./config2.json

#### Forcing execution without warnings

By default the CLI will reconfirm if data is overwritten locally or on Cognigy.AI.
You can force these checks to be skipped with the -y flag.

Example: cognigy clone -y or cognigy clone --forceYes

Some environments may have rate limits. This means that when executing commands that require a high number of API requests (e.g. clone), the env rate limit may be reached, and the process stops by throwing an error.

$3

cognigy init

Initializes a new Cognigy.AI CLI project

$3

cognigy clone

Clones a Virtual Agent from Cognigy.AI to disk

| Option | Alias | Type | Default | Description |
| ------------------- | ----- | ------ | ------- | --------------------------------------------------------------------- |
| --type | -t | String | agent | Which type of resource to clone (agent stands for the full project) |

Supported resource types for clone:

- agent (default, clones everything including AI Agents)
- flows
- endpoints
- lexicons
- aiAgents

$3

cognigy restore

Restores the local agent copy back into Cognigy.AI by executing a push for every resource.

| Option | Alias | Type | Default | Description |
| ------------------- | ----- | ------ | ------- | ----------------------------------------------------------------------- |
| --type | -t | String | agent | Which type of resource to restore (agent stands for the full project) |

$3

cognigy pull

Pulls a specific remote resource from Cognigy.AI

$3

cognigy push

Pushes a specific remote resource to Cognigy.AI

> You can't create resources or agents by pushing. Resources must already exist on Cognigy.AI
>
> For Flows, only Intents and Node configurations will be updated, not Flow structure

$3

cognigy diff

Compares a local resource to a remote resource

| Option | Alias | Type | Default | Description |
| ------------------- | ----- | ------ | ------- | ------------------------------------------------------------- |
| --mode | -m | String | full | Full (full) vs Node-by-Node (node) comparison of the Flow |

$3

cognigy train flow

Trains the NLU model of a specified Flow on Cognigy.AI

| Option | Alias | Type | Default | Description |
| ---------------------- | ----- | ------ | ------- | -------------------------------------------------------------------------------------------------- |
| --timeout | -t | Number | 10000 | Timeout in ms before training progress is no longer checked (training will continue on Cognigy.AI) |

$3

cognigy create snapshot [resourceDescription]

Creates a remote resource on Cognigy.AI and downloads it to disk.

> Currently only Snapshots and Locales can be created
> For Snapshots, use cognigy create snapshot snapname "My Description"
> For Locales, use cognigy create locale localename

| Option | Alias | Type | Default | Description |
| ----------------------------- | ------ | ------- | ------- | -------------------------------------------------------------------------------------------- |
| --timeout | -t | Number | 100000 | Timeout in ms before the creation process is no longer checked (will continue on Cognigy.AI) |
| --skipDownload | -s | Boolean | false | Skips download of created resource (for snapshots) |
| --fallbackLocale | --lf | String | - | ID (not Reference ID) of Locale to use for new Locale |
| --nluLanguage | --lnlu | String | - | NLU Language to set for new Locale |

$3

cognigy exportcsv flow

Exports the content of a Flow to CSV.

This command will go through all Flows in all Locales and create a content.csv file next to the JSON. This file can be used to update content.

$3

cognigy importcsv flow

Imports the content of a CSV back into a Flow.

This command will go through all Flows in all Locales and check if a valid content.csv exists. If yes, it will go through the Flow Chart and update all localized Nodes with the content from the CSV.

$3

cognigy localize flow

Adds localization to Flow Intents and Nodes in bulk.

This command will go through all Intents and Nodes in a given Locale and will add a localization if not already present.

| Option | Alias | Type | Default | Description |
| ------------------------------ | ----- | ------- | ------- | -------------------------------------------------------------------------------- |
| --localName | -l | String | - | Locale to add localizations to |
| --sourceLocale | --sl | String | - | Source Locale to create localization from (optional) |
| --localizeIntents | --li | Boolean | true | Whether to localize intents (if active, localizeNodes default is false) |
| --localizeNodes | --ln | Boolean | true | Whether to localize Nodes (if active, localizeIntents default is false) |
| --contentOnly | --co | Boolean | false | Only localize Say, Question and Optional Question Nodes (optional) |
| --reverse | -r | Boolean | false | Removes the localization from the selected Flow (can be combined with --li/--ln) |

$3

cognigy translate

Translates the plain text of a chosen resource, such all Nodes inside a Flow.

| Option | Alias | Type | Default | Description |
| ------------------------------- | ----- | ------- | ------- | -------------------------------------------------------------------------- |
| --localeName | -l | String | - | The locale to process |
| --fromLanguage | --fl | String | - | The language to translate from |
| --toLanguage | --tl | String | - | The language to translate to |
| --translator | --tr | String | - | The translation tool that should be used. 'google', 'microsoft' or 'deepl' |
| --translateIntents | --ti | Boolean | false | Whether to add localization to Flow Intents |
| --translateNodes | --tn | Boolean | false | Whether to add localization to Flow Nodes |
| --apiKey | -k | String | - | The API Key for the chosen translation tool |
| --forceYes | -y | Boolean | false | Whether to skip warnings and overwrite all content |

$3

cognigy execute

Executes a command of the Cognigy REST API Client. For more information on API calls, please see our OpenAPI documentation.

Supports injecting payloads either through pipes or the -d (--data) option:

- echo '{"flowId": "5f5618bce35138ed3ab9ab9a"}' | cognigy execute readFlow
- cognigy execute readFlow -d '{"flowId": "5f5618bce35138ed3ab9ab9a"}'

This command uses the baseUrl and apiKey parameters of your configuration.

| Option | Alias | Type | Default | Description |
| ------------------- | ----- | ------ | ------- | ----------------------------------------------- |
| --list | -l | - | - | Lists all available commands |
| --data | -d | string | - | Injects a data payload (must be in JSON format) |

$3

cognigy run playbooks

Schedules runs of one or more playbooks and checks their status.

Will either use a ./playbooks.json file or any other file you point it to. Format:

`
[
{
"playbookId": "",
"entrypoint": "", // snapshot ID or agent ID (if no snapshot is used)
"flowId": "", // this is the flow reference ID
"localeId": "" // this is the locale reference ID
},
{
"playbookId": "",
"entrypoint": "",
"flowId": "",
"localeId": ""
}
]
`

The run command outputs the status of the playbook runs and exits:

| Output | Exit Code |
| ------- | --------- |
| SUCCESS | 0 |
| FAILURE | 1 |
| TIMEOUT | 2 |

All details are written to ./playbookRunResults.json

$3

Cognigy Knowledge AI Documentation

FAQ

Frequently asked questions (FAQ)

Contributing

Make sure you pull origin from the develop branch
`git pull develop````

$3

Commit using the commitizen hook with semantic naming convetion promt

`bash
npx cz
``

$3

Create PR with any kind of feature/bugfix folloving the semantic message format to the develop branch.

Any PRs to develop needs to be merged as squash merges.

$3

Create a PR from develop to main and do a merge commit. This will automatically trigger a new release.
To make the release publish a new minor version to the npm registry, the commit message needs to follow the [semantic message format] and having at least one of the commits to main from the last release with a fix.