watsonx-playground-cli

CLI for /custom/settings parity: auth tokens, connections, look presets, agents, tools, tool data, testing, and WXO sync.

Install

npm install -g watsonx-playground-cli@latest

Configure

wxp auth set-token --token <playground_cli_token> --base-url https://your-site.example.com
wxp auth tokens list
wxp auth tokens create --name "CI token"
wxp auth tokens revoke ptk_xxx_yyy --yes

Connections

wxp connections list
wxp connections get conn-default
wxp connections add --file ./connection.json --activate --yes
wxp connections add --service-url https://api.dl.watson-orchestrate.ibm.com/instances/<id>/v1/orchestrate/runs --api-key <key> --token-mode ibmcloud --label "Prod" --activate --yes
wxp connections update conn-default --label "Prod" --custom-context-keys division,market --yes
wxp connections update conn-default --file ./connection-update.json --yes
wxp connections activate conn-default --yes
wxp connections remove conn-old --yes

Look / Branding

wxp look list
wxp look get look-default
wxp look create --file ./look.json --yes
wxp look update look-custom-1 --file ./look-update.json --yes
wxp look activate look-custom-1 --yes
wxp look generate-theme --brand-name "Ask HR" --dominant-color "#E65F2B" --json
wxp look upload-image --file ./logo.png --name ask-hr-logo --json
wxp look delete look-custom-1 --yes

Agents

wxp agents list
wxp agents fetch --connection-id conn-default --json
wxp agents sync --connection-id conn-default --metadata-policy preserve --missing-policy keep --yes
wxp agents push hr_assistant --file ./agent-update.json --connection-id conn-default --yes
wxp agents generate-draft --prompt "Build an HR policy assistant"
wxp agents improve-instructions --file ./agent-update.json --json
wxp agents chat hr_assistant --connection-id conn-default --prompt "Summarize open PTO requests"
wxp agents smoke --prompt "Summarize open PTO requests" --connection-id conn-default --agent-ids hr_assistant,travel_agent

agents sync persists the same remote metadata the web pull flow uses, including remoteAgentId, instructions, toolIds, yaml, welcomeHeadline, welcomeDisclaimer, and welcomeCards.

Tools

wxp tools list
wxp tools get my_tool
wxp tools create --file ./tool.json --yes
wxp tools update my_tool --file ./updates.json --yes
wxp tools delete my_tool --yes
wxp tools fetch --out ./tools-export.json
wxp tools push --file ./tools-export.json --overwrite --yes
wxp tools share my_tool --email [email protected] --yes
wxp tools unshare my_tool --email [email protected] --yes
wxp tools leave shared_tool --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools suggest-fields --tool-name "Travel Requests" --tool-description "Employee travel booking records" --json
wxp tools generate-draft --prompt "Build a PTO request tool"
wxp tools export my_tool --out ./my_tool.zip
wxp tools bundle-export --tool-ids pto_tool,expense_tool --agent-name hr_assistant --out ./tool-bundle.zip

Tool Data

wxp tools items get travel_requests --user-id viewer-1 --email [email protected] --owner-user-id owner-123 --owner-email [email protected]
wxp tools items initialize travel_requests --user-id viewer-1 --email [email protected] --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools items add travel_requests --user-id viewer-1 --email [email protected] --file ./item.json --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools items update travel_requests --user-id viewer-1 --email [email protected] --item-id row_1 --file ./item-update.json --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools items delete travel_requests --user-id viewer-1 --email [email protected] --item-id row_1 --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools items reset travel_requests --user-id viewer-1 --email [email protected] --owner-user-id owner-123 --owner-email [email protected] --yes
wxp tools users list travel_requests --owner-user-id owner-123 --owner-email [email protected]
wxp tools users delete travel_requests --user-id viewer-1 --email [email protected] --owner-user-id owner-123 --owner-email [email protected] --yes

Shared-tool data commands accept --owner-user-id and --owner-email so collaborators can act against the owner’s tool when access is allowed.

WXO Sync

wxp tools push-wxo --tool-ids pto_tool,expense_tool --overwrite --yes
wxp tools fetch-wxo --tool-names get_pto_tool,add_pto_tool --export-dir ./wxo-tools
wxp tools delete-wxo --tool-names get_pto_tool,add_pto_tool --yes
wxp tools import-wxo --tool-names get_pto_tool,add_pto_tool --overwrite --yes

Testing

wxp testing get
wxp testing save --file ./testing-suites.json --yes
wxp testing profiles list
wxp testing generate-cases --connection-id conn-default --agent-id hr_assistant --count 25 --focus "policy edge cases"
wxp testing run --agent-id hr_assistant --connection-id conn-default --cases-file ./cases.json
wxp testing run --agent-ids hr_assistant,travel_agent --connection-id conn-default --cases-file ./cases.json --json
wxp testing run --agent-id hr_assistant --service-url https://api.dl.watson-orchestrate.ibm.com/instances/<id>/v1/orchestrate/runs --api-key <key> --token-mode aws --cases-file ./cases.json
wxp testing cases template --connection-id conn-default --out ./cases-template.csv
wxp testing cases import --connection-id conn-default --agent-id hr_assistant --file ./cases.csv --yes
wxp testing cases export --connection-id conn-default --agent-id hr_assistant --out ./cases.csv
wxp testing baselines template --connection-id conn-default --agent-id hr_assistant --out ./baseline-template.csv
wxp testing baselines import --connection-id conn-default --agent-id hr_assistant --file ./baseline.csv --yes
wxp testing results export --connection-id conn-default --agent-id hr_assistant --out ./results.csv
wxp testing compare export --connection-id conn-default --agent-id hr_assistant --baseline-run-id run_baseline_1 --out ./comparison.csv

testing generate-cases uses saved connection context keys, saved agent instructions/descriptions, tool names, and testing profiles when --connection-id and --agent-id are provided.

testing run accepts exactly one of --agent-id or --agent-ids. Multi-agent mode fans out one run per agent and returns aggregated JSON results.

Testing cases can include profileUserIds; runtime sends the first attached profile as user_id, userid, userId, and customer_id.

Settings + Setup

wxp settings get
wxp settings save --file ./settings-update.json --yes
wxp settings get-api-key --connection-id conn-default
wxp setup doctor
wxp setup install-orchestrate --yes

Notes

• tools push-wxo and tools fetch-wxo use server-side sync endpoints; no local IBM ADK orchestrate CLI is required for those commands.
• tools push-wxo also republishes the default local agent for the active connection when one is configured.
• agents fetch is read-only; agents sync is the persist flow for connection-backed chat/smoke/testing runs.
• --token-mode supports ibmcloud and aws; default is ibmcloud.
• Mutating commands require confirm unless --yes is passed.
• Prefer --json for automation.

Exit codes

• 0: success
• 2: config/auth setup problem
• 3: unauthorized/forbidden API auth error
• 4: resource not found
• 5: network/connectivity error
• 64: usage error