DEV Community: AW

How to Build and Ship a Node.js CLI Tool: From Zero to npm

AW — Thu, 04 Jun 2026 07:21:35 +0000

Here is a step-by-step guide to building, testing, and publishing a production-quality Node.js CLI tool on npm — with TypeScript, automated testing, and CI in mind.

I've published two Node.js CLI tools to npm this year. Both are open source, both have tests, both are gzipped smaller than the average JPEG. And both taught me that shipping a CLI tool is surprisingly straightforward once you have the right setup.

This tutorial walks through everything I learned: project structure, TypeScript configuration, argument parsing, testing strategies, and publishing. By the end, you'll have a production-quality CLI you can ship to npm.

What we're building

A simple but useful converter CLI — the kind of tool every developer needs at some point. It accepts commands like:

mycli json yaml package.json
mycli ts 1748226460
mycli b64 encode "hello world"

Each converter is a self-contained module, so adding new ones takes minutes.

Step 1: Project setup

Start with the basics:

mkdir mycli && cd mycli
npm init -y

Install dependencies:

npm install --save-dev typescript @types/node
npx tsc --init

Your tsconfig.json should target Node.js 18+ and use ESM-compatible output:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./bin",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}

Step 2: Project structure

The structure that scales well:

mycli/
├── bin/              # compiled output
├── src/
│   ├── converters/   # one file per converter
│   │   ├── json-yaml.ts
│   │   ├── timestamp.ts
│   │   ├── base64.ts
│   │   └── ...
│   ├── cli.ts        # argument parsing + routing
│   └── index.ts      # exports for programmatic use
├── tests/            # test files
├── package.json
└── tsconfig.json

The key insight: each converter exports a simple function with a consistent signature. This makes them testable independently and trivially extensible.

// src/converters/timestamp.ts
export interface TimestampResult {
  iso: string;
  utc: string;
  locale: string;
  seconds: number;
  milliseconds: number;
}

export function convertTimestamp(input: string): TimestampResult {
  const ms = input === "now" ? Date.now() : parseInt(input) * 1000;
  const date = new Date(ms);
  return {
    iso: date.toISOString(),
    utc: date.toUTCString(),
    locale: date.toLocaleString(),
    seconds: Math.floor(ms / 1000),
    milliseconds: ms,
  };
}

Step 3: CLI entry point

The CLI entry point lives in src/cli.ts. It parses arguments and routes to the right converter:

#!/usr/bin/env node
import { convertTimestamp } from "./converters/timestamp.js";
import { convertColor } from "./converters/color.js";
// ... etc

const [command, subcommand, ...args] = process.argv.slice(2);

switch (command) {
  case "ts":
    console.log(convertTimestamp(args[0] ?? "now"));
    break;
  case "color":
    console.log(convertColor(args[0]));
    break;
  // ...
}

In package.json, point the bin field to the compiled entry point:

{
  "bin": {
    "mycli": "./bin/cli.js"
  }
}

Use "type": "module" in package.json for ESM, and make sure your tsconfig outputs ESM-compatible JavaScript.

Step 4: Testing

CLI tools need three kinds of tests:

Unit tests for converters. These are the simplest and most valuable:

// tests/timestamp.test.ts
import { describe, it, expect } from "vitest";
import { convertTimestamp } from "../src/converters/timestamp.js";

describe("timestamp converter", () => {
  it("converts a Unix timestamp to ISO", () => {
    const result = convertTimestamp("1748226460");
    expect(result.iso).toBe("2025-05-26T10:27:40.000Z");
  });

  it("handles 'now' keyword", () => {
    const before = Date.now();
    const result = convertTimestamp("now");
    const after = Date.now();
    expect(result.milliseconds).toBeGreaterThanOrEqual(before);
    expect(result.milliseconds).toBeLessThanOrEqual(after);
  });

  it("throws on empty input", () => {
    expect(() => convertTimestamp("")).toThrow();
  });
});

Edge case tests for input validation:

it("rejects garbage input", () => {
  expect(() => convertTimestamp("not-a-number")).toThrow();
});

it("handles very large timestamps", () => {
  const result = convertTimestamp("4102444800"); // year 2100
  expect(result.iso).toContain("2100");
});

Integration tests for the CLI itself:

it("CLI outputs valid JSON for timestamp command", async () => {
  const { stdout } = await exec("node bin/cli.js ts 1748226460");
  const parsed = JSON.parse(stdout);
  expect(parsed.iso).toBeDefined();
});

Running 70 tests with vitest takes under 2 seconds. This gives you confidence to add converters without breaking existing ones.

Step 5: Handling the tricky parts

Input validation. Always validate before converting. A converter that silently returns NaN or undefined is worse than one that throws:

if (!input || input.trim() === "") {
  throw new Error(
    "timestamp: expected a Unix timestamp (number) or 'now', got empty input"
  );
}

Format auto-detection. The color converter needs to accept hex, RGB, and HSL — and return all three. Parse the input to figure out which format it is, then convert to the other two. This is where most of the interesting logic lives.

Cross-platform compatibility. A test that passes on macOS might fail on Windows. Use os.EOL instead of \n, avoid shell-specific features, and test on both platforms if you can.

Step 6: Publishing to npm

Before your first publish:

Check name availability — npm view <name> to see if it's taken
Set up .gitignore — exclude node_modules/, bin/ (if you rebuild on install), and *.tsbuildinfo
Add a README — explain what it does, show usage examples, include badges for version, downloads, and bundle size

Publishing flow:

npm run build
npm test
npm version patch  # or minor, or major
npm publish

Use a granular access token for CI/CD (the old npm token create approach, not passkey auth which doesn't work for automation).

Step 7: What to track after shipping

After publishing, monitor:

Downloads — npm view <name> downloads for weekly trends
Issues — watch your GitHub repo for bug reports and feature requests
Bundle size — use bundlephobia.com to track size over time

The first week will likely see a trickle of downloads (my first tool got ~45/week, the second ~33/week). That's normal. Growth comes from articles like this one, Show HN posts, and word of mouth.

The results

After publishing, I had:

5.5 kB gzipped bundle — smaller than a single ad on most converter websites
70 passing tests — covering every converter, edge case, and CLI behavior
Zero runtime dependencies — installs instantly, no network calls at runtime
Cross-platform — works on macOS, Linux, and Windows

The tool works offline. Data never leaves your machine. And it's pipeable, scriptable, and composable with the rest of your toolchain.

Key takeaways

CLI tools are underrated. They're faster, more private, and more composable than any website. If you find yourself visiting the same converter site more than once a week, you should build a CLI for it.
Start with tests. Each converter is a pure function — input in, output out. These are the easiest tests you'll ever write, and they give you confidence to iterate quickly.
Ship early. Your first version doesn't need every converter under the sun. Ship with 3-4 converters, get feedback, then add more. The npm publish cycle takes 30 seconds.
Polish the README. Your README is your marketing page. Show examples, include a comparison table, add badges. It makes the difference between someone trying your tool and scrolling past.

The full source code is available at github.com/amitwaks/anyconv if you want to see the complete implementation. And the published package is on npm at anyconv.

Now go build something. Your terminal is waiting.

Why CLI Tools Beat Websites (and You Should Build More of Them)

AW — Tue, 26 May 2026 06:23:29 +0000

Every developer I know has the same bookmark folder. It's called "converters" or "tools" or "dev utilities." Inside: a timestamp converter, a JSON to YAML tool, a base64 encoder, a color picker, a byte calculator, a cron expression parser.

Fifteen browser tabs you open at least once a week. Each one has:

12 tracker scripts
A sticky newsletter popup
A "before you leave" modal
A CAPTCHA "just to make sure you're human"
Probably some data collection in the background

We're developers. We have terminals. Why do we keep doing this to ourselves?

The problem with converter websites

Let me walk through a scenario. You're debugging a production issue at 2 AM. You have a Unix timestamp from the logs: 1748226460. You need to know what time that is.

So you open Chrome. Type "timestamp converter." Click the first result (because it's 2 AM and you don't care about SEO). The page loads:

A full-screen interstitial ad for "10 Best Timestamp Tools of 2025"
You click "Skip"
A cookie consent banner slides up from the bottom
A newsletter popup slides in from the left
A "Hey, before you go!" modal prepares to ambush you when you leave
You paste your timestamp, get the result, and close the tab

That's 6 seconds of friction for a task that takes 50 milliseconds. And you do this 5-10 times a week.

The math works out to roughly 30-60 minutes per week of loading, dismissing modals, and context-switching between browser and terminal. That's 26-52 hours a year. On converter websites.

Why CLI tools win

A CLI tool does the same thing in one line:

anyconv ts 1748226460

No browser. No ads. No CAPTCHA. No context switch. The output is already in your terminal — copy it, pipe it, grep it, script it.

CLI tools win on five axes:

1. Speed

A CLI command takes ~50 milliseconds to produce output. A website takes 2-5 seconds to load, render, and become interactive. That's 40-100x faster — for the same result.

2. Composability

Websites are dead ends. You paste data in, get a result, copy it, and paste it somewhere else. A CLI tool lives in your pipeline:

curl https://api.github.com/repos/amitwaks/anyconv | anyconv json yaml | grep description

You can pipe it, redirect it, capture it, script it, chain it. A website can't do any of this.

3. Privacy

Every time you paste a config file, an API key, or a JWT token into a random website, you're trusting that site not to log it, sell it, or leak it.

CLI tools run on your machine. The data never leaves. This matters when you're converting credentials, environment variables, or internal configuration.

4. Offline

Websites require a network request. CLI tools install once and work everywhere — on a plane, in a disconnected server room, in a Docker build step that has no external network access.

5. Stability

Converter websites have a lifespan. They get acquired, go offline, redesign their UI, start requiring login, or inject ads that break the functionality. A CLI tool installed from npm works the same way forever.

Building a CLI tool: lessons from anyconv

I built anyconv — a single CLI that replaces 50+ converter websites. Here's what I learned.

Start with the pain you actually feel. I didn't survey 100 developers. I looked at my own browser history and found the 6 converter sites I visited most. Those became the first commands: JSON↔YAML, timestamps, base64, colors, byte sizes, number bases.

Design for the pipe. The best CLI tools aren't destinations — they're transforms in a pipeline. Every converter reads from stdin or a file, writes to stdout, and does nothing else. No config files, no flags, no interactive prompts.

cat data.json | anyconv json yaml | grep "name:"

The interface should be invisible. When you type anyconv color ff0000, you don't think about the interface. It's just "convert this thing to that format." No --input, --output, --from, --to flags. The command structure is just <from> <to> [input].

anyconv json yaml file.json    # clean. obvious. fast.
# not: anyconv --input file.json --from json --to yaml

Bundle size matters for CLIs too. Nobody installs a 200 MB tool to convert a color. anyconv is 5.5 kB gzipped — smaller than the hero image on most converter websites. It installs in under a second.

The bigger picture

This isn't really about converter websites. It's about a philosophy: the terminal is the best interface we have for developer tools, and most developer tools should be CLI-first.

Every time you reach for a browser-based tool, ask yourself:

Could this be a CLI command?
Could I pipe data into it instead of pasting?
Could I script this into my workflow?

If the answer is yes to any of those, it's worth building or finding a CLI tool. The hours you spend context-switching between browser and terminal add up fast.

I built anyconv because I was tired of converter websites. I released it open source because I figured other developers felt the same way. Eight hundred npm downloads later, it turns out they did.

anyconv on npm | GitHub

How to Validate Environment Variables in TypeScript (and Why You Should)

AW — Mon, 25 May 2026 08:49:05 +0000

Every developer has a story about a .env file causing a production outage. Maybe it was a missing DATABASE_URL that silently defaulted to undefined. Maybe NODE_ENV was set to staging instead of production, and staging API keys leaked into production traffic. Or perhaps a port number was accidentally typed as a string, and the server crashed with a cryptic type error.

Environment variables are the most common way to configure applications, but they have no built-in safety net. A typo, a missing value, or a misconfigured variable can reach production without a single warning — until your monitoring dashboard turns red.

In this tutorial, you'll learn how to define a schema for your environment variables, validate them automatically, generate TypeScript types from your schema, and catch configuration errors before they reach production.

The Problem: .env Files Have No Guardrails

Consider a typical .env file:

PORT=3000
DATABASE_URL=postgresql://localhost:5432/myapp
NODE_ENV=development
API_KEY=

Now consider what happens when:

PORT accidentally gets set to "abc" — your server fails to bind
NODE_ENV is set to "staging" — your production environment uses staging credentials
API_KEY is blank — third-party API calls fail with 401s
DATABASE_URL uses http:// instead of postgresql:// — the connection pool silently fails

Without validation, each of these scenarios causes a runtime failure. With validation, they're caught in CI before deployment.

Introducing Schema-Based Validation

The fix is simple: define what each variable should look like, then check your .env file against that schema before anything runs.

A schema for the variables above might look like:

{
  "vars": {
    "PORT": {
      "type": "number",
      "required": true,
      "format": "port",
      "default": 3000
    },
    "DATABASE_URL": {
      "type": "string",
      "required": true,
      "format": "url"
    },
    "NODE_ENV": {
      "type": "string",
      "enum": ["development", "production", "test"],
      "default": "development"
    },
    "API_KEY": {
      "type": "string",
      "required": true
    }
  }
}

This schema declares:

PORT must be a number, must be a valid port (1–65535), and defaults to 3000
DATABASE_URL must be a string, must be a valid URL, and is required
NODE_ENV can only be one of three values and defaults to development
API_KEY must be a string and is required

Validating Your .env File

The tool we'll use is env-haven, a zero-dependency CLI that validates .env files against a JSON schema. Install it with a single command:

npx env-haven

Save the schema above as checkmyenv.config.json in your project root. Then run:

env-haven

If all variables are valid, you'll see:

env-haven — Environment Variable Validation

  ✓ PORT = 3000
  ✓ DATABASE_URL = postgresql://localhost:5432/myapp
  ✓ NODE_ENV = development
  ✓ API_KEY = sk-abc123

PASS  4 vars — 4 passed, 0 failed

If something is wrong, you get clear error messages:

env-haven — Environment Variable Validation

  ✗ PORT = abc
    │ "PORT" must be a number (got "abc")
    │ "PORT" must be a valid port (1-65535, got "abc")
  ✗ NODE_ENV = staging
    │ "NODE_ENV" must be one of: development, production, test (got "staging")
  ✗ API_KEY = (not set)
    │ Missing required variable "API_KEY"

FAIL  4 vars — 1 passed, 3 failed

The exit code is 1 on failure, which means you can plug this into any CI pipeline:

# .github/workflows/validate-env.yml
name: Validate environment config
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx env-haven

This checks the default .env file. For staging or production, you can validate against different .env files by copying them into place before running the check.

Going Further: Generators

Typing out your schema is useful, but env-haven can do more.

Generate a .env.example

Keep your .env.example in sync with your schema automatically:

env-haven generate

This produces:

env-haven: Generated .env.example

The output file has every variable listed with its default value and a comment explaining what it's for. Required variables are marked explicitly:

# Server port
# PORT=3000
# ^^^ REQUIRED: uncomment and set this value

# PostgreSQL connection string
DATABASE_URL=

# Environment name
# NODE_ENV=development

# API authentication key
API_KEY=

Required variables are uncommented so they fail loudly if unset. Optional ones are commented out with their defaults filled in. This makes onboarding new team members trivial — they can copy .env.example to .env, uncomment the variables they need, and go.

Generate TypeScript Types

If you access environment variables through process.env, you've probably written something like this:

const port = parseInt(process.env.PORT || "3000", 10);

This works, but it's verbose, error-prone, and doesn't scale. A better approach is to define a typed interface for your environment. env-haven can generate it for you:

env-haven types

This creates an env.d.ts file:

// Auto-generated by env-haven

export interface Env {
  readonly PORT: number;
  readonly DATABASE_URL: string;
  readonly NODE_ENV: string;
  readonly API_KEY: string;
}

Now you can use it in your application:

import type { Env } from "./env";

function getEnv(): Env {
  return {
    PORT: parseInt(process.env.PORT!, 10),
    DATABASE_URL: process.env.DATABASE_URL!,
    NODE_ENV: process.env.NODE_ENV!,
    API_KEY: process.env.API_KEY!,
  };
}

Pair this with a validation step in your build, and you get compile-time confidence that your environment is correctly configured.

Schema Reference

Here's every validation rule available:

Rule	Example	What it checks
`type`	`"number"`, `"boolean"`, `"integer"`	Value has the correct JavaScript type
`required`	`true` / `false`	Value is present (unless a default is set)
`default`	`3000`	Fallback value when the variable is not set
`format`	`"url"`, `"email"`, `"port"`	Value matches an expected format
`enum`	`["dev", "prod"]`	Value is in the allow-list
`pattern`	`"^sk-"`	Value matches a regular expression
`min`	`1`	Minimum length (strings) or value (numbers)
`max`	`65535`	Maximum length (strings) or value (numbers)

Supported formats include: url, email, port, uuid, hostname, path, and regexp.

Integrating With Your Workflow

The most effective setup is three steps:

Commit your schema — checkmyenv.config.json lives in version control alongside your code
Validate in CI — run npx env-haven as a lint step in every pull request
Generate on change — run env-haven generate whenever the schema changes, and commit the updated .env.example

This creates a virtuous cycle: the schema is the source of truth, the .env.example is always accurate, and bad configuration never reaches production.

Conclusion

Environment variable validation is one of those small investments that pays for itself the first time it catches a bug. A schema takes five minutes to write, but it prevents the kind of production incidents that take hours to debug.

The tool we used, env-haven, is open source (MIT), has zero dependencies, and runs in under 100ms. Try it on your next project:

npx env-haven

Your future self — and your on-call rotation — will thank you.