Build a typed CLI from scratch with Commander.js + Zod

The problem with untyped CLIs

Commander.js is great for parsing arguments, but it hands you everything as string | undefined — regardless of what type you declared in the option definition. The <number> in .option("--count <number>") is cosmetic. What lands in your action handler is raw text from process.argv, and the coercion, validation, and type-narrowing is entirely on you. Most developers paper over this with parseInt(opts.count as string) and hope for the best. That works until a user passes "banana" and your tool crashes with a stack trace instead of a helpful message.

We already have the right tool for this: Zod. It's everywhere in the Node.js ecosystem for HTTP bodies, env vars, and config files — but rarely applied at the CLI layer. That's the gap this post fills. By the end you'll have a CLI that validates all inputs at the boundary, gives users readable error messages, and is fully typed end-to-end with no casts and no any.

1. Project scaffold

mkdir my-cli && cd my-cli

npm init -y

npm install commander zod

npm install -D typescript tsx @types/node

npx tsc --init

Three dependencies: commander for the CLI surface, zod for validation, tsx to run TypeScript directly during development without a compile step. Update tsconfig.json:

{

  "compilerOptions": {

    "strict": true,

    "target": "ES2022",

    "module": "Node16",

    "moduleResolution": "Node16",

    "outDir": "dist"

  }

}

strict: true is non-negotiable here — it's exactly what catches the class of bugs we're solving. Wire up bin and scripts in package.json:

{

  "bin": { "my-cli": "./dist/index.js" },

  "scripts": {

    "dev": "tsx src/index.ts",

    "build": "tsc"

  }

}

2. Your first typed command

import { Command } from "commander";



const program = new Command();



program

  .name("my-cli")

  .option("--name <string>", "Your name")

  .option("--count <number>", "How many times to greet")

  .action((opts) => {

    console.log(opts);

  });



program.parse(process.argv);

Run it:

npx tsx src/index.ts --name Alice --count 3

# { name: 'Alice', count: '3' }

count is '3' — a string. Commander doesn't coerce types. If you do arithmetic with it you get string concatenation. If you type-guard with typeof opts.count === 'number' it always returns false. This is the gap Zod fills.

3. Enter Zod — schema-validate your options

Treat program.opts() the same way you'd treat an untrusted HTTP request body: validate at the boundary, only work with the parsed output. Define a schema and run opts through it:

import { z } from "zod";



const OptionsSchema = z.object({

  name: z.string().min(1, "Name cannot be empty"),

  count: z.coerce.number().int().positive().default(1),

});



program.action((opts) => {

  const options = OptionsSchema.parse(opts);



  for (let i = 0; i < options.count; i++) {

    console.log(`Hello, ${options.name}!`);

  }

});

z.coerce.number() calls Number(value) before validating, converting Commander's "3" to 3. If someone passes --count banana, Zod rejects it cleanly instead of silently producing NaN. .int().positive() enforces additional constraints without a single if statement. .default(1) makes the option optional — Zod fills it in. After .parse(), options has the inferred type { name: string; count: number } — no annotation required.

4. User-friendly validation errors

Right now a failed parse throws a raw ZodError JSON blob at the user. Fix that with a small reusable helper using safeParse():

import { ZodSchema } from "zod";



function parseOptions<T>(schema: ZodSchema<T>, opts: unknown): T {

  const result = schema.safeParse(opts);



  if (!result.success) {

    console.error("Invalid options:\n");

    result.error.issues.forEach((issue) => {

      console.error(`  --${issue.path.join(".")}  ${issue.message}`);

    });

    console.error("\nRun with --help for usage.\n");

    process.exit(1);

  }



  return result.data;

}

Before vs after, when --name is missing:

# Before

ZodError: [{"code":"too_small","path":["name"],"message":"Name cannot be empty"...}]



# After

Invalid options:



  --name  Name cannot be empty



Run with --help for usage.

This helper is generic — T is inferred from the schema, so the return type is always exactly right. opts is unknown, which correctly models the untrusted input. Replace all direct .parse() calls with parseOptions(schema, opts) going forward.

5. Scaling to subcommands

As your CLI grows, each command gets its own schema and calls the same helper — no copy-pasted validation logic:

const InitSchema = z.object({

  dir: z.string().default("."),

  force: z.boolean().default(false),

});



const RunSchema = z.object({

  name: z.string().min(1),

  count: z.coerce.number().int().positive().default(1),

});



program

  .command("init")

  .option("--dir <path>", "Target directory")

  .option("--force", "Overwrite existing files")

  .action((opts) => {

    const options = parseOptions(InitSchema, opts);

    console.log(`Initializing in ${options.dir}`);

  });



program

  .command("run")

  .option("--name <string>", "Your name")

  .option("--count <number>", "How many times to greet")

  .action((opts) => {

    const options = parseOptions(RunSchema, opts);

    for (let i = 0; i < options.count; i++) {

      console.log(`Hello, ${options.name}!`);

    }

  });

Inside the init action, options has type { dir: string; force: boolean }. Inside run, it's { name: string; count: number }. TypeScript infers these separately from each schema — accessing options.name in the init handler is a compile error, not a runtime surprise.

6. Help menus and .env support

Commander generates --help automatically from your .option() descriptions — you already have it for free. One gotcha: Zod's .default() values don't appear in Commander's help output. Mirror them manually in the third argument to .option():

.option("--count <number>", "How many times to greet", "1")

For .env support, merge environment variables into opts before parsing. Zod doesn't care where values originate — it just validates the final object:

import "dotenv/config";



program.command("run").action((cliOpts) => {

  const merged = {

    name: process.env.CLI_NAME,

    count: process.env.CLI_COUNT,

    ...cliOpts, // CLI flags win over env vars

  };

  const options = parseOptions(RunSchema, merged);

});

Env vars as defaults, CLI flags as overrides — one schema validates both.

7. Publishing to npm

Add a shebang as the very first line of src/index.ts (before imports):

#!/usr/bin/env node

Build, make the output executable, test locally with npm link, then publish:

npm run build

chmod +x dist/index.js

npm link

my-cli run --name Cris --count 3  # test it

npm unlink my-cli

npm publish --access public

Verify with npx my-cli run --name Cris --count 3 — if that works, you're done.

Wrapping up

The pattern in one line: Commander owns the surface, Zod owns the contract. Commander parses and routes. Zod coerces, validates, defaults, and types. The parseOptions helper — 15 lines — is the glue, and it scales to any number of subcommands without modification.

This isn't CLI-specific either. The same schema-at-boundary approach applies to HTTP bodies, env vars, and config files. Validate everything at every input boundary, work only with validated data inside your logic, and an entire category of runtime bugs stops existing.

The full source is on GitHub: [link to your repo]

Next up: adding --json output mode and stdin piping so your CLI composes cleanly in shell pipelines.

Found this useful? Drop a reaction or leave a comment — feedback helps me prioritise what to cover next in this series.