cliweave library

A typed CLI framework: command routing, argument scanning, rendered help, structured exit codes, and shell-completion proposals.

Build commands with buildCommand, group them with buildRouteMap, assemble an Application with buildApplication, and dispatch with run.

The terminal logger, spinner, and colour theme live in a separate library (package:cliweave/terminal.dart) so that consumers who only need argument parsing do not pull them in.

This is a Dart implementation of the model introduced by Bloomberg's TypeScript @stricli/core. It is an independent project and is not affiliated with or endorsed by Bloomberg.

Classes

Application<C extends CommandContext>

A typed runnable application.

ApplicationConfiguration

Application configuration.

ApplicationContext

Minimal context suitable for applications that do not need custom state.

ApplicationFlag<C extends CommandContext>

An application-level flag installed by an integration.

ApplicationFlagArguments<C extends CommandContext>

Arguments passed to an integration application flag.

ApplicationHookArguments

Arguments passed to application lifecycle hooks.

BooleanFlag

Factories for boolean flags.

CliIntegration<C extends CommandContext>

A named application integration.

Command<C extends CommandContext>

A typed command.

CommandContext

A command-specific context.

CommandHookArguments<C extends CommandContext>

Arguments passed to command lifecycle hooks.

CommandInfo

Route information supplied while constructing a command context.

CommandParameters<F, A, C extends CommandContext>

Typed parameter schema for one command.

CompletionConfiguration

Input completion configuration (all fields optional, like TS).

CompletionScripts

Generates shell completion scripts for a command-line application.

CounterFlag

Factories for counter flags.

CurrentVersionNotLatestArguments

Arguments for currentVersionIsNotLatest.

DistanceOptions

Damerau-Levenshtein options used for did-you-mean suggestions.

DistanceWeights

Damerau-Levenshtein weights (distanceOptions.weights).

DocumentationConfiguration

Input documentation configuration (all fields optional, like TS).

EnumFlag

Factories for a finite set of CLI choices.

ExitCode

Mirror of stricli's ExitCode const object.

FlagBinding<T, C extends CommandContext>

Typed flag declaration.

FlagSet<T, C extends CommandContext>

A typed decoder for all flags of a command.

InputCompletion

A single completion proposal; kind mirrors the TS literal union (routing-target:command, routing-target:route-map, argument:flag, argument:value).

IntegrationValidationArguments<C extends CommandContext>

Build-time validation arguments for an integration.

LifecycleHooks<C extends CommandContext>

Ordered lifecycle callbacks for an integration.

LocalizationConfiguration

Localization configuration; dotweave supplies defaultLocale + loadText.

NoArgs

Marker returned by a command with no positional arguments.

NoCommandRegisteredArguments

Arguments for noCommandRegisteredForInput.

NoFlags

Marker returned by a command with no flags.

NoTextAvailableArguments

Arguments for noTextAvailableForLocale.

ParsedFlag

Factories for parser-backed flags.

Positional

Factories for positional parameters.

PositionalBinding<T, C extends CommandContext>

Typed positional declaration.

PositionalSet<T, C extends CommandContext>

A typed decoder for positional inputs.

RouteMap<C extends CommandContext>

A typed route map.

RouteScanResult<C extends CommandContext>

Immutable route selection supplied to integrations.

RoutingTarget<C extends CommandContext>

A typed node in a command routing tree.

RunContext<C extends CommandContext>

Runtime context source used by run, runApplication, and completion.

ScannerConfiguration

Input scanner configuration (all fields optional, like TS).

StdioWriteStream

Adapts a dart:io io.Stdout to WriteStream, emitting the same ANSI sequences Node's clearLine/cursorTo write.

TextBriefs

Briefs for the built-in flags.

TextHeaders

Section headers used by help rendering.

TextKeywords

Keywords used by help rendering (default =, separator =).

VersionInformation

Version information used by the default version integration.

WriteStream

The slice of an output stream a CLI needs: write text, know whether it is attached to a terminal, and move the cursor for in-place updates.

Enums

DisplayCaseStyle

stricli display case styles ("original" | "convert-camel-to-kebab").

ScannerCaseStyle

stricli scanner case styles ("original" | "allow-kebab-for-camel").

VersionCheckHook

Lifecycle point used by the version update check.

Constants

defaultDistanceOptions → const DistanceOptions

stricli's default distance options (dist index.js:1469).

Properties

textEn → ApplicationText

Mirror of stricli text_en (dist index.js:1068).

final

Functions

booleanParser<C extends CommandContext>(C context, String input) → bool

Context-aware strict boolean parser.

buildApplication<C extends CommandContext>(RoutingTarget<C> root, ApplicationConfiguration configuration, {List<CliIntegration<C>>? integrations}) → Application<C>

Builds an application.

buildCommand<C extends CommandContext, F, A>({required CommandDocs docs, required CommandParameters<F, A, C> parameters, required CommandFunction<C, F, A> func}) → Command<C>

Builds an eager command.

buildLazyCommand<C extends CommandContext, F, A>({required CommandDocs docs, required CommandParameters<F, A, C> parameters, required CommandLoader<C, F, A> loader}) → Command<C>

Builds a lazy command while preserving its input types.

buildRouteMap<C extends CommandContext>({required RouteMapDocs docs, required Map<String, RoutingTarget<C>> routes, String? defaultCommand, Map<String, String> aliases = const {}}) → RouteMap<C>

Builds a typed route map.

filterClosestAlternatives(String target, List<String> alternatives, DistanceOptions options) → List<String>

Mirror of filterClosestAlternatives: alternatives within the distance threshold, restricted to the minimum distance, sorted for stable output.

formatMessageForArgumentScannerError(ArgumentScannerError error, Map<String, String Function(ArgumentScannerError error)> formatter) → String

Mirror of formatMessageForArgumentScannerError; the formatter map is keyed by the error class name (matching TS constructor.name).

helpIntegration<C extends CommandContext>({String name = 'help', String? alias = 'h', String brief = 'Show help for this command', bool hidden = false, bool includeHidden = false, bool defaultForRouteMap = true, bool complete = true, DocumentationConfiguration? formatting}) → CliIntegration<C>

Creates the standard help integration.

joinWithGrammar(List<String> parts, {required String conjunction, required bool serialComma}) → String

Mirror of joinWithGrammar for conjunctive lists.

lookupPlatformEnv(String name) → String?

Default EnvLookup over Platform.environment.

looseBooleanParser<C extends CommandContext>(C context, String input) → bool

Context-aware loose boolean parser.

numberParser<C extends CommandContext>(C context, String input) → num

Context-aware numeric parser.

proposeCompletions<C extends CommandContext>(Application<C> app, List<String> inputs, RunContext<C> context) → Future<List<InputCompletion>>

Computes completion proposals.

run<C extends CommandContext>(Application<C> app, List<String> inputs, RunContext<C> context) → Future<void>

Runs an application and assigns its process exit code.

runApplication<C extends CommandContext>(Application<C> app, List<String> inputs, RunContext<C> context) → Future<int>

Runs an application and returns its intended exit code.

stringParser<C extends CommandContext>(C context, String input) → String

Context-aware identity parser.

versionIntegration<C extends CommandContext>({required VersionInformation info, String name = 'version', String? alias = 'v', String brief = 'Show the current version', bool hidden = false, bool complete = true, VersionCheckHook hook = VersionCheckHook.appStart, LifecycleHooks<C> hooks = const LifecycleHooks()}) → CliIntegration<C>

Creates the standard version flag and optional latest-version hook.

Typedefs

AnsiColorByStream = AnsiColorByStream

ANSI color support calculated independently for each process stream.

ApplicationText = ApplicationText

Localized application text and error formatters.

CommandContextBuilder<C extends CommandContext> = FutureOr<C> Function(CommandInfo info)

Builds context for one command invocation.

CommandDocs = CommandDocs

Documentation attached to a command.

CommandFunction<C extends CommandContext, F, A> = FutureOr<void> Function(C context, F flags, A args)

A command action with closed input types.

CommandLoader<C extends CommandContext, F, A> = FutureOr<CommandFunction<C, F, A>> Function()

Lazily loads a typed command action.

EnvLookup = String? Function(String name)

Reads an environment variable, returning null when it is not set.

InputParser<T, C extends CommandContext> = FutureOr<T> Function(C context, String input)

Parses one CLI input with access to the command context.

ResolvedApplicationConfiguration = ResolvedApplicationConfiguration

Resolved application configuration.

RouteMapDocs = RouteMapDocs

Documentation attached to a route map.

RunProcess = RunProcess

Process abstraction used by command contexts.

ValueCompletion<C extends CommandContext> = FutureOr<List<String>> Function(C context, String partial)

Proposes values with access to the command context.

Exceptions / Errors

AliasNotFoundError

No alias registered for -….

ArgumentParseError

Failed to parse "…" for …: ….

ArgumentScannerError

Base class for all argument-scanner errors.

EnumValidationError

Expected "…" to be one of (…).

FlagNotFoundError

No flag registered for --….

InvalidNegatedFlagSyntaxError

Cannot negate flag --… and pass "…" as value.

RouterInternalError

Error thrown for invalid router configuration, mirroring stricli's InternalError (src/util/error.ts).

UnexpectedFlagError

Too many arguments for --…, encountered "…" after "…".

UnexpectedPositionalError

Too many arguments, expected … but encountered "…".

UnsatisfiedFlagError

Expected input for flag --….

UnsatisfiedPositionalError

Expected argument for … / Expected at least … argument(s) for ….