Command-Line Interface

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.

To execute a task called myTask on the root project, type:

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

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

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

You can also run a task for all subprojects using a task selector that consists of only the task name.

The following command runs the test task for all subprojects when invoked from the root project directory:

To recap:

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

You can also specify multiple tasks. The tasks' dependencies determine the precise order of execution, 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.

Although Gradle will always attempt to execute the build quickly, command line ordering safety will also be honored.

For example, the following will execute clean and build along with their dependencies:

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.

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:

You can see that the test task is not executed, even though the dist task depends on it. The test task’s dependencies, such as compileTest, are not executed either. The dependencies of test that other tasks depend on, such as compile, are still executed.

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

This will force test and all task dependencies of test to execute. It is similar to 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.

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:

When executed with --continue, Gradle executes every task in the build if all the dependencies for that task are 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.

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

The same applies to 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 fB) matches fooBar and foo-bar.

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

Abbreviations can also be used with the -x command-line option.

For complex projects, it might be ambiguous 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:

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

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

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

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

Running the projects task gives you a list of the subprojects of the selected project, displayed in a hierarchy:

You also get a project report with Build Scan.

Running gradle tasks gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task:

By default, this report shows only those tasks assigned to a task group.

Groups (such as verification, publishing, help, build…​) are available as the header of each section when listing tasks:

You can obtain more information in the task listing using the --all option:

The option --no-all can limit the report to tasks assigned to a task group.

If you need to be more precise, you can display only the tasks from a specific group using the --group option:

Running gradle help --task someTask gives you detailed information about a specific task:

This information includes the full task path, the task type, possible task-specific command line options, and the description of the given task.

You can get detailed information about the task class types using the --types option or using --no-types to hide this information.

Build Scan gives a full, visual report of what dependencies exist on which configurations, transitive dependencies, and dependency version selection. They can be invoked using the --scan options:

This will give you a link to a web-based report, where you can find dependency information like this:

Running the dependencies task gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree.

Below is an example of this report:

Concrete examples of build scripts and output available in Viewing and debugging dependencies.

Running the buildEnvironment task visualises the buildscript dependencies of the selected project, similarly to how gradle dependencies visualizes the dependencies of the software being built:

Running the dependencyInsight task gives you an insight into a particular dependency (or dependencies) that match specified input:

The --configuration parameter restricts the report to a particular configuration such as compileClasspath.

Running the properties task gives you a list of the properties of the selected project:

You can also query a single property with the optional --property argument: