dart-cli-app-best-practices

Dart CLI Application Best Practices

1. Best Practices

Entrypoint Structure (bin/)

Keep the contents of your entrypoint file (e.g., bin/my_app.dart) minimal. This improves testability by decoupling logic from the process runner.

DO:

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

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

DON'T:

• Put complex logic directly in bin/my_app.dart.
• Define classes or heavy functions in the entrypoint.

Executable Scripts

For CLI tools intended to be run directly on Linux and Mac, add a shebang and ensure the file is executable.

DO:

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)

Properly handle process termination to allow for debugging and correct status reporting.

DO:

• 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;
  }
}

AVOID:

• Calling exit(code) directly, as it terminates the VM immediately, preventing "pause on exit" debugging and finally blocks from running.

Exception Handling

Uncaught exceptions automatically set a non-zero exit code, but you should handle expected errors gracefully.

[!IMPORTANT] Always write error messages, crash reports, and stack traces to stderr (using stderr.writeln()) rather than stdout (using print()). Writing errors to stdout is a CLI anti-pattern that pollutes shell pipes, making it difficult for users to chain commands and filter successful output.

Example:

import 'dart:io';

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