Piero Bosio Social Web Site Personale

Exciting news for #Fedify developers! We've just landed a major milestone for Fedify 2.0—the #CLI now runs natively on #Node.js and #Bun, not just #Deno (#456). If you install @fedify/cli@2.0.0-dev.1761 from npm, you'll get actual JavaScript that executes directly in your runtime, no more pre-compiled binaries from deno compile. This is part of our broader transition to Optique, a new cross-runtime CLI framework we've developed specifically for Fedify's needs (#374). This change means a more natural development experience regardless of your #JavaScript runtime preference. Node.js developers can now run the CLI tools directly through their familiar ecosystem, and the same goes for Bun users. While Fedify 2.0 isn't released yet, we're excited to share this progress with the community—feel free to try out the dev version and let us know how it works for you!

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: Update to Optique 0.6.0 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.

We're pleased to announce the release of Optique 0.5.0, which brings significant improvements to error handling, help text generation, and overall developer experience. This release maintains full backward compatibility, so you can upgrade without modifying existing code. Better code organization through module separation The large @optique/core/parser module has been refactored into three focused modules that better reflect their purposes. Primitive parsers like option() and argument() now live in @optique/core/primitives, modifier functions such as optional() and withDefault() have moved to @optique/core/modifiers, and combinator functions including object() and or() are now in @optique/core/constructs. // Before: everything from one module import { option, flag, argument, // primitives optional, withDefault, multiple, // modifiers object, or, merge // constructs } from "@optique/core/parser"; // After: organized imports (recommended) import { option, flag, argument } from "@optique/core/primitives"; import { optional, withDefault, multiple } from "@optique/core/modifiers"; import { object, or, merge } from "@optique/core/constructs"; While we recommend importing from these specialized modules for better clarity, all functions continue to be re-exported from the original @optique/core/parser module to ensure your existing code works unchanged. This reorganization makes the codebase more maintainable and helps developers understand the relationships between different parser types. Smarter error handling with automatic conversion One of the most requested features has been better error handling for default value callbacks in withDefault(). Previously, if your callback threw an error—say, when an environment variable wasn't set—that error would bubble up as a runtime exception. Starting with 0.5.0, these errors are automatically caught and converted to parser-level errors, providing consistent error formatting and proper exit codes. // Before (0.4.x): runtime exception that crashes the app const parser = object({ apiUrl: withDefault(option("--url", url()), () => { if (!process.env.API_URL) { throw new Error("API_URL not set"); // Uncaught exception! } return new URL(process.env.API_URL); }) }); // After (0.5.0): graceful parser error const parser = object({ apiUrl: withDefault(option("--url", url()), () => { if (!process.env.API_URL) { throw new Error("API_URL not set"); // Automatically caught and formatted } return new URL(process.env.API_URL); }) }); We've also introduced the WithDefaultError class, which accepts structured messages instead of plain strings. This means you can now throw errors with rich formatting that matches the rest of Optique's error output: import { WithDefaultError, message, envVar } from "@optique/core"; const parser = object({ // Plain error - automatically converted to text databaseUrl: withDefault(option("--db", url()), () => { if (!process.env.DATABASE_URL) { throw new Error("Database URL not configured"); } return new URL(process.env.DATABASE_URL); }), // Rich error with structured message apiToken: withDefault(option("--token", string()), () => { if (!process.env.API_TOKEN) { throw new WithDefaultError( message`Environment variable ${envVar("API_TOKEN")} is required for authentication` ); } return process.env.API_TOKEN; }) }); The new envVar message component ensures environment variables are visually distinct in error messages, appearing bold and underlined in colored output or wrapped in backticks in plain text. More helpful help text with custom default descriptions Default values in help text can sometimes be misleading, especially when they come from environment variables or are computed at runtime. Optique 0.5.0 allows you to customize how default values appear in help output through an optional third parameter to withDefault(). import { withDefault, message, envVar } from "@optique/core"; const parser = object({ // Before: shows actual URL value in help apiUrl: withDefault( option("--api-url", url()), new URL("https://api.example.com") ), // Help shows: --api-url URL [https://api.example.com] // After: shows descriptive text apiUrl: withDefault( option("--api-url", url()), new URL("https://api.example.com"), { message: message`Default API endpoint` } ), // Help shows: --api-url URL [Default API endpoint] }); This is particularly useful for environment variables and computed defaults: const parser = object({ // Environment variable authToken: withDefault( option("--token", string()), () => process.env.AUTH_TOKEN || "anonymous", { message: message`${envVar("AUTH_TOKEN")} or anonymous` } ), // Help shows: --token STRING [AUTH_TOKEN or anonymous] // Computed value workers: withDefault( option("--workers", integer()), () => os.cpus().length, { message: message`Number of CPU cores` } ), // Help shows: --workers INT [Number of CPU cores] // Sensitive information apiKey: withDefault( option("--api-key", string()), () => process.env.SECRET_KEY || "", { message: message`From secure storage` } ), // Help shows: --api-key STRING [From secure storage] }); Instead of displaying the actual default value, you can now show descriptive text that better explains where the value comes from. This is particularly useful for sensitive information like API tokens or for computed defaults like the number of CPU cores. The help system now properly handles ANSI color codes in default value displays, maintaining dim styling even when inner components have their own color formatting. This ensures default values remain visually distinct from the main help text. Comprehensive error message customization We've added a systematic way to customize error messages across all parser types and combinators. Every parser now accepts an errors option that lets you provide context-specific feedback instead of generic error messages. This applies to primitive parsers, value parsers, combinators, and even specialized parsers in companion packages. Primitive parser errors import { option, flag, argument, command } from "@optique/core/primitives"; import { message, optionName, metavar } from "@optique/core/message"; // Option parser with custom errors const serverPort = option("--port", integer(), { errors: { missing: message`Server port is required. Use ${optionName("--port")} to specify.`, invalidValue: (error) => message`Invalid port number: ${error}`, endOfInput: message`${optionName("--port")} requires a ${metavar("PORT")} number.` } }); // Command parser with custom errors const deployCommand = command("deploy", deployParser, { errors: { notMatched: (expected, actual) => message`Unknown command "${actual}". Did you mean "${expected}"?` } }); Value parser errors Error customization can be static messages for consistent errors or dynamic functions that incorporate the problematic input: import { integer, choice, string } from "@optique/core/valueparser"; // Integer with range validation const port = integer({ min: 1024, max: 65535, errors: { invalidInteger: message`Port must be a valid number.`, belowMinimum: (value, min) => message`Port ${String(value)} is reserved. Use ${String(min)} or higher.`, aboveMaximum: (value, max) => message`Port ${String(value)} exceeds maximum. Use ${String(max)} or lower.` } }); // Choice with helpful suggestions const logLevel = choice(["debug", "info", "warn", "error"], { errors: { invalidChoice: (input, choices) => message`"${input}" is not a valid log level. Choose from: ${values(choices)}.` } }); // String with pattern validation const email = string({ pattern: /^[^@]+@[^@]+\.[^@]+$/, errors: { patternMismatch: (input) => message`"${input}" is not a valid email address. Use format: user@example.com` } }); Combinator errors import { or, multiple, object } from "@optique/core/constructs"; // Or combinator with custom no-match error const format = or( flag("--json"), flag("--yaml"), flag("--xml"), { errors: { noMatch: message`Please specify an output format: --json, --yaml, or --xml.`, unexpectedInput: (token) => message`Unknown format option "${token}".` } } ); // Multiple parser with count validation const inputFiles = multiple(argument(string()), { min: 1, max: 5, errors: { tooFew: (count, min) => message`At least ${String(min)} file required, but got ${String(count)}.`, tooMany: (count, max) => message`Maximum ${String(max)} files allowed, but got ${String(count)}.` } }); Package-specific errors Both @optique/run and @optique/temporal packages have been updated with error customization support for their specialized parsers: // @optique/run path parser import { path } from "@optique/run/valueparser"; const configFile = option("--config", path({ mustExist: true, type: "file", extensions: [".json", ".yaml"], errors: { pathNotFound: (input) => message`Configuration file "${input}" not found. Please check the path.`, notAFile: (input) => message`"${input}" is a directory. Please specify a file.`, invalidExtension: (input, extensions, actual) => message`Invalid config format "${actual}". Use ${values(extensions)}.` } })); // @optique/temporal instant parser import { instant, duration } from "@optique/temporal"; const timestamp = option("--time", instant({ errors: { invalidFormat: (input) => message`"${input}" is not a valid timestamp. Use ISO 8601 format: 2024-01-01T12:00:00Z` } })); const timeout = option("--timeout", duration({ errors: { invalidFormat: (input) => message`"${input}" is not a valid duration. Use ISO 8601 format: PT30S (30 seconds), PT5M (5 minutes)` } })); Error customization integrates seamlessly with Optique's structured message format, ensuring consistent styling across all error output. The system helps you provide helpful, actionable feedback that guides users toward correct usage rather than leaving them confused by generic error messages. Looking forward This release focuses on improving the developer experience without breaking existing code. Every new feature is opt-in, and all changes maintain backward compatibility. We believe these improvements make Optique more pleasant to work with, especially when building user-friendly CLI applications that need clear error messages and helpful documentation. We're grateful to the community members who suggested these improvements and helped shape this release through discussions and issue reports. Your feedback continues to drive Optique's evolution toward being a more capable and ergonomic CLI parser for TypeScript. To upgrade to Optique 0.5.0, simply update your dependencies: npm update @optique/core @optique/run # or deno update For detailed migration guidance and API documentation, please refer to the official documentation. While no code changes are required, we encourage you to explore the new error customization options and help text improvements to enhance your CLI applications.

@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

@shollyethan oooh thank you for the heads-up Ethan! 🙏I’m not close to being ready yet (I need a few more months)… but good to hear there’s a v6.1 already 😅