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('myapp', 'My application')
  ..addCommand(ServeCommand())
  ..addCommand(DbMigrateCommand());

await runner.run(args);
Inheritance
  • Object
  • CommandRunner<T>
  • CommandRunner

Constructors

CommandRunner(String executableName, String description, {String namespaceSeparator = ':', int usageExitCode = 64, bool? ansi, Renderer? renderer, Write? out, Write? err, WriteRaw? outRaw, WriteRaw? errRaw, ReadLine? readLine, ExitCodeSetter? setExitCode, int? usageLineLength})
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
executableName → String
The name of the executable being run.
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
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
suggestionDistanceLimit → int
The maximum edit distance allowed when suggesting possible intended commands.
finalinherited
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
formatGlobalUsage({bool includeDescription = true}) → String
Formats global usage, grouping commands by namespace.
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> arguments) → 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