The watsonx Orchestrate ADK introduces the concept of environments (env). An environment can either be local with watsonx Orchestrate Development Edition, or remote with an account on a production watsonx Orchestrate IBM Cloud or AWS. When you activate an environment, every command other than orchestrate server and orchestrate chat is target to that environment, including but not limited to the importing, listing, and removal of agents, tools, and connections.

​
Environment commands

​
Creating an environment

Use the orchestrate env add command to create an environment to your local CLI.

[BASH]
orchestrate env add -n my-name -u https://my-service-isntance-url  
[INFO] - Environment 'my-name' has been created

Arguments

  • --name (-n) - The name of the environment.
  • --url (-u) - The service instance URL of the watsonx Orchestrate instance. This can be found on the service instance page.
  • --type (-t) - Optional, usually inferred based on the URL provided, but this allows you to specify what type of authentication your server uses. The following options are the accepted values for the type of environment:
    • ibm_iam: Refers to environments deployed on IBM Cloud, that use IBM’s Identity Access Management (IAM) authentication.
    • mcsp: Refers to environments deployed on Amazon Web Services (AWS), that use the Multi-Cloud Saas Platform (MCSP) authentication.
  • --activate (-a) - Optional, allows you to activate the environment as soon as it’s added.

​
Activating an environment

Use the orchestrate env activate command to authenticate against a given environment and target all commands other than orchestrate server and orchestrate chat to that environment.

Note: Authentication against a remote environment expires every two hours. After expiration, you need to run orchestrate env activate again. This behavior does not exist in the local environment.

To interactively activate an environment:

[BASH]
orchestrate env activate my-ibmcloud-saas-account
Please enter WXO API key: 
[INFO] - Environment 'my-ibmcloud-saas-account' is now active

To non-interactively log in for scripting, use the following:

[BASH]
orchestrate env activate my-ibmcloud-saas-account --apikey my-api-key
[INFO] - Environment 'my-ibmcloud-saas-account' is now active

​
Listing all environments

Use the orchestrate env list command to list all environments currently available to your CLI.

By default, you have one known as local. Your local environment refers to the watsonx Orchestrate Development Edition server. Others can be added by using the orchestrate env add command. The currently active environment will be indicated by an indicator saying (active) at the end of the line.

[BASH]
orchestrate env list
 local                      http://localhost:4321                                                 (active) 
 my-aws-saas-account        https://api.watson-orchestrate.ibm.com/instances/<instance-id>           
 my-ibmcloud-saas-account   https://api.watson-orchestrate.cloud.ibm.com/instances/<instance-id>

​
Removing an environment

Use the orchestrate env remove command to remove an environment from your environment list.

[BASH]
orchestrate env remove -n my-ibmcloud-saas-account
[INFO] - Successfully removed environment 'test'

​
Important configuration files

The watsonx Orchestrate CLI maintains two configuration files which are manipulated by the above env commands.

  • The first is ~/.config/orchestrate/config.yaml. This configuration file records each of your environments as well as which environment is currently active.

  • The second is ~/.cache/orchestrate/credentials.yaml. This file contains the JWT token from your last env activation used to authenticate with your environment.