IBM Cloudant CLI

The IBM Cloud® Command Line Interface (CLI) provides extra capabilities for service offerings. You can use IBM Cloudant CLI plug-in to manage throughput details and event types that are being sent from your IBM Cloudant account to the IBM Cloud® Activity Tracker service.

Prerequisites

Install the IBM Cloud CLI.
Install the IBM Cloudant CLI by running the following command:

ibmcloud plugin install cloudant

Use ibmcloud login command for logging in to your IBM Cloud account.
Set the IBM Cloudant service URL. For more information, see Service configuration.

You're notified on the command line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up to date so that you can use the latest commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.

Service configuration

When you make a server resource request, the IBM Cloudant account URL from the service credentials (for example, https://account.appdomain.cloud) is not available automatically in the plug-in. You need to set the URL of your Cloudant instance first. You can set the URL by inline configuration, global configuration, or setting an environment variable.

Inline configuration overrides the global configuration and the environment variable setting, while global configuration overrides the environment variable setting.

If you are unsure about your server URL, you can find it by the instance ID of your cloud resource. The instance ID can be found by the name of your service. The following example gets first the GUID then the CRN ID by service name (for example Cloudant-fg). Either of GUID and CRN ID can be used as <resource-id> to get the Cloudant instance URL.

# Get GUID of the service instance by service name, which can be used as a <resource-id> later
ibmcloud resource service-instance <service-name> --guid
# Get CRN ID of the service instance by service name, which can be used as a <resource-id> later
ibmcloud resource service-instance <service-name> --crn
# Get <service-url> of your Cloudant instance by resource ID (can be either the GUID or the CRN ID)
ibmcloud cloudant url -q --resource-id <resource-id>

Inline configuration

Inline configuration happens with the --service-url flag. All subcommands like events-config or capacity can be used with inline configured service URL, which comes from the ibmcloud cloudant url --resource-id <resource-id> command.

# Use events-config subcommand with inline configured service url
ibmcloud cloudant events-config --service-url <service-url>
# Use capacity subcommand with inline configured service url
ibmcloud cloudant capacity --service-url <service-url>

The following example shows a shorthand for using the events-config with inline configured service URL:

ibmcloud cloudant events-config --service-url $(ibmcloud cloudant url -q --resource-id <resource-id>)

Global configuration

Global configuration happens with the config subcommand. This stores a persistent configuration so that it does not need to be manually specified each time that the plugin is invoked. The following example sets the service url globally, which comes from the ibmcloud cloudant url --resource-id <resource-id> command, then uses the set value with subcommands like events-config or capacity.

# Set service url globally
ibmcloud cloudant config set service-url <service-url>
# Use events-config subcommand with globally configured service url
ibmcloud cloudant events-config
# Use capacity subcommand with globally configured service url
ibmcloud cloudant capacity

The following example shows a shorthand for setting the service URL with the help of the ibmcloud cloudant url subcommand:

ibmcloud cloudant config set service-url $(ibmcloud cloudant url -q --resource-id <resource-id>)

Environment variable setting

For this approach, you need to set the CLOUDANT_URL environment variable.

You can define this variable two ways:

Export them as environment variables, for example export CLOUDANT_URL=....
Store them in a credentials file.

As an alternative to ibmcloud login, you can set the environment variable CLOUDANT_APIKEY to an IAM API key.

Other information

The classic and the c subcommands were deprecated in version 0.0.5 and removed from version 0.1.0. The operations from the classic command are available on the cloudant command. Track the changes log for changes in the interface.

Globals

Commands

`ibmcloud cloudant url`

Retrieves the service URL from the given resource.

ibmcloud cloudant url --resource-id RESOURCE_ID

Command options

--resource-id (string): The ID of the cloud resource. Required.

Example

ibmcloud cloudant url \
    --resource-id="8d7af921-b136-4078-9666-081bd8470d94"

Options

--output (string): Choose an output format - can be 'json', 'yaml', or 'table'. Defaults to 'table'.
-j, --jmes-query (string): Provide a JMESPath query to customize output.
--service-url (string): Provide the base endpoint URL for the API.
-q, --quiet: Suppresses verbose messages.
-v, --version: Prints the plug-in version.

Example

ibmcloud cloudant
    --output=json \
    --jmes-query="[:10]" \
    --service-url="https://myservice.test.cloud.ibm.com"
    --quiet

Note: This example only demonstrates the global options available to all sub-commands and is not a valid command itself.

`ibmcloud cloudant config`

Global parameters can also be stored in persistent configuration so that they do not need to be manually specified each time the plug-in is invoked. Each parameter can be configured with the config command and its subcommands.

ibmcloud cloudant config

`ibmcloud cloudant config set`

Set a new config value for a specific option. Each subcommand of the set command maps to a global option. Each subcommand accepts a single argument, the string representation of the value to store for the option.

ibmcloud cloudant config set <option> <value>

Examples

ibmcloud cloudant config set service-url \
    'https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud'

`ibmcloud cloudant config get`

Print out the currently set value for a specific option. Each subcommand of the get command maps to a global option.

ibmcloud cloudant config get <option>

Examples

ibmcloud cloudant config get service-url

`ibmcloud cloudant config unset`

Unset the currently set value for a specific option. Each subcommand of the unset command maps to a global option.

The subcommands available for this service are: service-url, .

ibmcloud cloudant config unset <option>

Examples

ibmcloud cloudant config unset service-url

`ibmcloud cloudant config list`

List out all of the currently set config values.

ibmcloud cloudant config list

Examples

ibmcloud cloudant config list

Server

Commands for Server resource.

`ibmcloud cloudant capacity`

View the amount of provisioned throughput capacity that is allocated to an IBM Cloudant instance and what is the target provisioned throughput capacity.

ibmcloud cloudant capacity

Example

Example request

ibmcloud cloudant capacity

Example default output

Example CapacityThroughputInformation response.

blocks	5
query	25
read	500
write	250

Example full output

Example CapacityThroughputInformation response.

{
  "current" : {
    "throughput" : {
      "blocks" : 5,
      "query" : 25,
      "read" : 500,
      "write" : 250
    }
  },
  "target" : {
    "throughput" : {
      "blocks" : 10,
      "query" : 50,
      "read" : 1000,
      "write" : 500
    }
  }
}

Default JMESPath

A JMESPath query will be applied to this output of this command by default, if one is not provided by the user. The exact query will depend on the scenario and the output format requested. You can see the condition for each default JMESPath query in the following table:

Response	Output	Query
Success	Default	`current.throughput`
	Table	`current.throughput`
Error	Default	`current.throughput`
	Table	`current.throughput`
All pages	Default	`current.throughput`
	Table	`current.throughput`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud cloudant capacity-update`

Sets the target provisioned throughput capacity for an IBM Cloudant instance. When target capacity is changed, the current capacity asynchronously changes to meet the target capacity.

ibmcloud cloudant capacity-update --blocks BLOCKS

Command options

--blocks (int64)

A number of blocks of throughput units. A block consists of 100 reads/sec, 50 writes/sec, and 5 global queries/sec of provisioned throughput capacity. Not available for some plans. Required.

The minimum value is 1.

Example

Example request

ibmcloud cloudant capacity-update --blocks 10

Example default output

Example CapacityThroughputInformation response.

blocks	10
query	50
read	1000
write	500

Example full output

Example CapacityThroughputInformation response.

{
  "current" : {
    "throughput" : {
      "blocks" : 5,
      "query" : 25,
      "read" : 500,
      "write" : 250
    }
  },
  "target" : {
    "throughput" : {
      "blocks" : 10,
      "query" : 50,
      "read" : 1000,
      "write" : 500
    }
  }
}

Default JMESPath

Response	Output	Query
Success	Default	`target.throughput`
	Table	`target.throughput`
Error	Default	`target.throughput`
	Table	`target.throughput`
All pages	Default	`target.throughput`
	Table	`target.throughput`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

Monitoring

Commands for Monitoring resource.

`ibmcloud cloudant events-config`

Check event types that are being sent to IBM Cloud Activity Tracker for the IBM Cloudant instance.

ibmcloud cloudant events-config

Example

Example request

ibmcloud cloudant events-config

Example default output

Example ActivityTrackerEvents request and response.

management
data

Example full output

Example ActivityTrackerEvents request and response.

{
  "types" : [ "management", "data" ]
}

Default JMESPath

Response	Output	Query
Success	Default	`types`
	Table	`types`
Error	Default	`types`
	Table	`types`
All pages	Default	`types`
	Table	`types`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud cloudant events-config-update`

Configure event types that are being sent to IBM Cloud Activity Tracker for the IBM Cloudant instance.

ibmcloud cloudant events-config-update --types TYPES

Command options

--types ([]string)

An array of event types that are being sent to IBM Cloud Activity Tracker for the IBM Cloudant instance. "management" is a required element of this array. Required.

Allowable list items are: management, data. The maximum length is 2 items. The minimum length is 1 item.

Example

Example request

ibmcloud cloudant events-config-update --types management,data

Example output

Example Ok response.

{
  "ok" : true
}

`ibmcloud cloudant throughput`

View the current consumption of provisioned throughput capacity for an IBM Cloudant instance. The current consumption shows the quantities of reads, writes, and global queries conducted against the instance for a given second.

ibmcloud cloudant throughput

Example

Example request

ibmcloud cloudant throughput

Example default output

Example CurrentThroughputInformation response.

query	13
read	133
write	42

Example full output

Example CurrentThroughputInformation response.

{
  "throughput" : {
    "query" : 13,
    "read" : 133,
    "write" : 42
  }
}

Default JMESPath

Response	Output	Query
Success	Default	`throughput`
	Table	`throughput`
Error	Default	`throughput`
	Table	`throughput`
All pages	Default	`throughput`
	Table	`throughput`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.