Dart CLI Creator Skill

This skill provides guidelines and procedures for creating and improving top-quality Command-Line Interface (CLI) tools using Dart. As an agent, you must consistently follow these best practices when requested by the user to create or modify a Dart CLI.

🎯 Core Best Practices

1. Project Structure and Design

• bin/ directory: Place the entry point executable files for the CLI (e.g., bin/my_cli.dart). Keep this as a thin wrapper that only calls top-level functions or classes from lib/ or src/, avoiding complex logic here.
• lib/ directory: Place business logic, command implementations, and reusable utilities here (e.g., lib/src/commands/, lib/src/utils/).
• Separation of Concerns: Always separate the CLI input/output handling (argument parsing, UI rendering) from the core business logic to maximize testability.

2. Command-Line Arguments and Routing

• Leverage the args package: Use CommandRunner and Command classes from the standard args package to build a Git-like CLI with subcommands.
• Self-documenting: Carefully write description and help for each command, flag, and option, ensuring that --help provides sufficient usage information.

3. Rich UX (User Experience) and Logging

• Actively use mason_logger: Avoid standard print statements; use the mason_logger package instead.
  • Output color-coded messages with logger.info(), logger.success(), logger.err(), and logger.warn().
  • Display a spinner for time-consuming tasks using logger.progress('Doing something...').
  • Utilize logger.confirm() or logger.prompt() for user confirmations (y/n) or text input. If more advanced menu selections or spinners are needed, combine it with the interact package.
  • Tip: For a practical setup, define final logger = Logger(); at the top level in lib/logger.dart and import it across the project. This reduces boilerplate and is highly convenient (ideal for small to medium-sized CLI tools where DI is not mandatory).
• cli_completion: Consider using the cli_completion package to provide shell completion features by extending CompletionCommandRunner.

4. Proper Error Handling and Exit Strategies

• Exit Code: Always treat the result of the process as an appropriate exit code (0 for success, 1 or sysexits-compliant error codes for errors).
• Avoid direct exit() calls: Calling exit() directly causes the Dart VM to terminate immediately, potentially bypassing resource cleanup (like finally blocks). Instead, return an int from CommandRunner.run(), propagate it to the main function, set it to the exitCode property, and allow the process to exit naturally (e.g., after waiting for Process.stdout.close()).
• Custom Exception Classes and Handling: Define custom domain-specific exception classes (e.g., AppException) and throw them from deep within the call stack.
• Global Exception Catching: Wrap the entire execution of CommandRunner in a try-catch block to handle AppException, UsageException, and any uncaught exceptions. Rather than showing stack traces directly to the user, output errors gracefully using logger.err(e.message) and return an appropriate exit code.

5. Static Analysis and Code Formatting

• Apply pedantic_mono: Configure pedantic_mono in analysis_options.yaml and adhere to strict static analysis rules.
• [ZERO TOLERANCE]: Always resolve ALL errors, warnings, and info level lints immediately after making code changes. A "clean" analysis is mandatory for a project to be considered in a healthy state.

6. Distribution and Execution Configuration

• Shebang: Always include #!/usr/bin/env dart as the very first line of executable files directly under bin/.
• Pubspec Configuration: Define the CLI command name in the executables: section of pubspec.yaml to enable easy installation via dart pub global activate.

7. Auto-Update Check Feature

• Leverage pub_updater: Use pub_updater to check pub.dev or other registries for new version releases, either on every command execution or periodically.
• If a new version is available, provide an interactive UI prompting the user to update using logger.warn('Update available!') or an interact-based prompt.

8. Version Management and Release Process

• Robust Version Manipulation: When manipulating SemVer versions, avoid parsing versions manually whenever possible. Always rely on the pub_semver package (e.g., Version.parse, nextMajor, nextMinor) to prevent parsing failures related to edge cases like pre-release tags or build metadata.
• Automated Releases: To handle version bumping, CHANGELOG generation, git committing, and publishing to GitHub or pub.dev, utilize the release-pub skill. If creating an advanced Dart CLI, recommend using this agentic skill to coordinate complex CI/CD and release pipelines safely rather than instructing users to perform these steps manually.

🛠️ Project Skeleton (Basic Implementation Example)

When creating a CLI, use a structure and implementation similar to the following as a foundation.

Excerpt from pubspec.yaml

environment:
  sdk: ^3.11.0 # Always specify the latest stable version

dependencies:
  args: ^2.5.0
  cli_completion: ^0.4.0
  mason_logger: ^0.2.16
  pub_updater: ^0.4.0

dev_dependencies:
  pedantic_mono: any
  test: ^1.24.0

executables:
  my_cli:

bin/my_cli.dart

#!/usr/bin/env dart
import 'dart:io';

import 'package:my_cli/command_runner.dart';

Future<void> main(List<String> arguments) async {
  final exitCode = await MyCliCommandRunner().run(arguments);
  await flushThenExit(exitCode ?? 0);
}

/// Helper method to set the [status] to exitCode, and wait for the standard output/error to flush before exiting
Future<void> flushThenExit(int status) async {
  exitCode = status;
  await Future.wait<void>([
    stdout.close(),
    stderr.close(),
  ]);
}

lib/logger.dart

import 'package:mason_logger/mason_logger.dart';

/// The [Logger] shared across the application.
final logger = Logger();

lib/command_runner.dart

import 'package:args/args.dart';
import 'package:cli_completion/cli_completion.dart';
import 'package:mason_logger/mason_logger.dart';
import 'package:my_cli/logger.dart';
import 'package:pub_updater/pub_updater.dart';

class MyCliCommandRunner extends CompletionCommandRunner<int> {
  MyCliCommandRunner({PubUpdater? pubUpdater})
      : _pubUpdater = pubUpdater ?? PubUpdater(),
        super('my_cli', 'A highly robust Dart CLI tool.') {
    argParser
      ..addFlag(
        'version',
        abbr: 'v',
        negatable: false,
        help: 'Print the current version.',
      )
      ..addFlag(
        'verbose',
        help: 'Enable verbose logging.',
      );
    // TODO: addCommand(MyCustomCommand());
  }

  final PubUpdater _pubUpdater;

  Future<void> _checkForUpdates() async {
    try {
      final isUpToDate = await _pubUpdater.isUpToDate(
        packageName: 'my_cli',
        currentVersion: '1.0.0', // Optionally link to a packageVersion constant
      );
      if (!isUpToDate) {
        final latestVersion = await _pubUpdater.getLatestVersion('my_cli');
        logger.info('\nUpdate available: $latestVersion');
      }
    } catch (_) {}
  }

  @override
  Future<int> run(Iterable<String> args) async {
    try {
      final argResults = parse(args);
      if (argResults['verbose'] == true) {
        logger.level = Level.verbose;
      }

      // Check for version updates (consider asynchronous background execution)
      await _checkForUpdates();

      return await runCommand(argResults) ?? 0;
    } on FormatException catch (e) {
      logger
        ..err(e.message)
        ..info('')
        ..info(usage);
      return 64; // usage error
    } on UsageException catch (e) {
      logger
        ..err(e.message)
        ..info('')
        ..info(usage);
      return 64;
    } on AppException catch (e) {
      // Gracefully output custom domain exceptions
      logger.err(e.message);
      return 1;
    } catch (e, stackTrace) {
      logger
        ..err('An unexpected error occurred: $e')
        ..err('$stackTrace');
      return 1;
    }
  }

  @override
  Future<int?> runCommand(ArgResults topLevelResults) async {
    if (topLevelResults['version'] == true) {
      logger.info('my_cli version: 1.0.0');
      return 0;
    }
    return super.runCommand(topLevelResults);
  }
}

/// A custom exception specific to the domain.
class AppException implements Exception {
  const AppException(this.message);
  final String message;

  @override
  String toString() => message;
}

lib/src/commands/my_custom_command.dart

import 'package:args/command_runner.dart';
import 'package:my_cli/logger.dart';

class MyCustomCommand extends Command<int> {
  MyCustomCommand() {
    argParser.addOption(
      'name',
      abbr: 'n',
      help: 'Your name.',
      mandatory: true,
    );
  }

  @override
  String get description => 'A custom command example.';

  @override
  String get name => 'hello';

  @override
  Future<int> run() async {
    final name = argResults?['name'] as String?;
    final progress = logger.progress('Saying hello to $name...');

    // Simulate a time-consuming task
    await Future<void>.delayed(const Duration(seconds: 1));

    progress.complete('Hello, $name!');
    return 0; // Success
  }
}

🤖 Instructions for the Agent

When requested by the user to "create a CLI tool for doing X", etc.:

1. Follow the contents of this skill to structure a project centered around args and mason_logger. Always specify the latest stable Dart SDK version (where the patch version is 0, e.g., ^3.11.0) in pubspec.yaml.
2. Determine the directory structure and orchestrate/propose a set of commands based on the requirements.
3. Introduce pedantic_mono and generate high-quality code that adheres to strict static analysis.
4. (If necessary) After development is complete, document the usage instructions in README.md and present the user with installation steps, such as using dart pub global activate --source path ..