Single Command Tool

1// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
2// for details. All rights reserved. Use of this source code is governed by a
3// BSD-style license that can be found in the LICENSE file.
4
5/// Example template for a single-command Dart CLI script or utility.
6///
7/// Demonstrates argument parsing with `ArgParser`, standard I/O stream routing,
8/// and non-destructive exit code assignment via `exitCode`.
9library;
10
11import 'dart:io';
12
13import 'package:args/args.dart';
14import 'package:io/io.dart' show ExitCode;
15import 'package:stack_trace/stack_trace.dart';
16
17Future<void> main(List<String> args) async {
18  final parser = ArgParser()
19    ..addFlag(
20      'help',
21      abbr: 'h',
22      negatable: false,
23      help: 'Show usage information.',
24    )
25    ..addFlag(
26      'verbose',
27      abbr: 'v',
28      negatable: false,
29      help: 'Show detailed stack traces on fatal error.',
30    )
31    ..addOption(
32      'input',
33      abbr: 'i',
34      mandatory: true,
35      help: 'Path to the input file to process.',
36    );
37
38  try {
39    final results = parser.parse(args);
40
41    if (results.flag('help')) {
42      // Explicit help requested by user: write usage to stdout.
43      stdout
44        ..writeln('Usage: tool [options]')
45        ..writeln(parser.usage);
46      return;
47    }
48
49    await _runTool(results);
50  } on FormatException catch (e) {
51    // Argument parse error: write error message AND usage to stderr.
52    stderr
53      ..writeln('Error: ${e.message}')
54      ..writeln(parser.usage);
55    exitCode = ExitCode.usage.code;
56  } on ArgumentError catch (e) {
57    // Missing mandatory option error thrown by results.option():
58    stderr
59      ..writeln('Error: ${e.message}')
60      ..writeln(parser.usage);
61    exitCode = ExitCode.usage.code;
62  } catch (e, st) {
63    stderr.writeln('Fatal error: $e');
64    if (args.contains('-v') || args.contains('--verbose')) {
65      stderr.writeln(Trace.from(st).terse);
66    }
67    exitCode = ExitCode.software.code;
68  }
69}
70
71/// Encapsulates the tool's core business logic.
72///
73/// In larger applications, place this logic in `lib/src/` rather than
74/// directly in `bin/` so unit tests can import and test functions directly
75/// without needing to spawn an OS subprocess.
76Future<void> _runTool(ArgResults args) async {
77  final inputPath = args.option('input')!;
78  stdout.writeln('Processing $inputPath...');
79}