Setting Up a Dart CLI Project
Scaffold a new command-line project with dart create -t console my_tool, which generates a bin/my_tool.dart entry point, a pubspec.yaml, and a lib/ directory for shared logic; the convention is to keep bin/my_tool.dart thin, just parsing arguments and calling into lib/src/, so the core logic stays testable independent of the CLI shell. Once written, dart run bin/my_tool.dart --flag executes it via the Dart VM for fast iteration, while dart compile exe bin/my_tool.dart -o my_tool produces a standalone native executable with no Dart SDK dependency for distribution.
Cricket analogy: Scaffolding with dart create is like a franchise setting up its academy structure before a season starts, nets here, fitness there, so once matches begin every process already has its place.
Parsing Arguments with the args Package
The args package's ArgParser lets you declare flags (addFlag('verbose', abbr: 'v', negatable: false)), options that take a value (addOption('output', abbr: 'o', defaultsTo: 'build')), and even nested subcommands via addCommand(), mirroring how tools like git or flutter structure commands such as git commit -m or flutter build apk. Calling parser.parse(arguments) returns an ArgResults object where results['verbose'] or results['output'] give typed access to what the user passed, and results.rest captures any positional arguments left over after flags are consumed.
Cricket analogy: ArgParser's addFlag and addOption are like a match official's toss form with checkboxes for won toss and chose to bat, alongside a free-text field for ground name, structured input instead of parsing a rambling paragraph.
import 'package:args/args.dart';
void main(List<String> arguments) {
final parser = ArgParser()
..addFlag('verbose', abbr: 'v', negatable: false, help: 'Show detailed output')
..addOption('output', abbr: 'o', defaultsTo: 'build', help: 'Output directory');
final results = parser.parse(arguments);
final isVerbose = results['verbose'] as bool;
final outputDir = results['output'] as String;
if (isVerbose) {
print('Verbose mode enabled. Writing to $outputDir');
}
for (final file in results.rest) {
print('Processing $file -> $outputDir');
}
}Reading Input and Producing Output
For interactive prompts, stdin.readLineSync() blocks and reads a line of user input as a String? (null at end-of-stream), which pairs naturally with a loop to validate input and re-prompt on bad entries; use stdout.write() for output without a trailing newline (useful for prompts like Enter name: ) versus print(), which always appends one. Exit codes matter for shell scripting and CI pipelines: call exit(0) for success or a non-zero code like exit(64) for a usage error, from dart:io, so tools that pipe your CLI's output can detect failure via the shell's exit status.
Cricket analogy: stdin.readLineSync() blocking for input is like an umpire waiting for the third umpire's decision before play can resume, nothing continues until that signal is explicitly given.
Compiling and Distributing Your Tool
To make a CLI installable globally, declare an executables: section in pubspec.yaml mapping a command name to your bin/ script, then users run dart pub global activate my_tool (from pub.dev) or dart pub global activate --source path . (locally) to add it to their PATH via ~/.pub-cache/bin. For production distribution without requiring users to have the Dart SDK installed, dart compile exe produces a self-contained native binary per platform that you can attach to a GitHub release; note that AOT-compiled executables are platform- and architecture-specific, so a binary built on macOS ARM64 won't run on Linux x64.
Cricket analogy: Declaring executables in pubspec.yaml is like registering a player's name officially with the league before they're allowed to appear on any team sheet, a required step before activation.
Popular building blocks for CLI tools beyond args include package:cli_util for locating cache directories, package:io for ANSI-colored terminal output and progress indicators, and package:interact for interactive prompts and spinners — check pub.dev before hand-rolling any of these.
If you forget to declare your script under executables: in pubspec.yaml, dart pub global activate will still succeed but no command will be added to the user's PATH, silently leaving the tool unreachable from the shell.
- Scaffold with dart create -t console, keeping bin/ thin and lib/src/ holding the testable core logic.
- Use dart run for fast development iteration and dart compile exe to produce a standalone native binary.
- The args package's ArgParser handles flags, options with defaults, and nested subcommands via addCommand().
- stdin.readLineSync() reads interactive input; stdout.write() prints without a trailing newline for prompts.
- Use meaningful exit codes (0 for success, non-zero like 64 for usage errors) so shell scripts and CI can detect failure.
- Declare an executables: section in pubspec.yaml so dart pub global activate adds your command to the user's PATH.
- Compiled binaries from dart compile exe are platform- and architecture-specific and must be built separately per target.
Practice what you learned
1. What command scaffolds a new Dart console application?
2. In the args package, what does ArgResults.rest contain?
3. Why might dart compile exe -o my_tool built on macOS ARM64 fail to run on a Linux x64 machine?
4. What must be declared in pubspec.yaml for dart pub global activate to add a command to the user's PATH?
5. What's the idiomatic way to read a line of interactive user input in a Dart CLI?
Was this page helpful?
You May Also Like
Dart Best Practices
A working guide to idiomatic Dart: naming, null safety, collections, async patterns, and tooling that keeps a Dart codebase clean and fast.
Dart Quick Reference
A condensed cheat sheet covering Dart variables, types, control flow, collections, and null-safety operators for fast lookup.
Dart Interview Questions
The core Dart concepts interviewers actually probe — null safety, async programming, OOP/mixins, and Flutter-adjacent performance details.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics