args library Core

Command-line argument parsing and command runners for Artisanal.

This library provides CommandRunner and Command which extend package:args to provide a polished CLI experience with:

• Automatic help generation with Lip Gloss styling.
• Support for subcommands and nested command structures.
• Integration with Console for verbosity-aware output.
• Custom usage formatting and command listing.
• Automatic shell tab-completion with --completion-script flag (enabled by default, opt-out available).

Command Runner

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.

Defining Commands

Commands are the building blocks of your CLI. Each command has a name, description, and an optional set of arguments and subcommands.

Override the run() method to implement the command's logic. You can access the Console via the io property for styled output.

Access parsed arguments with Laravel-style helpers:

class GreetCommand extends Command<void> {
  @override
  String get name => 'greet';

  @override
  String get description => 'Greet someone.';

  GreetCommand() {
    argParser.addOption('name', abbr: 'n', help: 'Who to greet.');
    argParser.addFlag('shout', help: 'SHOUT the greeting.');
  }

  @override
  void run() {
    final name = option('name') as String? ?? 'World';
    final shout = option('shout') as bool;
    final message = argument(0); // first positional arg
    io.success('Hello, $name!');
  }
}

See Command.option, Command.argument, Command.hasOption, Command.arguments, and Command.argumentCount.

Usage

import 'package:artisanal/args.dart';

class MyCommand extends Command {
  @override
  String get name => 'hello';
  @override
  String get description => 'Say hello';

  @override
  void run() {
    print('Hello, world!');
  }
}

void main(List<String> args) {
  final runner = CommandRunner('my-cli', 'A great CLI');
  runner.addCommand(MyCommand());
  runner.run(args);
}

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.

Commands are the building blocks of your CLI. Each command has a name, description, and an optional set of arguments and subcommands.

Override the run() method to implement the command's logic. You can access the Console via the io property for styled output.

Access parsed arguments with Laravel-style helpers:

class GreetCommand extends Command<void> {
  @override
  String get name => 'greet';

  @override
  String get description => 'Greet someone.';

  GreetCommand() {
    argParser.addOption('name', abbr: 'n', help: 'Who to greet.');
    argParser.addFlag('shout', help: 'SHOUT the greeting.');
  }

  @override
  void run() {
    final name = option('name') as String? ?? 'World';
    final shout = option('shout') as bool;
    final message = argument(0); // first positional arg
    io.success('Hello, $name!');
  }
}

See Command.option, Command.argument, Command.hasOption, Command.arguments, and Command.argumentCount.

Classes

ArgParser

A class for taking a list of raw command line arguments and parsing out options and flags from them.

ArgResults

The results of parsing a series of command line arguments using ArgParser.parse.

Command<T>

Base command class for Artisanal-style CLI commands.

CommandListingEntry

An entry in a command listing.

CommandRunner<T>

An Artisanal-inspired wrapper around package:args CommandRunner.

HelpColorScheme

Color scheme for command help output.

ShellCompleter

Bridges the completion package to an Artisanal CommandRunner.

Functions

formatCommandListing(Iterable<CommandListingEntry> entries, {required String namespaceSeparator, String styleNamespace(String text)?, String styleCommand(String text)?}) → String

Formats a list of commands for display, grouping by namespace.

indentBlock(String input, int spaces) → String

Indents each line of input by spaces spaces.

Typedefs

UnknownCommandFallback<T> = FutureOr<T> Function(List<String> args)

Callback for handling arguments that do not match any top-level command.

Exceptions / Errors

ArgParserException

An exception thrown by ArgParser.

UsageException