Stop writing CLI validation. Parse it right the first time.

[hongminhee@hackers.pub]

I have this bad habit. When something annoys me enough times,
I end up building a library for it. This time, it was CLI validation code.

See, I spend a lot of time reading other people's code. Open source projects,
work stuff, random GitHub repos I stumble upon at 2 AM. And I kept noticing this
thing: every CLI tool has the same ugly validation code tucked away somewhere.
You know the kind:

if (!opts.server && opts.port) {
  throw new Error("--port requires --server flag");
}

if (opts.server && !opts.port) {
  opts.port = 3000; // default port
}

// wait, what if they pass --port without a value?
// what if the port is out of range?
// what if...

It's not even that this code is hard to write. It's that it's everywhere.
Every project. Every CLI tool. The same patterns, slightly different flavors.
Options that depend on other options. Flags that can't be used together.
Arguments that only make sense in certain modes.

And here's what really got me: we solved this problem years ago for other types
of data. Just… not for CLIs.

The problem with validation

There's this blog post that completely changed how I think about parsing.
It's called Parse, don't validate by Alexis King. The gist? Don't parse data
into a loose type and then check if it's valid. Parse it directly into a type
that can only be valid.

Think about it. When you get JSON from an API, you don't just parse it as any
and then write a bunch of if-statements. You use something like Zod to parse
it directly into the shape you want. Invalid data? The parser rejects it. Done.

But with CLIs? We parse arguments into some bag of properties and then spend
the next 100 lines checking if that bag makes sense. It's backwards.

So yeah, I built Optique. Not because the world desperately needed another CLI
parser (it didn't), but because I was tired of seeing—and writing—the same
validation code everywhere.

Three patterns I was sick of validating

Dependent options

This one's everywhere. You have an option that only makes sense when another
option is enabled.

The old way? Parse everything, then check:

const opts = parseArgs(process.argv);
if (!opts.server && opts.port) {
  throw new Error("--port requires --server");
}
if (opts.server && !opts.port) {
  opts.port = 3000;
}
// More validation probably lurking elsewhere...

With Optique, you just describe what you want:

const config = withDefault(
  object({
    server: flag("--server"),
    port: option("--port", integer()),
    workers: option("--workers", integer())
  }),
  { server: false }
);

Here's what TypeScript infers for config's type:

type Config = 
  | { readonly server: false }
  | { readonly server: true; readonly port: number; readonly workers: number }

The type system now understands that when server is false, port literally
doesn't exist. Not undefined, not null—it's not there. Try to access it and
TypeScript yells at you. No runtime validation needed.

Mutually exclusive options

Another classic. Pick one output format: JSON, YAML, or XML. But definitely not
two.

I used to write this mess:

if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) {
  throw new Error('Choose only one output format');
}

(Don't judge me, you've written something similar.)

Now?

const format = or(
  map(option("--json"), () => "json" as const),
  map(option("--yaml"), () => "yaml" as const),
  map(option("--xml"), () => "xml" as const)
);

The or() combinator means exactly one succeeds. The result is just
"json" | "yaml" | "xml". A single string. Not three booleans to juggle.

Environment-specific requirements

Production needs auth. Development needs debug flags. Docker needs different
options than local. You know the drill.

Instead of a validation maze, you just describe each environment:

const envConfig = or(
  object({
    env: constant("prod"),
    auth: option("--auth", string()),      // Required in prod
    ssl: option("--ssl"),
    monitoring: option("--monitoring", url())
  }),
  object({
    env: constant("dev"),
    debug: optional(option("--debug")),    // Optional in dev
    verbose: option("--verbose")
  })
);

No auth in production? Parser fails immediately. Trying to access --auth in
dev mode? TypeScript won't let you—the field doesn't exist on that type.

“But parser combinators though…”

I know, I know. “Parser combinators” sounds like something you'd need
a CS degree to understand.

Here's the thing: I don't have a CS degree. Actually, I don't have any degree.
But I've been using parser combinators for years because they're actually… not
that hard? It's just that the name makes them sound way scarier than they are.

I'd been using them for other stuff—parsing config files, DSLs, whatever.
But somehow it never clicked that you could use them for CLI parsing until
I saw Haskell's optparse-applicative. That was a real “wait, of course”
moment. Like, why are we doing this any other way?

Turns out it's stupidly simple. A parser is just a function. Combinators are
just functions that take parsers and return new parsers. That's it.

// This is a parser
const port = option("--port", integer());

// This is also a parser (made from smaller parsers)
const server = object({
  port: port,
  host: option("--host", string())
});

// Still a parser (parsers all the way down)
const config = or(server, client);

No monads. No category theory. Just functions. Boring, beautiful functions.

TypeScript does the heavy lifting

Here's the thing that still feels like cheating: I don't write types for my CLI
configs anymore. TypeScript just… figures it out.

const cli = or(
  command("deploy", object({
    action: constant("deploy"),
    environment: argument(string()),
    replicas: option("--replicas", integer())
  })),
  command("rollback", object({
    action: constant("rollback"),
    version: argument(string()),
    force: option("--force")
  }))
);

// TypeScript infers this type automatically:
type Cli = 
  | { 
      readonly action: "deploy"
      readonly environment: string
      readonly replicas: number
    }
  | { 
      readonly action: "rollback"
      readonly version: string
      readonly force: boolean
    }

TypeScript knows that if action is "deploy", then environment exists but
version doesn't. It knows replicas is a number. It knows force is
a boolean. I didn't tell it any of this.

This isn't just about nice autocomplete (though yeah, the autocomplete is great).
It's about catching bugs before they happen. Forget to handle a new option
somewhere? Code won't compile.

What actually changed for me

I've been dogfooding this for a few weeks. Some real talk:

I delete code now. Not refactor. Delete. That validation logic that used to
be 30% of my CLI code? Gone. It feels weird every time.

Refactoring isn't scary. Want to know something that usually terrifies me?
Changing how a CLI takes its arguments. Like going from --input file.txt to
just file.txt as a positional argument. With traditional parsers,
you're hunting down validation logic everywhere. With this?
You change the parser definition, TypeScript immediately shows you every place
that breaks, you fix them, done. What used to be an hour of “did I catch
everything?” is now “fix the red squiggles and move on.”

My CLIs got fancier. When adding complex option relationships doesn't mean
writing complex validation, you just… add them. Mutually exclusive groups?
Sure. Context-dependent options? Why not. The parser handles it.

The reusability is real too:

const networkOptions = object({
  host: option("--host", string()),
  port: option("--port", integer())
});

// Reuse everywhere, compose differently
const devServer = merge(networkOptions, debugOptions);
const prodServer = merge(networkOptions, authOptions);
const testServer = merge(networkOptions, mockOptions);

But honestly? The biggest change is trust. If it compiles, the CLI logic works.
Not “probably works” or “works unless someone passes weird arguments.”
It just works.

Should you care?

If you're writing a 10-line script that takes one argument, you don't need this.
process.argv[2] and call it a day.

But if you've ever:

• Had validation logic get out of sync with your actual options
• Discovered in production that certain option combinations explode
• Spent an afternoon tracking down why --verbose breaks when used with
  --json
• Written the same “option A requires option B” check for the fifth time

Then yeah, maybe you're tired of this stuff too.

Fair warning: Optique is young. I'm still figuring things out, the API might
shift a bit. But the core idea—parse, don't validate—that's solid.
And I haven't written validation code in months.

Still feels weird. Good weird.

Try it or don't

If this resonates:

• Tutorial: Build something real, see if you hate it
• Concepts: Primitives, constructs, modifiers, value parsers,
  the whole thing
• GitHub: The code, issues, angry rants

I'm not saying Optique is the answer to all CLI problems. I'm just saying
I was tired of writing the same validation code everywhere, so I built something
that makes it unnecessary.

Take it or leave it. But that validation code you're about to write?
You probably don't need it.

[badrihippo@fosstodon.org]

@hongminhee this is cool! I've never used NodeJS CLI apps, but I run into similar issues to the ones you described when using Python