Developing for Zowe CLI
Developing for Zowe CLI
You can extend Zowe™ CLI by developing plug-ins and contributing code to the base Zowe CLI or existing plug-ins.
How to contribute
You can contribute to Zowe CLI in the following ways:
- Add new commands, options, or other improvements to the base CLI.
- Develop a Zowe CLI plug-in.
You might want to contribute to Zowe CLI to accomplish the following objectives:
- Provide new scriptable functionality for yourself, your organization, or to a broader community.
- Make use of Zowe CLI infrastructure (profiles and programmatic APIs).
- Participate in the Zowe CLI community space.
Getting started
If you want to start working with the code immediately, review the Readme file in the Zowe CLI core repository and the Zowe contribution guidelines. The zowe-cli-sample-plugin GitHub repository is a sample plug-in that adheres to the guidelines for contributing to Zowe CLI projects.
Contribution guidelines
The Zowe CLI contribution guidelines contain standards and conventions for developing Zowe CLI plug-ins.
The guidelines contain critical information about working with the code, running/writing/maintaining automated tests, developing consistent syntax in your plug-in, and ensuring that your plug-in integrates with Zowe CLI properly:
For more information about ... | See: |
---|---|
General guidelines that apply to contributing to Zowe CLI and Plug-ins | Contribution Guidelines |
Conventions and best practices for creating packages and plug-ins for Zowe CLI | Package and Plug-in Guidelines |
Guidelines for running tests on Zowe CLI | Testing Guidelines |
Guidelines for running tests on the plug-ins that you build | Plug-in Testing Guidelines |
Versioning conventions for Zowe CLI and Plug-ins | Versioning Guidelines |
Tutorials
Follow these tutorials to get started working with the sample plug-in:
- Setting up: Clone the project and prepare your local environment.
- Installing a plug-in: Install the sample plug-in to Zowe CLI and run as-is.
- Extending a plug-in: Extend the sample plug-in with a new by creating a programmatic API, definition, and handler.
- Creating a new plug-in: Create a new CLI plug-in that uses Zowe CLI programmatic APIs and a diff package to compare two data sets.
- Implementing user profiles: Implement user profiles with the plug-in.
Plug-in development overview
At a high level, a plug-in must have imperative-framework
configuration (sample here). This configuration is discovered by imperative-framework
through the package.json imperative
key.
A Zowe CLI plug-in will minimally contain the following:
- Programmatic API: Node.js programmatic APIs to be called by your handler or other Node.js applications.
- Command definition: The syntax definition for your command.
- Handler implementation: To invoke your programmatic API to display information in the format that you defined in the definition.
The following guidelines and documentation will assist you during development:
Imperative CLI Framework documentation
Imperative CLI Framework documentation is a key source of information to learn about the features of Imperative CLI Framework (the code framework that you use to build plug-ins for Zowe CLI). Refer to these supplementary documents during development to learn about specific features such as:
- Auto-generated help
- JSON responses
- User profiles
- Logging, progress bars, experimental commands, and more!
- Authentication mechanisms
Authentication mechanisms
As an extender, you can change the way Zowe CLI uses various mechanisms of authentication when communicating with the mainframe.
Zowe CLI accepts various methods, or mechanisms, of authentication when communicating with the mainframe, and the method that the CLI ultimately follows is based on the service it is communicating with.
However, some services can accept multiple methods of authentication. When multiple methods are provided (in a profile or command) for a service, the CLI follows an order of precedence to determine which method to apply. Extenders can modify this order for their plug-in.
To learn the authentication methods used for different services and their order of precedence, refer to the following table:
service | Zowe V1 order of precedence | Zowe V2 order of precedence |
---|---|---|
API ML | 1. username, password 2. API ML token | 1. username, password 2. API ML token 3. PEM certificate |
Db2, FTP, most other services | username, password | username, password |
SSH | 1. SSH key 2. username, password | 1. SSH key 2. username, password |
ZOSMF direct connection | username, password | 1. username, password 2. PEM certificate |