Optique: Type-safe combinatorial CLI parser for TypeScript

nvm it looks like Claude wrote half the code here….

And the way you’re meant to do booleans feels a little weird but separately this doesn’t work, it results in an error because Optique thinks the option is required

const options = O.object({ watch: O.option("--watch") });
const result = O.run(options, { args: process.argv.slice(2) });

gives

Usage: foo.mts [[--watch]]
Error: Expected an option or argument, but got end of input.

what’s funny is that adding a separate option does fix the issue and --watch is correctly optional.

I love writing tiny CLIs in TypeScript, so I’m glad to see new stuff in this space. I genuinely think TypeScript is one of the best scripting languages available right now: it’s concise, nearly everyone knows a bit of it, it has a great type system, and Deno and Bun have usable stdlibs and let you run single-file scripts that embed their dependencies in the same file (like uv run with inline deps has done for python). My secret weapon for scripting is dax, which lets you run shell commands like this:

const result = await $`echo 1`.text();
console.log(result); // 1

While it’s early, Optique directly addresses a problem I’ve been having with CLI parsing in TypeScript, namely sharing common sets of arguments between commands in a typesafe way. I’ve been using Cliffy, which I like a lot (commander is also good) but I don’t know if there’s really a first class way to share set of arguments. You can make a function that takes a command and adds arguments to it, but I’m not sure the typing works out when you do that.

One possible downside with Optique is that it only handles the parsing part, so once your args are parsed, you still have to do some kind of pattern match on the result to actually call what you want to call. That’s fine, but it feels duplicative of the structure you’ve already set out in the parser definition. By contrast, the commander-style builders let you stick the function for executing a command right in alongside the arguments.

Here are some of my small TS CLIs in case anyone is curious what they look like:

• llm-cli, a tiny CLI LLM client with replies, history, post to github gist, etc
• aipr, a PR review tool wrapping llm-cli that takes a repo and PR number and spits out a review
• dq, like jq but you pass it JS code to eval (blog post about it). This one uses the built-in Deno parseArgs because it’s simple (they really should build something like Cliffy into the std lib).
• jprc, a tool that creates a PR and uses llm-cli to generate a branch name (see Overengineering PR create with jj)

This looks nice. 99,9% of my code is python and I dream about ArgumentParser.parse_args() returning something that type checkers understand. I am not the only one but it does not seem like an easy problem to solve unfortunately.

How can it be type-safe if the host language isnt?