CommandRunner<T> class Core

An Artisanal-inspired wrapper around package:args CommandRunner.

Provides a polished CLI experience with:

Grouped namespaced commands (e.g., ui:*, db:*) in help output
Sectioned command help (Description, Usage, Options)
Friendly error handling without stack traces
Global flags for verbosity, ANSI, and interactivity

The CommandRunner orchestrates the execution of commands and subcommands. It handles argument parsing, help generation, and error reporting.

Artisanal's runner is fully integrated with the Style system, providing beautiful, readable help output by default.

final runner = CommandRunner(
  CommandRunner.detectExecutableName(),
  'My application',
)
  ..addCommand(ServeCommand())
  ..addCommand(DbMigrateCommand());

await runner.run(args);

Inheritance

Object
CommandRunner<T>
CommandRunner

Implementers

HarnessCommandsMixin

Constructors

CommandRunner(String executableName, String description, {String namespaceSeparator = ':', int usageExitCode = 64, bool enableShellCompletion = true, bool? ansi, Renderer? renderer, Write? out, Write? err, WriteRaw? outRaw, WriteRaw? errRaw, ReadLine? readLine, ExitCodeSetter? setExitCode, int? usageLineLength, HelpColorScheme? helpColorScheme, UnknownCommandFallback<T>? unknownCommandFallback}): Creates a new command runner.

Properties

argParser → ArgParser: The top-level argument parser.
no setterinherited
commands → Map<String, Command<T>>: An unmodifiable view of all top-level commands defined for this runner.
no setterinherited
description → String: A short description of this executable.
finalinherited
enableShellCompletion → bool: Whether automatic shell tab-completion is enabled.
final
executableName → String: The name of the executable being run.
finalinherited
hashCode → int: The hash code for this object.
no setterinherited
helpColorScheme → HelpColorScheme: The color scheme used for help output.
final
interactive → bool: Whether interactive prompts are enabled.
no setter
invocation → String: A single-line template for how to invoke this executable.
no setterinherited
io → Console: The I/O helper for console output.
no setter
namespaceSeparator → String: Separator used to group commands into namespaces.
final
renderer → Renderer: The renderer for output.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
shellCompleter → ShellCompleter: The shell completion helper for this runner.
no setter
shellCompletionScript → String: A generated shell completion script for this executable.
no setter
suggestionDistanceLimit → int: The maximum edit distance allowed when suggesting possible intended commands.
finalinherited
unknownCommandFallback → UnknownCommandFallback<T>?: Optional handler for unknown top-level commands.
final
usage → String: Generates a string displaying usage information for the executable.
no setteroverride
usageExitCode → int: Exit code set when a UsageException occurs.
final
usageFooter → String?: An optional footer for usage.
no setterinherited
verbosity → Verbosity: The current verbosity level.
no setter

Methods

addCommand(Command<T> command) → void: Adds Command as a top-level command to this runner.
inherited
allCommandsInNamespace(String namespace) → Map<String, Command<T>>: Returns all commands whose full name starts with namespace followed by namespaceSeparator.
formatGlobalUsage({bool includeDescription = true}) → String: Formats global usage, grouping commands by namespace.
getNamespaces() → List<String>: Returns all unique namespace prefixes from registered commands.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
parse(Iterable<String> args) → ArgResults: Parses args and returns the result, converting an ArgParserException to a UsageException.
inherited
printUsage() → void: Prints the usage information for this runner.
override
run(Iterable<String> args) → Future<T?>: Parses args and invokes Command.run on the chosen command.
override
runCommand(ArgResults topLevelResults) → Future<T?>: Runs the command specified by topLevelResults.
inherited
toString() → String: A string representation of this object.
inherited
usageException(String message) → Never: Throws a UsageException with message.
override
writeErr(String line) → void: Writes a line to stderr.
writeOut(String line) → void: Writes a line to stdout.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

detectExecutableName() → String: Auto-detects the executable name from Platform.script.