Suppose we have a custom task with some properties that can be configured. Normally we would add the configuration in the build script. But we can also use command line options to configure a task. So when we run the task from the command line we can provide a configuration value for the task on the command line. To see which command line options are available for a task we can use the Gradle built-in task help followed by the option --task and the task name. To indicate a property as command line option we use a @Option annotation. We can specify the name of the command line option, a short description and also the order that is used to display the options with the help task.

Let's create a sample custom task and use the @Option annotation. In the following build file we create a custom task GenerateVersionFile. This task generates a file with a default name of version.txt in the build/ directory. The file contains the project version value. We make the property that defines the output filename as a command line option. This way the name can be defined when we run Gradle (and still of course using the default configuration in a build file).

// Import Option annotation
import org.gradle.api.internal.tasks.options.Option

version = 'demo'

// Create a task of the custom task type GenerateVersionFile.
task generateVersionFile(type: GenerateVersionFile)

 * Custom task to generate a version value in a file.
class GenerateVersionFile extends DefaultTask {

    String version

    // Specify outputFile property as
    // command line option.
    // Use as --outputFile filename.
    @Option(option = "outputFile",
            description = "File to store the project version in",
            order = 1)
    Object outputFile

    GenerateVersionFile() {
        // Set default value for outputFile as version.txt.
        outputFile = 'version.txt'

        // Description for the task.
        description = 'Generate a file with the project version'

    void generate() {
        // Create directory for the output file if
        // it doesn't exist.
        final File versionFileDestination = getOutputFile()

        // Save version in file.
        versionFileDestination.text = getVersion()

    String getVersion() {
        return project.version

    File getOutputFile() {
        return new File(project.buildDir, outputFile)


If we run the help task for the generateVersionFile task we can see that our command line option is shown in the list of available options:

$ gradle help --task generationVersionFile
Detailed task information for generateVersionFile


     GenerateVersionFile (GenerateVersionFile)

     --outputFile     File where the project version is stored

     Generate a file with the project version



Total time: 2.933 secs

Now we invoke the generateVersionFile task with a value for the command line option:

$ gradle generateVersionFile --outputFile version.saved


Total time: 0.826 secs
$ more build/version.saved

Written with Gradle 3.1.

Original blog post