Written by Adam Wolfe, Zowe CLI Squad Lead and Product Owner at Broadcom
The Open Mainframe Project’s Zowe version 3 was released in October. This article, which originally ran on the Zowe Medium blog, highlights some of the new capabilities and breaking changes in Zowe CLI V3 and tells you how to install the new version.
New Capability: Search for a String in Spool Files and PDS Members
One of our most frequently requested enhancements has been the ability to search for a string in a set of members. For example, a developer may need to locate the source of a given error code or message in a library containing source code, something that can be readily accomplished in ISPF, but was more complicated when working with Zowe CLI or Zowe Explorer.
Previously, a user could download data sets to their local hard drive, then use scripts or searching functionality available in their OS or IDE to locate instances of a given string. However, rather than requiring users to perform a sequence of manual steps, Zowe CLI V3 provides new commands to search members, sequential data sets, and job spool files for a given string, providing a list of data sets, members, or spool files that contain the string along with line numbers for each occurrence.
Breaking Changes
While many users will be able to simply install Zowe CLI V3 and get to work, this will not be the case for everyone. Zowe CLI V3 introduced several “breaking” changes that could cause scripts or plug-ins designed for V2 to fail with V3 or could require the user to adjust their configuration to upgrade to V3 (in the case of V1 profiles).
Removal of Support for V1 Profiles
Zowe CLI V3 does not support V1 profiles. For V3, you will need to use the configuration format introduced in Zowe V2 known as “team config”. If you have already implemented a team config for Zowe CLI V2, your configuration will be fully compatible with the new version of Zowe CLI.
However, if you are still using V1 profiles (a collection of .yaml files in the ~/.zowe/profiles directory), you will need to upgrade to a team config. To make it easier for users to upgrade from V1 profiles, Zowe CLI will continue to provide the zowe config convert command in V3 to enable users to automatically convert their existing V1 profiles to a team config.
Team config enables you to store profiles for all of your services in a single .json file that can be easily shared with your team, reducing the burden of configuration for individual users. There are a number of excellent blogs on the topic of team configuration to help you get started, including:
- ‘Enterprise rollout of Zowe CLI’
- ‘Zowe CLI: Getting started with Team Config’
- ‘Password management for Zowe CLI profiles’
New REST Error Message Format
To make it easier for users to understand why a given command has failed, Zowe CLI V3 will feature a new error message format for presenting errors from REST APIs. The new format provides the same level of detail as error messages in V2 but presents the information in a more logical order, with text coloration to help users identify what caused the error. For details on the new error format, refer to Gene Johnston’s article ‘Improved usability of error messages in Zowe CLI’.
Users with scripts that parse error messages will need to update their scripts to accommodate the new format.
Changes to How You Run Zowe CLI
Prior to being contributed to the Zowe project, the CLI was part of a Broadcom offering and was known as the “Brightside CLI” and could be invoked by entering bright in a terminal (e.g., bright files list dataset to list data sets). In Zowe CLI V1 and V2, users could continue using the bright command to run Zowe CLI. However, the bright command is being retired and will no longer be available in Zowe CLI V3.
Warning: Scripts that run Zowe CLI using the bright command, will not work with Zowe CLI V3.
If your scripts use the bright command to run Zowe CLI, simply replace bright with zowe to ensure that your scripts will work with V3. Alternatively, you could create a script named bright in a directory on your PATH, that passes all arguments to Zowe CLI. For example, a bash script could look something like this:
#!/bin/bash
zowe "$@" # Call Zowe CLI, and forward all arguments
This would allow you to continue invoking Zowe CLI with the bright command, which could be more convenient than updating all of your scripts.
Installing Zowe CLI V3
Users interested in upgrading to Zowe CLI V3 (and who have implemented, or are prepared to implement, a team configuration) can install the latest V3 release by opening a terminal and running npm install -g @zowe/cli. To confirm that the installation was successful, run the command zowe --version. You should see something like:
PS C:\> zowe -V
CLI Version: 8.1.1
Zowe Release Version: v3.0.0
From here, you can try out any of the new capabilities and confirm that your configuration and scripts will continue to work with Zowe CLI V3. If you need to return to V2 for any reason, you can run the command npm install -g @zowe/cli@zowe-v2-lts to go back to the most recent V2 release.
Final Thoughts
Zowe CLI follows semantic versioning guidelines and publishes new major versions (e.g., V1, V2, and V3) every 2 years with the rest of the Zowe project. According to semantic versioning, breaking changes can only be introduced at the time that a new major version is released.
Because Zowe CLI can usually introduce new functionality in minor versions (without breaking changes), the transition to V3 is more of an opportunity to reduce technical debt, improve technical currency, and make incremental improvements to functionality in ways that might be breaking for plug-ins or certain users (e.g., removing the bright command).
With V3, Zowe CLI continues to become more capable, stable, and mature. By upgrading to V3, users can position themselves to receive ongoing releases of new capabilities for the next two years. While V3 is the active LTS version, Zowe CLI V2 will continue to receive periodic bugfixes and security patches (but no new features), so if you have scripts that use Zowe CLI V2 in pipelines or other automation, for example, it may make sense to stay on V2 to avoid needing to adjust scripts to accommodate changes made in the initial release of Zowe CLI V3. To update Zowe CLI to the latest V2 release, run the command npm install -g @zowe/cli@zowe-v2-lts.
Reach out to the CLI Squad
Users can submit an enhancement request or bug report by opening an issue in the Zowe CLI repository.
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the Open Mainframe Project Slack Channel register here.
