Imported from zowe/zowex (.agents/skills/zo-ssh/SKILL.md). Install upstream with npx skills add zowe/zowex --skill zo-ssh. Copyright stays with the author.

zo over SSH — deploy and operate

This skill is an alternative to the zowe CLI (z/OSMF REST): it uses the zo native backend driven over SSH stdio instead. Use it when the target z/OS system has SSH but no z/OSMF. It's for operating on a remote target host's datasets/jobs/USS — unrelated to building or testing this repo's own native code, which uses npm run z:rebuild / npm run z:test.

Two helpers, one command grammar. Pick the one for your platform — they take the same subcommands, flags, env vars, and config keys:

Everything below is written with the bash helper; on Windows substitute zx.ps1 (or install the zx.cmd shim — §0) and PowerShell variable syntax. Windows-specific behavior and gotchas are collected in §8 — read that section before your first call on Windows.

Everything below uses two shell variables you should set once per target:

ZX_HOST=user@host          # ssh target (z/OS USS)
ZX_DIR=/u/$USER/zowex      # remote deploy dir; pick anything the user can write

If the user gives only a hostname, ask for (or infer) the SSH user and a writable USS directory.

If you are an LLM/agent running this skill, always set your own unique ZX_STATE first — never rely on the default. All zx state (config, persistent-session pid, FIFOs, ControlMaster socket) lives under $ZX_STATE, which defaults to one shared directory per UID (/tmp/zx.$UID). That default is meant for a human's interactive shell. If an agent run uses it too, it collides with any persistent session the user has open — zx use/zx deploy overwrites their saved host config, zx start/zx stop/zx reset clobbers their session, and vice versa. It also lets two concurrent agent runs stomp on each other the same way.

export ZX_STATE=/tmp/zx-agent-$$.$UID   # unique per agent run; keep it short (see §6 ControlPath note)

$env:ZX_STATE = "$env:TEMP\zx-agent-$PID"   # same rule on Windows (default is %TEMP%\zx.%USERNAME%)

Do this at the very start of every session, before the first zx/$zx call — deploy included. Never call zx reset under a ZX_STATE a human or another agent might be using (see §7).

Local prereqs (bash): ssh, sftp, jq, base64, bash ≥3.2, and curl or wget. Run .agents/skills/zo-ssh/zx check to verify. (jq is the only one not stock on macOS — if it's missing, ask the user to install it via their package manager, e.g. Homebrew on macOS, before continuing.) Local prereqs (Windows): ssh + sftp (the Windows OpenSSH Client feature) and Windows PowerShell 5.1 or newer. No jq/base64/curl needed — zx.ps1 does JSON, base64, and downloads in-process. Run .agents\skills\zo-ssh\zx.ps1 check to verify. Remote prereqs: SSH login + a writable USS directory. The zowex binary is self-contained. Bundle: zx deploy will auto-download the latest server.pax.Z from github.com/zowe/zowex/releases if it isn't found locally. Default save path is ~/.local/share/zx/server.pax.Z (%LOCALAPPDATA%\zx\server.pax.Z on Windows) — always user-writable, works whether the helper is run directly or via PATH. Downloads automatically without prompting. To pin a specific version or path, set ZX_PAX to it. Set GITHUB_TOKEN if the API is rate-limited on a shared corporate IP.

0 · Add zx to your PATH (optional but recommended)

Run once to symlink the helper into ~/.local/bin (created if absent):

.agents/skills/zo-ssh/zx install          # -> ~/.local/bin/zx  (default)
.agents/skills/zo-ssh/zx install ~/bin    # -> ~/bin/zx          (custom dir)

zx install prints an export PATH=... line if the target directory isn't already on your PATH — paste it into your shell profile (~/.zshrc, ~/.bashrc, etc.).

On Windows there are no symlink permissions to worry about — install writes a zx.cmd shim that launches the script with -ExecutionPolicy Bypass, so it works regardless of the machine's execution policy:

.agents\skills\zo-ssh\zx.ps1 install              # -> ~\.local\bin\zx.cmd  (default)
.agents\skills\zo-ssh\zx.ps1 install C:\tools     # -> C:\tools\zx.cmd      (custom dir)

It prints the $env:PATH / [Environment]::SetEnvironmentVariable(...) line to run if the directory isn't on PATH yet.

After that, every command below can be called as zx ... directly. To remove the symlink/shim: zx uninstall.

1 · One-time deploy

The easiest path — just run zx deploy:

zx deploy user@host [/remote/dir]

If server.pax.Z isn't present locally, zx deploy will:

1. Hit the GitHub releases API to find the latest release asset (*.pax.Z)
2. Show you the filename and destination, then download it automatically
3. Continue with the normal sftp → unpax → verify flow

The release asset may carry a version in its name (e.g. zowex-0.7.0-server.pax.Z); zx saves it as server.pax.Z at the ZX_PAX path.

Manual / pinned-version deploy — download the .pax.Z from github.com/zowe/zowex/releases, then:

ZX_PAX=/path/to/downloaded.pax.Z
zx deploy user@host [/remote/dir]

Low-level steps (if you need to do it by hand):

# 1a. push the bundle (binary mode is sftp default for `put`)
sftp -b - "$ZX_HOST" <<EOF
-mkdir $ZX_DIR
cd $ZX_DIR
put server.pax.Z
bye
EOF

# 1b. unpax on the host (extracts flat: ./zo)
ssh "$ZX_HOST" "cd $ZX_DIR && pax -rvf server.pax.Z && chmod +x zo"

ZX_BIN=$ZX_DIR/zo

# 1c. verify
ssh "$ZX_HOST" "$ZX_BIN --help"

If pax -rvf fails on the .Z, do uncompress server.pax.Z && pax -rvf server.pax.

The CLI also exposes tso / system / tool subcommands — run $ZX_BIN <cmd> --help if you need one of those interactively. Only a subset is exposed via JSON-RPC (see §3; tso is RPC-backed, most of system/tool is CLI-only). Console is special: on servers newer than v0.8.0 the console CLI group exists only in the separate APF-authorized zoa binary, and the consoleCommand RPC (see §3) is how zo server reaches it. This CLI-only gap isn't limited to those groups: data-set copy is CLI-only too (no copyDataset RPC — see §3's Datasets table). When in doubt whether a zo data-set/job/uss verb has an RPC equivalent, check $ZX_BIN data-set --help against §3 rather than assuming parity.

2 · Talking to the server

zo server reads JSON-RPC 2.0 requests on stdin and writes JSON responses on stdout, one object per line. Auth is whatever SSH gave you — there is no in-band handshake.

Wire behavior (verified against v0.6.0):

• The server emits one ready banner line first: {"status":"ready","message":"...","data":{"version":"..."}}. Consume and discard it before reading responses.
• With the default worker pool, responses can arrive out of order (matched by id). For scripted/sequential use, start with -w 1 to serialize. The zx helper does this.
• Unknown methods return {"error":{"code":-32601,"message":"Unrecognized command <name>"}}.
• Result shape: {"id":N,"result":{"success":true, ...},"jsonrpc":"2.0"}. Common result fields: data (b64 for readDataset/readFile/readSpool; plain text for unixCommand/tsoCommand), items (lists), jobId/jobName (submitJcl), etag (readDataset), returnedRows.

2a · The zx helper (preferred)

zx=.agents/skills/zo-ssh/zx     # or alias/symlink it onto PATH

$zx deploy user@host [/remote/dir]   # one-time per host (idempotent); also saves config
$zx ds list "SYS1.*"                 # works immediately — auto one-shot
$zx job submit foo.jcl
$zx start                            # optional: persistent session = faster repeated calls
$zx job status JOB01234
$zx stop

On Windows, same sequence:

$zx = '.agents\skills\zo-ssh\zx.ps1'   # or install the zx.cmd shim onto PATH (§0)

& $zx deploy user@host /u/user/zowex
& $zx ds list "SYS1.*"
& $zx start                               # strongly recommended on Windows - see §8
& $zx job status JOB01234
& $zx stop

zx remembers host+bin in $ZX_STATE/config (config.json for zx.ps1; set by deploy or zx use <host> <bin>; overridable via ZX_HOST/ZX_BIN env). Every grouped command auto-detects whether a persistent session is live and falls back to a one-shot ssh if not.

Command groups (run zx help for the full list):

There is no zx group yet for the ESM certificate / key ring commands (zo system cert ... / zo system keyring ..., servers newer than v0.7.0) — drive them with zx rpc <method> (see §3's Certificates table) or CLI passthrough: ssh "$ZX_HOST" "$ZX_BIN system keyring list-rings $USER".

Output: grouped commands pretty-print by default (lists → one per line, b64 → decoded, status → key=value). Add -j/--json anywhere (before or after the group) for raw JSON: zx ds list "SYS1.*" -j or zx -j ds list "SYS1.*".

zx info shows config + whether a session is live. zx reset is a harder stop: kills the session, closes the ControlMaster socket, and removes the entire $ZX_STATE directory — useful when the state gets corrupted or you want a clean slate.

2b · One-shot

For a single call without the persistent session (note -w 1; first output line is the ready banner):

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"listJobs","params":{"owner":"*","prefix":"XYZ*"}}' \
  | ssh "$ZX_HOST" "$ZX_BIN server -w 1" | sed 1d

2c · Isolated / parallel connections (second host without disturbing the first)

All zx state — config, persistent-session pid, FIFOs, and the SSH ControlMaster socket — lives under $ZX_STATE, which defaults to one shared directory per UID (/tmp/zx.$UID). That means zx deploy/zx use for a second host overwrites the first host's saved config, and — more importantly — _live() (the check every grouped command uses to decide "route through the persistent session or go one-shot") only checks whether a pid exists, not which host it's for. If a persistent session is already live for host A and you need one-shot calls against host B without touching it, exporting ZX_HOST/ZX_BIN alone is not enough — the dispatcher will still shove your request down host A's session.

Fix: give the second host its own ZX_STATE so it never sees host A's pid file or socket:

export ZX_STATE=/tmp/zx-<label>.$UID     # short — see ControlPath length note below
export ZX_HOST=user@hostB
zx deploy "$ZX_HOST" /remote/dir          # writes config under the isolated ZX_STATE only
zx ds list "HLQ.*"                        # one-shot; host A's session/socket is untouched

If host B needs password auth and you can't leave an interactive prompt open, prime the ControlMaster once with sshpass using the same ControlPath pattern zx uses, then let zx reuse the socket silently for subsequent calls:

sshpass -p "$PASSWORD" ssh -o ControlMaster=auto -o ControlPath="$ZX_STATE/cm-%C" \
  -o ControlPersist=30m -T "$ZX_HOST" exit

Do this under the same isolated $ZX_STATE you'll use for the real zx calls — the %C token resolves to the same socket path either way, so zx's own ssh invocations find it already open and skip the password prompt. Never run zx start/zx stop/zx reset in this workflow — those only make sense for the single shared default state and reset will nuke whichever $ZX_STATE is currently exported.

On Windows the same isolation rule applies — a separate $env:ZX_STATE gives you a separate config, pid file, and named pipe (the pipe name is derived from the state directory), so two ZX_STATEs never see each other's sessions. The ControlMaster/sshpass priming above does not apply: Windows OpenSSH has no connection multiplexing. Instead give each host its own ZX_STATE and run zx start per host — each gets its own long-lived ssh connection, and each authenticates once (§8).

Envelope

{"jsonrpc":"2.0","method":"<name>","params":{...},"id":<int>}

• id must be unique per request within a session.
• All data fields (file/dataset content, JCL text) are base64.
• Responses are standard JSON-RPC 2.0: {"jsonrpc":"2.0","id":N,"result":{...}} or {"...","error":{...}}.

3 · Method reference

Datasets

No copyDataset RPC — at least as of server v0.6.0, copyDataset isn't wired over JSON-RPC (returns -32601 Unrecognized command) even though it exists as a CLI verb. zx ds copy calls the CLI directly instead (zo data-set copy <src> <dst> [--ow|-r], via SSH passthrough — see §2's CLI-vs-RPC note). If you're issuing raw RPC via zx rpc or zx -j ds copy-style JSON, don't rely on copyDataset — shell out to the CLI form instead.

Jobs

USS

TSO

Console

Server version gate: consoleCommand exists only in servers newer than v0.8.0 (zowex PR #1110). On older servers it returns -32601 Unrecognized command.

The server spawns the APF-authorized zoa binary per request (located next to zo, on the server's PATH, or via ZOA_PATH on the remote host) — the server itself never holds APF authorization. Prereqs on the host: zoa installed and extattr +ap'd by a system programmer, and ESM OPERCMDS grants (MVS.* profiles, e.g. MVS.REPLY.* for WTOR replies) for anything beyond informational D ... displays. consoleName defaults to the SSH user's ID plus a digit suffix; console activation can be gated per user with MVS.MCSOPER.<name> profiles. Failures come back with actionable messages ("command not found" → zoa not installed; "Not authorized" → not APF-authorized or ESM denied).

Certificates / key rings (ESM)

Server version gate: these methods exist only in servers newer than v0.7.0 (zowex PR #1079). On older servers they return -32601 Unrecognized command. The caller's SSH user needs the corresponding ESM IRR.DIGTCERT.* / RDATALIB authority — without it, calls fail with a SAF diagnostic (see below), not an auth prompt.

CLI equivalents live under zo system cert ... and zo system keyring ....

Conventions shared by these methods:

• "*" as keyring is the ESM virtual key ring (all of the owner's certificates) — valid for list/count/show/export reads; rejected as a target for create/delete-ring/import/connect (use the database/fromDatabase booleans instead).
• Failures return result.success:false with message, service, and a structured safReturns object (functionCode, safReturnCode, esmReturnCode, esmReasonCode); GSK (System SSL) failures add gskReturnCode. Non-fatal SAF warnings (rc 4) succeed with a warning string.
• owner, keyring, and label are case-sensitive (userids normally uppercase).

unixCommand / tsoCommand are the escape hatches for anything not covered. MVS console commands have their own method on servers newer than v0.8.0 — consoleCommand (see the Console table above). On older servers, run the APF-authorized companion binary directly on the host: ssh "$ZX_HOST" "zoa console issue ..." (zo console issue only exists on pre-v0.8.x binaries and requires the old fat zoa there too).

4 · zowe-CLI → zx mapping

When porting a workflow that used the zowe CLI:

Submit-then-poll pattern:

JID=$(zx job submit f.jcl | grep '^jobId=' | cut -d= -f2)
while [[ $(zx -j job status "$JID" | jq -r .result.status) == ACTIVE ]]; do sleep 2; done
zx job spools "$JID"          # list spool files with their IDs
zx job spool  "$JID" 2        # read spool file #2 (JESMSGLG, etc.)

5 · File transfer

ds get|put go through base64-in-JSON, so use them for text members (REXX/JCL/parmlib/source). For load modules or anything large/binary, stage through USS:

zx uss sh 'cp -B "//'\''SYS1.LINKLIB(IEFBR14)'\''" /tmp/iefbr14.bin'
zx uss get /tmp/iefbr14.bin

For whole-PDS ds get, run zx start first — one persistent session is much faster than N one-shot SSH connects. ds put of a directory may hit zo DEQ contention on rapid same-PDS writes; failures are reported per-member and the command exits non-zero if any failed.

6 · Troubleshooting

7 · Cleanup

zx stop                              # kill persistent session (ControlMaster socket kept for 30m)
zx reset                             # harder: also kills ControlMaster + wipes $ZX_STATE dir
ssh "$ZX_HOST" "rm -rf $ZX_DIR"     # remove the remote binary (only if you deployed it)

Only remove $ZX_DIR on the remote side if you created it for this session.

On Windows, zx.ps1 stop shuts down the session host and reaps its ssh child (tracked in $ZX_STATE\ssh-pid), and zx.ps1 reset additionally wipes the state directory. There is no ControlMaster socket to close.

8 · Windows notes (zx.ps1)

Behavior differences vs. the bash helper — everything else (subcommands, -j, ZX_HOST/ZX_BIN/ZX_STATE/ZX_PAX/ZX_TIMEOUT/GITHUB_TOKEN, method coverage, output shapes) is the same.

• Requires Windows PowerShell 5.1+ (the version that ships with Windows) or PowerShell 7. No jq, base64, curl, or wget — JSON, base64, and the release download are done in-process.
• No connection multiplexing. Windows OpenSSH doesn't implement ControlMaster/ControlPath, so every one-shot call is a new SSH connection (slower, and one auth per call with passwords). zx start is the stand-in: it launches a hidden-ish background PowerShell host that owns one long-lived zo server -w 1 over ssh and answers one request per named-pipe connection. Every grouped command auto-routes through it when it's live, exactly like the bash version. Use zx start for anything more than a couple of calls, and always for a whole-PDS ds get/ds put.
  • The host is started with -NoNewWindow so it keeps your console: with password auth, ssh's prompt appears in your terminal during zx start (which waits up to 60s, or ZX_TIMEOUT if larger, for the ready banner). Key auth (ssh-keygen + append your public key to the host's ~/.ssh/authorized_keys) avoids the prompt entirely.
  • The pipe name is derived from $env:ZX_STATE, so per-agent/per-host isolation works the same way (§2c) and there's no socket-path length limit (the bash ControlPath too long problem doesn't exist here).
  • zx info prints the state dir, config, pid, and pipe name.
• Output goes through the PowerShell pipeline (Write-Output), so zx ds list "X.*" | Select-String FOO, $rows = zx -j ds list "X.*" | ConvertFrom-Json, and Tee-Object all work. Errors and progress lines go to stderr. Caveat: PowerShell 5.1's > writes UTF-16 — use zx ds get / zx uss get for files, or Out-File -Encoding utf8.
• State/paths: $env:ZX_STATE defaults to %TEMP%\zx.%USERNAME% and holds config.json, pid, ssh-pid, ready, err, ssh-err. $env:ZX_PAX defaults to %LOCALAPPDATA%\zx\server.pax.Z.
• Extra ssh options: $env:ZX_SSH_OPTS is split on whitespace and prepended to every ssh/sftp call, e.g. $env:ZX_SSH_OPTS = '-i C:\keys\zos_id -o StrictHostKeyChecking=accept-new'. Since ssh honors the first value for an option, anything you set here wins over zx.ps1's own defaults.
• Local paths may use \ or /; they're normalized for sftp (which treats \ as an escape). Relative paths resolve against the current directory.
• zo CLI passthroughs (zx tool, zx system parmlib|subsystems|symbol, zx ds copy) work the same — they run as their own ssh command, not through the session pipe. Everything RPC-backed — including zx console (consoleCommand) and zx ds get|put --binary — goes through the session when one is live.