Sign inSign up

bruceadams/wdscli

By bruceadams

•Updated about 9 years ago

Command line interface to the IBM Watson Discovery Service API

Image
0

5.4K

bruceadams/wdscli repository overview

⁠wdscli

Command line interface to the IBM Watson Discovery Service API Travis build status AppVeyor build status

⁠Installing

Binaries (for 64bit x86) are published on our Github releases⁠ page.

  • wdscli.exe Microsoft Windows binary
  • wdscli.linux Linux binary; statically linked. wdscli will run in an empty Docker image (that is: based on scratch⁠) as well as in any Linux distribution.
  • wdscli.macos macOS binary

Also, the Linux binary is available packaged in a small Docker image based on alpine⁠ and published on Docker Hub⁠.

Grab the binary for your machine and get it onto your PATH. On macOS, you can use the watson-developer-cloud/tools⁠ tap with Homebrew⁠ like this:

brew tap watson-developer-cloud/tools
brew install watson-developer-cloud/tools/watson-discovery-tool

Please notice that the installed binary on macOS is named watson-discovery-tool not wdscli. (I may get around to completely renaming this project.)

⁠Example

$ wdscli help
wdscli 2.2.0
Bruce Adams <[email protected]>
Basic administration for Watson Discovery Service.

USAGE:
    wdscli [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c, --credentials <credentials>    A JSON file containing service credentials. Default is the
                                       value of the environment variable WDSCLI_CREDENTIALS_FILE or
                                       'credentials.json' when WDSCLI_CREDENTIALS_FILE is not set.

SUBCOMMANDS:
    add-document             Add a document to a collection. [aliases: ad]
    crawler-configuration    Print out crawler configuration. [aliases: cc]
    create-collection        Create a new collection using the most recently created
                             configuration [aliases: cl]
    create-configuration     Create a new configuration. [aliases: cn]
    create-environment       Create a writable environment [aliases: ce]
    delete-collection        Delete a collection. [aliases: dl]
    delete-configuration     Delete a configuration. [aliases: dn]
    delete-document          Delete a document from a collection. [aliases: dd]
    delete-environment       Delete the writable environment [aliases: de]
    generate-completions     Generate a shell command completion script.
    help                     Prints this message or the help of the given subcommand(s)
    notices                  Query ingestion notices for a collection. [aliases: n]
    overview                 Displays information about existing resources. [aliases: o]
    preview                  Preview conversion and enrichment for a document. [aliases: p]
    query                    Query a collection. [aliases: q]
    show-collection          Displays detailed information about a collection. [aliases: sl]
    show-configuration       Displays detailed information about a configuration. [aliases: sn]
    show-document            Displays status information about a document. [aliases: sd]
    show-environment         Displays detailed information about an environment. [aliases: se]
$ wdscli help overview
wdscli-overview
Displays information about existing resources.

USAGE:
    wdscli overview [FLAGS]

FLAGS:
    -g, --guid       Display the GUID for each item
    -h, --help       Prints help information
    -V, --version    Prints version information
$ wdscli overview

Environment: "ba-cadence-testing", size=0, 4 GB disk, 1007.38 MB memory
   Configurations: "Default Configuration"
                   "extract all; english"
   Collections: "irs-pdf" ↳ "extract all; english", 2094 available, 12 failed

Environment: "Watson News Environment" - read only
   Configurations: "Default Configuration"
   Collections: "watson_news" ↳ "Default Configuration", 17271335 available

⁠Running

⁠Credentials

Every wdscli command (except help) requires credentials for a Watson Discovery Service instance.

⁠Credentials from Bluemix web console

On https://console.ng.bluemix.net/dashboard/apps/⁠, find the Watson Discovery instance you want to work with and select that service. The service instance overview screen has three tabs:

  • Manage — Service credentials — Connections

Select the Service credentials tab, then select View credentials to see the credentials in JSON format.

⁠Credentials from command line cf tool

The cf command line tool (and the enhanced for Bluemix variant bx) is very powerful. That power comes with a vast array of options that takes time to learn. If you already use cf, you can get the credentials for your service instance with a few commands. First, you need to find the name(s) of the credentials (there can be more than one) with the cf service-keys command (notice keys is plural here). For my service instance named ba-demo:

$ cf service-keys ba-demo
Getting keys for service instance ba-demo as [email protected]...

name
Credentials-1

The credentials name shown here, Credentials-1, is what Bluemix usually creates when you create a service a service instance using the Bluemix web console. The cf service-key (singular key) will show the JSON formatted credentials, like this:

$ cf service-key ba-demo Credentials-1
Getting key Credentials-1 for service instance ba-demo as [email protected]...

{
 "password": "a password",
 "url": "https://gateway.watsonplatform.net/discovery/api",
 "username": "74c397c5-1ef1-4976-a0e8-89a0b831d679"
}

To directly write these credentials to a file, you can use tail -5 to only save the last five lines of the output, which is in JSON format.

$ cf service-key ba-demo Credentials-1 | tail -5 > credentials.json

⁠Customizing X-Global-Transaction-ID

There is a subtle feature for customizing the value of the HTTP header X-Global-Transaction-ID. The value of the environment variable X_GLOBAL_TRANSACTION_ID will be used as the beginning of the header value. (The default is wdsapi.)

For example, running this command:

X_GLOBAL_TRANSACTION_ID=demo-tx-header wdscli overview

will send X-Global-Transaction-ID headers with the values: demo-tx-header-0, demo-tx-header-1, demo-tx-header-2 … The sequence number is incremented for each Discovery API call that is made.

⁠Building

I highly recommend installing Rust using https://rustup.rs⁠ (which boils down to curl -sSf https://sh.rustup.rs | sh). This project depends on several packages from https://crates.io⁠ and wdsapi⁠.

cargo build

Tag summary

Content type

Image

Digest

Size

6.8 MB

Last updated

about 9 years ago

docker pull bruceadams/wdscli