Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications.

Building Dart CLI Applications Contents [1. Core Architecture & Process Lifecycle]( 1 core architecture process lifecycle) [2. Streams, Diagnostics & Formatting]( 2 streams diagnostics formatting) [3. Project Configuration & Packaging]( 3 project configuration packaging) [4. Argument Parsing & Command Routing]( 4 argument parsing command routing) [5. Native Async & Modern Stack Traces]( 5 native async modern stack traces) [6. Subprocess Spawning & AOT Resilience]( 6 subprocess spawning aot resilience) [7. Signal Handling & Terminal Teardown]( 7 signal handling terminal teardown) [8. Testing CLI Applications]( 8 testing cli applications) [9. Modern Compilation & Distribution]( 9 modern compilation distribution) [10. Workflows & Audit Checklist]( 10 workflows audit checklist) [References & Examples]( references examples) 1. Core Architecture & Process Lifecycle Avoid Destructive Exits ( exit(N) ) Calling dart:io 's exit(int code) invokes Platform::Exit(code) in the C++ runtime. It immediately terminates the OS process without unwinding the Dart stack: Debugger Disconnect : When launched with pause isolates on exit , the VM Service pauses isolates before shutdown to allow IDE inspection. exit() terminates the OS process before the VM Service can pause or inspect state. Coverage Loss : package:coverage queries execution lines over VM Service RPCs during the paused on exit state. exit() destroys the process before RPC extraction, yielding 0% coverage. Buffer Truncation : stdout and stderr are buffered asynchronous IOSink streams. exit() drops unflushed bytes. Resource Leaks : finally blocks (closing locks, deleting temp directories) are bypassed. Rule : Avoid calling exit(code) directly during normal execution; set exitCode = code or return an integer exit code from CommandRunner<int (from package:args ) and allow the asynchronous main() function to return naturally. Do not call exit() on unhandled errors; throw an unhandled Error or exception so the runtime unwinds cleanly and exits with a non zero status. Standard POSIX exit codes ( /usr/include/sysexits.h ): 0 : Success ( EX OK / ExitCode.success.code ) 64 : Command line usage error ( EX USAGE / ExitCode.usage.code ) 65 : Data format error ( EX DATAERR / ExitCode.data.code ) 70 : Internal software crash ( EX SOFTWARE / ExitCode.software.code ) 78 : Configuration error ( EX CONFIG / ExitCode.config.code ) Note : Prefer importing package:io/io.dart and using ExitCode constants (e.g., ExitCode.usage.code , ExitCode.software.code ) rather than magic integer literals. For minimal standalone scripts without package dependencies, standard POSIX integer literals ( 0 , 64 , 70 ) may be used. The Thin Entrypoint Pattern ( bin/ vs. lib/src/ ) Keep bin/ .dart files strictly as minimal entrypoint trampolines (instantiate runner, pass args , await exit code). Place all command definitions, argument parsers, formatters, and business logic inside lib/src/ . Rationale : Code in bin/ cannot be cleanly imported via package: URIs. Moving logic into lib/src/ allows the entire command runner, subcommand hierarchy, and business logic to be unit tested in memory in milliseconds ( < 2ms ) without spawning OS subprocesses. 2. Output, Diagnostics & Formatting Data vs. Diagnostics : Write intended program results and machine readable data exclusively to stdout . Write warnings, error messages, and debug logs exclusively to stderr . The Error Usage Rule : When an argument parsing or mandatory option error occurs ( FormatException , UsageException , or ArgumentError thrown when accessing a missing mandatory: true option via results.option(...) ), both the error message and the usage text must write to stderr , and exit code 64 ( EX USAGE / ExitCode.usage.code ) must be returned. stdout should ONLY receive usage help when the user explicitly requests it via help or h . No print() in Error Handlers : print() routes to stdout . Use stderr.writeln() for all failure notifications. For standard output, prefer stdout.writeln() over print() to comply with the [ avoid print ](https://dart.dev/tools/linter rules/avoid print) lint rule (unless analysis options.yaml explicitly configures avoid print: false ). Terminal Capability Detection & NO COLOR : Verify stdout.hasTerminal , stdout.supportsAnsiEscapes , and !Platform.environment.containsKey('NO COLOR') before emitting ANSI color or cursor escape codes: Machine Readable Modes : When json or machine flags are passed, format data as JSON to stdout and route logs to stderr . 3. Project Configuration & Packaging Scaffolding & Pubspec Executable Mapping ( executables: ) Scaffold new command line projects using dart create t console <package name , which initializes the standard bin/ and lib/ layout. Always declare executables in pubspec.yaml under executables: to map command names to scripts in bin/ , enabling clean invocation via dart run <command (without specifying bin/...dart ) and configuring global binary symlinks for dart install : Single Source Versioning ( package:build version ) Avoid hardcoding version strings in bin/ .dart or manually synchronizing constant files. Use package:build version to generate lib/src/version.dart containing const packageVersion = 'x.y.z'; directly from pubspec.yaml during builds. Caching Conventions Store transient cache files in .dart tool/<package name / . Never write persistent cache files directly to the project root. 4. Argument Parsing & Command Routing Import package:args to manage command line arguments: Simple Scripts : Use ArgParser directly with addFlag() and addOption() . Multi Command Tools : Implement CommandRunner<int and extend Command<int for each subcommand, returning POSIX exit codes directly. Type Safe Accessors : Use results.flag('name') , results.option('name') , and results.multiOption('name') (available in package:args 2.5+) instead of map indexing operator [] to eliminate manual type casts ( as bool , as String? ). Complex Options Models : For applications with extensive flags, use package:build cli to generate strongly typed options classes. Leverage named default overrides (e.g. {String? hostDefaultOverride} ) to cleanly merge configuration files with CLI flags. 5. Native Async & Modern Stack Traces Avoid Chain.capture() : The Dart VM natively preserves asynchronous stack frames across await suspension points. Chain.capture wraps the event loop in custom Zones, incurring substantial allocation overhead and trapping errors across Zone boundaries. Sanitize with Trace.from(st).terse : Use static utilities from package:stack trace on uncaught errors without capturing zones: 6. Subprocess Spawning & AOT Resilience When spawning Dart SDK subprocesses or executing other Dart tools (e.g., dart format , dart test , build runner ): Do not assume Platform.resolvedExecutable or Platform.executable points to the dart command line executable : In standalone AOT compiled binaries ( dart install / dart compile exe ), resolvedExecutable points to the compiled application binary itself, causing recursive self invocation loops or flag rejection crashes. Use package:cli util : Resolve the Dart SDK executable using cli util.dartExecutable or cli util.sdkPath instead of writing custom PATH or directory scrapers. See version requirements and detailed technical guide in [references/aot sdk discovery.md](references/aot sdk discovery.md). 7. Signal Handling & Terminal Teardown If your CLI alters terminal modes, displays spinners, or opens listening sockets: Windows Signal Guard : On Windows, ProcessSignal.sigterm.watch() throws UnsupportedError . Guard sigterm with if (!Platform.isWindows) . Echo & Line Mode Teardown : If setting stdin.echoMode = false or stdin.lineMode = false , check if (!stdin.hasTerminal) return; first, and install a SIGINT listener and finally block to restore them so user keystrokes remain visible after exit. Cursor Visibility : If emitting ANSI hide cursor ( \x1B[?25l ), always restore cursor visibility ( \x1B[?25h ) on exit or cancellation. Socket Cleanup : Explicitly close listening HttpServer or ServerSocket instances ( server.close(force: true) ) on termination signals to immediately release OS ports. See detailed patterns in [references/signals and terminal.md](references/signals and terminal.md). 8. Testing CLI Applications Structure testing across two distinct layers: 1. Unit Tests (In Memory, < 5ms ) : Test command classes, option parsing, and business logic directly by importing package:<pkg /src/... in test/ . 2. Integration Tests (Subprocesses) : Use package:test process and package:test descriptor to verify end to end binary execution, process I/O streaming, and OS exit codes: 9. Modern Compilation & Distribution Dart 3.12+ standardizes CLI distribution around dart run and dart install (moving away from dart pub global activate ): Ephemeral Execution (JIT) : dart run <package @<version [args] downloads and runs the CLI on demand. Global Installation (Native AOT) : dart install <package compiles the package entrypoint to a fast native standalone binary in ~/.dart/install/bin/ . Local Development : Use dart run <command (resolves via executables: in pubspec.yaml ) or dart run bin/cli.dart . Bundling Dynamic Libraries & Code Assets : Use dart build cli . Outputs bundle to build/cli/ /bundle/ . Standalone Executable Compilation : Use dart compile exe bin/cli.dart o <output path . 10. Workflows & Audit Checklist Implementation Workflow [ ] Declare entry points in pubspec.yaml under executables: . [ ] Keep bin/ .dart as a thin entrypoint; place command logic in lib/src/ . [ ] Return integer exit codes or set exitCode = N ; avoid raw exit(N) . [ ] Direct errors, warnings, and usage on parse failure to stderr . [ ] Use results.flag() , results.option() , and results.multiOption() for type safety. [ ] Validate useAnsi (checking stdout.hasTerminal , supportsAnsiEscapes , and NO COLOR ) before emitting ANSI codes. [ ] Spawn child tools using cli util.dartExecutable , never Platform.resolvedExecutable . [ ] Unit test command runners in memory; test end to end binary execution with test process . References & Examples Single Command Tool Template : [examples/single command tool.dart](examples/single command tool.dart) Multi Command Runner Template : [examples/multi command runner.dart](examples/multi command runner.dart) AOT SDK Discovery & Subprocess Spawning : [references/aot sdk discovery.md](references/aot sdk discovery.md) Signal Handling & Terminal Teardown : [references/signals and terminal.md](references/signals and terminal.md)

dart-build-cli-app