Command-Line Interface

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This page is written against Gradle 9.8.1 (released on 2026-10-07). Every example was run on JDK 26 on macOS on 2026-10-16, through the Gradle Wrapper of a scratch copy of the tidepool project (described below); the JDK 26 that started the client also ran the daemon, because no daemon JVM criteria were set. Console output is shown as printed, except that the scratch directory was shortened to <tidepool>, that the line Consider enabling configuration cache to speed up this build that Gradle prints at the end of a build run without the configuration cache and the daemon start-up notices were removed, and that long listings were cut with grep (the filter is part of the command shown) or with an explicit ellipsis line. Gradle 8.14.x was not installed for this page, so differences with it are taken from the official documentation and the release notes and are marked "not run here".

The command line is the primary way to drive Gradle: IDEs, CI servers and scripts all end up running the same gradlew command (see CI & IDE Integration). This page covers how to name the work to do (task selectors, project paths, abbreviations), how to change which tasks run (-x, --rerun, --continue), the reporting tasks that answer "what is in this build?", the options that change speed, logging and the environment, and continuous builds. Which options can be moved into gradle.properties is on Build Environment & Properties; the daemon options are on Gradle Daemon; the wrapper itself is on Gradle Wrapper. The equivalents in Ant and Maven are at the end.

The synopsis

The official page gives the structure of a Gradle command as follows:

gradle [taskName...] [--option-name...]
gradle [--option-name...] [taskName...]

Source: Gradle: Command-Line Interface

Four rules from that page govern everything below:

Options may come before or after the task names. ./gradlew build --parallel and ./gradlew --parallel build are the same command. The only exception is a task option (below), which must follow its task.
Several tasks are separated by spaces (./gradlew clean build) and run in one build, in the order their dependencies allow.
Options that take a value accept it with or without =, and the documentation recommends = (--console=plain).
Options that switch a behaviour on have a --no- inverse: --build-cache and --no-build-cache, --parallel and --no-parallel. Many long options also have a short one (--help and -h, --continuous and -t).

All of the examples use ./gradlew, the wrapper script, as the official page recommends; gradle (a locally installed distribution, see Installation) accepts exactly the same arguments. The built-in help prints the usage line and the options in groups:

./gradlew -h | head -12

To see help contextual to the project, use gradlew help

To see more detail about a task, run gradlew help --task <task>

To see a list of available tasks, run gradlew tasks

USAGE: gradlew [option...] [task...]

--                                   Signals the end of built-in options. Parses subsequent parameters as tasks or task options only.

Help:

(The first lines of the output are the hint about the contextual help task. The complete list is reproduced in the option reference below.)

A build that fails ends the process with a non-zero exit code: the runs on this page ended with 0 on success and 1 on failure, which is what CI servers and shell scripts test.

The scratch project

The examples use a copy of the running tidepool project with three subprojects: tidepool-model, tidepool-engine (depends on the model, uses Commons CSV) and tidepool-cli (depends on the engine, uses picocli and the application plugin). The settings file declares the repositories once and the subprojects; the root build file configures every subproject, including the JUnit 5 test dependencies. The versions of the libraries are written inline here to keep the page short; the recommended place for them is a version catalog, see Version Catalogs.

The test in tidepool-engine fails on request: it reads the system property tidepool.fail, which the root build file sets from the project property failTests (so -PfailTests=true makes one test fail). That gives the failure options something to act on.

Kotlin DSL

// settings.gradle.kts
rootProject.name = "tidepool"

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

include("tidepool-model", "tidepool-engine", "tidepool-cli")

Groovy DSL

// settings.gradle
rootProject.name = 'tidepool'

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

include 'tidepool-model', 'tidepool-engine', 'tidepool-cli'

Kotlin DSL

// build.gradle.kts (root)
subprojects {
    apply(plugin = "java")

    group = "io.tidepool"
    version = "1.0.0"

    tasks.withType<JavaCompile>().configureEach {
        options.release = 17
    }

    tasks.withType<Test>().configureEach {
        useJUnitPlatform()
        systemProperty("tidepool.fail", providers.gradleProperty("failTests").orElse("false").get())
    }

    dependencies {
        "testImplementation"(platform("org.junit:junit-bom:5.13.4"))
        "testImplementation"("org.junit.jupiter:junit-jupiter")
        "testRuntimeOnly"("org.junit.platform:junit-platform-launcher")
    }
}

Groovy DSL

// build.gradle (root)
subprojects {
    apply plugin: 'java'

    group = 'io.tidepool'
    version = '1.0.0'

    tasks.withType(JavaCompile).configureEach {
        options.release = 17
    }

    tasks.withType(Test).configureEach {
        useJUnitPlatform()
        systemProperty 'tidepool.fail', providers.gradleProperty('failTests').orElse('false').get()
    }

    dependencies {
        testImplementation platform('org.junit:junit-bom:5.13.4')
        testImplementation 'org.junit.jupiter:junit-jupiter'
        testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    }
}

The subproject build files are one-liners. tidepool-model applies java-library; tidepool-engine applies it too and adds the dependencies; tidepool-cli applies application. The run task is told to format numbers in the English locale so that the output below does not depend on the machine:

Kotlin DSL

// tidepool-engine/build.gradle.kts
plugins {
    `java-library`
}

dependencies {
    api(project(":tidepool-model"))
    implementation("org.apache.commons:commons-csv:1.14.1")
}

// tidepool-cli/build.gradle.kts
plugins {
    application
}

dependencies {
    implementation(project(":tidepool-engine"))
    implementation("info.picocli:picocli:4.7.7")
}

application {
    mainClass = "io.tidepool.cli.Main"
}

tasks.named<JavaExec>("run") {
    systemProperty("user.language.format", "en")
    systemProperty("user.country.format", "US")
}

Groovy DSL

// tidepool-engine/build.gradle
plugins {
    id 'java-library'
}

dependencies {
    api project(':tidepool-model')
    implementation 'org.apache.commons:commons-csv:1.14.1'
}

// tidepool-cli/build.gradle
plugins {
    id 'application'
}

dependencies {
    implementation project(':tidepool-engine')
    implementation 'info.picocli:picocli:4.7.7'
}

application {
    mainClass = 'io.tidepool.cli.Main'
}

tasks.named('run') {
    systemProperty 'user.language.format', 'en'
    systemProperty 'user.country.format', 'US'
}

Both versions of the project were built and the commands below were run on both with the same results; the DSL matters only for the build files, never for the command line. This build is configuration-cache compatible: it was run with --configuration-cache (see below) and the entry was stored and reused.

These files are this page’s own setup for the examples, not an example taken from the manual.

Executing tasks

Task selectors and project paths

A task is named with its path: the project path, a colon, and the task name. A leading colon makes the path absolute from the root project:

./gradlew :tidepool-cli:run --args="../data/stations.csv BOS" -q

Boston: -0.662 m

(-q keeps only what the program prints. The decimal point follows the JVM default locale: this run used an English locale, and a locale such as Spanish prints -0,662 m. The relative path in --args is relative to the working directory of the run task, the project directory of tidepool-cli.) The ways of writing a task name behave as follows:

Command Meaning

Command	Meaning
`./gradlew :tidepool-cli:jar`	The `jar` task of that project, spelled with an absolute path.
`./gradlew tidepool-cli:jar`	The same task; the leading colon is optional when the command is run from the root.
`./gradlew jar`	A task selector: the `jar` task of every project that has one, reached from the root project where the command is run.
`./gradlew :jar`	The `jar` task of the root project only. The root project of tidepool has no Java plugin, so here it fails with `Cannot locate tasks that match ':jar' as task 'jar' not found in root project 'tidepool'`.

./gradlew :tidepool-cli:jar

The jar task of that project, spelled with an absolute path.

./gradlew tidepool-cli:jar

The same task; the leading colon is optional when the command is run from the root.

./gradlew jar

A task selector: the jar task of every project that has one, reached from the root project where the command is run.

./gradlew :jar

The jar task of the root project only. The root project of tidepool has no Java plugin, so here it fails with Cannot locate tasks that match ':jar' as task 'jar' not found in root project 'tidepool'.

A selector is the common case. ./gradlew test ran the test tasks of all three subprojects above, and ./gradlew run found the single run task in tidepool-cli:

./gradlew run --dry-run

:tidepool-model:compileJava SKIPPED
:tidepool-engine:compileJava SKIPPED
:tidepool-cli:compileJava SKIPPED
:tidepool-cli:processResources SKIPPED
:tidepool-cli:classes SKIPPED
:tidepool-engine:processResources SKIPPED
:tidepool-engine:classes SKIPPED
:tidepool-engine:jar SKIPPED
:tidepool-model:processResources SKIPPED
:tidepool-model:classes SKIPPED
:tidepool-model:jar SKIPPED
:tidepool-cli:run SKIPPED

BUILD SUCCESSFUL in 918ms

Some selectors run only in the project the command is invoked on and not in its subprojects; the official page names help and dependencies as examples. When Gradle is invoked from inside a subproject directory the project name is omitted (cd tidepool-engine && ../gradlew test), and the -p option (--project-dir) starts the build in another directory without changing into it.

Source: Gradle: Executing tasks in multi-project builds

Several tasks, and their order

Tasks are run in the order their dependencies require, which may differ from the order on the command line when the command line does not constrain it. One constraint is kept: the command line order safety rule. ./gradlew clean build runs clean before build even if running them the other way round would be faster, because clean removes what build creates; the order depends on tasks declaring what they create, consume or remove (see Incremental Build).

Source: Gradle: Executing tasks, Gradle: Command line order safety

Task options

An option placed right after a task name belongs to that task, not to Gradle: run --args=... above, or test --tests=.... Task options are listed by help --task, which also prints the task’s type, its description and all the projects that have it:

./gradlew help --task test -q

Detailed task information for test

Paths
     :tidepool-cli:test (registered by plugin 'org.gradle.jvm-test-suite')
     :tidepool-engine:test (registered by plugin 'org.gradle.jvm-test-suite')
     :tidepool-model:test (registered by plugin 'org.gradle.jvm-test-suite')

Type
     Test (org.gradle.api.tasks.testing.Test)

Options
     --debug-jvm     Enable debugging for the test process. The process is started suspended and listening on port 5005.

     --no-debug-jvm     Disables option --debug-jvm.

     --fail-fast     Stops test execution after the first failed test.

     --no-fail-fast     Disables option --fail-fast.

     --test-dry-run     Simulate test execution.

     --no-test-dry-run     Disables option --test-dry-run.

     --tests     Sets test class or method name to be included (in addition to the test task filters), '*' is supported.

     --rerun     Causes the task to be re-run even if up-to-date.

Description
     Runs the test suite.

Group
     verification

If a task defines an option with the same name as a built-in Gradle option (the official page uses the example of a profile option), the built-in one wins unless the task name is preceded by --: gradle mytask --profile passes --profile to Gradle, while gradle — mytask --profile=value passes it to the task. Every task also has the built-in --rerun option (below). How to declare an option on your own task is on Writing Custom Tasks.

Source: Gradle: Show task usage details, Gradle: Task options, Gradle: Declaring and using command line options

Name abbreviation

Neither the project nor the task name needs to be written in full. Any prefix that identifies it uniquely works, and camel-case patterns are expanded against camel-case and kebab-case names: tEn:tes is tidepool-engine:test, and :t-c:jar is :tidepool-cli:jar (the pattern t-c matches tidepool-cli because both words start with the given letters). Abbreviations also work after -x. When the abbreviation matches two names Gradle refuses to guess:

./gradlew :tidepool-cli:ja

[Incubating] Problems report is available at: file://<tidepool>/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
Ambiguous matches
  Cannot locate tasks that match ':tidepool-cli:ja' as task 'ja' is ambiguous in project ':tidepool-cli'. Candidates are: 'jar', 'javadoc'.

* Try:
> Run gradlew tasks to get a list of available tasks.
> For more on name expansion, please refer to https://docs.gradle.org/9.8.1/userguide/command_line_interface.html#sec:name_abbreviation in the Gradle documentation.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights from a Build Scan (powered by Develocity).
> Get more help at https://help.gradle.org.

BUILD FAILED in 261ms

A task name that does not exist at all gets a spelling suggestion (the same unabbreviated, unprefixed name was used):

./gradlew buidl

[Incubating] Problems report is available at: file://<tidepool>/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
No matches
  Task 'buidl' not found in root project 'tidepool' and its subprojects. Some candidates are: 'build'.

* Try:
> Run gradlew tasks to get a list of available tasks.
> For more on name expansion, please refer to https://docs.gradle.org/9.8.1/userguide/command_line_interface.html#sec:name_abbreviation in the Gradle documentation.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights from a Build Scan (powered by Develocity).
> Get more help at https://help.gradle.org.

BUILD FAILED in 276ms

At the info log level Gradle says how each abbreviation was expanded, which is the way to check that a typo did not select something unexpected:

./gradlew -i :t-c:jar --dry-run | grep -E 'matched|exact|abbreviat|Found'
./gradlew -i tEn:tes --dry-run | grep -E 'matched|exact|abbreviat|Found'

Task path ':t-c:jar' matched project ':tidepool-cli'
Task name matched 'jar'
Task path 'tEn:tes' matched project ':tidepool-engine'
Abbreviated task name 'tes' matched 'test'

Source: Gradle: Name abbreviation, Gradle: Tracing name expansion

An option Gradle does not know is reported against the task it followed, not against Gradle, which is confusing the first time:

./gradlew build --nonsense

FAILURE: Build failed with an exception.

* What went wrong:
Problem configuring task :tidepool-cli:build from command line.
> Unknown command-line option '--nonsense'.

* Try:
> Run gradlew help --task :tidepool-cli:build to get task usage details.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights from a Build Scan (powered by Develocity).
> Get more help at https://help.gradle.org.

BUILD FAILED in 259ms

Choosing which tasks run

Excluding tasks: -x

-x (--exclude-task) removes a task from the build, together with the dependencies that only that task needed. The first listing shows what :tidepool-engine:build would run (a dry run, so nothing is executed); the second excludes test; the third also excludes compileJava:

./gradlew :tidepool-engine:build --dry-run

:tidepool-model:compileJava SKIPPED
:tidepool-engine:compileJava SKIPPED
:tidepool-engine:processResources SKIPPED
:tidepool-engine:classes SKIPPED
:tidepool-engine:jar SKIPPED
:tidepool-engine:assemble SKIPPED
:tidepool-engine:compileTestJava SKIPPED
:tidepool-engine:processTestResources SKIPPED
:tidepool-engine:testClasses SKIPPED
:tidepool-model:processResources SKIPPED
:tidepool-model:classes SKIPPED
:tidepool-model:jar SKIPPED
:tidepool-engine:test SKIPPED
:tidepool-engine:check SKIPPED
:tidepool-engine:build SKIPPED

BUILD SUCCESSFUL in 330ms

./gradlew :tidepool-engine:build -x test --dry-run

:tidepool-model:compileJava SKIPPED
:tidepool-engine:compileJava SKIPPED
:tidepool-engine:processResources SKIPPED
:tidepool-engine:classes SKIPPED
:tidepool-engine:jar SKIPPED
:tidepool-engine:assemble SKIPPED
:tidepool-engine:check SKIPPED
:tidepool-engine:build SKIPPED

BUILD SUCCESSFUL in 309ms

compileTestJava, processTestResources, testClasses and test are gone: they were needed only by test. compileJava stays, because classes, jar and assemble still need it. Excluding that too removes the model’s tasks, which only compileJava of the engine needed:

./gradlew :tidepool-engine:build -x test -x compileJava --dry-run

:tidepool-engine:processResources SKIPPED
:tidepool-engine:classes SKIPPED
:tidepool-engine:jar SKIPPED
:tidepool-engine:assemble SKIPPED
:tidepool-engine:check SKIPPED
:tidepool-engine:build SKIPPED

BUILD SUCCESSFUL in 327ms

Excluding a task from the command line is a tool for a one-off run. A task that should never run in a given build is better disabled in the build file; see Tasks.

Source: Gradle: Excluding tasks from execution

Forcing tasks to run

Gradle skips a task whose inputs and outputs have not changed (the task is reported UP-TO-DATE; see Incremental Build). Two options override that. --rerun is a task option and re-runs only the task it follows; --rerun-tasks is a Gradle option and re-runs every task in the build, as if everything had been cleaned, but without deleting the outputs.

The first run of :tidepool-engine:test after a clean, the second run (nothing changed), the third run with --rerun, and a run of two test tasks with --rerun-tasks (the filter keeps the task line, the result and the counts):

./gradlew clean
./gradlew :tidepool-engine:test | grep -E 'engine:test( |$)|BUILD|actionable'
./gradlew :tidepool-engine:test | grep -E 'engine:test( |$)|BUILD|actionable'
./gradlew :tidepool-engine:test --rerun | grep -E 'engine:test( |$)|BUILD|actionable'
./gradlew :tidepool-engine:test :tidepool-model:test --rerun-tasks | grep -E 'engine:test( |$)|BUILD|actionable'

> Task :tidepool-engine:test
BUILD SUCCESSFUL in 1s
5 actionable tasks: 5 executed

> Task :tidepool-engine:test UP-TO-DATE
BUILD SUCCESSFUL in 355ms
5 actionable tasks: 5 up-to-date

> Task :tidepool-engine:test
BUILD SUCCESSFUL in 673ms
5 actionable tasks: 1 executed, 4 up-to-date

> Task :tidepool-engine:test
BUILD SUCCESSFUL in 1s
7 actionable tasks: 7 executed

(The four outputs are printed one after the other, separated by blank lines; the clean output is omitted.) Note the counts: --rerun executed one task and left the four it depends on up to date, while --rerun-tasks executed all seven.

Source: Gradle: Forcing tasks to execute, Gradle: Built-in task options

When a task fails: --continue

By default Gradle stops at the first task failure, which shortens the build and avoids cascades of unrelated errors. --continue runs every task whose own dependencies succeeded and reports all the failures at the end. The tests of the engine are made to fail with -PfailTests=true; without --continue the model’s tests are never reached, with it they run:

./gradlew build -PfailTests=true | grep -E 'engine:test|model:test|BUILD|failing|FAILED|went wrong|Execution failed|AssertionFailed|tests completed|TideEngineTest'
./gradlew build -PfailTests=true --continue | grep -E 'engine:test|model:test|BUILD|failing|FAILED|went wrong|Execution failed|AssertionFailed|tests completed|TideEngineTest'

> Task :tidepool-engine:testClasses UP-TO-DATE
> Task :tidepool-engine:test FAILED
TideEngineTest > failsOnRequest() FAILED
    org.opentest4j.AssertionFailedError at TideEngineTest.java:24
2 tests completed, 1 failed
* What went wrong:
Execution failed for task ':tidepool-engine:test'.
> There were failing tests. See the report at: file://<tidepool>/tidepool-engine/build/reports/tests/test/index.html
BUILD FAILED in 603ms

> Task :tidepool-engine:testClasses UP-TO-DATE
> Task :tidepool-engine:test FAILED
TideEngineTest > failsOnRequest() FAILED
    org.opentest4j.AssertionFailedError at TideEngineTest.java:24
2 tests completed, 1 failed
> Task :tidepool-model:testClasses UP-TO-DATE
> Task :tidepool-model:test
* What went wrong:
Execution failed for task ':tidepool-engine:test'.
> There were failing tests. See the report at: file://<tidepool>/tidepool-engine/build/reports/tests/test/index.html
BUILD FAILED in 801ms

(The two outputs are printed one after the other, separated by a blank line.) The second build still ends with BUILD FAILED and exit code 1; --continue changes what is executed, not the verdict. --no-continue is the inverse and is the default. A task is skipped even under --continue when something it depends on failed: tests do not run when the code they test does not compile. --continue is the natural option for CI, where one run should report all failing modules and all failing checks; the failure of the test task here also names the HTML report to open.

Source: Gradle: Continue the build after a task failure

Running the application

The run task of the application plugin passes --args to the program’s main method. The program exits with 1 for an unknown station, and the task turns a non-zero exit value into a build failure:

./gradlew :tidepool-cli:run --args="../data/stations.csv XXX" | grep -E 'Unknown|BUILD|FAILED|went wrong|non-zero'

> Task :tidepool-cli:run FAILED
Unknown station: XXX
* What went wrong:
> Process 'command '/Library/Java/JavaVirtualMachines/jdk-26.jdk/Contents/Home/bin/java'' finished with non-zero exit value 1
BUILD FAILED in 727ms

Source: Gradle User Manual: Command-Line Interface, running applications, Gradle User Manual: The Application Plugin

Looking at the build

Gradle ships reporting tasks that answer questions about a build without changing anything. They are ordinary tasks and take part in the usual selection rules (the "run only in the project invoked on" ones are projects, dependencies, properties and help).

Projects and tasks

projects prints the project hierarchy and the directory of each subproject:

./gradlew projects -q

Projects:

------------------------------------------------------------
Root project 'tidepool'
------------------------------------------------------------

Location: <tidepool>

Project hierarchy:

Root project 'tidepool'
+--- Project ':tidepool-cli'
+--- Project ':tidepool-engine'
\--- Project ':tidepool-model'

Project locations:

project ':tidepool-cli' - /tidepool-cli
project ':tidepool-engine' - /tidepool-engine
project ':tidepool-model' - /tidepool-model

To see a list of the tasks of a project, run gradlew <project-path>:tasks
For example, try running gradlew :tidepool-cli:tasks

(The project locations lines show the directory relative to the root, which is why the root’s own path is absent.) tasks lists the tasks that belong to a group, by default; --all adds the ungrouped ones and prefixes every task with its project; --group shows only one group; --groups selects several groups; --types adds the task class; --provenance adds where each task was registered. --provenance and the provenance in failure messages came in Gradle 9.5.

./gradlew tasks --group=verification -q
./gradlew tasks --group="build setup" --provenance -q

------------------------------------------------------------
Tasks runnable from root project 'tidepool'
------------------------------------------------------------

Verification tasks
------------------
check - Runs all checks.
test - Runs the test suite.

To see all tasks and more detail, run gradlew tasks --all

To see more detail about a task, run gradlew help --task <task>

------------------------------------------------------------
Tasks runnable from root project 'tidepool'
------------------------------------------------------------

Build Setup tasks
-----------------
init (registered by plugin 'org.gradle.build-init') - Initializes a new Gradle build.
updateDaemonJvm - Generates or updates the Gradle Daemon JVM criteria.
wrapper (registered by plugin 'org.gradle.wrapper') - Generates Gradle wrapper files.

To see all tasks and more detail, run gradlew tasks --all

To see more detail about a task, run gradlew help --task <task>

(The two outputs are printed one after the other.) The help --task test output above is the third reporting form: the details of one task, with every project that has it.

Source: Gradle: Listing projects, Gradle: Listing tasks, Gradle 9.5.0 release notes: Task provenance in reports and failure messages

Dependencies

dependencies prints the resolved tree of every configuration of the project it runs in; --configuration restricts it to one. dependencyInsight explains one dependency: which variant was selected, with which attributes, and the path that led to it. Both are used heavily with the dependency pages (see Declaring Dependencies & Configurations and Dependency Resolution, Conflicts & Capabilities).

./gradlew :tidepool-engine:dependencies --configuration runtimeClasspath -q
./gradlew :tidepool-engine:dependencyInsight --dependency commons-csv --configuration runtimeClasspath -q

------------------------------------------------------------
Project ':tidepool-engine'
------------------------------------------------------------

runtimeClasspath - Runtime classpath of source set 'main'.
+--- project ':tidepool-model'
\--- org.apache.commons:commons-csv:1.14.1
     +--- commons-io:commons-io:2.20.0
     \--- commons-codec:commons-codec:1.19.0

A web-based, searchable dependency report is available by adding the --scan option.

org.apache.commons:commons-csv:1.14.1
  Variant runtime:
    | Attribute Name                 | Provided     | Requested    |
    |--------------------------------|--------------|--------------|
    | org.gradle.status              | release      |              |
    | org.gradle.category            | library      | library      |
    | org.gradle.libraryelements     | jar          | jar          |
    | org.gradle.usage               | java-runtime | java-runtime |
    | org.gradle.dependency.bundling |              | external     |
    | org.gradle.jvm.environment     |              | standard-jvm |
    | org.gradle.jvm.version         |              | 17           |

org.apache.commons:commons-csv:1.14.1
\--- runtimeClasspath

A web-based, searchable dependency report is available by adding the --scan option.

(The two outputs are printed one after the other.) The requested attribute org.gradle.jvm.version is 17 because the build file sets options.release = 17; the other tools' scopes and the mapping to Gradle configurations are on Dependency Management Fundamentals. buildEnvironment does the same for the dependencies of the build scripts themselves (the plugins), and dependencyInsight also accepts --all-variants and --single-path.

Source: Gradle: Listing project dependencies, Gradle: Viewing and debugging dependencies

Properties

properties lists every property of the project, which is more than a hundred lines of internal objects; --property selects one:

./gradlew :tidepool-engine:properties --property version -q

------------------------------------------------------------
Project ':tidepool-engine'
------------------------------------------------------------

version: 1.0.0

Source: Gradle: Listing project properties

Previewing the build: --dry-run and --task-graph

--dry-run (-m) prints the tasks that would run, with every action disabled (all the listings marked SKIPPED above). Since Gradle 9.1, --task-graph prints the dependency graph itself, with each task’s type; a task whose subtree was already printed is shown with (*):

./gradlew :tidepool-cli:jar --task-graph -q

Tasks graph for: :tidepool-cli:jar
\--- :tidepool-cli:jar (org.gradle.api.tasks.bundling.Jar)
     +--- :tidepool-cli:classes (org.gradle.api.DefaultTask)
     |    +--- :tidepool-cli:compileJava (org.gradle.api.tasks.compile.JavaCompile)
     |    |    +--- :tidepool-engine:compileJava (org.gradle.api.tasks.compile.JavaCompile)
     |    |    |    \--- :tidepool-model:compileJava (org.gradle.api.tasks.compile.JavaCompile)
     |    |    \--- :tidepool-model:compileJava (*)
     |    \--- :tidepool-cli:processResources (org.gradle.language.jvm.tasks.ProcessResources)
     \--- :tidepool-cli:compileJava (*)

(*) - details omitted (listed previously)

The graph is the answer to "why does this task run?", which a flat dry-run list cannot give. The graph of the Gradle build lifecycle that this comes from is on Build Lifecycle.

Source: Gradle: Execution options, Gradle 9.1.0 release notes: Task graph visualization

Dependencies and the network

--offline forbids network access; builds then use only what is in the dependency cache. With an empty Gradle user home (a per-example GRADLE_USER_HOME was used so that the shared cache stayed untouched) it fails with a message that names the missing module:

GRADLE_USER_HOME=<own home> ./gradlew :tidepool-engine:compileJava --offline

> Task :tidepool-model:compileJava UP-TO-DATE
> Task :tidepool-engine:compileJava FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':tidepool-engine:compileJava' (registered by plugin class 'org.gradle.api.plugins.JavaBasePlugin').
> Could not resolve all files for configuration ':tidepool-engine:compileClasspath'.
   > Could not resolve org.apache.commons:commons-csv:1.14.1.
     Required by:
         project ':tidepool-engine'
      > No cached version of org.apache.commons:commons-csv:1.14.1 available for offline mode.

(The wrapper download, the welcome text and the last part of the failure message, * Try: and the footer, were removed from the listing; the lines shown are as printed.) --refresh-dependencies (-U) is the opposite: it refreshes the state of the dependencies (the help text is "Refreshes the state of dependencies") instead of trusting what the cache holds. --offline is therefore a way to prove that a build works without the network, and -U a way to start from what the repositories serve now. The rules of the cache are on Dependency Locking, Verification & Caching.

Source: Gradle: Execution options

Speed: the performance options

The official page groups these under "Performance options". Their effect and the guidance on when to use each is on the pages named in the table; this page shows how they appear on the command line.

Option Default What it does

Option	Default	What it does
`--parallel`, `--no-parallel`	off	Builds independent projects at the same time.
`--max-workers=n`	processors	The maximum number of concurrent workers.
`--build-cache`, `--no-build-cache`	off	Reuses task outputs, also across checkouts and machines (see Build Cache).
`--configuration-cache`, `--no-configuration-cache`	off	Reuses the result of the configuration phase (see Configuration Cache & Isolated Projects).
`--configuration-cache-problems=warn\|fail`	`fail`	Whether configuration cache problems fail the build.
`--configure-on-demand`, `--no-configure-on-demand`	off	Configures only the projects the requested tasks need (incubating).
`--isolated-projects`, `--no-isolated-projects`	off	Configures projects in parallel; implies `--configuration-cache` (incubating; the Isolated Projects feature became incubating in Gradle 9.7).
`--watch-fs`, `--no-watch-fs`	on where supported	File system watching: reuses what Gradle learned about the file system between builds.
`--priority=normal\|low`	`normal`	The scheduling priority of the daemon and the processes it starts.
`--profile`	off	Writes a high-level HTML timing report to the build directory.
`--scan`	off	Publishes a Build Scan.

--parallel, --no-parallel

off

Builds independent projects at the same time.

--max-workers=n

processors

The maximum number of concurrent workers.

--build-cache, --no-build-cache

off

Reuses task outputs, also across checkouts and machines (see Build Cache).

--configuration-cache, --no-configuration-cache

off

Reuses the result of the configuration phase (see Configuration Cache & Isolated Projects).

--configuration-cache-problems=warn|fail

fail

Whether configuration cache problems fail the build.

--configure-on-demand, --no-configure-on-demand

off

Configures only the projects the requested tasks need (incubating).

--isolated-projects, --no-isolated-projects

off

Configures projects in parallel; implies --configuration-cache (incubating; the Isolated Projects feature became incubating in Gradle 9.7).

--watch-fs, --no-watch-fs

on where supported

File system watching: reuses what Gradle learned about the file system between builds.

--priority=normal|low

normal

The scheduling priority of the daemon and the processes it starts.

--profile

off

Writes a high-level HTML timing report to the build directory.

--scan

off

Publishes a Build Scan.

The mechanics:

--parallel was run above with clean build --parallel, whose last two lines were:
```
BUILD SUCCESSFUL in 1s
16 actionable tasks: 16 executed
```
It is only a safe default for builds whose tasks and projects do not share mutable state, and build logic should be written for it; see Multi Project Builds.

The build cache needs a first run that stores the outputs and a second that loads them. A clean build with --build-cache stored the outputs of every cacheable task; the next clean build with the flag restored them (a per-example Gradle user home was used so that the first run started with an empty cache; the filter keeps the compilation and test tasks):

./gradlew clean build | grep -E 'FROM-CACHE|BUILD|actionable|:compileJava|:test( |$)'
./gradlew clean build --build-cache | grep -E 'FROM-CACHE|BUILD|actionable|:compileJava|:test( |$)'
./gradlew clean build --build-cache | grep -E 'FROM-CACHE|BUILD|actionable|:compileJava|:test( |$)'

> Task :tidepool-model:compileJava
> Task :tidepool-engine:compileJava
> Task :tidepool-cli:compileJava
> Task :tidepool-cli:test NO-SOURCE
> Task :tidepool-engine:test
> Task :tidepool-model:test
BUILD SUCCESSFUL in 21s
16 actionable tasks: 16 executed

> Task :tidepool-model:compileJava
> Task :tidepool-engine:compileJava
> Task :tidepool-cli:compileJava
> Task :tidepool-cli:test NO-SOURCE
> Task :tidepool-engine:test
> Task :tidepool-model:test
BUILD SUCCESSFUL in 2s
16 actionable tasks: 16 executed

> Task :tidepool-model:compileJava FROM-CACHE
> Task :tidepool-engine:compileJava FROM-CACHE
> Task :tidepool-cli:compileJava FROM-CACHE
> Task :tidepool-cli:test NO-SOURCE
> Task :tidepool-engine:compileTestJava FROM-CACHE
> Task :tidepool-engine:test FROM-CACHE
> Task :tidepool-model:compileTestJava FROM-CACHE
> Task :tidepool-model:test FROM-CACHE
BUILD SUCCESSFUL in 835ms
16 actionable tasks: 9 executed, 7 from cache

(The three outputs are printed one after the other.) The first run stored nothing because the cache was off; the second ran every task and stored the outputs of the cacheable ones; the third loaded seven tasks (the compilation and the tests) FROM-CACHE, and the other nine (the three clean tasks, the three jar tasks, startScripts, distTar and distZip) ran normally; lifecycle tasks such as classes and build have no actions and are not counted, as the summary line says. The compileTestJava lines of the third run appear only there because the filter keeps lines that contain FROM-CACHE.

The configuration cache stores the result of the configuration phase for a given set of requested tasks and reuses it while its inputs are unchanged. The first listing stores the entry (Calculating task graph ...); the second changes a Gradle property that the build reads while configuring (failTests), so the entry cannot be reused and a new one is stored; the third repeats the second and reuses it (Reusing configuration cache.). The filter keeps the cache messages and the verdict:
```
./gradlew :tidepool-engine:test --configuration-cache | grep -E 'cache|Calculating|Reusing|BUILD|Configuration'
./gradlew :tidepool-engine:test --configuration-cache -PfailTests=true | grep -E 'cache|Calculating|Reusing|BUILD|Configuration'
./gradlew :tidepool-engine:test --configuration-cache -PfailTests=true | grep -E 'cache|Calculating|Reusing|BUILD|Configuration'
```
```
Calculating task graph as no cached configuration is available for tasks: :tidepool-engine:test
BUILD SUCCESSFUL in 444ms
Configuration cache entry stored.

Calculating task graph as configuration cache cannot be reused because Gradle property 'failTests' has changed.
BUILD FAILED in 886ms
Configuration cache entry stored.

Reusing configuration cache.
BUILD FAILED in 951ms
Configuration cache entry reused.
```
(The three outputs are printed one after the other; the second and third builds fail, as asked, with -PfailTests=true.) The configuration cache is not on by default in Gradle 9.8.1: the 9.0 release made it the preferred mode and announced that it will be the default in Gradle 10, so the flag, org.gradle.configuration-cache=true in gradle.properties (which is what gradle init writes, see below), or --no-configuration-cache to switch it off again, is how it is controlled. Task code that reads the Project object at execution time is not compatible with it (the warning example in warnings and deprecations below).
--profile writes build/reports/profile/profile-<timestamp>.html, a per-task and per-project time report, without needing a server. The official page says that --scan is preferred.
--scan creates a Build Scan, which captures the build’s metadata and sends it to a Develocity server (the public service by default; --develocity-url names a private one, and the plugin is auto-applied by the flag). The first use may ask to accept the terms of use. Not run here: the build data would be published to an external service. Nearly every failure message in this page ends with Run with --scan to get full insights from a Build Scan, and the dependencies output with A web-based, searchable dependency report is available by adding the --scan option, which is how the option is advertised.

The daemon options (--daemon, --no-daemon, --foreground, --status, --stop) are on Gradle Daemon; the build-cache and configuration-cache pages above and Performance Profiling & Build Scans cover the rest.

Source: Gradle: Performance options, Gradle: Enable Build Scan, Gradle: Build cache, Gradle: Enabling the configuration cache

Output: logging, console and warnings

Log levels and stack traces

The default log level is lifecycle. The options, from least to most verbose, are -q (--quiet, errors only), -w (--warn), the default, -i (--info) and -d (--debug, which includes the normal stack trace). The property org.gradle.logging.level sets the same thing from gradle.properties. A small build that logs one message at each level shows what each option keeps:

Kotlin DSL

// build.gradle.kts
tasks.register("levels") {
    doLast {
        logger.error("error message")
        logger.quiet("quiet message")
        logger.warn("warn message")
        logger.lifecycle("lifecycle message")
        logger.info("info message")
        logger.debug("debug message")
    }
}

Groovy DSL

// build.gradle
tasks.register('levels') {
    doLast {
        logger.error 'error message'
        logger.quiet 'quiet message'
        logger.warn 'warn message'
        logger.lifecycle 'lifecycle message'
        logger.info 'info message'
        logger.debug 'debug message'
    }
}

Each command was run, and only the lines of the messages (and the BUILD line of the default run) were kept with grep message; for -d, the time stamp that precedes every debug line was also removed:

$ ./gradlew levels
error message
quiet message
warn message
lifecycle message
$ ./gradlew levels -q
error message
quiet message
$ ./gradlew levels -w
error message
quiet message
warn message
$ ./gradlew levels -i
error message
quiet message
warn message
lifecycle message
info message
$ ./gradlew levels -d | grep message
[ERROR] [org.gradle.api.Task] error message
[QUIET] [org.gradle.api.Task] quiet message
[WARN] [org.gradle.api.Task] warn message
[LIFECYCLE] [org.gradle.api.Task] lifecycle message
[INFO] [org.gradle.api.Task] info message
[DEBUG] [org.gradle.api.Task] debug message

The Groovy DSL version was run with -i and printed the same five messages. -s (--stacktrace) prints the stack trace of every exception, including the ones caused by the build script, and -S (--full-stacktrace) the unfiltered, very long, trace. Writing messages from build logic is on Directories & Logging.

Source: Gradle: Logging options, Gradle: Debugging options

The console

--console takes auto (default: rich on a terminal, plain otherwise), plain, colored, rich and verbose; plain is the default when the output is not a terminal, which is why the listings on this page have no progress bar. verbose prints the task names and outcomes as in Gradle 3.5 and earlier. --console-unicode allows or forbids Unicode characters, and org.gradle.console sets the mode from a property.

Since Gradle 9.6 the NO_COLOR environment variable is honoured: when it is set and non-empty, colour is suppressed while the other styling (bold, underline, progress bars) is kept. The last line of a build with --console=rich, with the escape characters made visible by cat -v, without and with the variable:

$ ./gradlew :tidepool-model:jar --console=rich --rerun-tasks | cat -v | grep BUILD
^[[32;1mBUILD SUCCESSFUL^[[0;39m in 264ms^[[0K
$ NO_COLOR=1 ./gradlew :tidepool-model:jar --console=rich --rerun-tasks | cat -v | grep BUILD
^[[1mBUILD SUCCESSFUL^[[m in 294ms^[[0K

Source: Gradle: Customizing log format, Gradle 9.6.0 release notes: NO_COLOR support

Warnings and deprecations

By default Gradle does not print each deprecation warning but only a summary at the end of the build, saying that the build is incompatible with the next major release. --warning-mode changes that: all prints every warning, fail prints them and fails the build if there were any, summary is the default, none prints nothing, not even the summary. This build deliberately uses a deprecated API (the project object at execution time, which is also what prevents the configuration cache):

Kotlin DSL

// build.gradle.kts
tasks.register("showBuildDir") {
    doLast {
        println("build dir: " + project.buildDir.name)
    }
}

Groovy DSL

// build.gradle
tasks.register('showBuildDir') {
    doLast {
        println 'build dir: ' + project.buildDir.name
    }
}

./gradlew showBuildDir

> Task :showBuildDir
build dir: build

[Incubating] Problems report is available at: file://<legacy>/build/reports/problems/problems-report.html

Deprecated Gradle features were used in this build, making it incompatible with Gradle 10.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/9.8.1/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD SUCCESSFUL in 457ms
1 actionable task: 1 executed

./gradlew showBuildDir --warning-mode=all

> Task :showBuildDir
Invocation of Task.project at execution time has been deprecated. This will fail with an error in Gradle 10. This API is incompatible with the configuration cache, which will become the only mode supported by Gradle in a future release. Consult the upgrading guide for further information: https://docs.gradle.org/9.8.1/userguide/upgrading_version_7.html#task_project
	at Build_gradle$$$result$1$1.execute(build.gradle.kts:3)
	(Run with --stacktrace to get the full stack trace of this deprecation warning.)
build dir: build

[Incubating] Problems report is available at: file://<legacy>/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 442ms
1 actionable task: 1 executed

./gradlew showBuildDir --warning-mode=fail

> Task :showBuildDir
Invocation of Task.project at execution time has been deprecated. This will fail with an error in Gradle 10. This API is incompatible with the configuration cache, which will become the only mode supported by Gradle in a future release. Consult the upgrading guide for further information: https://docs.gradle.org/9.8.1/userguide/upgrading_version_7.html#task_project
	at Build_gradle$$$result$1$1.execute(build.gradle.kts:3)
	(Run with --stacktrace to get the full stack trace of this deprecation warning.)
build dir: build

[Incubating] Problems report is available at: file://<legacy>/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
Deprecated Gradle features were used in this build, making it incompatible with Gradle 10

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights from a Build Scan (powered by Develocity).
> Get more help at https://help.gradle.org.

BUILD FAILED in 396ms
1 actionable task: 1 executed

--warning-mode=none printed only the task and BUILD SUCCESSFUL. With the Groovy DSL the all output starts with the build file and line (Build file '<project>/build.gradle': line 3) and the stack frame is a Groovy closure instead of the script class. A CI build that must not regress should use --warning-mode=fail, or -Dorg.gradle.warning.mode=fail in the CI environment. The same output has the line [Incubating] Problems report is available at ...: --problems-report (on by default) and --no-problems-report control the HTML report of build problems, which is an incubating feature.

Source: Gradle: Showing or hiding warnings, Gradle: Reporting problems

Non-interactive mode

Some tasks ask questions when Gradle is attached to a terminal; init is the best known. Gradle 9.6 added --non-interactive (incubating), which makes Gradle use the default values instead of prompting, and the Gradle property org.gradle.console.interactive=false has the same effect. The official page recommends it for CI pipelines, scripts and other automated callers. gradle init was run with the option in an empty directory with the Gradle 9.8.1 distribution, and then, for comparison, without it but with the standard input redirected from /dev/null:

gradle init --non-interactive
ls

> Task :init
Learn more about Gradle by exploring our Samples at https://docs.gradle.org/9.8.1/samples

BUILD SUCCESSFUL in 678ms
1 actionable task: 1 executed
build.gradle.kts
gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle.kts

gradle init < /dev/null
ls

> Task :init
Learn more about Gradle by exploring our Samples at https://docs.gradle.org/9.8.1/samples

BUILD SUCCESSFUL in 910ms
1 actionable task: 1 executed
build.gradle.kts
gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle.kts

The two results are identical, as expected: with no terminal attached there is nothing to prompt. The case the option exists for, a terminal that is attached but must not be asked, could not be run here (the commands were run from a tool, not a terminal). The generated gradle.properties contains one line, org.gradle.configuration-cache=true, so a project created by Gradle 9.8.1 starts with the configuration cache on. The init task itself is on Installation.

Source: Gradle: Non-interactive mode, Gradle 9.6.0 release notes: Non-interactive mode

Continuous builds

-t (--continuous) keeps Gradle running after the tasks have finished and runs them again whenever the inputs of the tasks change. It needs file system watching (so it does not work with --no-daemon), waits for a quiet period after a change before building (the property org.gradle.continuous.quietperiod, in milliseconds), and, in a terminal, ends with CTRL-D. This run was time-bounded: the build was started in the background, the Java source of the model was edited after twelve seconds (a comment line appended, then removed again afterwards), and the process was stopped after another eight seconds, because without a terminal there is no CTRL-D:

./gradlew :tidepool-model:test --continuous &
sleep 12; echo "// edit" >> tidepool-model/src/main/java/io/tidepool/model/Height.java
sleep 8; kill %1

> Task :tidepool-model:compileJava UP-TO-DATE
> Task :tidepool-model:processResources NO-SOURCE
> Task :tidepool-model:classes UP-TO-DATE
> Task :tidepool-model:compileTestJava UP-TO-DATE
> Task :tidepool-model:processTestResources NO-SOURCE
> Task :tidepool-model:testClasses UP-TO-DATE
> Task :tidepool-model:test UP-TO-DATE

BUILD SUCCESSFUL in 272ms
3 actionable tasks: 3 up-to-date

Waiting for changes to input files...
modified: <tidepool>/tidepool-model/src/main/java/io/tidepool/model/Height.java
Change detected, executing build...

> Task :tidepool-model:compileJava
> Task :tidepool-model:processResources NO-SOURCE
> Task :tidepool-model:classes
> Task :tidepool-model:compileTestJava UP-TO-DATE
> Task :tidepool-model:processTestResources NO-SOURCE
> Task :tidepool-model:testClasses UP-TO-DATE
> Task :tidepool-model:test UP-TO-DATE

BUILD SUCCESSFUL in 53ms
3 actionable tasks: 1 executed, 2 up-to-date

Waiting for changes to input files...

Gradle noticed the change, recompiled the class and saw that the tests did not need to run again, since the compiled class was byte-for-byte the same (the comment changed nothing in the bytecode), which is what incremental build is for. Four limitations from the official page matter in practice: changes to build logic (the build files themselves) are not picked up and need a restart; only files inside the project directory are watched; creating a previously missing input directory may not trigger a build; and a task that modifies its own inputs causes an endless loop of builds. IDEs have their own continuous compilation, and the official page suggests running ./gradlew <task> --continuous in a terminal next to the IDE.

Source: Gradle: Continuous build, Gradle: Terminating continuous build, Gradle: Continuous build limitations

Environment options

These options choose the files and properties a build starts from. Their long-term home is gradle.properties and the environment (see Build Environment & Properties); on the command line they are the per-run override:

Option Meaning

Option	Meaning
`-g`, `--gradle-user-home`	The Gradle user home (default `~/.gradle`): caches, downloaded distributions, daemon logs and `init.d` scripts. The environment variable `GRADLE_USER_HOME` (the same directory) was used above to give examples an empty cache.
`-p`, `--project-dir`	The directory the build starts in (default: the working directory).
`--project-cache-dir`	The per-project cache directory (default: `.gradle` in the root project).
`-P`, `--project-prop`	A project property for the build, `-Pname=value`, read in a build file with `providers.gradleProperty("name")`. The `-PfailTests=true` above is one.
`-D`, `--system-prop`	A JVM system property of the build process, `-Dname=value`; `org.gradle.*` properties such as `-Dorg.gradle.warning.mode=fail` can be set this way.
`-I`, `--init-script`	An init script to run before the build (see Init Scripts & the Tooling API).
`--include-build`	Run the build as a composite that includes another build (see Composite Builds).
`-a`, `--no-rebuild`	Do not rebuild project dependencies; useful for debugging `buildSrc`, but "can lead to wrong results".

-g, --gradle-user-home

The Gradle user home (default ~/.gradle): caches, downloaded distributions, daemon logs and init.d scripts. The environment variable GRADLE_USER_HOME (the same directory) was used above to give examples an empty cache.

-p, --project-dir

The directory the build starts in (default: the working directory).

--project-cache-dir

The per-project cache directory (default: .gradle in the root project).

-P, --project-prop

A project property for the build, -Pname=value, read in a build file with providers.gradleProperty("name"). The -PfailTests=true above is one.

-D, --system-prop

A JVM system property of the build process, -Dname=value; org.gradle.* properties such as -Dorg.gradle.warning.mode=fail can be set this way.

-I, --init-script

An init script to run before the build (see Init Scripts & the Tooling API).

--include-build

Run the build as a composite that includes another build (see Composite Builds).

-a, --no-rebuild

Do not rebuild project dependencies; useful for debugging buildSrc, but "can lead to wrong results".

The security options are -F/--dependency-verification=strict|lenient|off, -M/--write-verification-metadata, --refresh-keys and --export-keys (dependency verification), and --write-locks and --update-locks (dependency locking); they are on Dependency Locking, Verification & Caching. -P and -D are the options most often mistaken for each other. In Maven -D defines a user property and -P activates profiles; in Gradle -P defines a project property and -D a JVM system property.

Source: Gradle: Environment options, Gradle: Command-line flags

Option reference

The table is the Gradle 9.8.1 ./gradlew -h output, grouped as the help groups it, with the page of this section where the option is explained when it is not on this page. "Since" shows the release that introduced options added in the 9.x line, taken from the release notes. Incubating options may change.

Option Meaning Where / since

Option	Meaning	Where / since
Help
`-h`, `-?`, `--help`	Print the built-in help.	here
`-v`, `--version`	Print version information and exit.	Installation
`-V`, `--show-version`	Print version information and continue.	here
`--`	Ends the built-in options: what follows is parsed as tasks and task options.	here
Logging
`-q`, `-w`, `-i`, `-d`, `--quiet`, `--warn`, `--info`, `--debug`	Log level.	here
`-s`, `-S`, `--stacktrace`, `--full-stacktrace`	Stack traces for exceptions.	here
`--console`, `--console-unicode`	Console mode and Unicode.	here
`--non-interactive`	Do not prompt (incubating).	here; 9.6
Configuration
`-g`, `-p`, `--project-cache-dir`, `-P`, `-D`, `-I`, `--include-build`	Environment options.	here
`--offline`, `-U`, `--refresh-dependencies`	Network and cache refresh.	here
Execution
`-x`, `--exclude-task`	Exclude a task.	here
`--continue`, `--no-continue`	Keep going after a task failure.	here
`-t`, `--continuous`	Continuous build.	here
`-m`, `--dry-run`	Print tasks without running their actions.	here
`--rerun-tasks`	Ignore up-to-date and cache results.	here
`-a`, `--no-rebuild`	Do not rebuild project dependencies.	here
Performance
`--parallel`, `--max-workers`, `--priority`	Parallelism and scheduling.	here
`--build-cache`, `--configuration-cache`, `--configuration-cache-problems`	Caches.	here
`--configure-on-demand`, `--isolated-projects`	Incubating configuration optimisations.	here
`--watch-fs`	File system watching.	here
Security
`-F`, `--dependency-verification`, `-M`, `--write-verification-metadata`, `--export-keys`, `--refresh-keys`	Dependency verification.	Dependency Locking, Verification & Caching
`--write-locks`, `--update-locks`	Dependency locking (`--update-locks` is incubating).	same page
Diagnostics
`--problems-report`, `--no-problems-report`	The HTML problems report (incubating).	here
`--profile`	Timing report.	here
`--task-graph`	Print the task graph instead of running.	here; 9.1
`--warning-mode`	`all`, `fail`, `summary`, `none`.	here
`--property-upgrade-report`	Experimental property upgrade report (incubating).	not covered
Daemon
`--daemon`, `--no-daemon`, `--foreground`, `--status`, `--stop`	Daemon control.	Gradle Daemon
Develocity
`--scan`, `--no-scan`, `--develocity-url`, `--develocity-plugin-version`	Build Scans; the last two for a private server (`--develocity-url` triggers the auto-application of the plugin).	here (not run here)

Help

-h, -?, --help

Print the built-in help.

here

-v, --version

Print version information and exit.

Installation

-V, --show-version

Print version information and continue.

here

--

Ends the built-in options: what follows is parsed as tasks and task options.

here

Logging

-q, -w, -i, -d, --quiet, --warn, --info, --debug

Log level.

here

-s, -S, --stacktrace, --full-stacktrace

Stack traces for exceptions.

here

--console, --console-unicode

Console mode and Unicode.

here

--non-interactive

Do not prompt (incubating).

here; 9.6

Configuration

-g, -p, --project-cache-dir, -P, -D, -I, --include-build

Environment options.

here

--offline, -U, --refresh-dependencies

Network and cache refresh.

here

Execution

-x, --exclude-task

Exclude a task.

here

--continue, --no-continue

Keep going after a task failure.

here

-t, --continuous

Continuous build.

here

-m, --dry-run

Print tasks without running their actions.

here

--rerun-tasks

Ignore up-to-date and cache results.

here

-a, --no-rebuild

Do not rebuild project dependencies.

here

Performance

--parallel, --max-workers, --priority

Parallelism and scheduling.

here

--build-cache, --configuration-cache, --configuration-cache-problems

Caches.

here

--configure-on-demand, --isolated-projects

Incubating configuration optimisations.

here

--watch-fs

File system watching.

here

Security

-F, --dependency-verification, -M, --write-verification-metadata, --export-keys, --refresh-keys

Dependency verification.

Dependency Locking, Verification & Caching

--write-locks, --update-locks

Dependency locking (--update-locks is incubating).

same page

Diagnostics

--problems-report, --no-problems-report

The HTML problems report (incubating).

here

--profile

Timing report.

here

--task-graph

Print the task graph instead of running.

here; 9.1

--warning-mode

all, fail, summary, none.

here

--property-upgrade-report

Experimental property upgrade report (incubating).

not covered

Daemon

--daemon, --no-daemon, --foreground, --status, --stop

Daemon control.

Gradle Daemon

Develocity

--scan, --no-scan, --develocity-url, --develocity-plugin-version

Build Scans; the last two for a private server (--develocity-url triggers the auto-application of the plugin).

here (not run here)

The tasks add options of their own (--tests, --args, --rerun, --all, --property, --configuration, --dependency, --task), listed by help --task.

Gradle 8.14 and the books

The command line of Gradle 8.14 (the last 8.x line) is the same as above for everything that is not tagged with a release in this page, but four additions are missing there. Not run here, taken from the release notes: --task-graph appeared in 9.1, tasks --provenance in 9.5, and --non-interactive and NO_COLOR in 9.6. Gradle 8.14 can run on a JVM as old as 8, while Gradle 9 needs JVM 17 or later to run the build (the wrapper, the client and the Tooling API client can still start on JVM 8); every example here started on JDK 26. How this reads for a migration from 8.14 is on Upgrading Gradle.

The command-line text of the Gradle 1.x books is only partly current:

Old text or practice Today

Old text or practice	Today
`--daemon` to opt in to the daemon	The daemon has been the default since Gradle 3.0; `--no-daemon` switches it off. See Gradle Daemon.
`-u` (`--no-search-upward`) to stop the search for `settings.gradle`	Removed in Gradle 5.0 (the upgrade notes say all builds need a settings file). Since Gradle 7.0 a build without a settings file is an error, except for `init` and diagnostic flags such as `--version`.
`--recompile-scripts`, `-Dtest.single=...`, `-Dtest.debug`	Removed in Gradle 5.0; use test filtering (`test --tests=...`) and `test --debug-jvm`.
`task name << { }` in build scripts	Removed in 5.0; see Tasks.

--daemon to opt in to the daemon

The daemon has been the default since Gradle 3.0; --no-daemon switches it off. See Gradle Daemon.

-u (--no-search-upward) to stop the search for settings.gradle

Removed in Gradle 5.0 (the upgrade notes say all builds need a settings file). Since Gradle 7.0 a build without a settings file is an error, except for init and diagnostic flags such as --version.

--recompile-scripts, -Dtest.single=..., -Dtest.debug

Removed in Gradle 5.0; use test filtering (test --tests=...) and test --debug-jvm.

task name << { } in build scripts

Removed in 5.0; see Tasks.

Source: Gradle: Upgrading from Gradle 4.x to 5.0, potential breaking changes, Gradle: Upgrading from Gradle 6.x to 7.0, Gradle 9.1.0 release notes, Gradle 9.6.0 release notes

Equivalents in Ant and Maven

Need Gradle Maven Ant

Need	Gradle	Maven	Ant
Run a named unit of work	`gradle <task>`	`mvn <phase>` or `mvn prefix:goal`	`ant <target>`
More diagnostic output	`-i`, `-d`	`-X`	`-v`, `-d`
Less output	`-q`	`-q`	`-q`, `-S`
Stack trace on failure	`-s`	`-e`	(in the `-d` output)
Define a property	`-Pname=value` (project) or `-Dname=value` (system)	`-Dname=value`	`-Dname=value`
Alternate build file or directory	`-p dir`	`-f path`	`-f file`
Exclude a task or module	`-x task`	`-pl '!module'` (excludes modules, not phases)	(no option)
Which modules to build	task selectors and project paths (`:sub:task`)	`-pl`, `-am`, `-amd`, `-rf`	`subant` in a build file
Keep going after a failure	`--continue`	`-fae`	`-k`
Offline	`--offline`	`-o`	(no option)
Refresh dependencies	`-U`	`-U`, `-UA`, `-UM`	(no option)
Parallel build	`--parallel`	`-T`	(no option)
Dry run	`-m`, `--task-graph`	(no option)	(no option)
List what the build contains	`tasks`, `projects`, `help --task`	plugin goals such as `help:effective-pom`	`-projecthelp`
Rebuild when files change	`-t`	(no option)	(no option)

Run a named unit of work

gradle <task>

mvn <phase> or mvn prefix:goal

ant <target>

More diagnostic output

-i, -d

-X

-v, -d

Less output

-q

-q, -S

Stack trace on failure

-s

-e

(in the -d output)

Define a property

-Pname=value (project) or -Dname=value (system)

-Dname=value

Alternate build file or directory

-p dir

-f path

-f file

Exclude a task or module

-x task

-pl '!module' (excludes modules, not phases)

(no option)

Which modules to build

task selectors and project paths (:sub:task)

-pl, -am, -amd, -rf

subant in a build file

Keep going after a failure

--continue

-fae

-k

Offline

--offline

-o

(no option)

Refresh dependencies

-U

-U, -UA, -UM

(no option)

Parallel build

--parallel

-T

(no option)

Dry run

-m, --task-graph

(no option)

List what the build contains

tasks, projects, help --task

plugin goals such as help:effective-pom

-projecthelp

Rebuild when files change

-t

(no option)

(The Ant column is the 1.10.18 ant -h and the Maven column the 3.10.0 mvn -h plus its documented use of -pl; the options of those tools were not run for this page, "no option" meaning that the help lists none. -pl '!module' is Maven’s way of excluding projects and is on Running Maven (CLI).) Ant’s options are on Running Ant; the wider comparison of how the three tools are driven is on Comparing Ant, Maven & Gradle, and the wrapper equivalents are on Maven Wrapper.

Command-Line Interface

The synopsis

The scratch project

Executing tasks

Task selectors and project paths

Several tasks, and their order

Task options

Name abbreviation

Choosing which tasks run

Excluding tasks: -x

Forcing tasks to run

When a task fails: --continue

Running the application

Looking at the build

Projects and tasks

Dependencies

Properties

Previewing the build: --dry-run and --task-graph

Dependencies and the network

Speed: the performance options

Output: logging, console and warnings

Log levels and stack traces

The console

Warnings and deprecations

Non-interactive mode

Continuous builds

Environment options

Option reference

Gradle 8.14 and the books

Equivalents in Ant and Maven

References