Multi Command Runner

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 production multi-command Dart CLI application.
6///
7/// Demonstrates structured subcommands using `CommandRunner<int>`, standard POSIX
8/// exit code constants from `package:io`, and proper `stderr` usage formatting.
9library;
10
11import 'dart:io';
12
13import 'package:args/args.dart';
14import 'package:args/command_runner.dart';
15import 'package:io/io.dart' show ExitCode;
16import 'package:stack_trace/stack_trace.dart';
17
18Future<void> main(List<String> args) async {
19  final runner = ToolCommandRunner();
20
21  try {
22    final status = await runner.run(args);
23    exitCode = status ?? ExitCode.success.code;
24  } on UsageException catch (e) {
25    // Usage errors (invalid flags/arguments) must write to stderr.
26    stderr
27      ..writeln(e.message)
28      ..writeln(e.usage);
29    exitCode = ExitCode.usage.code;
30  } catch (e, st) {
31    stderr.writeln('Fatal error: $e');
32    if (args.contains('-v') || args.contains('--verbose')) {
33      stderr.writeln(Trace.from(st).terse);
34    }
35    exitCode = ExitCode.software.code;
36  }
37}
38
39class ToolCommandRunner extends CommandRunner<int> {
40  ToolCommandRunner() : super('tool', 'Multi-command production CLI utility.') {
41    argParser
42      ..addFlag(
43        'verbose',
44        abbr: 'v',
45        negatable: false,
46        help: 'Show verbose stack traces on failure.',
47      )
48      ..addFlag('version', negatable: false, help: 'Print tool version.');
49
50    addCommand(ProcessCommand());
51  }
52
53  @override
54  Future<int?> runCommand(ArgResults topLevelResults) async {
55    if (topLevelResults.flag('version')) {
56      // In production, reference packageVersion from generated lib/src/version.dart (via package:build_version).
57      stdout.writeln('tool version 1.0.0');
58      return ExitCode.success.code;
59    }
60    return super.runCommand(topLevelResults);
61  }
62}
63
64class ProcessCommand extends Command<int> {
65  @override
66  final String name = 'process';
67
68  @override
69  final String description = 'Process input files.';
70
71  ProcessCommand() {
72    argParser.addOption(
73      'input',
74      abbr: 'i',
75      mandatory: true,
76      help: 'Path to input file.',
77    );
78  }
79
80  @override
81  Future<int> run() async {
82    final input = argResults!.option('input')!;
83    stdout.writeln('Processing $input...');
84    return ExitCode.success.code;
85  }
86}