Introducing Command Line Tools for Watson Visual Recognition

The Watson Visual Recognition service is a powerful tool that enables you to leverage cognitive computer vision to extract information from any image library. You can even go beyond standard object classification and use what are called ‘custom classifiers’ to train the Watson service to recognize specific items or conditions of your choosing. For example, you can train Watson to classify breeds of animals, identify rust on metal objects, detect cracks in a pipe, interpret satellite imagery, and much, much more.

Previously you would have used the REST interface to interact with the service directly to train and test your custom classifiers, but things just got a whole lot easier. I’d like to introduce you to the Watson Visual Recognition command line interface utility.

Using the command line interface, you no longer need to figure out how to post your files for training or classification using CURL or some other HTTP client utility. Instead, you can simply invoke a command and point it to the files that you want to train or test, and it just works. This is incredibly helpful if you are performing iterative development and testing of custom classifiers, enabling you to create, test, and remove custom classifiers with ease.

To install the Watson Visual Recognition command line utility (CLI), first make sure you have Node.js installed, then open up a terminal and run:

npm install -g watson-visual-recognition-utils

Once you have the CLI installed, you’ll be able to use one-step commands to interact with the visual recognition service. Note: You must have a valid Visual Recognition key to use this tool. If you do not have one, you can get a free trial here.


Run either the command watson-visual-recognition-utils or wvru in the terminal (both are aliases to the same code), you should see something like this:

$ watson-visual-recognition-utils
Watson Visual Recognition - Custom Classifier Utilities
Usage:  [options]


   api-usage [options] View IBM Watson Visual Recognition API Key usage and limits
   classifier-list [options] List all custom classifiers
   classifier-detail [options] Fetch custom classifier verbose details
   classifier-classify [options] Classify an image
   classifier-create [options] Create a new custom classifier
   classifier-delete [options] Delete a custom classifier
   key-set Save your Watson Visual Recognition key in CLI preferences
   key-unset Remove your Watson Visual Recognition key in CLI preference


   -h, --help output usage information
   -V, --version output the version number

You can either pass the Visual Recognition key as a CLI parameter, or save it in encrypted preferences using the key-set command so it does not need to be passed with every invocation.

Create a new classifier

To create a new custom classifier, invoke the classifier-create command. You can specify multiple positive classes, and optionally a negative collection of images, per service specs at:

$ watson-visual-recognition-utils classifier-create
  • You can specify multiple positive classes
    • requires pairs of –positive-class (string for class name) and –positive-path (path to zip file for positive images).
    • pairs are processed in order specified
  • You can optionally specify a negative zip file
    contains negative images for the classifier

One positive and one negative training set:

watson-visual-recognition-utils classifier-create --name classifier_name --positive-class rust --positive-path ./ --negative-path ./

Multiple positive classes and a negative training set:

watson-visual-recognition-utils classifier-create --name train_parts --positive-class wheels --positive-path ./ --positive-class rails --positive-path ./ --positive-class springs --positive-path ./ --negative-path ./

Classify (invoke a classifier)

To classify an image using using the CLI, you should invoke the classifier-classify command and pass parameters to identify the path to the image and the classifier ids that should be used as a comma delimited list. You can also specify default to use the default Watson classifier:

watson-visual-recognition-utils classifier-classify --image ./path/to/image.jpg --classifier_ids default,cracks_123456

Output from the classify service will be displayed as a JSON object.

Screenshot of the Watson Visual Recognition CLI

What Next?

Ready to get started? First you need to make sure you have an API key to start using the Watson Visual Recognition service. Next, install the command line interface using Node.js/npm. Then you’re ready to start creating and testing your own custom classifiers. Be sure to check the Watson Visual Recognition documentation for any service related questions. You can also submit bugs or feature request, or even contribute to the project source code over on Github.


Learn more about the Visual Recognition Service on Watson Cloud

Join The Discussion

Your email address will not be published. Required fields are marked *