bluemixUtility command

Use the IBM Cloud® command-line utility to configure your on-premises Liberty server to use certain IBM Cloud cloud services.

IBM® Bluemix® is now IBM Cloud, and references to these names both refer to the same cloud platform at https://cloud.ibm.com, formerly https://console.bluemix.net.

Discontinued feature: The bluemixUtility-1.0 feature is discontinued. To configure access to IBM Cloud services, such as Cloudant®, dashDB®, or Watson™ Services, see the documentation for the cloud service that you want to configure.

Sources

Learn about IBM Cloud services, such as Watson and Cloudant services, that you can use with the command-line utility.

To register for or log in to a IBM Cloud account, see Sign up for IBM Cloud.
To learn more about Watson, see Watson services.
To learn more about Cloudant services, see Getting started with Cloudant NoSQL DB.

Syntax

The command syntax is as follows:

bluemixUtility action [options]

Use the following action commands:

login

Log in to IBM Cloud. If you run the login command without any options, the tool prompts you for more information, such as username and password. After a successful login, IBM Cloud credentials are saved to a file so that you can run other commands without specifying username and password again.

If you log in to IBM Cloud with the Cloud Foundry (cf) client, the bluemixUtility uses the credentials saved by the cf client. For more information, see Cloud Foundry (cf) commands.

marketplace

List all the IBM Cloud services that can be configured by using the command-line utility.

createService

Create a service instance from the IBM Cloud catalog.

listServices

List all the available IBM Cloud service instances.

showService

Show information about a service instance.

import

Import a configuration for a service. The imported service configuration and its dependencies are placed in the following directory:

${wlp.user.dir}/shared/config/services/serviceName

listImports

List all imported service configurations that can be bound to a Liberty server.

bind

Bind a IBM Cloud service configuration to a Liberty server. The configuration for a service may provide default values for certain options, such as the jndiName of a dataSource element. In some cases, the default values do not match what the application expects. Use the --v option to override a default value with the value that your application expects.

unbind

Unbind a service configuration from a Liberty server.

deleteService

Delete a service instance.

switch

Switch to a different IBM Cloud organization or space.

info

View IBM Cloud connection information.

help

Use the help action on each command to view descriptions, usage, and options.

logout

Log out of IBM Cloud. The logout command deletes the file that was created when you logged in with IBM Cloud credentials.

Usage

View usage examples that you can run for each action.

Use the following command to run the login action:

bluemixUtility login [options]

Use the following command to run the marketplace action:

bluemixUtility marketplace [serviceType...]

Use the following command to run the createService action:

bluemixUtility createService [options] serviceType servicePlan serviceName

Use the following command to run the listServices action:

bluemixUtility listServices

Use the following command to run the showService action:

bluemixUtility showService [options] serviceName

Use the following command to run the import action:

bluemixUtility import [options] serviceName

Use the following command to run the listImports action:

bluemixUtility listImports [serverName]

Use the following command to run the bind action:

bluemixUtility bind [options] serverName serviceName

Use the following command to run the unbind action:

bluemixUtility unbind serverName serviceName

Use the following command to run the deleteService action:

bluemixUtility deleteService [options] serviceName

Use the following command to run the switch action:

bluemixUtility switch [options]

Use the following command to run the logout action:

bluemixUtility logout

Options

View the available options for each action.

The following options are available for the bluemixUtility login command:

--api=url: Bluemix API endpoint, for example, https://api.ng.bluemix.net. The API endpoint can also be set as the Bluemix region name. For example, it can be set to us-south for the US South region, eu-gb for the London, UK region, and au-syd for the Sydney, Australia region.
--user=username: User name of IBM Cloud account.
--password=password: Password of IBM Cloud account.
--org=organizationName: Organization name.
--space=spaceName: Space name.
--sso: A one-time passcode that is required to log in using a IBM Cloud federated ID. To generate the passcode, go to the IBM Cloud passcode website specified by the command, and then enter the generated passcode on the command line. This option is not required for signing in using an IBM id.

The following options are available for the bluemixUtility marketplace command:

[serviceType...]: Show detailed information about a particular IBM Cloud service. Specify multiple service names by separating them with a space.

The following options are available for the bluemixUtility createService command:

--credentialName=name: The name of the service credential. By default, credential-1 is used.
serviceType: The type of service to create.
servicePlan: The name of service plan.
serviceName: The name of service to create.

No options are available for the bluemixUtility listServices command.

The following options are available for the bluemixUtility showService command:

--showCredentials: Display service credentials.
serviceName: The name of a IBM Cloud service.

The following options are available for the bluemixUtility import command:

--acceptLicense: Automatically indicate acceptance of license terms and conditions.
--credentialName=name: The name of the service credential. By default, the first credential that is found is used.
--encodeAlgorithm=[xor|aes]: Specifies how to encode sensitive information in the imported service configuration. Supported encodings values are xor and aes. The default encoding algorithm is xor.
--encodeKey=key: Specifies the key to be used when you are encoding with AES encryption. If this option is not provided, a default key is used.
--p[parameter]=value: Specifies parameters that help in generating and importing a configuration for a service.
serviceName: The name of a IBM Cloud service.

The following options are available for the bluemixUtility listImports command:

[serverName]: List the services that are already bound to this particular server.

The following options are available for the bluemixUtility bind command:

--v[variable]=value: Override variables in the imported service configuration.
--acceptLicense: Automatically indicate acceptance of license terms and conditions.
serverName: Name of the server to bind to the service configuration.
serviceName: Name of the imported service configuration.

The following options are available for the bluemixUtility unbind command:

serverName: Name of the server to unbind the service configuration from.
serviceName: Name of the service configuration to unbind.

The following options are available for the bluemixUtility deleteService command:

--force: Force deletion without confirmation.
serviceName: Name of the service to delete.

The following options are available for the bluemixUtility switch command:

--org=organizationName: Organization name.
--space=spaceName: Space name.

No options are available for the bluemixUtility info command.

No options are available for the bluemixUtility logout command.

Return codes

Table 1. Return codes and explanations
Return code	Explanation
0	The command successfully completed the requested operation.
20	One or more command-line arguments or options are not valid.
21	An unknown runtime exception has occurred.
22	An IO error occurred, typically when trying to delete a file from the file system.
24	User abort. Occurs when user fails to respond to a prompt or cancels the operation.
26	An unknown exception has occurred.
27	IBM Cloud authentication error when attempting to log in, or attempting to perform a task without being logged in.
28	A generic error when communicating with IBM Cloud.
29	A generic error when communicating with the configuration service.
30	A generic service configuration error has occurred.
31	A generic feature installation error has occurred.
255	An unknown error has occurred.