Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

dart-build-cli-app

Use when creating Dart command-line tools, parsing CLI arguments with args, handling exit codes, or managing child processes.

dhruvanbhalara · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add dhruvanbhalara/skills --skill dart-build-cli-app

About this skill


name: dart-build-cli-app description: Use when creating Dart command-line tools, parsing CLI arguments with args, handling exit codes, or managing child processes. metadata: platforms: "dart" languages: "dart" category: "development"

Building Dart CLI Applications

Contents

Project Setup & Architecture

Initialize new CLI projects using the official Dart template to ensure standard directory structures.

  • Run dart create -t cli <project_name> to scaffold a console application with basic argument parsing.
  • Place executable entry points (files containing main()) exclusively in the bin/ directory.
  • Place internal implementation logic in lib/src/ and expose public APIs via lib/<project_name>.dart.
  • Enforce formatting in CI environments by running dart format . --set-exit-if-changed. This returns exit code 1 if formatting violations exist.

Argument Parsing & Command Routing

Implement the args package to manage command-line arguments, flags, and subcommands.

  • If building a simple script: Use ArgParser directly to define flags (addFlag) and options (addOption).
  • If building a complex, multi-command CLI (like git): Implement CommandRunner and extend Command for each subcommand.
  • Define global arguments on the CommandRunner.argParser and command-specific arguments on the individual Command.argParser.
  • Catch UsageException to gracefully handle invalid arguments and display the automatically generated help text.

Execution & Error Handling

Use the io and stack_trace packages to build reliable, production-ready CLI tools.

  • Use the io package's ExitCode enum to return standard POSIX exit codes (e.g., ExitCode.success.code, ExitCode.usage.code).
  • Use sharedStdIn from the io package if multiple asynchronous listeners need sequential access to standard input.
  • Wrap the application execution in Chain.capture() from the stack_trace package to track asynchronous stack chains.
  • Format output stack traces using Trace.terse or Chain.terse to strip noisy core library frames and present readable errors to the user.

Testing CLI Applications

Use test_process and test_descriptor to write high-fidelity integration tests for your CLI.

  • Define expected filesystem states using test_descriptor (d.dir, d.file).
  • Create the mock filesystem before execution using await d.Descriptor.create().
  • Spawn the CLI process using TestProcess.start('dart', ['run', 'bin/cli.dart', ...args]).
  • Validate standard output and error streams using StreamQueue matchers (e.g., emitsThrough, emits).
  • Assert the final exit code using await process.shouldExit(0).
  • Validate resulting filesystem mutations using await d.Descriptor.validate().

Compilation & Distribution

Select the appropriate compilation target based on your distribution requirements.

  • If testing locally during development: Use dart run bin/cli.dart. This uses the JIT compiler for rapid iteration.
  • If bundling code assets and dynamic libraries: Use dart build cli. This runs build hooks and outputs to build/cli/_/bundle/.
  • If distributing a standalone native executable: Use dart compile exe bin/cli.dart -o <output_path>. This bundles the Dart runtime and machine code into a single file.
  • If distributing multiple apps with strict disk space limits: Use dart compile aot-snapshot bin/cli.dart. Run the resulting .aot file using dartaotruntime.

Dart supports cross-compiling to Linux from macOS, Windows, or Linux hosts. Use the --target-os and --target-arch flags with dart compile exe or dart compile aot-snapshot.

  • --target-os=linux (Only Linux is currently supported as a cross-compilation target)
  • --target-arch=arm64 (64-bit ARM)
  • --target-arch=x64 (x86-64)
  • --target-arch=arm (32-bit ARM)
  • --target-arch=riscv64 (64-bit RISC-V)

Example: dart compile exe --target-os=linux --target-arch=arm64 bin/cli.dart

Workflows

Task Progress: Implement a New CLI Command

  • Create a new class extending Command in lib/src/commands/.
  • Define the name and description properties.
  • Register command-specific flags in the constructor using argParser.addFlag() or argParser.addOption().
  • Implement the run() method with the core logic.
  • Register the new command in the CommandRunner instance in bin/cli.dart using addCommand().
  • Run validator -> Execute dart run bin/cli.dart help <command_name> to verify help text generation.

Task Progress: Compile and Release Native Executable

  • Run validator -> Execute dart format . --set-exit-if-changed to ensure code formatting.
  • Run validator -> Execute dart analyze to ensure no static analysis errors.
  • Run validator -> Execute dart test to pass all integration tests.
  • Compile for host OS: dart compile exe bin/cli.dart -o build/cli-host
  • Compile for Linux (if host is macOS/Windows): dart compile exe --target-os=linux --target-arch=x64 bin/cli.dart -o build/cli-linux-x64

Examples

Example: CommandRunner Implementation

import 'dart:io';
import 'package:args/command_runner.dart';
import 'package:stack_trace/stack_trace.dart';

class CommitCommand extends Command {
  @override
  final String name = 'commit';
  @override
  final String description = 'Record changes to the repository.';

  CommitCommand() {
    argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files
Read the complete source ↗