Using Zowe CLI

Last Updated: 2/7/2019, 2:50:05 PM

Using Zowe CLI

This section contains information about using Zowe CLI.

Displaying Zowe CLI help

Zowe CLI contains a help system that is embedded directly into the command-line interface. When you want help with Zowe CLI, you issue help commands that provide you with information about the product, syntax, and usage.

Displaying top-level help

To begin using the product, open a command line window and issue the following command to view the top-level help descriptions:

zowe --help

Tip: The command zowe initiates the product on a command line. All Zowe CLI commands begin with zowe.

Displaying command group, action, and object help

You can use the --help global option get more information about a specific command group, action, or object. Use the following syntax to display group-level help and learn more about specific command groups (for example, zos-jobs and zos-files):

zowe <group, action, or object name> --help
zowe zos-files create --help

Zowe CLI command groups

Zowe CLI contains command groups that focus on specific business processes. For example, the zos-files command group provides the ability to interact with mainframe data sets. This article provides you with a brief synopsis of the tasks that you can perform with each group. For more information, see Display Zowe CLI Help.

The commands available in the product are organized in a hierarchical structure. Command groups (for example, zos-files) contain actions (for example, create) that let you perform actions on specific objects (for example, a specific type of data set). For each action that you perform on an object, you can specify options that affect the operation of the command.

Important! Before you issue these commands, verify that you completed the steps in Create a Zowe CLI profile and Test Connection to z/OSMF to help ensure that Zowe CLI can communicate with z/OS systems.

Zowe CLI contains the following command groups:

plugins

The plugins command group lets you install and manage third-party plug-ins for the product. Plug-ins extend the functionality of Zowe CLI in the form of new commands.

With the plugins command group, you can perform the following tasks:

  • Install or uninstall third-party plug-ins.
  • Display a list of installed plug-ins.
  • Validate that a plug-in integrates with the base product properly.

Note: For more information about plugins syntax, actions, and options, open Zowe CLI and issue the following command:

zowe plugins -h

profiles

The profiles command group lets you create and manage profiles for use with other Zowe CLI command groups. Profiles allow you to issue commands to different mainframe systems quickly, without specifying your connection details with every command.

With the profiles command group, you can perform the following tasks:

  • Create, update, and delete profiles for any Zowe CLI command group that supports profiles.
  • Set the default profile to be used within any command group.
  • List profile names and details for any command group, including the default active profile.

Note: For more information about profiles syntax, actions, and options, open Zowe CLI, and issue the following command:

zowe profiles -h

provisioning

The provisioning command group lets you perform IBM z/OSMF provisioning tasks with templates and provisioned instances from Zowe CLI.

With the provisioning command group, you can perform the following tasks:

  • Provision cloud instances using z/OSMF Software Services templates.
  • List information about the available z/OSMF Service Catalog published templates and the templates that you used to publish cloud instances.
  • List summary information about the templates that you used to provision cloud instances. You can filter the information by application (for example, DB2 and CICS) and by the external name of the provisioned instances.
  • List detail information about the variables used (and their corresponding values) on named, published cloud instances.

Note: For more information about provisioning syntax, actions, and options, open Zowe CLI and issue the following command:

zowe provisioning -h

zos-console

The zos-console command group lets you issue commands to the z/OS console by establishing an extended Multiple Console Support (MCS) console.

With the zos-console command group, you can perform the following tasks: Important! Before you issue z/OS console commands with Zowe CLI, security administrators should ensure that they provide access to commands that are appropriate for your organization.

  • Issue commands to the z/OS console.
  • Collect command responses and continue to collect solicited command responses on-demand.

Note: For more information about zos-console syntax, actions, and options, open Zowe CLI and issue the following command:

zowe zos-console -h

zos-files

The zos-files command group lets you interact with data sets on z/OS systems.

With the zos-files command group, you can perform the following tasks:

  • Create partitioned data sets (PDS) with members, physical sequential data sets (PS), and other types of data sets from templates. You can specify options to customize the data sets you create.
  • Download mainframe data sets and edit them locally in your preferred Integrated Development Environment (IDE).
  • Upload local files to mainframe data sets.
  • List available mainframe data sets.
  • Interact with VSAM data sets directly, or invoke Access Methods Services (IDCAMS) to work with VSAM data sets.

Note: For more information about zos-files syntax, actions, and options, open Zowe CLI and issue the following command:

zowe zos-files -h

zos-jobs

The zos-jobs command group lets you submit jobs and interact with jobs on z/OS systems.

With the zos-jobs command group, you can perform the following tasks:

  • Submit jobs from JCL that resides on the mainframe or a local file.
  • List jobs and spool files for a job.
  • View the status of a job or view a spool file from a job.

Note: For more information about zos-jobs syntax, actions, and options, open Zowe CLI and issue the following command:

zowe zos-jobs -h

zos-tso

The zos-tso command group lets you issue TSO commands and interact with TSO address spaces on z/OS systems.

With the zos-tso command group, you can perform the following tasks:

  • Excecute REXX scripts
  • Create a TSO address space and issue TSO commands to the address space.
  • Review TSO command response data in Zowe CLI.

Note: For more information about zos-tso syntax, actions, and options, open Zowe CLI and issue the following command:

zowe zos-tso -h

zosmf

The zosmf command group lets you work with Zowe CLI profiles and get general information about z/OSMF.

With the zosmf command group, you can perform the following tasks:

  • Create and manage your Zowe CLI zosmf profiles. You must have at least one zosmf profile to issue most commands. Issue the zowe help explain profiles command in Zowe CLI to learn more about using profiles.
  • Verify that your profiles are set up correctly to communicate with z/OSMF on your system. For more information, see Test Connection to z/OSMF.
  • Get information about the current z/OSMF version, host, port, and plug-ins installed on your system.

Note: For more information about zosmf syntax, actions, and options, open Zowe CLI and issue the following command:

zowe zosmf -h

Defining Zowe CLI connection details

Zowe CLI has a command option order of precedence that lets you define arguments and options for commands in multiple ways (command-line, environment variables, and profiles). This provides flexibility when you issue commands and write automation scripts. This topic explains order of precedence and different methods for specifying your mainframe connection details.

Understanding command option order of precedence

Before you issue commands, it is helpful to understand the command option order of precedence. The following is the order in which Zowe CLI searches for your command arguments and options when you issue a command:

  1. Arguments and options that you specify directly on the command line.
  2. Environment variables that you define in the computer's operating system. For more information, see Defining Environment Variables
  3. User profiles that you create.
  4. The default value for the argument or option.

The affect of the order is that if you omit an argument/option from the command line, Zowe CLI searches for an environment variable that contains a value that you defined for the argument/option. If Zowe CLI does not find a value for the argument/option in an environment variable, Zowe CLI searches your user profiles for the value that you defined for the option/argument. If Zowe CLI does not find a value for the argument/option in your profiles, Zowe CLI executes the command using the default value for the argument/option.

Note: If a required option or argument value is not located, you receive a syntax error message that states Missing Positional Argument or Missing Option.

Creating Zowe CLI profiles

Profiles are a Zowe CLI functionality that let you store configuration information for use on multiple commands. You can create a profile that contains your username, password, and connection details for a particular mainframe system, then reuse that profile to avoid typing it again on every command. You can switch between profiles to quickly target different mainframe subsystems.

To create a zosmf profile, issue the following command. Refer to the available options in the help text to define your profile:

zowe profiles create zosmf-profile --help

Creating a profile to access an API Mediation Layer

You can create profiles that access an either an exposed API or API Mediation Layer (API ML) in the following ways:

  • When you create a profile, specify the host and port of the API that you want to access. When you only provide the host and port configuration, Zowe CLI connects to the exposed endpoints of a specific API.

  • When you create a profile, specify the host, port, and the base path of API ML instance that you want to access. Using the base path to API ML, Zowe CLI routes your requests to an appropriate instance of the API based on the system load and the available instances of the API.

Example:

The following example illustrates the command to create a profile that connects to z/OSMF through API ML with the base path my/api/layer:

zowe profiles create zosmf myprofile -H <myhost> -P <myport> -u <myuser> --pw <mypass> --base-path <my/api/layer>

For more information, see Accessing an API Mediation Layer.

  • When you create a profile, specify the host and port of the API that you want to access. When you only provide the host and port configuration, Zowe CLI connects to the exposed endpoints of a specific API.

  • When you create a profile, specify the host, port, and the base path of the API Mediation Layer instance that you want to access. Using the base path to an API Mediation Layer, Zowe CLI routes your requests to an appropriate instance of the API based on the system load and the available instances of the API.

Example:

The following example illustrates the command to create a profile that connects to z/OSMF through API Mediation Layer with the base path my/api/layer:

zowe profiles create zosmf myprofile -H <myhost> -P <myport> -u <myuser> --pw <mypass> --base-path <my/api/layer>

After you create a profile, verify that it can communicate with z/OSMF. For more information, see Testing Zowe CLI connection to z/OSMF.

Defining Environment Variables

You can define environment variables in your environment to execute commands more efficiently. You can store a value, such as your password, in an environment variable, then issue commands without specifying your password every time. The term environment refers to your operating system, but it can also refer to an automation server, such as Jenkins or a Docker container. In this section we explain how to transform arguments and options from Zowe CLI commands into environment variables and define them with a value. In this section we explain how to transform arguments and options from Zowe CLI commands into environment variables and define them with a value.

  • Assigning an environment variable for a value that is commonly used.

    For example, you might want to specify your mainframe user name as an environment variable on your computer. When you issue a command and omit the --username argument, Zowe CLI automatically uses the value that you defined in the environment variable. You can now issue a command or create any profile type without specifying your user name repeatedly.

  • Overriding a value that is used in existing profiles.

    For example, you might want to override a value that you previously set on multiple profiles to avoid recreating each profile.This reduces the number of profiles that you need to maintain and lets you avoid specifying every option on command line for one-off commands.

  • Specifying environment variables in a Jenkins environment (or other automation server) to store credentials securely.

    You can set values in Jenkins environment variables for use in scripts that run in your CI/CD pipeline. You can define Jenkins environment variables in the same manner that you can on your computer. You can also define sensitive information in the Jenkins secure credential store. For example, you might need to define your mainframe password in the secure credential store so that it is not available in plain text.

Transforming arguments/options to environment variable format

Transform the option/argument into the correct format for a Zowe CLI environment variable, then define values to the new variable. The following rules apply to this transformation:

  • Prefix environment variables with ZOWE_OPT_
  • Convert lowercase letters in arguments/options to uppercase letters
  • Convert hyphens in arguments/options to underscores

Tip: See your operating system documentation for information about how to set and get environment variables. The procedure for setting environment variables varies between Windows, Mac, and various versions of Linux operating systems.

Examples:

The following table shows command line options that you might want to transform and the resulting environment variable to which you should define the value. Use the appropriate procedure for for your operating system to define the variables.

Command Option Environment Variable Use Case
--user ZOWE_OPT_USER Define your mainframe user name to an environment variable to avoid specifying it on all commands or profiles.
--reject-unauthorized ZOWE_OPT_REJECT_UNAUTHORIZED Define a value of true to the --reject-unathorized flag when you always require the flag and do not want to specify it on all commands or profiles.

Setting environment variables in an automation server

You can use environment variables in an automation server, such as Jenkins, to write more efficient scripts and make use of secure credential storage.

You can either set environment variables using the SET command within your scripts, or navigate to Manage Jenkins > Configure System > Global Properties and define an environment variable in the Jenkins GUI. For example:

jenkins gui

Using secure credential storage

Automation tools such as Jenkins automation server usually provide a mechanism for securely storing configuration (for example, credentials). In Jenkins, you can use withCredentials to expose credentials as an environment variable (ENV) or Groovy variable.

Note: For more information about using this feature in Jenkins, see Credentials Binding Plugin in the Jenkins documentation.

Integrating with API Mediation Layer

The API Mediation Layer provides a single point of access to a defined set of microservices. The API Mediation Layer provides cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and API documentation.

When Zowe CLI executes commands that connect to a service through the API Mediation Layer, the layer routes the command execution requests to an appropriate instance of the API. The routing path is based on the system load and available instances of the API.

Use the --base-path option on commands to let all of your Zowe CLI core command groups (excludes plug-in groups) access REST APIs through an API Mediation Layer. To access API Mediation Layers, you specify the base path, or URL, to the API gateway as you execute your commands. Optionally, you can define the base path URL as an environment variable or in a profile that you create.

Examples:

The following example illustrates the base path for a REST request that is not connecting through an API Mediation Layer to one system where an instance of z/OSMF is running:

https://mymainframehost:port/zosmf/restjobs/jobs

The following example illustrates the base path (named api/v1/zosmf1) for a REST request to an API mediation layer:

https://myapilayerhost:port/api/v1/zosmf1/zosmf/restjobs/jobs

The following example illustrates the command to verify that you can connect to z/OSMF through an API Mediation Layer that contains the base path my/api/layer:

zowe zosmf check status -H <myhost> -P <myport> -u <myuser> --pw <mypass> --base-path <my/api/layer>

More Information:

Writing scripts to automate mainframe actions

You can combine multiple Zowe CLI commands in bash or shell scripts to automate actions on z/OS. You can implement scripts to enhance your development workflow, automate repetitive test or build tasks, and orchestrate mainframe actions from continuous integration/continuous deployment (CI/CD) tools such as Jenkins or TravisCI.

Writing a Script

Write a script that executes multiple CLI commands.

Note: The type of script that you write depends on the programming languages that you use and the environment where the script is executed. The following procedure is a general guide to Zowe CLI scripts, but you might need to refer to third-party documentation to learn more about scripting in general.

Follow these steps:

  1. Create a new file on your computer with the extension .sh. For example, testScript.sh.

    Note: On Linux, an extension is not required. You make the file executable by issuing the command chmod u+x testScript.

  2. At the top of the file, specify the interpreter that your script requires. For example, type #!/bin/sh or #!/bin/sh.

    Note: The command terminal that you use to execute the script depends on what you specify at the top of your script. Bash scripts require a bash interpreter (bash terminal), while shell scripts can be run from any terminal.

  3. Write a script using a series of Zowe CLI commands.

    Tip: You can incorporate commands from other command-line tools in the same script. You might choose to "pipe" the output of one command into another command.

  4. From the appropriate command terminal, issue a command to execute the script. The command you use to execute script varies by operating system.

The script runs and prints the output in your terminal. You can run scripts manually, or include them in your automated testing and delivery pipelines.

Example: Clean up Temporary Data Sets

The script in this example lists specified data sets, then loops through the list of data sets and deletes each file. You can use a similar script to clean up temporary data sets after use.

Note: This script must be run from a bash terminal.

#!/bin/bash
set -e
# Project cleanup script - deletes temporary project data sets
# Obtain the list of temporary project data sets 
dslist=$(zowe files ls ds "my.project.ds*")
# Delete each data set in the list
IFS=$'\n'
for ds in $dslist
do
     echo "Deleting Temporary Project Dataset: $ds"
     zowe files delete ds "$ds" -f
done

Example: Submit Jobs and Save Spool Output

The script in this example submits a job, waits for the job to enter output status, and saves the spool files to local files on your computer.

Note: This script must be run from a bash terminal.

#! /bin/env bash
#submit our job
jobid=$(zowe zos-jobs submit data-set "boech02.public.cntl(iefbr14)" --rff jobid --rft string)
echo "Submitted our job, JOB ID is $jobid"
#wait for job to go to output
status="UNKNOWN"
while [[ "$status" != "OUTPUT"]]; do
    echo "Checking
    status of job $jobid" status=$(zowe zos-jobs view job-status-by-jobid "$jobid" --rff status --rft string)
    echo "Current status is $status"
    sleep 5s
done;
echo "Job completed in OUTPUT status. Final result of job: "
zowe zos-jobs view job-status-by-jobid "$jobid"
# get a list of all of the spool files for our job now that it's in output
spool_ids=$(zowe zos-jobs list spool-files-by-jobid "$jobid" --rff id --rft table)
# save each spool ID to a custom file name
while read -r id; do
     zowe zos-jobs view spool-file-by-id "$jobid" "$id" > ./${jobid}_spool_${id}.txt
     echo "Saved spool DD to ./${jobid}_spool_${id}.txt"
done <<< "$spool_ids"