Configuring Zowe CLI
This section explains how to define and verify your connection to the mainframe through the CLI. You can also configure CLI settings, such as the level of detail produced in logs and the location of the home directory on your computer.
Note The configuration for the CLI is stored on your computer in a directory such as C:\Users\user01.zowe. The configuration includes log files, your profile information, and CLI plug-ins that are installed. When you troubleshoot an issue with the CLI, the log files in the imperative and zowe folders contain valuable information.
- Testing Zowe CLI connection to z/OSMF
- Defining Zowe CLI connection details
- Setting CLI log levels
- Setting the CLI home directory
Testing Zowe CLI connection to z/OSMF
You can issue a command at any time to receive diagnostic information from the server and confirm that Zowe CLI can communicate with z/OSMF or other mainframe APIs.
Tip: We recommend that you append
--help to the end of commands in the product to see the complete set of commands and options available to you. For example, issue
zowe profiles --help to learn more about how to list profiles, switch your default profile, or create different profile types.
Without a Profile
Verify that your CLI can communicate with z/OSMF by issuing the following command:
zowe zosmf check status --host <host> --port <port> --user <username> --pass <password>
Verify that you can use your default profile to communicate with z/OSMF by issuing the following command:
zowe zosmf check status
Verify that you can use a specific profile to communicate with z/OSMF by issuing the following command:
zowe zosmf check status --zosmf-profile <profile_name>
The commands return a success or failure message and display information about your z/OSMF server. For example, the z/OSMF version number and a list of installed plug-ins. Report any failure to your systems administrator and use the information for diagnostic purposes.
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
- Creating Zowe CLI profiles
- Defining environment variables
- Integrating with API Mediation Layer
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:
- Arguments and options that you specify directly on the command line.
- Environment variables that you define in the computer's operating system. For more information, see Defining Environment Variables
- User profiles that you create.
- 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
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.
For more information, see Accessing an API Mediation Layer.
The following example illustrates the command to create a profile that connects to z/OSMF through API ML with the base path
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
--usernameargument, 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
- 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.
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|
| || ||Define your mainframe user name to an environment variable to avoid specifying it on all commands or profiles.|
| || ||Define a value of |
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:
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.
--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.
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:
The following example illustrates the base path (named
api/v1/zosmf1) for a REST request to an API mediation layer:
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
zowe zosmf check status -H <myhost> -P <myport> -u <myuser> --pw <mypass> --base-path <my/api/layer>
Setting Zowe CLI log levels
You can set the log level to adjust the level of detail that is written to log files:
Important! Setting the log level to TRACE or ALL might result in "sensitive" data being logged. For example, command line arguments will be logged when TRACE is set.
| ||Zowe CLI logging level||Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)||DEBUG|
| ||Imperative CLI Framework logging level||Log4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)||DEBUG|
Setting the Zowe CLI home directory
You can set the location on your computer where Zowe CLI creates the .zowe directory, which contains log files, profiles, and plug-ins for the product:
| ||Zowe CLI home directory location||Any valid path on your computer||Your computer default home directory|