CliRunner<T> class

A CommandRunner with styled help, a Logger and standard flags.

It is a drop-in replacement: rename CommandRunner to CliRunner and Command to CliCommand, and the app runs as before.

What it adds:

  • logger, shared by every CliCommand as CliCommand.logger.
  • Global flags: -v, --verbose (Level.verbose), -q, --quiet (Level.quiet), --[no-]color (--no-color turns colour off, --color turns it on even in pipes), --plain (the logger's prompts ask plain line questions, see withPlainMode), and --version when version is set. They apply while run runs and are restored after. A global flag is not added when the runner's argParser or any command's parser already defines an option with the same name (or no-color for --color); the user's option wins. An abbreviation that is already taken is left out.
  • Help in the layout of Cobra and gh, wrapped to usageLineLength: the description, Usage:, commands grouped by Command.category in aligned columns, flags with their defaults and allowed values, CliCommand.examples, and the footer. Colour follows the logger: none in pipes, with NO_COLOR, --no-color or in plain mode.
  • runAndExit, which prints errors and exits with a standard code.
  • Shell completions for bash, zsh and fish, when completions is true and the runner has a command: a completion command that prints, installs and uninstalls the script, and a hidden __complete command the script calls on each Tab. It completes commands, flags and the allowed values of options; CliCommand.completeValue adds values only the app knows. As with the global flags, a command of yours with the same name wins.
Inheritance
  • Object
  • CommandRunner<T>
  • CliRunner

Constructors

CliRunner(String executableName, String description, {String? version, Logger? logger, int? usageLineLength, int suggestionDistanceLimit = 2, bool completions = true})
usageLineLength defaults to the terminal width, or 80 without a terminal. logger defaults to a new Logger.

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
completions → bool
Whether the runner adds the completion and __complete commands.
final
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
invocation → String
A single-line template for how to invoke this executable.
no setterinherited
logger → Logger
The logger every CliCommand uses.
final
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
usageFooter → String?
An optional footer for usage.
no setterinherited
version → String?
Printed by --version as <executableName> version <version>. The flag exists only when this is set.
final

Methods

addCommand(Command<T> command) → void
Adds Command as a top-level command to this runner.
inherited
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.
override
printUsage() → void
Prints the usage information for this runner.
override
run(Iterable<String> args) → Future<T?>
Parses args, applies the global flags and runs the command, as CommandRunner.run does. Errors are thrown, not printed; see runAndExit.
override
runAndExit(Iterable<String> args) → Future<Never>
Runs args like run, then sets io.exitCode, flushes logger and its output, and exits.
runCommand(ArgResults topLevelResults) → Future<T?>
Runs the command specified by topLevelResults.
override
toString() → String
A string representation of this object.
inherited
usageException(String message) → Never
Throws a UsageException with message.
override

Operators

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