Cheat Sheet & Mini-Tutorial: watsonx Orchestrate CLI (for local dev & remote config)

We’ll walk through the watsonx Orchestrate CLI a part of the (ADK) essentials—from setting up environments to managing agents, connections, and loading an IBM watsonx.ai model. The goal: give us a copy-pasteable, reliable reference that’s easy to follow and ready for day-to-day work.

• Official docs: IBM watsonx Orchestrate Developer Guide
• Background on LLM connections: LLMs & AI Gateway

1. What we’ll cover
2. Prerequisites
3. Environments
4. Agents
5. Connections
6. LLM (watsonx.ai) via AI Gateway
7. Recap

1. What we’ll cover

1. Prerequisites
2. Environments (list, activate, inspect, remove)
3. Agents (list, export, import)
4. Connections (list, configure, credentials, remove)
5. LLM (watsonx.ai) setup (schema, connection, model definition, import)
6. Troubleshooting & tips
7. Recap (copy-paste quick refs)

We’ll use the we perspective and keep each action small and verifiable.

2. Prerequisites

• We have the orchestrate CLI installed and authenticated.
• We have an IBM Cloud API key if we plan to activate remote environments.
• We know (or can create) the App ID names for our connections (e.g., watsonx_credentials).

Tip: Keep secrets (API keys, passwords) out of history by using environment variables and a .env file that isn’t checked into source control.

3. Environments

List environments

orchestrate env list

Remove an environment

export ENV_TO_DELETE=my-watsonx_orchestrate_remote-access
orchestrate env remove --name ${ENV_TO_DELETE}

Inspect local CLI configuration

cat ~/.config/orchestrate/config.yaml

The following code is an example for the content of the config file.

cached_user_env:
  AUTHORIZATION_URL: ''
  DOCKER_COMPOSE_FILE_PATH: docker-compose.yml
  SAAS_WDU_RUNTIME: none
  USE_SAAS_ML_TOOLS_RUNTIME: 'False'
  WO_DEVELOPER_EDITION_SOURCE: myibm
  WO_INSTANCE: ''
context:
  active_environment: local
environments:
  local:
    wxo_url: http://localhost:4321
  mjsech-watsonx_orchestrate_remote-access:
    auth_type: ibm_iam
    wxo_url: https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/XXXXXX
license:
  accepts_license_agreements: true
python_registry:
  test_package_version_override: null
  type: pypi

Activate an environment on IBM Cloud

export ENVIRONMENT_NAME=mjsech-watsonx_orchestrate_remote-access
export API_KEY=XXXX
orchestrate env activate --api-key ${API_KEY} ${ENVIRONMENT_NAME}

Why we do this: activation binds the CLI to a target environment so subsequent commands (agents, connections, models) go to the right place.

---

4. Agents

List agents

orchestrate agents list

Export an agent definition

export NAME=YOUR_AGENT
export KIND="native"
export OUTPUT="./${NAME}_export.yaml"
orchestrate agents export --name ${NAME} --kind ${KIND} --output ${OUTPUT} --agent-only

Import an agent definition

export NAME=YOUR_AGENT
export APP_ID=YOUR_CONNECTION_NAME
export FILE="./${NAME}_export.yaml"
orchestrate agents import --file ${FILE} --app-id ${APP_ID}

Tip: Export before edits (versioning in Git), then re-import to apply changes with confidence.

---

5. Connections

List connections

orchestrate connections list

Remove a connection

export APP_ID=YOUR_CONNECTION_NAME
orchestrate connections remove --app-id ${APP_ID}

Configure a connection (structure & routing)

export APP_ID=YOUR_CONNECTION_NAME
export URL=""
export TYPE=team
export ENVIRONMENT="live"
export KIND="basic"
orchestrate connections configure --app-id ${APP_ID} --kind ${KIND} --env ${ENVIRONMENT} --type ${TYPE} --url ${URL}

Set credentials for a connection

export APP_ID=YOUR_CONNECTION_NAME
export TYPE=team
export ENVIRONMENT="draft"
export SERVICE_USERNAME=""
export SERVICE_PASSWORD=""
orchestrate connections set-credentials --app-id ${APP_ID} --environment ${ENVIRONMENT} --username ${SERVICE_USERNAME} --password ${SERVICE_PASSWORD}

Note: --env/--environment may appear in different examples; we stick to the flag used by our CLI version. If a command errors, run orchestrate connections --help to confirm the flag name.

---

6. LLM (watsonx.ai) via AI Gateway

We’ll configure a watsonx.ai provider connection, then define and load a model that points to our watsonx Space/Project/Deployment.

Provider schema (reference)

{
  "api_key": "string",                 // required
  "watsonx_space_id": "string",        // at least one of space/project/deployment is required
  "watsonx_project_id": "string",      // at least one of space/project/deployment is required
  "watsonx_deployment_id": "string",   // at least one of space/project/deployment is required
  "watsonx_cpd_url": "string",         // required for on-prem (CPD)
  "watsonx_cpd_username": "string",    // required for on-prem (CPD)
  "watsonx_cpd_password": "string",    // required for on-prem (CPD)
  "watsonx_version": "string",
  "custom_host": "string",
  "url_to_fetch": "string",
  "forward_headers": ["string"],
  "request_timeout": 30,
  "transform_to_form_data": false
}

Minimal example:

{
  "api_key": "XXX",
  "watsonx_space_id": "XXX",
  "request_timeout": 60,
  "transform_to_form_data": false
}

Step 1: Activate the environment we want to use (local or remote)

orchestrate env activate local
# or remote as shown earlier

Step 2: Create a connection for watsonx credentials

orchestrate connections add --app-id watsonx_credentials

Step 3: Configure the connection metadata

orchestrate connections configure \
  --app-id watsonx_credentials \
  --env draft \
  --kind key_value \
  --type team

Step 4: Inject secrets (API key, etc.)

If we keep secrets in .env:

source ./.env
orchestrate connections set-credentials \
  --app-id watsonx_credentials \
  --env draft \
  --entries "api_key=${WATSONX_APIKEY}"

Add other entries as needed, e.g. watsonx_space_id, watsonx_project_id, or watsonx_deployment_id.

Step 5: Define the model (YAML)

./models_config/granite-3-3-8b-instruct.yaml

spec_version: v1
kind: model
name: watsonx/ibm/granite-3.3-8b-instruct
display_name: IBM watsonx.ai (Granite)
description: |
  IBM watsonx.ai model using Space-scoped configuration.
tags:
  - ibm
  - watsonx
model_type: chat
provider_config:
  watsonx_space_id: my-space-id

We keep the model name stable; only adjust provider_config values for different environments (dev/stage/prod).

Step 6: Import (load) the model

orchestrate models import \
  --file ./models_config/granite-3-3-8b-instruct.yaml \
  --app-id watsonx_credentials

Expected output (example):

[INFO] - Be sure to include the following required fields for provider 'watsonx' in the connection 'watsonx_credentials':
        - api_key
[INFO] - Successfully added the model 'virtual-model/watsonx/ibm/granite-3.3-8b-instruct'

If we see a missing field message, we re-run the set-credentials step to add the missing entries.

The image below shows the new available model!

---

6. Troubleshooting & Tips

• “Command not found”: verify the CLI is installed and on PATH.
• Permissions/401/403: confirm the API key is valid and the target Space/Project/Deployment exists.
• Wrong environment: run orchestrate env list and orchestrate env activate ... to ensure we’re targeting the right place.
• Flag differences: CLI versions can evolve; use --help to validate flags like --env vs --environment.
• Secrets hygiene: prefer --entries with environment variables; avoid putting raw secrets in your shell history.

---

7. Recap (copy-paste quick refs)

Environments

orchestrate env list
cat ~/.config/orchestrate/config.yaml
orchestrate env activate local
orchestrate env activate --api-key ${API_KEY} ${ENVIRONMENT_NAME}
orchestrate env remove --name ${ENV_TO_DELETE}

Agents

orchestrate agents list
orchestrate agents export --name ${NAME} --kind ${KIND} --output ${OUTPUT} --agent-only
orchestrate agents import --file ${FILE} --app-id ${APP_ID}

Connections

orchestrate connections list
orchestrate connections add --app-id ${APP_ID}
orchestrate connections configure --app-id ${APP_ID} --env draft --kind key_value --type team
orchestrate connections set-credentials --app-id ${APP_ID} --env draft --entries "api_key=${WATSONX_APIKEY}"
orchestrate connections remove --app-id ${APP_ID}

Models

orchestrate models import --file ./models_config/granite-3-3-8b-instruct.yaml --app-id watsonx_credentials

---

Next steps

• Deep dive in the docs:
  • IBM watsonx Orchestrate Developer Guide
  • LLMs & AI Gateway (watsonx.ai)

Happy orchestrating, these reliable CLI flows we can reuse across projects and environments.

---

I hope this was useful to you and let’s see what’s next?

Greetings,

Thomas

#watsonxorchestratecli, #connection, #environment, #aigateway, #agent, #watsonxorchestrate