Optique CLI Parser Patterns

Start at https://optique.dev/llms.txt online; these rules also work offline.

Core rules

• Use run() from @optique/run for apps, parse()/runParser() to embed.
• With runParser(), onError(exitCode, error) supplies a structured Message; help.onShow(exitCode, page) supplies the final DocPage. Both follow output. Supply stdout: () => {} for custom help rendering. See https://optique.dev/concepts/runners.md#structured-help-callbacks.
• In tests, use parseArgs()/parseArgsSync() from @optique/testing/parser for parser results, captureRun() from @optique/testing/run for runner output/exits, captureProgramRun() from @optique/testing/discover for dispatch, and createCliRunner() from @optique/testing/cli for real CLIs. Pin colors/maxWidth in tests; defaults use terminal and environment.
• Compose parsers with object(), tuple(), seq(), or(), merge(), and modifiers. Do not hand-write argument scanners around Optique parsers.
• For command/option help headings, set the runner's helpSections: { commands: "Commands", options: "Options" }. It groups untitled entries only on pages with visible commands. See https://optique.dev/cookbook.md#command-and-option-headings-in-help.
• Let TypeScript infer results unless another API needs a separate interface.
• Parsers usually require input. optional(p) yields undefined; use withDefault(p, value) or withDefault(flag("-v"), false) for fallbacks.
• Use semantic message helpers; keep canonical errors unthemed. Since 1.3.0, theme/messageFormatter should preserve initialWidth, quoting, and width options. flag() has static/callback errors.unexpectedValue since 1.4.0. Mismatch callbacks may be skipped; avoid side effects.
• Use value parsers such as integer(), choice(), biject(), regExp(), url(), origin(), and uuid() instead of validating raw strings after parsing. Use regExp({ flags }) for user-supplied sources, biject() for one-to-one mappings, transform() for mapped results, and choice(values, { key }) for custom string matching that returns the declared spelling. Use normalizeInput() for raw-string cleanup and path() from @optique/run/valueparser for file-system paths. Write a custom value parser only when these tools do not cover the domain.
• Since 1.4.0, -p8080/-vp8080 accept attached values. Values consume the literal suffix (-p=5 gives "=5"); full single-dash names win.
• Async value parsers like @optique/git make containing parsers async. Await run()/parse()/runParser() or, for bindKeyring(), runAsync().
• Use dependency() when one value parser controls another's valid values. For a multi-level chain, wrap the middle derivation too: dependency(source.deriveSync(...)). Optique resolves such chains by dependency order, independently of object/tuple field order.
• Use derivePromptConfig(source, resolver) (from @optique/prompt, re-exported by @optique/inquirer and @optique/clack) when a prompt's choices or message depend on another parsed value. The resolver may be async and runs only at the real prompt fallback, after the named sources resolve; pass [sourceA, sourceB] when it reads several sources. The resolver's prompt kind must return the wrapped parser's value type. Derive the wrapped parser separately when the CLI domain should change, and make it a dependency source only if another consumer needs its answer. Pass a lone resolver for fetched choices, forwarding its signal to the fetch.
• Pass { validate, maxAttempts, signal } as a generated prompt wrapper's third argument, including prompt() from @optique/inquirer and @optique/clack. The validator returns undefined to accept the prompted value or a structured Message to retry, synchronously or asynchronously. Attempt limits must be positive integers and default to unlimited retries. Selection prompts keep their config and use the shared validate option.
• Implement a custom adapter's execute(config, context) so retries can show context.previousValidationMessage, and forward context.signal when the prompt library supports aborting active work. Adapter-native validation remains separate and completes inside one shared attempt.
• Build subcommands with command() combined by or(); add a literal field such as command: constant("serve") per branch for a discriminated union. Show hidden aliases in help with showAliases on command() or runner.
• Use run(parser, { completion: "both" }) for completion, or the object form with completion.errors for custom shell errors. Do not hand-write scripts.
• Use usageLine: [{ type: "ellipsis" }] in runner options when a large root synopsis should become a compact Usage: myapp ... line. This applies only to root full help; use command()'s usageLine for subcommand help.
• Use showUsage: false in runner options when full help should show the brief and command or option sections without the Usage: synopsis. For deeply nested command trees, add commandList: "top-level" when root help should list only first-level command groups.
• Use termWidth: "auto" in runner options when descriptions should align after the widest visible help term. Optique measures terminal display width after adding built-in help/version/completion entries.

Canonical app shape

import { object } from "@optique/core/constructs";
import { message } from "@optique/core/message";
import { withDefault } from "@optique/core/modifiers";
import { argument, flag, option } from "@optique/core/primitives";
import { integer, string } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = object({
  input: argument(string({ metavar: "FILE" }), {
    description: message`Input file to process.`,
  }),
  port: withDefault(
    option("--port", integer({ min: 1, max: 65535 }), {
      description: message`Port to listen on.`,
    }),
    3000,
  ),
  verbose: withDefault(
    flag("-v", "--verbose", { description: message`Enable verbose logging.` }),
    false,
  ),
});

const config = run(parser, {
  brief: message`Process a file.`,
  completion: "both",
  showDefault: true,
  termWidth: "auto",
});

console.log(`Processing ${config.input} on port ${config.port}.`);