How to Quickly Build Applications Using the @zowe/cli npm Package (Part 1)
The most common use case for Zowe CLI is to install it, create a profile, and begin issuing commands:
Often, users of the CLI then embed these commands in scripts to create automation for higher-level z/OS operations (for things like building, deploying, and testing).
Additional Zowe CLI Usage
A lesser known way to use the Zowe CLI is as an npm package. You can use this package to build scripts and write automation similar to using the CLI directly, but instead, you use TypeScript, programmatic APIs.
By programmatic API s — we’re talking about interfaces, functions, methods, library code, etc — not REST APIs which also appear in the broader Zowe space.
The difference is that you programmatically call into the code that Zowe CLI itself uses via TypeScript APIs (i.e. you use the Zowe CLI as a library).
Building on the Zowe CLI package this way helps to quickly create cross-platform mainframe tools which make use of the 1 million+ packages on npmjs registry. For example, you can create editor extensions or also create graphical, cross-platform (Windows, Mac, and Linux) applications using something like Electron.
Goal
To get started, we’ll cover the bare minimum to start calling the Zowe CLI package.
We’ll initialize a new Node.js application written in TypeScript, add the Zowe CLI package dependency (plus a few others), and write a few lines of code to call a method to get z/OS jobs.
In a future write-up, we can look at more advanced methods to load profiles and integrate with other frameworks like Electron.
Clone Setup
If you want to get started quickly, follow this section; otherwise, skip to Manual Setup
Follow these steps to clone a starter project:
git clone https://github.com/dkelosky/use-zowe-cli-packagecd use-zowe-cli-packagenpm install
Manual Setup
If you followed the “Clone Setup” section, skip ahead to Begin Coding — “Hello World” TypeScript
The prerequisites to use the Zowe CLI package programmatically are the same as the Zowe CLI itself — you’ll need Node.js (of course, on the z/OS side, you’ll need z/OSMF REST APIs configured with proper security access).
Open a terminal on your workstation (e.g. Windows command prompt) and create a development folder: use-zowe-cli-package. cd use-zowe-cli-package and initialize a new project via npm init. Repeatedly press enter on the prompts until a package.json is created:
You can update this file directly with any text editor using proper values and syntax for .json files or indirectly update this file via npm commands.
Add Dependencies
Issue npm install --save @zowe/cli --ignore-script to add the Zowe CLI package to the dependencies of your package.json. This command will create a node_modules folder in which the @zowe/cli package (and its dependencies) will be installed.
Next, issue npm install --save-dev typescript @types/node to add the TypeScript compiler to the devDependencies of your package.json, pull the TypeScript packages (and its dependencies) into your node_modules folder, and add TypeScript definitions for Node.js APIs.
Add tsconfig
You can run the TypeScript compiler via npx tsc with the --init option to create a default tsconfig.json. This is a configuration file for the TypeScript compiler on how to tanspile to JavaScript.
For this project, create a tsconfig.json manually that contains this:
Initialize for Source Control
Lastly, prepare for source control. Create a .gitignore containing:
Then:
git init→ initialize for source controlgit add .→ stage all files not in.gitignoregit commit -m "initial commit→ commit staged files
From here, you could also push to your favorite hosted repository (a.k.a GitHub 😃).
Begin Coding —” Hello World” TypeScript
To start coding, create a simple TypeScript file src/index.ts. Its contents should be code to write a message to the console: console.log("hello world");.
Update the package.json to add a new script. Within the scripts section, add “build”: “tsc — pretty”,.
This update to the package.json enables you to use an npm run build to build (transpile) your TypeScript to JavaScript (of course you can use the tsc command directly or run npx tsc, but npm run build is a common approach).
Run npm run build && node lib to run your “hello world” code:
You’re now a Node.js/TypeScript programmer 😉!
Using the Zowe CLI TypeScript Programmatic APIs
Once you get “hello world” running, use this code sample to get z/OS job information printed to the workstation console:
Using methods (or functions?), like getJobs(), from the Zowe CLI package means that you simply call the method/function programmatically to perform a z/OS operation (in this case, to get jobs and print to a workstation console):
$ npm run build && node lib
Got job: RUNMAIN INPUT
Got job: RUNMAIN INPUTThat’s it!
Recap
Although it may not look like much, you also didn’t write much! 25 lines of code in the example above were needed (counting whitespace and comments) to get z/OS jobs for a user.
There are many others programmatic APIs for z/OS operations to use besides those dealing with z/OS jobs. Many exist for: data sets, TSO, z/OS console, and other areas.
API Documentation
At the time of writing this, there isn’t a shared, published API document describing what APIs are available for the Zowe CLI (or imperative) package. However, if you clone the Zowe CLI repo and issue npm run typedoc, you can get a local TSDoc view of the APIs:
Making Something Interesting
This is merely how to get started using the Zowe CLI npm package programmatic APIs. From here, the intent is to quickly build something greater. In the next write-up, we’ll look at Electron to build a graphical app using the Zowe CLI code.
