yargs 18 CLI options validated with Zod 4: working versions (tested 2026-10-15)

{
  "name": "yargs-zod-cli",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "yargs": "18.2.0",
    "zod": "4.6.7"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "tsx": "4.23.15",
    "@types/yargs": "17.0.35"
  }
}

import yargs from "yargs/yargs";
import { hideBin } from "yargs/helpers";
import { z } from "zod";

export const DeployOpts = z.object({
  env: z.enum(["dev", "staging", "prod"]),
  tag: z.string().regex(/^v\d+\.\d+\.\d+$/),
  dryRun: z.boolean().default(false),
  regions: z.array(z.string().min(2)).min(1),
});

export type DeployOpts = z.infer<typeof DeployOpts>;

export async function parseDeploy(argv: string[]) {
  const raw = await yargs(argv)
    .scriptName("deploy")
    .option("env", { type: "string", demandOption: true })
    .option("tag", { type: "string", demandOption: true })
    .option("dry-run", { type: "boolean", default: false })
    .option("regions", { type: "array", string: true, demandOption: true })
    .exitProcess(false)
    .parseAsync();

  const parsed = DeployOpts.safeParse({
    env: raw.env,
    tag: raw.tag,
    dryRun: raw.dryRun ?? raw["dry-run"],
    regions: raw.regions,
  });
  if (!parsed.success) {
    return { ok: false as const, issues: z.flattenError(parsed.error).fieldErrors };
  }
  return { ok: true as const, data: parsed.data };
}

export function fromProcessArgv(argv = process.argv) {
  return parseDeploy(hideBin(argv));
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { parseDeploy } from "../src/cli.ts";

test("parses valid deploy argv", async () => {
  const r = await parseDeploy(["--env", "prod", "--tag", "v1.2.3", "--regions", "us", "eu", "--dry-run"]);
  assert.equal(r.ok, true);
  if (r.ok) {
    assert.equal(r.data.env, "prod");
    assert.equal(r.data.tag, "v1.2.3");
    assert.equal(r.data.dryRun, true);
    assert.deepEqual(r.data.regions, ["us", "eu"]);
  }
});

test("rejects bad tag", async () => {
  const r = await parseDeploy(["--env", "dev", "--tag", "nope", "--regions", "us"]);
  assert.equal(r.ok, false);
  if (!r.ok) assert.ok(r.issues.tag);
});