Optique 0.6.0: Shell completion support for type-safe CLI parsers

[hongminhee@hackers.pub]

Optique 0.6.0 is here, bringing intelligent shell completion to your type-safe
command-line applications. This release introduces built-in completion support
for Bash, zsh, fish, PowerShell, and Nushell, making your CLIs more
discoverable and user-friendly—all without sacrificing type safety or requiring
duplicate definitions.

For those new to [Optique]: it's a TypeScript CLI parser library that takes
a fundamentally different approach from traditional configuration-based parsers.
Instead of describing your CLI with configuration objects, you compose parsers
from small, type-safe functions. TypeScript automatically infers the exact
types of your parsed data, ensuring compile-time safety while the parser
structure itself provides runtime validation. Think of it as bringing the
composability of parser combinators (inspired by Haskell's
optparse-applicative) together with the type safety of TypeScript's type
system.

Shell completion that just works

The standout feature of this release is comprehensive shell completion support.
Unlike many CLI frameworks that require separate completion definitions,
Optique's completion system leverages the same parser structure used for
argument parsing. This means your completion suggestions automatically stay
synchronized with your CLI's actual behavior—no duplicate definitions, no
manual maintenance.

import { object } from "@optique/core/constructs";
import { argument, option } from "@optique/core/primitives";
import { string, choice } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = object({
  format: option("-f", "--format", choice(["json", "yaml", "xml"])),
  output: option("-o", "--output", string({ metavar: "FILE" })),
  verbose: option("-v", "--verbose"),
  input: argument(string({ metavar: "INPUT" })),
});

// Enable completion with a single option
const config = run(parser, { completion: "both" });

Users can now press Tab to get intelligent suggestions:

myapp <TAB>                    # Shows available commands and options
myapp --format <TAB>           # Shows: json, yaml, xml
myapp --format=<TAB>           # Same suggestions with equals syntax
myapp -<TAB>                  # Shows: -f, -o, -v, and other short options

Setting up completion is straightforward. Users generate a completion script
for their shell and source it:

# Bash
myapp completion bash > ~/.bashrc.d/myapp.bash
source ~/.bashrc.d/myapp.bash

# zsh
myapp completion zsh > ~/.zsh/completions/_myapp

# fish
myapp completion fish > ~/.config/fish/completions/myapp.fish

# PowerShell
myapp completion pwsh > myapp-completion.ps1
. ./myapp-completion.ps1

# Nushell
myapp completion nu | save myapp-completion.nu
source myapp-completion.nu

The completion system works automatically with all Optique parser types. When
you use choice() value parsers, the available options become completion
suggestions. When you use path() parsers, file system completion kicks in
with proper handling of extensions and file types. Subcommands, options, and
arguments all provide context-aware suggestions.

What makes Optique's completion special is that it leverages the same parser
structure used for argument parsing. Every parser has an optional suggest()
method that provides context-aware suggestions based on the current input.
Parser combinators like object() and or() automatically aggregate
suggestions from their constituent parsers, ensuring your completion logic
stays in your TypeScript code where it benefits from type safety and testing.

Optique handles the differences between shells transparently. Bash uses the
complete command with proper handling of word splitting, zsh leverages its
powerful compdef system with completion descriptions, fish provides
tab-separated format with automatic file type detection, PowerShell uses
Register-ArgumentCompleter with AST-based parsing, and Nushell integrates
with its external completer system. For file and directory completions, Optique
delegates to each shell's native file completion system, ensuring proper
handling of spaces, symlinks, and platform-specific path conventions.

Custom completion suggestions

For domain-specific value parsers, you can implement custom completion logic
that provides intelligent suggestions based on your application's needs:

import type { ValueParser, ValueParserResult } from "@optique/core/valueparser";
import type { Suggestion } from "@optique/core/parser";
import { message } from "@optique/core/message";

function httpMethod(): ValueParser<string> {
  const methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];

  return {
    metavar: "METHOD",
    parse(input: string): ValueParserResult<string> {
      const method = input.toUpperCase();
      if (methods.includes(method)) {
        return { success: true, value: method };
      }
      return {
        success: false,
        error: message`Invalid HTTP method: ${input}. Valid methods: ${methods.join(", ")}.`,
      };
    },
    format(value: string): string {
      return value;
    },
    *suggest(prefix: string): Iterable<Suggestion> {
      for (const method of methods) {
        if (method.toLowerCase().startsWith(prefix.toLowerCase())) {
          yield {
            kind: "literal",
            text: method,
            description: message`HTTP ${method} request method`
          };
        }
      }
    },
  };
}

The built-in value parsers also provide intelligent suggestions. For instance,
the locale() parser suggests common locale identifiers, the url() parser
offers protocol completions when configured with allowedProtocols, and the
timezone parsers from @optique/temporal use Intl.supportedValuesOf() for
dynamic timezone suggestions.

Enhanced command documentation

This release also introduces new documentation capabilities for the command()
parser. You can now provide separate brief and description texts, along
with a footer for examples and additional information:

import { command, object, constant } from "@optique/core/primitives";
import { message } from "@optique/core/message";

const deployCommand = command(
  "deploy",
  object({
    action: constant("deploy"),
    // ... options
  }),
  {
    brief: message`Deploy application to production`,  // Shown in command list
    description: message`Deploy the application to the production environment.
    
This command handles database migrations, asset compilation, and cache warming
automatically. It performs health checks before switching traffic to ensure
zero-downtime deployment.`,  // Shown in detailed help
    footer: message`Examples:
  myapp deploy --environment staging --dry-run
  myapp deploy --environment production --force

For deployment documentation, see: https://docs.example.com/deploy`
  }
);

The brief text appears when listing commands (like myapp help), while
description provides detailed information when viewing command-specific help
(myapp deploy --help or myapp help deploy). The footer appears at the
bottom of the help text, perfect for examples and additional resources.

Command-line example formatting

To make help text and examples clearer, we've added a new commandLine()
message term type. This displays command-line snippets with distinct cyan
coloring in terminals, making it immediately clear what users should type:

import { message, commandLine } from "@optique/core/message";
import { run } from "@optique/run";

const config = run(parser, {
  footer: message`Examples:
  ${commandLine("myapp --format json input.txt")}
  ${commandLine("myapp --format=yaml --output result.yml data.txt")}
  
To enable shell completion:
  ${commandLine("myapp completion bash > ~/.bashrc.d/myapp.bash")}
  ${commandLine("source ~/.bashrc.d/myapp.bash")}`,
  
  completion: "both"
});

These command examples stand out visually in help text, making it easier for
users to understand how to use your CLI.

Migration guide

If you're already using Optique, adding completion support is straightforward:

1. Update to Optique 0.6.0
2. Add the completion option to your run() configuration:

// Before
const config = run(parser, { help: "both" });

// After
const config = run(parser, { 
  help: "both",
  completion: "both"  // Adds both 'completion' command and '--completion' option
});

That's it! Your CLI now supports shell completion. The completion option
accepts three modes:

• "command": Only the completion subcommand (e.g., myapp completion bash)
• "option": Only the --completion option (e.g., myapp --completion bash)
• "both": Both patterns work

For custom value parsers, you can optionally add a suggest() method to
provide domain-specific completions. Existing parsers continue to work without
modification—they just won't provide custom suggestions beyond what the parser
structure implies.

Looking forward

Shell completion has been one of the most requested features for Optique, and
we're thrilled to deliver it in a way that maintains our core principles: type
safety, composability, and zero duplication. Your parser definitions remain
the single source of truth for both parsing and completion behavior.

This release represents a significant step toward making Optique-based CLIs as
user-friendly as they are developer-friendly. The completion system proves that
we can provide sophisticated runtime features without sacrificing the
compile-time guarantees that make Optique unique.

We hope you find the new shell completion feature useful and look forward to
seeing what you build with it!

Getting started

To start using Optique 0.6.0:

deno add --jsr @optique/core@^0.6.0 @optique/run@^0.6.0
npm  add       @optique/core@^0.6.0 @optique/run@^0.6.0
pnpm add       @optique/core@^0.6.0 @optique/run@^0.6.0
yarn add       @optique/core@^0.6.0 @optique/run@^0.6.0
bun  add       @optique/core@^0.6.0 @optique/run@^0.6.0

For complete documentation, visit optique.dev. Check out the new
shell completion guide for detailed setup instructions and advanced usage
patterns.

For bug reports and feature requests, please visit our GitHub repository.