dart-build-cli-app

Name: dart-build-cli-app
Author: flutter

2.7kstars159forks

How to install dart-build-cli-app?

flutter/agent-plugins/dart-build-cli-app

$npx -y skills add flutter/agent-plugins --skill dart-build-cli-app

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Building Dart CLI Applications
2
3	## Contents
4	- [Project Setup & Architecture](#project-setup--architecture)
5	- [Argument Parsing & Command Routing](#argument-parsing--command-routing)
6	- [Execution & Error Handling](#execution--error-handling)
7	- [Testing CLI Applications](#testing-cli-applications)
8	- [Compilation & Distribution](#compilation--distribution)
9	- [Workflows](#workflows)
10	- [Examples](#examples)
11
12	## Project Setup & Architecture
13
14	Initialize new CLI projects using the official Dart template to ensure standard directory structures.
15
16	* Run `dart create -t cli <project_name>` to scaffold a console application with basic argument parsing.
17	* Place executable entry points (files containing `main()`) exclusively in the `bin/` directory.
18	* Place internal implementation logic in `lib/src/` and expose public APIs via `lib/<project_name>.dart`.
19	* Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist.
20
21	## Argument Parsing & Command Routing
22
23	Import the `args` package to manage command-line arguments, flags, and subcommands.
24
25	* If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`).
26	* If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand.
27	* Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`.
28	* Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text.
29	* Validate Help Text Accuracy: Ensure the help text provides all necessary information to run the tool. If the help text references a compiled executable name, and the user needs to add it to their PATH to run it that way, provide clear instructions on how to do so in the help text or description.
30
31	## Execution & Error Handling
32
33	Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools.
34
35	* Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`).
36	* Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input.
37	* Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains.
38	* Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user.
39	* Do not swallow exceptions in lower-level logic or storage classes unless recovery is possible. Let them bubble up or rethrow them so higher-level commands know operations failed.
40	* Fail fast and with non-zero exit codes: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes (e.g., using `exit(1)` or triggering a 64 exit code after a caught `UsageException`).
41
42	## Testing CLI Applications
43
44	> [!IMPORTANT]
45	> All new commands and significant features must be covered by automated tests. Manual verification is not sufficient for testing logic. However, manual verification of help text and user experience (UX) is still required to ensure the interface is intuitive and correct.
46
47	Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI.
48
49	* Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`).
50	* Create the mock filesystem before execution using `await d.Descriptor.create()`.
51	* Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`.
52	* Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`).
53	* Assert the final exit code using `await process.shouldExit(0)`.
54	* Validate resulting filesystem mutations using `await d.Descriptor.validate()`.
55
56	## Compilation & Distribution
57
58	Select the appropriate compilation target based on your distribution requirements.
59
60	* If testing locally during development: Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration.
61	* If bundling code assets and dynamic libraries: Use `dart build cli`. This runs build hooks and outputs to `build/cli/_/bundle/`.
62	* 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.
63	* If distributing multiple apps with strict disk space limits: Use `dart compile aot-snapshot bin/cli.dart`. Run the resulting `.aot` file using `dartaotruntime`.
64
65	<details>
66	<summary>Cross-Compilation Targets (Linux Only)</sum

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

dart-build-cli-app

2.7kstars159forks

View on GitHub

How to install dart-build-cli-app?

flutter/agent-plugins/dart-build-cli-app

$npx -y skills add flutter/agent-plugins --skill dart-build-cli-app

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Building Dart CLI Applications
2
3	## Contents
4	- [Project Setup & Architecture](#project-setup--architecture)
5	- [Argument Parsing & Command Routing](#argument-parsing--command-routing)
6	- [Execution & Error Handling](#execution--error-handling)
7	- [Testing CLI Applications](#testing-cli-applications)
8	- [Compilation & Distribution](#compilation--distribution)
9	- [Workflows](#workflows)
10	- [Examples](#examples)
11
12	## Project Setup & Architecture
13
14	Initialize new CLI projects using the official Dart template to ensure standard directory structures.
15
16	* Run `dart create -t cli <project_name>` to scaffold a console application with basic argument parsing.
17	* Place executable entry points (files containing `main()`) exclusively in the `bin/` directory.
18	* Place internal implementation logic in `lib/src/` and expose public APIs via `lib/<project_name>.dart`.
19	* Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist.
20
21	## Argument Parsing & Command Routing
22
23	Import the `args` package to manage command-line arguments, flags, and subcommands.
24
25	* If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`).
26	* If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand.
27	* Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`.
28	* Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text.
29	* Validate Help Text Accuracy: Ensure the help text provides all necessary information to run the tool. If the help text references a compiled executable name, and the user needs to add it to their PATH to run it that way, provide clear instructions on how to do so in the help text or description.
30
31	## Execution & Error Handling
32
33	Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools.
34
35	* Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`).
36	* Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input.
37	* Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains.
38	* Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user.
39	* Do not swallow exceptions in lower-level logic or storage classes unless recovery is possible. Let them bubble up or rethrow them so higher-level commands know operations failed.
40	* Fail fast and with non-zero exit codes: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes (e.g., using `exit(1)` or triggering a 64 exit code after a caught `UsageException`).
41
42	## Testing CLI Applications
43
44	> [!IMPORTANT]
45	> All new commands and significant features must be covered by automated tests. Manual verification is not sufficient for testing logic. However, manual verification of help text and user experience (UX) is still required to ensure the interface is intuitive and correct.
46
47	Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI.
48
49	* Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`).
50	* Create the mock filesystem before execution using `await d.Descriptor.create()`.
51	* Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`.
52	* Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`).
53	* Assert the final exit code using `await process.shouldExit(0)`.
54	* Validate resulting filesystem mutations using `await d.Descriptor.validate()`.
55
56	## Compilation & Distribution
57
58	Select the appropriate compilation target based on your distribution requirements.
59
60	* If testing locally during development: Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration.
61	* If bundling code assets and dynamic libraries: Use `dart build cli`. This runs build hooks and outputs to `build/cli/_/bundle/`.
62	* 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.
63	* If distributing multiple apps with strict disk space limits: Use `dart compile aot-snapshot bin/cli.dart`. Run the resulting `.aot` file using `dartaotruntime`.
64
65	<details>
66	<summary>Cross-Compilation Targets (Linux Only)</sum

People who liked this also viewed

6 picks

Type