`config` commands and usage

The config command further has different commands within, using which you can configure watsonx.data environment in IBM cpdctl. This topic lists the commands with brief description of the tasks that can be performed.

watsonx.data on IBM Software Hub

watsonx.data on IBM Cloud®

The config command manages the configuration of profile and users for watsonx.data. The watsonx.data instance must be open in the web browser while configuring and performing the operations.

Syntax

./cpdctl config [commands]

The config command supports the following commands:

user
profile

Tip: You can set user and profile by running these commands separately. It is recommended to use the combined commands to set the profile and users through a single command. For more information, see Using the commands user and profile together (Recommended).

Configuring encryption key for IBM `cpdctl`

To secure your passwords and API keys, IBM cpdctl uses AES-256 encryption. You can use a custom encryption key or the default hardcoded key provided by IBM cpdctl.

You can provide a custom encryption key for AES-256 by setting the CPDCTL_ENCRYPTION_KEY_PATH environment variable pointing to the path of encryption key file holding directory. If this environment variable is not set, cpdctl will use its own hardcoded encryption key.

For macOS and Linux:

export CPDCTL_ENCRYPTION_KEY_PATH=/path/cpdctl.key

For Windows Command Prompt:

set CPDCTL_ENCRYPTION_KEY_PATH=/path/cpdctl.key

For Windows PowerShell:

$env:CPDCTL_ENCRYPTION_KEY_PATH = "/path/cpdctl.key"

`user`

The user command manage users in watsonx.data.

Syntax

./cpdctl config user [commands]

The user command further supports the following commands:

Options	Description
`./cpdctl config user set [commands]`	Set the credentials for a user in `cpdctl` configuration to connect to watsonx.data instance.
`./cpdctl config user list`	List the credentials stored in `cpdctl` configuration that is used to connect to watsonx.data instance.
`./cpdctl config user get <username>`	Get the credentials of a user stored in `cpdctl` configuration that is used to connect to watsonx.data instance.
`./cpdctl config user unset <username>`	Remove the currently set username from the `cpdctl` configuration of watsonx.data instance.

./cpdctl config user set [commands] further supports the following commands as options to be used for setting the credentials:

--apikey (string) : Set user apikey

--password (string) : Set user password

--token-file (string) : Set location of a file that contains user token

--username (string) : Set user name

Example setting up a user:

Software instance:

./cpdctl config user set <user> --username <onprem_username> --password <onprem_password>

./cpdctl config user set user1 --username cpadmin --password xyz

For watsonx.data software, it is recommended to use --username and --password which are used to login to the console.

Cloud instance:

./cpdctl config user set <user> --username <saas_username> --apikey <APIKEY>

./cpdctl config user set user2 --username user@ibm.com --apikey APIKEY

For watsonx.data on IBM Cloud, it is recommended to use --username and --apikey which are used to login to the console. For more information see, Get API key.

`profile`

The profile command manage profiles in watsonx.data.

Note: Single sign-on (SSO) login is enabled in cpdctl.

Syntax

./cpdctl config profile [commands]

The profile command supports the following commands:

Options	Description
`./cpdctl config profile set [commands]`	Set watsonx.data environment profile in `cpdctl` configuration.
`./cpdctl config profile list`	List all watsonx.data environment profiles set in `cpdctl` configuration.
`./cpdctl config profile get <profilename>`	Get details of the watsonx.data environment profile from `cpdctl` configuration.
`./cpdctl config profile unset <profilename>`	Remove watsonx.data environment profile from `cpdctl` configuration.
`./cpdctl config profile current`	Get details of the current watsonx.data environment profile used from `cpdctl` configuration.
`./cpdctl config profile use <profilename>`	Use a particular watsonx.data environment profile from `cpdctl` configuration.

./cpdctl config profile set [commands] further supports the following commands as options to be used for setting the credentials:

--apikey (string) : Create a user having this API key and associate it with the profile. Used for SaaS and Onprem. Recommended to use for SaaS instance.

--common-services-url (string) : Set Common Services URL for the profile

--iam-integration-enabled () : Set if IAM integration is enabled on CP4D

--ibmcloud (string) : Connect the profile to IBM Cloud CLI session metadata. Flag value specifies IBM Cloud CLI configuration directory. If no value is given, default IBM Cloud CLI configuration directory is assumed.

--password (string) : Create a user having this password and associate it with the profile. Used for Onpremise. Recommended to use for Onpremise instance.

--region (string) : IBM cloud region.

--token-file (string) : Create a user having this token location and associate it with the profile.

--url (string) : Set URL for the profile

--user (string) : Set user for the profile

--username (string) : Create a user having this name and associate it with the profile.

Example for setting up a profile with the user configured in user section:

Software instance:

cpdctl config profile set <profile_name> --user <user> --url <profile_url>

./cpdctl config profile set onprem --user user1 --url http://cpd-cpd-instance.apps.docteam-wxd-cluster.cp.fyre.ibm.com/

Cloud instance:

./cpdctl config profile set <profile_name> --user <user> --url <profile_url> --region <region_name>

./cpdctl config profile set saas --user user2 --url https://cloud.ibm.com/ --region us-south

Developer edition (Software instance):

cpdctl config profile set <profile_name> --user <user> --url <profile_url>

./cpdctl config profile set dev --user user3 --url https://<clustername>.fyre.ibm.com:9443

Using the commands `user` and `profile` together (Recommended)

You can combine the 2 commands user and profile together to configure instance profile in cpdctl configuration. A sample illustration of how to use the combination is provided below:

Note: Single sign-on (SSO) login is enabled in cpdctl.

Setting up a software instance profile:

Syntax:

cpdctl config profile set <profile_name> --username <onprem_username> --password <onprem_password> --url <onprem_url> \
  --env "WATSONX_DATA_INSTANCE_ID=<instance-id>"

Example:

./cpdctl config profile set onprem --username cpadmin --password xyz --url http://cpd-cpd-instance.apps.docteam-wxd-cluster.cp.fyre.ibm.com/ \
  --env "WATSONX_DATA_INSTANCE_ID=1752571384257912"

For watsonx.data software, it is recommended to use --username and --password which are used to login to the console.

Setting up a cloud instance profile:

Syntax:

cpdctl config profile set <profile_name> --username <saas_username> --apikey <APIKEY> --url <saas_url> --region <region_name> \
  --env "WATSONX_DATA_INSTANCE_ID=<crn>" \
  --env "WATSONX_DATA_URL=<WXD-base-url>"

Example:

./cpdctl config profile set saas --username user@ibm.com --apikey APIKEY --url https://cloud.ibm.com/ --region us-south \
  --env "WATSONX_DATA_INSTANCE_ID=crn:v1:staging:public:lakehouse:us-south:a/781f752068d44638a3b2a13de58d3cfe:2c590eda-8d51-4269-86ce-a6dfb84c8267::" \
  --env "WATSONX_DATA_URL=https://us-south.lakehouse.dev.cloud.ibm.com/"

For watsonx.data on IBM Cloud, it is recommended to use --username and --apikey which are used to login to the console. For more information see, Get API key.

Setting up an MCSP instance profile:

Syntax:

cpdctl config profile set <profile_name> \
--auth-scope <type of scope> \
--auth-id <authentication-id> \
--username <username>
--apikey <apikey> --url <mcsp_url> \
--region <region_name> \
  --env "WATSONX_DATA_INSTANCE_ID=<crn>" \
  --env "WATSONX_DATA_URL=<WXD-base-url>"

When --auth-scope is set to 'services', --auth-id must be the watsonx.data instance ID. If the API key is generated against a service ID, use ServiceId-<actual-service-id> as --username, otherwise use the personal ID.

Example:

cpdctl config profile set aws-testsaas \
--auth-scope services \
--auth-id 6343297492 \
--username ServiceId-3d388-9c8a-46d0-aa1e-f023523dc497 or (--username WXD-SRE-Automation@ibm.com)
--apikey <apikey> --url https://aws.console.dev.saas.ibm.com/ \
--region eu-central-1 \
   --env "WATSONX_DATA_INSTANCE_ID=crn:v1:aws-staging:public:lakehouse:eu-central-1:sub/20240301-2217-2804-10db-9f85ef3e0651:20250708-1207-3732-200d-84006d5910b8::" \
   --env "WATSONX_DATA_URL=https://console-aws-eucentral1.lakehouse.dev.saas.ibm.com"

Setting up a software instance development edition profile:

Syntax:

cpdctl config profile set <profile_name> --username <dev_username> --password <dev_password> --url <dev_url> \
  --env "WATSONX_DATA_INSTANCE_ID=<instance-id>"

Example:

./cpdctl config profile set dev --username ibmlhadmin --password xyz --url https://<clustername>.fyre.ibm.com:9443 \
  --env "WATSONX_DATA_INSTANCE_ID=0000-0000-0000-0000"

For watsonx.data software development edition, it is recommended to use --username and --password which are used to login to the console.

Setting the instance ID as environment variable

Important: Starting from cpdctl version 1.8.5, users no longer need to set the instance ID as environment variable. This method is deprecated and will be completely removed in a future release. Instead, you must set the instance ID directly using the profile command, as described in Using the commands user and profile together (Recommended).

You must set an instance ID to access the corresponding environment to run the cpdctl commands. To set the instance ID, you can use the WX_DATA_INSTANCE_ID environment variable. This allows you to avoid specifying the instance ID with each command.

Note: You must use INSTANCE_ID in watsonx.data 2.1.1 version.

To set the variable, run the following command in macOS and Linux:

export WX_DATA_INSTANCE_ID=<instance-id_value>

Where, <instance-id_value> is the instance ID of the watsonx.data software instance or CRN of your watsonx.data instance on IBM Cloud which can be accessed by clicking the i icon on the homepage.

To set the variable, run the following command in Windows Command Prompt:

set WX_DATA_INSTANCE_ID=<instance-id_value>

To set the variable, run the following command in Windows PowerShell:

$env:WX_DATA_INSTANCE_ID = "<instance-id_value>"

config commands and usage

Configuring encryption key for IBM cpdctl

user

profile

Using the commands user and profile together (Recommended)

Setting the instance ID as environment variable

`config` commands and usage

Configuring encryption key for IBM `cpdctl`

`user`

`profile`

Using the commands `user` and `profile` together (Recommended)