Accessing Images via CLI (Command Line)¶

To pull images via a terminal or automation pipeline, you cannot use your WSO2 Account Credentials as previously. You must use a User Token or a Service Token generated from the WSO2 Support Portal.

Prerequisites: Generate a Token¶

Note: This is done in the WSO2 Support Portal, not the Registry Portal.

1. Log in to the WSO2 Support Portal.
2. Navigate to Projects > My Projects > Registry Tokens.
3. Click Generate Token and provide a descriptive name (e.g., "Jenkins-Pipeline-Token").
4. Important: Copy the Token ID and Token Secret immediately. The secret is shown only once.

Please refer to the Registry Token Management section for additional information.

Docker CLI¶

The Docker CLI is the standard method for authenticating and pulling images from the WSO2 Container Registry. Use this method for straightforward image pull operations.

Login¶

Open your terminal and run the login command using the credentials generated above.

• Username: Your generated Token ID.
• Password: Your generated Token Secret.

docker login registry.wso2.com
# When prompted for Username: Paste your Token ID
# When prompted for Password: Paste your Token Secret

Alternatively, in a single line:

docker login registry.wso2.com -u '<Your_Token_ID>' -p '<Your_Token_Secret>'

e.g : docker login registry.wso2.com -u 'robot$example-token' -p 'top_secret'

Pull an Image¶

After logging into the container registry successfully, you can pull images from the product repositories to which you are subscribed. i.e.:

docker pull registry.wso2.com/wso2-apim/am:4.5.0-alpine

Harbor CLI¶

WSO2 container registry is powered by the open source project, Harbor. Therefore, the Harbor CLI can be used to access the registry too. It suits automated workflows and CI/CD pipelines which need more control. It provides capabilities such as browsing repositories, querying artifacts, filtering, and discovering the latest available image tags within your subscribed projects.

The Harbor CLI can be installed by following the installation guide. The WSO2 Container Registry supports repository and artifact operations via the Harbor CLI. For more information refer to the Harbor CLI documentation.

Login¶

harbor login registry.wso2.com -u '<Your_Token_ID>' -p '<Your_Token_Secret>'

e.g : harbor login registry.wso2.com -u 'robot$example-token' -p 'top_secret'

Listing Artifacts and Tags¶

To list all artifacts in a repository filtered by a specific major version:

harbor artifact list <project>/<repository> \
  -q "tags=~<major-version>." \
  -s '-push_time' \
  -n 100 \
  -o json | jq -r '.Payload[].tags[].name' \
  | grep -E '^<major-version>\.[0-9]+\.[0-9]+\.[0-9]+$' \
  | sort -V

For example:

harbor artifact list wso2-apim/am -q "tags=~4." -n 100 -o json | jq -r '.Payload[].tags[].name' | grep -E '^4\.[0-9]+\.[0-9]+\.[0-9]+$' | sort -V

Finding the Latest Tag¶

To programmatically identify the latest pinned image tag for a given major version:

harbor artifact list <project>/<repository> \
  -q "tags=~<major-version>." \
  -s '-push_time' \
  -n 100 \
  -o json | jq -r '.Payload[].tags[].name' \
  | grep -E '^<major-version>\.[0-9]+\.[0-9]+\.[0-9]+$' \
  | sort -V \
  | tail -1

For example:

harbor artifact list wso2-apim/am -q "tags=~4." -n 100 -o json | jq -r '.Payload[].tags[].name' | grep -E '^4\.[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1