Dartle Documentation

Dartle CLI

Dartle is mostly meant to be used as a CLI (Command-Line Interface) Application.

Users are expected to run commands on a terminal (or use other tools to do it) to drive a build.

In this page, features of the Dartle CLI are explained in detail.

Informational Options

Use -h, or --help to show usage:

➜  dartle-website git:(dartle-1.0) ✗ dartle --help
Dartle 1.0.0

https://github.com/renatoathaydes/dartle

Usage: dartle [<options>] [<tasks>]

Runs a Dartle build.
Tasks are declared in the dartle.dart file. If no task is given, the
default tasks are run.

Options:
-l, --log-level              Set the log level.
                             [trace, debug, info (default), warn, error, profile]
-c, --[no-]color             Use ANSI colors to colorize output.
                             (defaults to on)
-f, --force-tasks            Force all selected tasks to run.
-p, --[no-]parallel-tasks    Allow tasks to run in parallel using Isolates.
                             (defaults to on)
-s, --show-tasks             Show all tasks in this build. Does not run any tasks when enabled.
-g, --show-task-graph        Show the task graph for this build. Does not run any tasks when enabled.
-z, --reset-cache            Reset the Dartle cache.
-v, --version                Show the Dartle version.
-h, --help                   Show this help message.
-d, --disable-cache          Whether to disable the Dartle cache.

When the informational options are used, i.e. --help, --show-tasks and --show-task-graph, no build tasks are run.

To see what tasks are available in a build, on a directory containing a dartle.dart script, use the -s flag:

➜  dartle-website git:(dartle-1.0) ✗ dartle -s
======== Showing build information only, no tasks will be executed ========

Tasks declared in this build:

==> Setup Phase:
  * clean
==> Build Phase:
  * downloadMagnanimous [up-to-date]
      Download Magnanimous
  * runMagnanimous [default] [up-to-date]
      Builds the Dartle Website using Magnanimous
==> TearDown Phase:
  No tasks in this phase.

The following tasks were selected to run, in order:

  downloadMagnanimous
      runMagnanimous

The output depends on the build script, as that’s what defines the tasks in a build. In the above case, we’re using the Dartle Website’s own Dartle script.

At the end of the output above, you can see the tasks that would’ve executed if the -s flag hadn’t been given.

Tasks further to the right are executed after tasks to the left. In the output above, that means downloadMagnanimous runs first, and then runMagnanimous runs once it completes.

Task may also be executed in parallel, in which case they are shown at the same level.

For example:

  taskA
  taskB
      taskC
          taskD
          taskE

This would mean that taskA and taskB execute simultaneously (using different Dart Isolates by default) at first, then once they complete, taskC executes, and finally taskD and taskE execute in parallel.

The -g option shows a task graph, which makes it easy to understand the tasks’ dependencies:

➜  dartle-website git:(dartle-1.0) ✗ dartle -g
======== Showing build information only, no tasks will be executed ========

Tasks Graph:

- clean
- downloadMagnanimous
- runMagnanimous
  \--- downloadMagnanimous

The following tasks were selected to run, in order:

  downloadMagnanimous
      runMagnanimous

In very simple builds, this may not look very helpful, but on more complex builds, like jb’s Dartle build, it can become quite handy:

➜  jb git:(main) ✗ dartle -g
======== Showing build information only, no tasks will be executed ========

Tasks Graph:

- analyzeCode
  +--- format
  |     +--- generateEmbeddedAssets
  |     |--- generateJbConfigModel
  |     |--- generateLicenses
  |     \--- generateVersionFile
  |--- generateEmbeddedAssets
  |--- generateJbConfigModel
  |--- generateLicenses
  |--- generateVersionFile
  \--- runPubGet
- build
  +--- analyzeCode ...
  |--- format ...
  |--- runPubGet
  \--- test
       +--- analyzeCode ...
       |--- cleanExamples
       |--- compileExe
       |     \--- analyzeCode ...
       \--- setupTestMvnRepo
            \--- buildMvnRepoListsProject
- clean
  +--- cleanExamples
  \--- cleanTests
- distribution
  \--- compileExe ...
- emptyGeneratedAssets

The following tasks were selected to run, in order:

  generateJbConfigModel
  generateLicenses
  generateVersionFile
  cleanExamples
      buildMvnRepoListsProject
          setupTestMvnRepo
              generateEmbeddedAssets
              runPubGet
                  format
                      analyzeCode
                          compileExe
                              test
                                  build

The ... after some tasks shown above means that the dependencies of the task are not being shown as they appeared earlier in the graph already.

The graph shows task dependencies as child nodes, so in the graph above, while emptyGeneratedAssets has no dependencies, build depends on analyzeCode, format, runPubGet and test directly (and those tasks have their own dependencies).

Running Tasks

If you run dartle without any arguments, the default task(s) defined in the build will be executed. If no default task is defined, an error occurs.

To run one or more specific tasks, give the name of the task(s) as arguments. For example, to run clean and compileExe (i.e. run a clean build that compiles an executable):

➜  jb git:(main) ✗ dartle clean compileExe
2026-05-19 19:46:22.434484 - dartle[main 1085] - INFO - Executing 9 tasks out of a total of 17 tasks: 2 tasks selected, 9 dependencies, 2 up-to-date
2026-05-19 19:46:22.434680 - dartle[main 1085] - INFO - Running task 'clean'
2026-05-19 19:46:22.434824 - dartle[main 1085] - INFO - Running task 'generateJbConfigModel'
2026-05-19 19:46:22.434869 - dartle[main 1085] - INFO - Running task 'generateLicenses'
2026-05-19 19:46:22.434946 - dartle[main 1085] - INFO - Running task 'generateVersionFile'
Formatted lib/src/jb_config.g.dart
Formatted 1 file (1 changed) in 0.02 seconds.
Formatted lib/src/licenses.g.dart
Formatted 1 file (1 changed) in 0.04 seconds.
2026-05-19 19:46:26.246886 - dartle[main 1085] - INFO - Running task 'generateEmbeddedAssets'
2026-05-19 19:46:26.246947 - dartle[main 1085] - INFO - Running task 'runPubGet'
Will not generate lib/src/jbuild_jar.g.dart as it already exists (size > 32)!
Resolving dependencies...
Downloading packages...
  _fe_analyzer_shared 96.0.0 (100.0.0 available)
  analyzer 10.2.0 (13.0.0 available)
  async 2.13.0 (2.13.1 available)
  build 4.0.4 (4.0.6 available)
  build_runner 2.12.2 (2.15.0 available)
  built_value 8.12.4 (8.12.6 available)
  dart_style 3.1.7 (3.1.9 available)
  json_annotation 4.11.0 (4.12.0 available)
  matcher 0.12.19 (0.12.20 available)
  meta 1.18.1 (1.18.2 available)
  test 1.30.0 (1.31.1 available)
  test_api 0.7.10 (0.7.12 available)
  test_core 0.6.16 (0.6.18 available)
  vm_service 15.0.2 (15.2.0 available)
  xml 6.6.1 (7.0.1 available)
Got dependencies!
15 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.

2026-05-19 19:46:26.493890 - dartle[main 1085] - INFO - Running task 'format'
2026-05-19 19:46:26.800615 - dartle[main 1085] - INFO - Running task 'analyzeCode'
Analyzing ....
No issues found!
2026-05-19 19:46:27.606614 - dartle[main 1085] - INFO - Running task 'compileExe'

Generated: /Users/renatoathaydes/programming/projects/jb/build/bin/jb

✔ Build succeeded in 9s, 21ms

Notice how Dartle automatically ran several tasks, even though only clean and compileExe were called explicitly. You can check that the tasks executing match the dependency graph printed in the previous section!

Dartle can match partial names when there’s no ambiguity, using capital letters as word separators.

An example should make it clear how that works.

Imagine a build with the following tasks:

To run the compileJava task, you may use:

dartle compileJava

Or:

dartle compJ

Or even:

dartle cJ

Because there’s no other tasks whose name start with c and then J.

Using just dartle compile wouldn’t work because that could match either compileJava or compileDart.

Similarly, cD would match compileDart, tJ would match testJava, and tD matches testDart.

Task and Dartle arguments

By default, all arguments are passed directly to Dartle. The example below sets the log-level to debug and runs the example task:

$ dartle example -l debug

If you want to pass arguments to a task, prepend the argument with :… in the example below, the argument abc will be passed to the example task.

$ dartle example :abc -l debug

Changing the order of the arguments does not affect the result, so the invocation below is equivalent to the previous one:

$ dartle example -l debug :abc

When running more than one task, arguments are passed to the latest task specified.

In the example below, task taskA gets arguments 123 and 456, while taskB gets 789:

$ dartle taskA :123 :456 taskB :789

The order in which tasks run depends only on their interdependencies, not on the order in which the tasks are invoked. Hence, in the example above, if taskA and taskB have no interdependencies, they run immediately, in parallel. If taskA depends on taskB, taskB will run before taskA despite it being invoked last.

Next Steps

Check out the Dartle Tasks documentation to familiarize yourself with the main concept in Dartle.

Or if you prefer, go directly to Dartle for Dart if you want to use Dartle to build Dart projects, or Derived Build Tools to build your own build tool using Dartle as a library.