The command-line interface is one of the primary methods of interacting with Gradle. The following serves as a reference of executing and customizing Gradle use of a command-line or when writing scripts or configuring continuous integration.

Use of the Gradle Wrapper is highly encouraged. You should substitute ./gradlew or gradlew.bat for gradle in all following examples when using the Wrapper.

Executing Gradle on the command-line conforms to the following structure. Options are allowed before and after task names.

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

If multiple tasks are specified, they should be separated with a space.

Options that accept values can be specified with or without = between the option and argument; however, use of = is recommended.

--console=plain

Options that enable behavior have long-form options with inverses specified with --no-. The following are opposites.

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

Many long-form options, have short option equivalents. The following are equivalent:

--help
-h

Many command-line flags can be specified in gradle.properties to avoid needing to be typed. See the configuring build environment guide for details.

The following sections describe use of the Gradle command-line interface, grouped roughly by user goal. Some plugins also add their own command line options, for example --tests for Java test filtering. For more information on exposing command line options for your own tasks, see Declaring and using command-line options.

Executing tasks

You can learn about what projects and tasks are available in the project reporting section. Most builds support a common set of tasks known as lifecycle tasks. These include the build, assemble, and check tasks.

In order to execute a task called "myTask" on the root project, type:

$ gradle :myTask

This will run the single "myTask" and also all of its task dependencies.

Specify options for a task

To pass an option to a task, prefix the option name with -- after the task name:

$ gradle exampleTask --exampleOption=exampleValue

Disambiguate task options from built-in options

Gradle does not prevent tasks from registering options that conflict with Gradle’s built-in options, like --profile or --help. You can disambiguate conflicting task options from Gradle’s built-in options with a -- delimiter before the task name in your command:

$ gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]

Consider a task named "mytask" that accepts an option named "profile":

  • If you run gradle mytask --profile, Gradle accepts --profile as the built-in Gradle option.

  • If you run gradle — mytask --profile=exampleValue, Gradle passes --profile as a task option.

Executing tasks in multi-project builds

In a multi-project build, subproject tasks can be executed with ":" separating subproject name and task name. The following are equivalent when run from the root project:

$ gradle :my-subproject:taskName
$ gradle my-subproject:taskName

You can also run a task for all subprojects by using a task selector that consists of the task name only. For example, this will run the "test" task for all subprojects when invoked from the root project directory:

$ gradle test

Some tasks selectors, like help or dependencies, will only run the task on the project they are invoked on and not on all the subprojects. The main motivation for this is that these tasks print out information that would be hard to process if it combined the information from all projects.

When invoking Gradle from within a subproject, the project name should be omitted:

$ cd my-subproject
$ gradle taskName

When executing the Gradle Wrapper from subprojects, one must reference gradlew relatively. For example: ../gradlew taskName. The community gdub project aims to make this more convenient.

Executing multiple tasks

You can also specify multiple tasks. The tasks will be executed as quickly as possible while still honoring task dependencies. Precise order of execution is determined by the tasks' dependencies, and a task having no dependencies may execute earlier than it is listed on the command-line. For example, the following will execute the test and deploy tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.

$ gradle test deploy

Command line order safety

Although Gradle will always attempt to execute the build as quickly as possible, command line ordering safety will also be honored. For example, the following will execute clean and build along with their dependencies.

$ gradle clean build

However, the intention implied in the command line order is that clean should run first, and then build. It would be incorrect to execute clean after build, even if doing so would cause the build to execute faster, since clean would remove what build created. Conversely, if the command line order was build followed by clean, it would not be correct to execute clean before build. Although Gradle will execute the build as quickly as possible, it will also respect the safety of the order of tasks specified on the command line and ensure that clean runs before build when specified in that order.

Note that command line order safety relies on tasks properly declaring what they create, consume or remove. See up-to-date checks for further information.

Excluding tasks from execution

You can exclude a task from being executed using the -x or --exclude-task command-line option and providing the name of the task to exclude.

commandLineTutorialTasks
Figure 1. Simple Task Graph
Excluding tasks
$ gradle dist --exclude-task test

> Task :compile
compiling source

> Task :dist
building the distribution

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

You can see that the test task is not executed, even though it is a dependency of the dist task. The test task’s dependencies such as compileTest are not executed either. Those dependencies of test that are required by another task, such as compile, are still executed.

Forcing tasks to execute

You can force Gradle to execute all tasks ignoring up-to-date checks using the --rerun-tasks option:

$ gradle test --rerun-tasks

This will force test and all task dependencies of test to execute. It’s a little like running gradle clean test, but without the build’s generated output being deleted.

Alternatively, you can tell Gradle to rerun a specific task using the --rerun built-in task option.

Continue the build after a task failure

By default, Gradle aborts execution and fails the build when any task fails. This allows the build to complete sooner and prevents cascading failures from obfuscating the root cause of an error. You can use the --continue option to force Gradle to execute every task when a failure occurs:

$ gradle test --continue

When executed with --continue, Gradle executes every task in the build if all of the dependencies for that task completed without failure. For example, tests do not run if there is a compilation error in the code under test because the test task depends on the compilation task. Gradle outputs each of the encountered failures at the end of the build.

Many test suites fail the entire "test" task if any tests fail. Code coverage and reporting tools frequently run after the test task, so this "fail fast" behavior may halt execution before those tools run.

Name abbreviation

When you specify tasks on the command-line, you don’t have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, it’s likely gradle che is enough for Gradle to identify the check task.

The same applies for project names. You can execute the check task in the library subproject with the gradle lib:che command.

You can use camel case patterns for more complex abbreviations. These patterns are expanded to match camel case and kebab case names. For example the pattern foBa (or even fB) matches fooBar and foo-bar.

More concretely, you can run the compileTest task in the my-awesome-library subproject with the gradle mAL:cT command.

Abbreviated project and task names
$ gradle  mAL:cT

> Task :my-awesome-library:compileTest
compiling unit tests

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

You can also use these abbreviations with the -x command-line option.

Tracing name expansion

For complex projects, it might not be obvious if the intended tasks were executed. When using abbreviated names, a single typo can lead to the execution of unexpected tasks.

When INFO, or more verbose logging is enabled, the output will contain extra information about the project and task name expansion. For example, when executing the mAL:cT command on the previous example, the following log messages will be visible:

No exact project with name ‘:mAL’ has been found. Checking for abbreviated names.
Found exactly one project that matches the abbreviated name ‘:mAL’: ':my-awesome-library'.
No exact task with name ‘:cT’ has been found. Checking for abbreviated names.
Found exactly one task name, that matches the abbreviated name ‘:cT’: ':compileTest'.

Common tasks

The following are task conventions applied by built-in and most major Gradle plugins.

Computing all outputs

It is common in Gradle builds for the build task to designate assembling all outputs and running all checks.

$ gradle build

Running applications

It is common for applications to be run with the run task, which assembles the application and executes some script or binary.

$ gradle run

Running all checks

It is common for all verification tasks, including tests and linting, to be executed using the check task.

$ gradle check

Cleaning outputs

You can delete the contents of the build directory using the clean task, though doing so will cause pre-computed outputs to be lost, causing significant additional build time for the subsequent task execution.

$ gradle clean