Cognigy Sessions: CLI and API

Welcome to Cognigy Sessions, our Techinar series from Conversational AI experts for experts. In every episode, we will do a deep dive into another Cognigy.AI topic. As a low code platform, Cognigy.AI comes with a lot of features that are designed to empower non-technical users. But in some cases, it's a developer's job to make the magic happen. So this episode is all about customizing Cognigy on code-level. In this session, we will show you: How to leverage the power of Cognigy.AI's comprehensive API. How a Command Line Interface allows you to automate developer tasks. And finally, how to build a continuous integration pipeline based on API and CLI. This recording is also available in our Help Center. Please follow the link below to access additional resources and go to our community for questions and discussions. Also, please be invited to start a free trial and explore Cognigy.AI's API in action if you are not already a Cognigy.AI user. And with that, let's start today's session.

Hi, everyone, my name is Phil, and today I'll be showing you around the Cognigy CLI or Command Line Interface. Now, what is the CLI? CLI as I said stands for Command Line Interface and it lets you interact with your Cognigy resources directly from the Command Line on Windows, Mac, or Linux. It has a lot of capabilities, such as editing existing Cognigy resources such as Flows and Lexicons directly on your harddrive, triggering actions within Cognigy.AI such as training Flows, creating Snapshots, and more. Exporting and importing content from Flows as CSV for easier editing. You have the ability to translate Flows and Intents using services like Google Translate or Microsoft Translate. Or you can execute any API command directly from the Command Line, which is really useful for scripting certain actions.

If you want to follow along you need two things: You need access to Cognigy.AI, which you can get at "signup.cognigy.ai" if you don't have a trial account yet and you need the Cognigy CLI. And you can install that by typing "npm install@cognigy/cognigy-cli -g" if you want to install it globally or you can take a look at the link below on npmjs.com where you find the package as well.

Now, let's look at the architecture of how everything fits together. On top, we have Cognigy.AI, which is our low-code Conversational AI editor, and you can access that at, for example, trial.cognigy.ai. This is where you can interface with Flows and Lexicons using our graphical user interface. You can also interact with all resources in Cognigy.AI through the Cognigy API so you can make REST API calls, which are documented in our OpenAPI documentation. And we've built a tool called the Cognigy REST API Client, a JavaScript module, which you can use to interface with the API from your JavaScript code, so from Node JS, for example. It is available for you to install as an npm module. It's called @cognigy/rest-api-client. And then we have the Cognigy Command Line Interface, the Cognigy CLI. The Cognigy CLI uses the REST API client. It makes a lot of the commands available in a more user-friendly way so that you can use your command line, for example, your Bash or your Windows command interface, to then interact with Cognigy through the REST API client and the API. And that's what we're going to look at today.

Now, the basic principle behind the CLI is that the CLI will pull information from Cognigy.AI and store it on your harddrive. Then you can work with those local copies on your harddrive, and then when you save them, you can push the changes back to Cognigy. So whilst you're sometimes doing that, most of the time you're making your changes locally and then you're pushing them back into Cognigy. So, for example, if you have a number of Flows on Cognigy.AI, you can pull them onto the harddrive and we'll show how all of that works and examples in a second. Then you can edit them on your harddrive and push them back to Cognigy.AI where they are then available. There are certain limitations at this stage. The CLI can only create Locales and Snapshots. It cannot create new Flows, new Lexicons, or Endpoints. You have to create those on the Cognigy.AI installation and then you can edit those using the CLI. So you create them on the Cognigy.AI Installation, pull them to your harddrive. You can edit them there and then push them back up. But you cannot create new Flows, new Lexicons etc. using the CLI at the stage. The CLI also cannot change Flow structure. So whilst you can edit existing Nodes, Intents etc, you cannot add new Nodes and you cannot move Nodes around on the chart using the CLI. You need to do that either on the Cognigy.AI platform itself through the user interface, or of course if you want you can do that through the API as well.

There are a lot of available commands. We have an init command which initializes a new CLI project. We have a clone command which takes a whole Virtual Agent and clones it to your disk. We have a restore command, which takes the Virtual Agent on your disk and pushes it back to Cognigy.AI. We have a diff command which shows the difference by comparing a local resource with its corresponding remote resource, like what has changed between those two resources.

We have a push command which pushes an individual resource like one specific Flow from disk to Cognigy.AI and a corresponding pull command, which pulls a resource from Cognigy.AI back to disk. The train command trains the Intent models of a Flow. The create command, as referenced earlier, allows you to create Snapshots or Locales. This is really useful if you want to create a Snapshot, for example, on an hourly basis or a daily basis, and download it to your harddrive to then push into a, for example, a version management repository. You can export CSV and import CSV, which takes the content of a Flow, the Say Nodes, the Question Nodes, and exposes them as a CSV file to be edited in, for example, Excel. And that import CSV reverses that process and it takes the CSV and pushes it back into the Flow format. The localize command lets you add localizations to Flow Intents and Nodes. Something that is very useful: If you have hundreds of Nodes or Intents so you don't need to do it manually. And the translate command then translates those localized Nodes from a language to another language. So you don't have to translate that manually and you don't have to copy-paste. And last but not least, there is the execute command, which executes a command of the Cognigy Rest API client directly from your command line.

So let's have some fun and start playing around with the Cognigy CLI. We're going to start by looking at init, clone, restore, pull, and push which are some of the major commands that we'll be using here today.

Now, pulling up my visual studio code here, you can see that I'm on the command line and I only have a backup file here at the moment, which I'm going to be using a little bit later. But let's start by installing the Cognigy CLI. So what we would do is we would potentially as sudo, "npm install @cognigy/cognigy-cli -g", and we want to install that globally. I need to pop in my password here. And now the CLI will be installed globally. After we have installed it we can then use it from anywhere in our system. So if we just clear this here, we can now see that the Cognigy command is available from anywhere in our system.

Now, in order to get started, we first need to initialize the Cognigy CLI, which will create a config file for us. Luckily, we have a command for that and we can just type Cognigy in it and then go through the different questions here. What's the name for your configuration? Maybe we call it CLI test. What's your Cognigy.AI API Key? Now you do find your API Key in your Cognigy installation under your profile and if you scroll down you'll find your API Key here. You can copy it by clicking on it. Now I'm just going to type any API Key here. And then what is the ID of the Virtual Agent you would you would like to work with. You find the ID of your Virtual Agent also in your Cognigy installation and the ID is this part up here. So it comes after "agent/" and then before the next slash. So you can take that and copy that into your CLI here. Now, what is the base URL to connect with? This is not the URL where you log in, but it's the API URL. So here it's this URL. So I need to just type enter. Where do we want to store the Agent on the local drive. You can just choose the default here, which is "/agent". And then where do we want to store the file. And here we store it in the config file. And now you can see here we have the config file.

Now, in order to get started, we need to clone our Cognigy Agent. So in order to do that, we type "cognigy clone". We get a warning that this will override all the data we have stored locally, which we don't have at the moment, which is fine. So do you want to proceed and we type, yes. And now it's starting to clone this Agent to disk. You can already see an Agent folder was created and now the Agent exists. Now but before we look at the Agent here, we actually going to quickly look at it on the Cognigy installation. This is the Agent we're using. Now this Agent has a number of resources. It has one Flow, this Flow has a number of Nodes, has a LookUp Node, some Cases, three Say Nodes. It has two Intents: Cancel Order and Order Status.

It also has a Lexicon with currently three entries which have one Slot Tag assigned each and a synonym and the Cognigy one also has some data attached to it. And we also have an Endpoint, which is a Webchat Endpoint, which we can see here. So again, we have one Flow, one Lexicon, and one Endpoint. Now if we go back to the CLI, we can see that we now have an Endpoints, a Flows and a Lexicon folder. And inside those folders, we have - for the Flows - a Locales JSON and we have one folder per Flow. And it has the name of the Flow. Now, so here we have the main Flow. The main Flow again has a subfolder for the Locale, and in that it has its information.

If we quickly look at that, for the Flow, we have a config file which gives us the ID, a reference ID, the name etc. I would recommend not changing that. And we have the Chart, which has information about all the Nodes. There appears structural information which we cannot edit using the CLI. And then here we have information about the actual Nodes. Right, here we have a Say Node, for example. And for example, here it says "you said {{input.text}}". Now, if we look back on the Cognigy installation and we find this, then it is this Node here which says "you said {{input.text}}". We also have an Intents JSON file. This is an Intent export. It is exactly the same format that you would get to if you went to your Intents and downloaded the Intents as JSON. So you can you can actually upload this file that was downloaded from the CLI back into Cognigy manually if you want.

Now for the Lexicon, we have two files. We have a config JSON as well. Again, please don't change that one. And we have a CSV export and here we can see we have Google, Microsoft, and Cognigy, all are a company, Microsoft has a synonym and Cognigy has some data attached to it. For the Endpoint, we have two files as well. We have the config. In this case, you can change the config because it actually contains a lot of information that you might want to change, like the settings etc. But, and this is really nice, it contains also the Transformer. And you can edit the Transformer directly inside Cognigy if you want. And why don't we do that? Why don't we try that out? So here we could now, there's a console log in here and we're going to change this to Hello Cognigy. We save the Transformer and maybe we make a different change as well. Maybe we make a change to the Flow. And here we added this text and we say, "You said {{input text}} mate". Now we have changed this and now we can push this information back. What we could do is a Cognigy restore, which would restore the whole Agent back to Cognigy. Or, we can selectively push resources. Let's try that out.

So we can do cognigy push flow main. This would only push the main Flow back to the Cognigy installation. Again, we're getting a warning. And do you want to proceed? In this case, yes. Starting to push Flow Main to Cognigy.AI. This is now being pushed and it's finished. So if we look at the Cognigy.AI installation, we should now see the changes already applied in our Flow. And here you can see it now says "You said {{input.text }} mate".

What you can also see when you look at your Task Manager, we actually imported Intents through the CLI. And so just taking this Intents JSON, it is importing it just as if you had uploaded it. Let's do the same with the Endpoint. In this case, we would say "cognigy push endpoint" and then the name of the Endpoint, which I believe is Webchat, yes. And we can add a flag to it, which is -y, which means we're not going to be asked, do you want to proceed? Which makes it easier for scripting, right. Now, this is pushing the Endpoint up. This has now been pushed. We can now go to the Endpoints and the Webchat Endpoint, do a quick refresh here and then we should see the amended Transformer function. And you can see the Transformer function here has now been amended to actually show what we changed on the harddrive.

Now, of course, we can also edit resources on Cognigy and then pull them back into the CLI. So if we, for example, want to revert this change or we said, I heard you said and - maybe here we use a Token. And now we want to pull this change back into the CLI. We would now go to the CLI and pull this resource in by saying Cognigy pull Flow Main. This would override the local content that we have. And once we have pulled that in, we can see already updated here now that now here we have this information and we can also see the encoded Token that we have in here.

Now that we've seen how we can pull resources from Cognigy.AI and push resources back to Cognigy.AI, let's take a look at the Diff command, which enables us to see the difference between resources we have locally on disk and on Cognigy.AI. Now, for that, we've got to make some changes to our Flow so that we can actually see something that has changed. So maybe we here we are going to at the word mate at the end and maybe here we are adding a second text. We're also going to make a change to one of the Lexicons. This one here, and we are going to add a Synonym to Cognigy, maybe Cognigy with an I and we're going to manipulate some of the data as well. So currently we have location Germany and then maybe we add City Duesseldorf as well.

Last but not least, we're going to make a change to an Endpoint, so here we have the Webchat Endpoint and we will go in and change the Webchat configuration where maybe we change the title. So currently it says Webchat title and we're going to call it "Cognigy Webchat". And maybe we don't say write a reply, but we say send a reply. So now we've made a number of changes on Cognigy.AI and now we want to see those changes in the CLI. So the way to do that is to say cognigy diff and then the resource that we want to diff. So, for example, in this case, it would be diff Flow Main. Now, we let this run, it's running a diff now between the local version and the remote version and the remote one is red and the local one is green.

So here we can for example see: In this Node it says "you said {{input.text}} mate" on remote but a local it just says the green text, right. Or, here we have this text on remote and we don't have this at all on local. In diff Flows, we can actually enter a what's called a Node mode where we can only diff on a Node level. And we actually get the Node ID and then how it differs etc. Now, we can, of course, also diff Lexicons, so if we diff Lexicon Lex1, we're going to see what it looks like and what has changed. So here we can see, in the third line, Cognigy a Synonym was added and some data was added as well.

Last but not least we can do this with Endpoints as well. So, diff Endpoint Webchat, and here we will now see those, those differences, right. The input placeholder changed, the title changed and of course, the last change date changed as well.

Next up is the Training of NLU Models via the CLI. This is actually really simple. All we got to do is we have to go back to the CLI and we have to type Cognigy train, then the resource. Of course, it's always Flows that we train and we want to train the Flow Main. This is now going to train the Flow in each Locale. Now, here we only have one Locale. So it is training Intents for Locale en-US. Intents trained. And now this model has been trained on the Cognigy installation. And you can see this here and you can also see a task that will start it and just finished. So the Intent model was trained using the CLI.

Similar to training Intents, you can also create Snapshots using the Cognigy CLI. In order to do that, you go in and type Cognigy create. And by the way, if you need help, you can always type --help. And it's going to give you more information about the command, right. So here we can say Cognigy create Snapshot and then the Snapshot name. So let's try that out. Cognigy create Snapshot. Let's call it snap1, and we can give it a description if we want. And Cognigy is now going away and creating the Snapshot. Now, if we can actually monitor what's happening in realtime on the Cognigy installation. If we go back here, we can see there is a task now Create Snapshot. This is what the CLI is now doing. Now, the Snapshot was created. The CLI will automatically kick off a second task, which is prepare download. And it's going to show up here in a second. Packaging Snapshot for download. So this is now here, packaging Snapshot. And once this has been done, the CLI will automatically download the Snapshot for us. So using that mechanism, you could, for example, on a daily basis take a backup Snapshot of your Virtual Agent and pull it to disk. Now we have success, created Snapshot snap1 and downloaded it to agent/snapshots/snap1.csnap. Let's take a look. Here we go. And here we now have our csnap file on disk.

An often requested feature is to be able to edit the content of a Flow directly from within something like Microsoft Excel, so like editing CSV. And we've enabled this using the CLI where you can export and import CSV from and back into Cognigy. Now, in the CLI, the way you do that is you type Cognigy exportcsv, then from where you want to do that. In this case, it would be the Flow Main. We're doing this, it is super fast. It has now been exported and we can see the content in here. So of course, we only have exported the content of textual Nodes because those are the only ones we can edit in this in this case here. And we can now edit this here. Maybe we type "we will cancel your order of course". We save this and now we import this back in. So we type importcsv Flow Main. This is now importing it, it has now imported it and now we would say Cognigy push Flow Main to push this back to the Cognigy installation. And then we should see our change, where it will now say "we will cancel the order of course" on the Cognigy installation. Now, if we refresh the screen, we should see this under the cancelOrder Intent. And here it now says "we will cancel the order of course". This is not just content, not just textual content, but we can also do this for the structured content that Cognigy has, like Galeries, Quick Replies etc.

Next, we're going to look at the Cognigy CLI and how to use it for Localization and Translation of Flows. Just as a recap, we go back to Cognigy. We can see this Flow currently only exists in one Locale. We know that because there's no Locale dropdown up here or anywhere else. And let's create a second Locale so that we can then show the localization features. We create this by going to localization here and say create new Locale. Maybe we call it de-DE. We give it a NLU language. On this case German and give it a Fallback Locale, for example, English.

If we now go to the Flow, we'll see that all of a sudden we'll have a Locale dropdown up here and we can switch between the Locales, by choosing a different one and we can see which Flow Nodes have been localized depending on if they're colored or not. For example, this Node has not been localized. It's currently falling back to the English Locale when it's hit. And we can add a localization using the UI here, we can add an empty localization or copy it from another language. You can see now it's it's colored and we can now make those changes here. So I could translate this now, for example "Sie haben x gesagt". And I could save this now. And you can see this has been changed, but it's really only been changed in the German Locale. Now, what you would need to do is you would need to go through the Flow and add localizations to all your Nodes. You can also remove them from here and you would need to do the same thing for the Intents.

Now, luckily, we have the CLI where we can do this in an easier way. So here, if we now want to do this, we have to pull the Flow again because we added the Locale and we made some changes. Take a look at the left side here. Currently, we have the main Flow and only the en-US folder. Now, if I pull the main Flow again, it's going to override this. And then afterwards we are going to have a de-DE folder as well. So we have the en-US folder, the de-DE folder. And actually, if we take a look at the Locales JSON, we can see that we now have two Locales in this: A German one and the English one.

Now the localized command comes with a lot of options and you can take a look at those by using help. And here what we can do is we can say Cognigy localize Flow Main, then we have to put in the Locale that we want to work in. So we want to add localizations in the de-DE local. We want to copy the localization or the content from the en-US Locale so it doesn't create empty Locales. We have some more options here: Like -li, localize Intents. This means only localized Intents. -ln, localized Nodes, means only localize Nodes in the Chart. If none of these options is chosen, then both are true. So both will be localized and we can say -co, which is only going to create localizations for Content Nodes such as Say Nodes, Question Nodes, and Optional Question Nodes. We also have a -r option which reverses the localizations, which takes them away again.

So let's try this out. This will add localizations to Intents and Flow Nodes. This is now done, it's done directly on the server in this case. And then it pulled a local Flow copy. So if we go back to our Cognigy installation and refresh, we should now see localizations on all the Say Nodes, which we do see and we should see localizations on the Intents, which we also have now. That's what the localized command does.

Now, using the CLI, we can now go ahead and translate those localized Nodes from one language to another. And we can do that by using the Cognigy translate command, which you can see here. And there's a number of options and the syntax is Cognigy translate options, resource type, and resource name. So in our case, this would be Cognigy translate Flow Main, in the Locale de-DE that we're. We can optionally specify a from language and we have to specify a to language. So we don't specify from language in order to detect it. So we'll say to language, de. We need to pick a translator. We currently support Google Translate, Microsoft Translate, or DeepL. And this demo here, we're going to use Google and then you can say only translate Intents, only translate Nodes. Or if you don't choose either of those, then it's both. And then you put in your API Key for the chosen application and that should be it. We are now getting our regular warning. This will overwrite the data for the Flow Main, do you want to proceed? Yes. It's now going ahead translating the two Intents of my Flow Main. It is translating the Nodes and it's then refreshing the local Flow copy. So whilst it's doing that, we can already take a look at the results. So if we refresh our screen here, the Say Nodes in the German Locale should have been translated now "Du hast gesagt X Kumpel", "Ich habe gehört, Sie sagten, bla". So all the Nodes have been translated. The same goes for the Intents. Now the cancelOrder Intent and the orderStatus. And by the way, this also works for more complex data types such as Galeries etc. And it also works for Default Replies. CognigyScript, as you can see here, is not translated, so the CLI automatically takes care of that.

Now, last but not least, there is the Cognigy Execute command. The Cognigy Execute command lets you execute any method of the Cognigy REST API client directly from your command line. And this is what it looks like. So if you type Cognigy execute, you need to add a command name afterwards, but you can type -l to see all the commands that are available and there is a lot of API methods available here and I'll let you explore those in your own time.

But what I'm going to do is I'm just going to take this one as an example, which is an Index Flows command and you can pass data in. This is a JSON object here and we'll just quickly make sure that this ID is correct. So this should give us a list of all the Flows in this project and here you go. And you can see. Yeah, it's correct. This is what the API call here would return. And you cannot just do index calls, but you can actually do any call. That is possible. OK, thank you very much. I hope you enjoyed this intro to the Cognigy CLI. It is available on npm. It is also available on GitHub open source. So if you want to look at the code and how it was written, please take a look at the CLI on GitHub, download it, contribute if you like. We're always happy to get the community involved in our projects with that. Thank you very much and have a lot of fun trying it out.

Thank you very much for watching our Session on Cognigy.AI  API and CLI. Don't forget to visit our Cognigy.AI Help Center under support.cognigy.com for additional resources and information and a link to a community where you can ask questions or leave us feedback for this episode. Thank you very much for watching and see you next time.