Python-based command line tool to manage workspaces and test conversations for IBM Watson Assistant on IBM Cloud
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Watson Conversation Tool

The Watson Conversation Tool (wctool) is a Python-based command line tool to manage workspaces of the IBM Watson Assistant (formerly Conversation) service on IBM Cloud. It was written to explore the API to manage workspaces.
Note that to manage workspaces from the command line this tool is not a requirement. The API provides REST functions that can be invoked from tools like curl.

This project is described in the following blog posts:


The tool consists of a single Python script, In order to use it, you need Python and the SDK for the Watson services installed.

If you have been working with the Watson service and Python before, you probably already have everything installed. If not, you need to install Python and then head over to the Watson Developer Tools and follow the link to the Python SDK. Install the SDK, too. Now download a copy of this repository or clone it.
To use the tool, copy config.sample.json or config.ICFsample.json to config.json and insert your service credentials. Note that the service URL depends on the IBM Cloud region. It is shown as part of the credentials.

Some commands and parameters:

LIST all workspaces:

GET (full) information about a workspace and print or save it
-g -id workspaceID -full       
-g -id workspaceID -o outfile

UPDATE an existing workspace (with optionally intents, entities, etc. read from existing workspace file):
-u -id workspaceID [-name newName] [-lang newLanguage] [-desc newDescription]
  [-intents] [-entities] [-dialog_nodes] [-counterexamples] [-metadata] [-i input-workspace]

DELETE an existing workspace:
-delete -id workspaceID

CREATE a new workspace (with intents, entities etc. read from existing workspace file):
-c -name workspace-name -desc workspace-description -lang workspace-language -i input-workspace

List LOGS for a specific workspace with an optional filter string
-logs -id workspaceID -filter filter-string

Have DIALOG using a specific workspace
-dialog -id workspaceID [-outputonly] -[-actionmodule file]

See the included Jupyter Notebook SampleSession.ipynb for details on how to invoke the commands. Note that in the current state the tool prints out the values for all possible options for debugging purposes. This could be simply disabled in the code. The filter expressions are documented as part of the Watson Conversation service.

Dialog option and contexts

When using the dialog option, the current session context is stored (persisted) in session_context.json. It allows to continue a session later on. The file is closed after writing out the current context. After the new message input is obtained from the user, the file session_context.json is opened again and its content retrieved. This allows to modify the context object between dialog turns. Context variables can be set, modified or deleted. This includes system variables. Use with caution... :)
The stored session context can even be used to switch to different workspaces or even instances with every dialog turn. It helps command line testing of duplicated / replicated chatbots for highly available apps.

The optional parameter -outputonly lets the tool only dump the returned text output, not the entire response object. This is useful when testing the output or showcasing a dialog from the command line.

The tool supports server actions in Watson Assistant. If present in the config file, the tool will pass in the IBM Cloud Functions credentials. As a starter, use config.ICFsample.json. The option was introduced to work on this tutorial for a database-backed Slackbot which makes use of IBM Cloud Functions.

The tool also supports client actions. You can pass in the file to handle client actions using -actionmodule filename. A sample module is shown in file It could be dynamically loaded using -actionmodule handleClientAction.sample. Note that the file extension .py is not passed in.

Documentation and Resources

Here are some useful links to documentation and other resources:


See LICENSE for license information.

The tool is provided on a "as-is" basis and is un-supported. Use with care...

Contribute / Contact Information

If you have found errors or some instructions are not working anymore, then please open an GitHub issue or, better, create a pull request with your desired changes.

You can find more tutorials and sample code at: and