Building a CLI Tool in TypeScript

I’ve been building CLI tools for years. Most of them were throwaway scripts — until I needed something production-grade. Here’s how I approached it.

The setup

Starting with a clean TypeScript project using tsup for bundling. No Webpack, no Rollup config hell. Just a tsup.config.ts and you’re done.

1
import { defineConfig } from "tsup";
2

3
export default defineConfig({
4
  entry: ["src/cli.ts"],
5
  format: ["esm"],
6
  target: "node20",
7
  clean: true,
8
  dts: true,
9
  shims: true,
10
});

Parsing arguments

I used to reach for yargs or commander. These days, I parse args manually and validate with Zod. Fewer dependencies, full control.

1
import { z } from "zod";
2

3
const argsSchema = z.object({
4
  command: z.enum(["init", "build", "deploy"]),
5
  flags: z.object({
6
    verbose: z.boolean().default(false),
7
    output: z.string().optional(),
8
    concurrency: z.number().int().positive().default(4),
9
  }),
10
});
11

12
function parseArgs(argv: string[]) {
13
  const [command, ...rest] = argv.slice(2);
14
  const flags: Record<string, unknown> = {};
15

16
  for (let i = 0; i < rest.length; i++) {
17
    if (rest[i] === "--verbose") flags.verbose = true;
18
    if (rest[i] === "--output") flags.output = rest[++i];
19
    if (rest[i] === "--concurrency") flags.concurrency = Number(rest[++i]);
20
  }
21

22
  return argsSchema.parse({ command, flags });
23
}

The nice thing about Zod here is you get validation and types in one pass. If someone passes --concurrency abc, it throws a clear error.

Structured logging

console.log doesn’t cut it for CLI tools. You need levels, colors, and structured output for piping.

1
import { createLogger } from "./logger";
2

3
const log = createLogger({ verbose: flags.verbose });
4

5
log.info("Starting build", { output: flags.output });
6
log.debug("Resolved config", { config }); // only shown with --verbose
7
log.error("Build failed", { error: err.message });

The implementation is ~40 lines. No need for winston or pino in a CLI context.


10 collapsed lines
1
type Level = "debug" | "info" | "warn" | "error";
2

3
const COLORS: Record<Level, string> = {
4
  debug: "\x1b[90m",
5
  info: "\x1b[36m",
6
  warn: "\x1b[33m",
7
  error: "\x1b[31m",
8
};
9

10
const RESET = "\x1b[0m";
11

12
export function createLogger(opts: { verbose: boolean }) {
13
  return {
14
    debug(msg: string, data?: Record<string, unknown>) {
15
      if (!opts.verbose) return;
16
      write("debug", msg, data);
17
    },
18
    info(msg: string, data?: Record<string, unknown>) {
19
      write("info", msg, data);
20
    },
21
    warn(msg: string, data?: Record<string, unknown>) {
22
      write("warn", msg, data);
23
    },
24
    error(msg: string, data?: Record<string, unknown>) {
25
      write("error", msg, data);
26
    },
27
  };
28
}
29

30
function write(level: Level, msg: string, data?: Record<string, unknown>) {
31
  const prefix = `${COLORS[level]}[${level}]${RESET}`;
32
  const suffix = data ? ` ${JSON.stringify(data)}` : "";
33
  process.stderr.write(`${prefix} ${msg}${suffix}\n`);
34
}

Handling async operations

Most CLI tools need to do async work — reading files, making HTTP requests, spawning processes. Here’s a pattern I use for concurrent file processing:

1
async function processFiles(paths: string[], concurrency: number) {
2
  const results: Map<string, Result> = new Map();
3
  const queue = [...paths];
4

5
  async function worker() {
6
    while (queue.length > 0) {
7
      const path = queue.shift()!;
8
      try {
9
        const content = await Bun.file(path).text();
10
        const transformed = await transform(content);
11
        results.set(path, { ok: true, data: transformed });
12
      } catch (err) {
13
        results.set(path, { ok: false, error: String(err) });
14
      }
15
    }
16
  }
17

18
  await Promise.all(Array.from({ length: concurrency }, () => worker()));
19
  return results;
20
}

Python equivalent

For comparison, here’s how I’d do the same arg parsing in Python with Pydantic:


16 collapsed lines
1
from pydantic import BaseModel, Field
2
from enum import Enum
3
import sys
4

5

6
class Command(str, Enum):
7
    init = "init"
8
    build = "build"
9
    deploy = "deploy"
10

11

12
class Flags(BaseModel):
13
    verbose: bool = False
14
    output: str | None = None
15
    concurrency: int = Field(default=4, gt=0)
16

17

18
class Args(BaseModel):
19
    command: Command
20
    flags: Flags
21

22

23
def parse_args(argv: list[str]) -> Args:
24
    args = argv[1:]
25
    command = args[0] if args else ""
26
    flags: dict = {}
27

28
    i = 1
29
    while i < len(args):
30
        match args[i]:
31
            case "--verbose":
32
                flags["verbose"] = True
33
            case "--output":
34
                i += 1
35
                flags["output"] = args[i]
36
            case "--concurrency":
37
                i += 1
38
                flags["concurrency"] = int(args[i])
39
        i += 1
40

41
    return Args(command=command, flags=Flags(**flags))
42

43

44
if __name__ == "__main__":
45
    config = parse_args(sys.argv)
46
    print(f"Running {config.command.value} with {config.flags}")

Same idea — schema validates and types in one shot. Pydantic and Zod are spiritual siblings.

Lessons learned

Keep dependencies minimal. Every npm install is a liability in a CLI tool. Users notice startup time.
Write to stderr for logs, stdout for data. This makes piping work correctly: mycli build | jq .
Fail fast with clear errors. Nobody wants a stack trace. Catch, format, exit with a non-zero code.
Test the arg parser separately. It’s the most fiddly part and the easiest to unit test.

The full source is about 300 lines. No framework, no magic. Just TypeScript doing what it does best.