Profiles & credentials

A profile is a named set of service endpoints and authentication settings. Commands that talk to remote services (plan, apply, destroy, test) read the active profile to know where each service lives and how to authenticate.

Where profiles live

Profiles live in ~/.wxctl/profiles.yaml. This is a YAML file, distinct from the resource config.yaml you pass to -f. It is written with 0600 permissions (owner read/write only); keep it out of git. wxctl init scaffolds this file for you, then you fill in the credentials by hand:

wxctl init                            # scaffold every service into ~/.wxctl/profiles.yaml
wxctl init -f config.yaml             # scaffold only the services your config uses
wxctl init -f config.yaml -p staging  # scaffold a named profile
wxctl init --edit                     # scaffold, open $EDITOR, then validate

-f, --filename narrows the scaffold to the services a configuration references, instead of every supported service.
-p, --profile names the profile being written. Omit it to write the default profile.
--edit opens $VISUAL or $EDITOR on the file and, after you save and exit, runs the same live checks as wxctl profile validate.
--force re-scaffolds an existing profile to placeholders; other profiles and preferences in the file are preserved.

To point at a file somewhere other than ~/.wxctl/profiles.yaml, pass --profile-path <path>.

What the scaffold looks like

wxctl init writes two profiles: an active default profile in SaaS shape, and a commented default-software alternative in Cloud Pak for Data / Software Hub shape. Each service block carries a format-hint url, its auth_type, and for every credential field both a commented ${env:...} line and an active PASTE_YOUR_<FIELD>_HERE placeholder. Here is the scaffold for a config that uses object storage and watsonx Orchestrate:

~/.wxctl/profiles.yaml

# wxctl profiles: credentials for the IBM services wxctl manages.
#
# This is NOT a resource config.yaml (which describes what to deploy). This file
# holds per-profile service endpoints and auth. Keep it private.
#
# Active-profile precedence: -p NAME  >  $WXCTL_PROFILE  >  ~/.wxctl/active_profile  >  "default".
#
# Fill each service block one of two ways:
#   1. Replace "PASTE_YOUR_<FIELD>_HERE" with the real value, or
#   2. Delete that PASTE line and uncomment the "# <field>: ${env:WXCTL_...}" line
#      above it to read the value from that environment variable at run time.
#
# This file is written with 0600 permissions (owner read/write only). Keep secrets out of git.
#
# Next step: wxctl profile validate
#
profiles:
  default:
    deployment: saas
    cloud_object_storage:
      url: "https://s3.<REGION>.cloud-object-storage.appdomain.cloud"
      auth_type: hmac
      # access_key: ${env:WXCTL_CLOUD_OBJECT_STORAGE_ACCESS_KEY}
      access_key: "PASTE_YOUR_ACCESS_KEY_HERE"
      # secret_key: ${env:WXCTL_CLOUD_OBJECT_STORAGE_SECRET_KEY}
      secret_key: "PASTE_YOUR_SECRET_KEY_HERE"
    watsonx_orchestrate:
      url: "https://api.<REGION>.watson-orchestrate.cloud.ibm.com"
      auth_type: apikey
      # apikey: ${env:WXCTL_WATSONX_ORCHESTRATE_APIKEY}
      apikey: "PASTE_YOUR_APIKEY_HERE"

# --- Software (CP4D / watsonx on-prem) alternative: uncomment and edit to use ---
#   default-software:
#     deployment: software
#     watsonx_orchestrate:
#       url: "https://cpd-cpd.apps.<CLUSTER_DOMAIN>"
#       auth_type: zenapikey
#       # username: ${env:WXCTL_WATSONX_ORCHESTRATE_USERNAME}
#       username: "PASTE_YOUR_USERNAME_HERE"
#       # apikey: ${env:WXCTL_WATSONX_ORCHESTRATE_APIKEY}
#       apikey: "PASTE_YOUR_APIKEY_HERE"

The URL values are format hints: replace the bracketed part (<REGION>, <CLUSTER_DOMAIN>) with your real host. wxctl profile validate catches a wrong host immediately.

Fill in credentials

Fill each service block one of two ways:

Inline: replace "PASTE_YOUR_<FIELD>_HERE" with the real value.
From the environment: delete the PASTE line and uncomment the # <field>: ${env:WXCTL_...} line above it. wxctl resolves the variable at run time, so nothing sensitive is written to disk. This also makes one profile portable across environments: point dev and prod at the same ${env:APIKEY} and set the value per shell.

A filled SaaS profile, credentials masked:

~/.wxctl/profiles.yaml

profiles:
  default:
    deployment: saas
    watsonx_orchestrate:
      url: "https://api.us-south.watson-orchestrate.cloud.ibm.com"
      auth_type: apikey
      apikey: "••••••••••••••••••••••••••••••••"
    cloud_object_storage:
      url: "https://s3.us-south.cloud-object-storage.appdomain.cloud"
      auth_type: hmac
      access_key: "••••••••••••••••••••••••••••••••"
      secret_key: "${env:COS_SECRET_KEY}"

For an on-prem Software Hub, uncomment the -software profile: watsonx services share one https://cpd-cpd.apps.<CLUSTER_DOMAIN> host and authenticate with zenapikey (username + API key) or cp4d (username + password); object storage still uses hmac. profiles.yaml holds as many profiles as you need. Keep a SaaS dev profile and an on-prem prod profile side by side and select one per command with -p dev / -p prod (see Choosing the active profile).

Validate

After you fill in credentials, verify the profile against the live services:

wxctl profile validate            # check the default profile
wxctl profile validate staging    # check a named profile

It prints a per-service line and exits non-zero if any service fails, so scripts can gate on it. wxctl init --edit runs the same checks automatically when your editor exits.

Choosing the active profile

When a command needs credentials, wxctl resolves the active profile in this order; the first match wins:

The -p, --profile <name> flag
The WXCTL_PROFILE environment variable
The name stored in ~/.wxctl/active_profile
default

wxctl apply -f config.yaml -p staging              # explicit flag wins
WXCTL_PROFILE=staging wxctl apply -f config.yaml   # via environment

Authentication types

Each service in a profile declares an auth_type that selects how wxctl obtains a token. The table lists the type and the fields it uses; wxctl init scaffolds the right auth_type per service.

Type	`auth_type`	Config fields
IBM Cloud API key	`apikey`	`apikey`
ZenApiKey (Software Hub)	`zenapikey`	`username`, `apikey`
Cloud Pak for Data	`cp4d` / `icp4d`	`username`, `password`
HMAC (object storage)	`hmac`	`access_key`, `secret_key`
Concert API key	`c_api_key`	`apikey`
Instana API token	`api_token`	`apikey`
Planning Analytics session	`pa_session`	`apikey`
Basic	`basic`	`username`, `password`
Bearer token	`bearer`	`apikey`
None (local)	`none`	(none)

SaaS services authenticate with apikey; Software (Cloud Pak for Data / Software Hub) services use zenapikey or cp4d. apikey is rejected on Software and zenapikey on SaaS. hmac covers object-storage (S3 / COS) services.

Credentials live only in ~/.wxctl/profiles.yaml and in the environment variables your YAML references with ${env:VAR}. Never commit credentials into a configuration file; keep them in your profile or the environment.

Next steps

Declarative model

Resources, references, and ${env:VAR} interpolation.

Pipeline

The stages every command runs.

​Where profiles live

​What the scaffold looks like

​Fill in credentials

​Validate

​Choosing the active profile

​Authentication types

​Next steps

Declarative model

Pipeline

Where profiles live

What the scaffold looks like

Fill in credentials

Validate

Choosing the active profile

Authentication types

Next steps