Using the IBM® RSE API Plug-in for Zowe™ CLI as a Node.js SDK

If you've used the IBM RSE API Plug-in for Zowe CLI to interact with z/OS® from the command line or within VS Code through IBM Z Open Editor and Zowe Explorer, you might not have noticed something interesting hiding in plain sight: the same npm package, @ibm/rse-api-for-zowe-cli, is also a fully featured Node.js SDK. You can import it directly into your Node.js projects and build automations, tools, or integrations that communicate with z/OS through IBM Remote System Explorer (RSE) REST APIs.

Let's take a quick look at what the SDK is, how to get started, and some of the things that you can do with it.

What is the RSE API, and why use it as an SDK?

IBM RSE API is the REST layer that powers IBM Z Open Editor, Zowe Explorer through its RSE profile type, and the IBM RSE API plug-in for Zowe CLI. It provides access to z/OS resources such as data sets, UNIX System Services files, jobs and TSO or shell commands over HTTPS by using a JWT-based authentication model. The Node.js package that implements the CLI commands exposes its core functionality through public TypeScript classes. As a result, the same capabilities that power the CLI are available directly from your code.

Using the SDK offers several advantages compared to invoking CLI commands:

• Programmatic control: Call individual API methods and work directly with structured TypeScript response objects instead of parsing CLI output.
• Session reuse: Create a Session once, reuse it across multiple calls, and take advantage of built-in token caching. For example, CheckStatus responses are cached for 20 minutes.
• No z/OSMF dependency: Useful in environments that use the RSE infrastructure without a z/OSMF configuration.
• Zowe SDK interoperability: The RSE SDK builds on @zowe/imperative and the Zowe SDK ecosystem, making it easy to combine RSE and z/OSMF operations in the same application.

Setting up your project

Prerequisites

• Node.js 22 or later
• Access to a z/OS system running IBM RSE API (minimum supported version: 1.1.6)

Install the package

npm install @ibm/rse-api-for-zowe-cli @zowe/imperative

@zowe/imperative is a peer dependency that provides the Session object and shared utilities. All Session instances are passed to RSE SDK methods.

Create a session

The entry point for every SDK call is an imperative.Session. You can create a session directly or load credentials from an existing Zowe team configuration profile.

import * as imperative from "@zowe/imperative";

const session = new imperative.Session({
  hostname: "myzos.example.com",
  port: 6800,
  user: "<RSE_USERID>",
  password: "<RSE_PASSWORD>",
  protocol: "https",
  type: "basic"
});

For token-based authentication, which is the preferred approach for long-running tools, call the AuthLogin.getToken() method. The SDK updates the session in place:

import { AuthLogin } from "@ibm/rse-api-for-zowe-cli";

// Exchanges user/password credentials for a JWT and updates session.ISession.tokenValue
await AuthLogin.getToken(
  session,
  "rse-profile-name",
  myProfile,
  /*autoRefreshToken=*/ true
);

When autoRefreshToken is set to true, the SDK automatically renews the token before it expires. This capability helps prevent long-running operations from failing because of an expired token.

Checking server status and capability gating

Before making API calls, it is good practice to verify the server is reachable and determine which capabilities the target RSE API version supports. The CheckStatus class provides both capabilities.

import { CheckStatus, RseApiCapability } from "@ibm/rse-api-for-zowe-cli";

// Get server version and status information (result is cached for 20 minutes)
const status = await CheckStatus.getRseStatus(session);
console.log(status);

// Guard a code path on a specific capability
const supportsJobNotifications = await CheckStatus.isCapabilitySupported(
  session,
  RseApiCapability.JOB_NOTIFICATION
);

if (supportsJobNotifications) {
  // ... use job notification APIs
}

// Or throw an error if the server does not support a required capability
await CheckStatus.requireCapability(
  session,
  RseApiCapability.VSAM_CREATION,
  "createVsam"
);

The RseApiCapability enum maps capabilities to the corresponding RSE API versions that introduce them. For example, JOB_NOTIFICATION became available in RSE API v1.2.2, while foundational capabilities such as BASIC_FILE_OPS and JWT_AUTH are available in the minimum supported version, v1.1.6. Using requireCapability() instead of explicit version checks makes the code self-documenting by indicating why a minimum version is required.

Working with data sets

Listing members of a partitioned data set

import { List } from "@ibm/rse-api-for-zowe-cli";

const response = await List.allMembers(session, "MY.PDS");

const memberNames: string[] = response.apiResponse.items.map(
  (item) => item.memberName
);
console.log(memberNames.join("\n"));

Listing UNIX System Services files

const listing = await List.fileList(session, "/u/myuser/myproject");
console.log(listing.apiResponse);

The List class also provides dataSetsMatchingPattern, allMembers with range options when the RANGE_SEARCH capability is supported, and fileHierarchy for recursive directory traversal.

Downloading and uploading files

Download a data set member

import { Download } from "@ibm/rse-api-for-zowe-cli";

await Download.dataSet(session, "MY.PDS(MYMEMBER)", {
  file: "./local-output/MYMEMBER.cbl"
});

Upload a local file to a data set

import { Upload } from "@ibm/rse-api-for-zowe-cli";

await Upload.fileToDataset(session, "./local/MYMEMBER.cbl", "MY.PDS(MYMEMBER)");

Upload a UNIX System Services file

await Upload.fileToUSSFile(session, "./local/hello.sh", "/u/myuser/hello.sh");

The Upload class automatically detects binary files and switches to binary transfer mode when required.

Submitting and monitoring jobs

Submitting JCL and waiting for the results is one of the most common automation use cases.

import { SubmitJobs, MonitorJobs } from "@ibm/rse-api-for-zowe-cli";

// Submit a job from a data set member
const job = await SubmitJobs.submitJob(session, {
  jobDataSet: "MY.JCL(COMPILE)"
});
console.log(`Submitted ${job.jobid} (${job.jobname})`);

// Wait for the job to complete
const completedJob = await MonitorJobs.waitForJobOutputStatus(session, job);
console.log(`Job ended with: ${completedJob.retcode}`);

In RSE API 1.2.2 and later, the JOB_NOTIFICATION capability enables a notification-based model that reduces polling overhead for long-running jobs. Support for this capability can be verified by using CheckStatus.isCapabilitySupported().

Running TSO and shell commands

import { IssueCommand } from "@ibm/rse-api-for-zowe-cli";

// Issue a TSO command
const tsoResult = await IssueCommand.tsoCommand(session, "LISTUSER MYUSERID");
console.log(tsoResult);

// Issue a UNIX System Services shell command
const shellResult = await IssueCommand.unixShellCommand(
  session,
  "ls -la /u/myuser"
);
console.log(shellResult);

Searching data sets and UNIX System Services files

import { Search } from "@ibm/rse-api-for-zowe-cli";

// Search for a string across MVS data set members (PDS members)
const mvsResults = await Search.performSearch(session, {
  pattern: "MY.PDS.*",
  searchString: "DISPLAY",
  regex: false
});

// Search in UNIX System Services files by content
// Search.uss(session, ussPath, fileName, options)
const ussResults = await Search.uss(session, "/u/myuser/src", "*", {
  text: "TODO"
});

Capability-aware code: a practical pattern

Because RSE API capabilities accumulate across versions, a robust SDK client can determine the capabilities supported by the connected server during startup and adjust its logic accordingly. Instead of checking each capability individually over the network, use getAllCapabilitiesForVersion(), which computes the complete capability set locally from the version string returned by CheckStatus.getRseStatus():

import * as imperative from "@zowe/imperative";
import {
  CheckStatus,
  RseApiCapability,
  getAllCapabilitiesForVersion
} from "@ibm/rse-api-for-zowe-cli";

async function buildCapabilitySet(
  session: imperative.Session
): Promise<Set<RseApiCapability>> {
  const status: any = await CheckStatus.getRseStatus(session);
  const version: string = status.rseapi_version; // e.g. "1.2.4"
  return new Set(getAllCapabilitiesForVersion(version));
}

// Use at startup: one network call and no per-capability polling
const capabilities = await buildCapabilitySet(session);

if (capabilities.has(RseApiCapability.COMBINED_SPOOL_DOWNLOAD)) {
  // Use single-call combined spool download (RSE API 1.2.4+)
} else {
  // Fall back to per-spool-file download
}

Note: This pre-check supports application-specific branching logic, but it does not bypass the SDK's internal capability checks. Individual SDK methods, such as Download.dataSet, List.fileHierarchy, and others, perform their own CheckStatus.apiVersionCheck() call before execution. Because getRseStatus() caches its response for 20 minutes, these checks incur minimal overhead after the initial call. However, they continue to run and return an error if the server version does not meet the minimum requirement for the method.

What's exported from the package

The SDK surface is extensive. The top-level @ibm/rse-api-for-zowe-cli package re-exports functionality from the following modules:

The complete API reference is available at RSE API SDK reference.

Where to go from here

• Full SDK reference — ibm.github.io/zopeneditor-about/Docs/rse_cli_sdk.html
• Z Open Editor documentation — ibm.github.io/zopeneditor-about
• Zowe SDK docs — docs.zowe.org for @zowe/imperative and related packages

The RSE API package serves a dual purpose. It powers the IBM RSE API Plug-in for Zowe CLI and provides the RSE connection protocol used by IBM Z Open Editor and Zowe Explorer. At the same time, it provides a Node.js SDK that can be used to build custom z/OS tools, automations, and integrations.