Dart CLI Application Best Practices

1. When to use this skill

• Creating a new Dart CLI application.
• Refactoring an existing CLI entrypoint (

  bin/

  ).
• Reviewing CLI code for quality and standards.
• Setting up executable scripts for Linux/Mac.

2. Best Practices

Entrypoint Structure (

bin/

)

bin/my_app.dart

// bin/my_app.dart
import 'package:my_app/src/entry_point.dart';

Future<void> main(List<String> arguments) async {
  await runApp(arguments);
}

• Put complex logic directly in

  bin/my_app.dart

  .
• Define classes or heavy functions in the entrypoint.

Executable Scripts

1. Add

   #!/usr/bin/env dart

   to the first line.
2. Run

   chmod +x bin/my_script.dart

   to make it executable.

#!/usr/bin/env dart

void main() => print('Ready to run!');

Process Termination (

exitCode

)

• Use the

  exitCode

  setter to report failure.
• Allow

  main

  to complete naturally.
• Use standard exit codes (sysexits) for clarity (e.g.,

  64

  for bad usage,

  78

  for configuration errors).
  • See

    package:io

    ExitCode

    class or FreeBSD sysexits man page.

import 'dart:io';

void main() {
  if (someFailure) {
    exitCode = 64; // DO!
    return;
  }
}

• Calling

  exit(code)

  directly, as it terminates the VM immediately, preventing "pause on exit" debugging and

  finally

  blocks from running.

Exception Handling

Future<void> main(List<String> arguments) async {
  try {
    await runApp(arguments);
  } catch (e, stack) {
    print('App crashed!');
    print(e);
    print(stack);
    exitCode = 1; // Explicitly fail
  }
}

3. Recommended Packages

package:stack_trace

package:build_version

package:args

package:build_cli

package:checked_yaml

package:json_serializable

package:test_process

package:test_descriptor

package:http

4. Conventions

• File Caching: Write cached files to

  .dart_tool/[pkg_name]/

  .
• User-Agent: Always set a User-Agent header in HTTP requests, including version info.
• ANSI Output: Use

  package:io

  for handling ANSI colors and styles.