gem-hunter
Language: Dart
Build declarative and type-safe CLI apps with the help of code generation.
🚧 This package is in early preview and is subject to API changes.
Build CLI applications from plain Dart classes and functions.
| Before | After |
|---|---|
|
|
|
The ability to quickly whip up a command line script or application is a
powerful skill for a developer to have. Compared to the Dart language itself,
which offers a tremendous developer experience when building all kinds of apps,
cli-based libraries like package:args leave something to be desired when it
comes to easily building and maintaining application logic.
cli-gen aims to offer quality-of-life improvements for building and
maintaining CLI apps, by allowing you to generate command line APIs from plain
Dart functions. It achives this by providing the following features:
--help text inference from function declarations, doc comments, and default
valuescli-gen was designed to make writing CLI applications as intuitive as writing
any other Dart functions.
Add cli_annotations to your pubspec dependencies and cli_gen and
build_runner as dev dependencies.
name: dart_git description: An implementation of the git CLI in Dart. environment: sdk: ^3.0.0 dependencies: cli_annotations: ^0.1.0 dev_dependencies: build_runner: ^2.4.8 cli_gen: ^0.1.0 # define an executable name (optional) executables: dart_git: main
You can optionally define an executable name and activate it using pub global activate.
Run the build runner to generate the code for your CLI application.
$ dart run build_runner build
# or to watch for changes
$ dart run build_runner watch -dCreate a CommandRunner by annotating a class with @cliRunner and extending
the generated superclass (using the usual _$ prefix).
The generated code contains a single CommandRunner.run() method, which is the
entry point for your CLI application, to be called from the main function.
@cliRunner class GitRunner extends _$GitRunner { // ... }
Inside the CommandRunner class, create a Command by creating a method and
annotating it with @cliCommand. See the Features section for more
information on the supported types and features.
@cliRunner class GitRunner extends _$GitRunner { @cliCommand Future<void> merge({ required String branch, MergeStrategy strategy = MergeStrategy.ort, bool? commit, }) async { // ... `git merge` logic ... } }
You can create as many commands inside the CommandRunner class as you'd like:
@cliRunner class GitRunner extends _$GitRunner { @cliCommand Future<void> merge({ required String branch, MergeStrategy strategy = MergeStrategy.ort, bool? commit, }) async { /* ... */ } @cliCommand Future<void> stashPush() async { /* ... */ } @cliCommand Future<void> stashPop() async { /* ... */ } // ... }
As your application grows, you may want to separate your commands into their own groups.
To do so, create a Subcommand class by annotating the class with
@cliSubcommand and extending the generated superclass.
@cliSubcommand class StashSubcommand extends _$StashSubcommand { @cliCommand Future<void> push() async { /* ... */ } @cliCommand Future<void> pop() async { /* ... */ } }
Subcommands can then be connected to the main CommandRunner class, or to
another Subcommand class, by using the @cliMount annotation.
@cliRunner class GitRunner extends _$GitRunner { @cliMount StashSubcommand get stash => StashSubcommand(); }
Finally, create a main function that calls the run method on your
CommandRunner.
void main(List<String> arguments) async { final runner = GitRunner(); await runner.run(arguments); }
Your application is ready to go! 🎉
Run a command to test out the generated help text and see the argument parsing in action.
# activate the executable (if executable is defined in `pubspec.yaml`) $ dart pub global activate . --source=path # run the application $ dart_git merge --help
You should see the following output:
$ dart_git merge --help
Join two or more development histories together.
Usage: git-runner merge [arguments]
--branch (mandatory)
--commit
--options
Run "git-runner help" to see global options.cli-gen automatically parses incoming string arguments into the correct type,
and automatically informs your user if they've entered an invalid value.
You can define your command methods with any Dart primitive type or enum, and
cli-gen will automatically parse the incoming string arguments into the
correct type.
@cliCommand Future<void> myCustomCommand({ // Use any supported type, nullable or not Uri? outputFile, // Enums can automatically be parsed from strings MergeStrategy? strategy, // Custom types can also be used, but require passing your own // String parser to the `@Option` annotation @Option(parser: Email.fromString) Email? email, }) async { // ... }
NOTE: Types that can be automatically parsed are: String, int, double, bool, num, Uri, BigInt, and DateTime
The Collection types List, Set, and Iterable are also supported, and can
be used in combination with any of the above supported types.
@cliCommand Future<void> myCustomCommand({ List<Uri>? inputFiles, }) async { // ... }
CLI applications typically provide a --help option that displays a list of
available commands and descriptions of their parameters, to help users
understand how they can interact with the application.
Rather than manually manitaining these details yourself, cli-gen automatically
generates help text from your annotated methods, based on the method and
parameter names, doc comments, default values, and whether each parameter is
required or not.
@cliCommand Future<void> myCustomCommand({ // Required parameters will be shown to the user as `mandatory` required String requiredParam, // Optional and/or nullable parameters are not `mandatory` int? optionalParam, // Default values are also shown in the help text String defaultPath = '~/', // Use doc comments (i.e. 3 slashes) to display a description of the parameter /// A parameter that uses a doc comment String someDocumentedParameter, }) async { // ... }
The above Dart function will generate a cli command with the following help text:
$ my-custom-command --help Save your local modifications to a new stash. Usage: git stash my-custom-command [arguments] -h, --help Print this usage information. --required-param (mandatory) --optional-param --default-path (defaults to "~/") --some-documented-parameter A parameter that uses a doc comment Run "git help" to see global options.
You can also generate descriptions for your commands and the entire application by using doc comments on the annotated classes and methods.
/// A dart implementation of the git CLI. @cliRunner class GitRunner extends _$GitRunner { /// Merge two or more development histories together. @cliCommand Future<void> commit() async { // ... } }
will generate:
$ git-runner --help
A dart implementation of the git CLI.
Usage: git-runner [arguments]
-h, --help Print this usage information.
Available commands:
commit Merge two or more development histories together.
Run "git help" to see global options.Enums are unique in that they inherently define a finite set of allowable
values. cli-gen can use that information to generate a list of allowed values
in the help text.
enum Values { a, b, c }
Using the above Values enum as a parameter to a cliCommand will generate the
following help text:
--values (allowed: a, b, c)
If you ever need to override the default allowed values, you can do so by
providing a list of values to the allowed parameter of the @Option
annotation.
cli_gen can handle trailing positional parameters.
For example, you may have a command that requires a path argument. Rather than
define a named flag like git push --remote="origin", you can instead allow
users to pass the argument using git push origin.
Positional parameters can be defined using Dart's positional parameter syntax:
@cliCommand Future<void> push( String remote, // positional parameter String? branch, { // positional parameter bool force = false, // named parameter }) async { /* ... */ }
cli-gen translates Dart class, method and parameter names to kebab-case, which
is the convention for CLI commands and flags.
For example, a method named stashChanges will be translated to
stash-changes, and a parameter named outputFile will be translated to
--output-file.
To override the default behavior, simply provide a name to the respective
annotation (supported for @cliCommand, @cliSubcommand, @cliRunner, and
@Option).
cli-gen generates code that uses package:args classes and utilities to
manage command hierarchies and help text generation. The annotations included
with this package are a 1:1 mapping to similar or identical concepts included
with package:args, for example:
@cliRunner
CommandRunner classrun method that should be passed args and run from your main
functionCommandRunner.addCommand@cliCommand
Command classrun method with a call to your method or function@cliSubcommand
Command classCommand.addSubcommandExamples of generated code can be found in the example project, within their
respective .g.dart files.
Several projects were researched as references of CLI ergonomics and macro libraries, including:
cli-gen is released under the MIT License. See LICENSE for details.