loading . . . Stop writing CLI validation. Parse it right the first time. 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. https://hackers.pub/@hongminhee/2025/stop-writing-cli-validation-parse-it-right-the-first-time
