Dart CLI Application Best Practices

1. When to use this skill

Use this skill when:

• 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/ )

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:

• Add #!/usr/bin/env dart to the first line.

• 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.

Example:

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

Use these community-standard packages owned by the Dart team to solve common CLI problems:

Category Recommended Package Usage

Stack Traces package:stack_trace

detailed, cleaner stack traces

Arg Parsing package:args

standard flag/option parsing

Testing package:test_process

integration testing for CLI apps

Testing package:test_descriptor

file system fixtures for tests

Networking package:http

standard HTTP client (remember user-agent!)

ANSI Output package:io

handling ANSI colors and styles

4. Interesting community packages

Category Recommended Package Usage

Configuration package:json_serializable

strongly typed config objects

CLI Generation package:build_cli

generate arg parsers from classes

Version Info package:build_version

automatic version injection

Configuration package:checked_yaml

precise YAML parsing with line numbers

5. 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.