<appendix id='gradle_command_line'>
    <title>Gradle Command Line</title>
    <para>The
        <command>gradle</command>
        command has the following usage:
        <cmdsynopsis>
            <command>gradle</command>
            <arg choice="opt" rep="repeat">option</arg>
            <arg choice="opt" rep="repeat">task</arg>
        </cmdsynopsis>
        The command-line options available for the
        <command>gradle</command>
        command are listed below:
    </para>
    <variablelist>
        <varlistentry>
            <term><option>-?</option>, <option>-h</option>, <option>--help</option>
            </term>
            <listitem>
                <para>Shows a help message.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-a</option>, <option>--no-rebuild</option>
            </term>
            <listitem>
                <para>Do not rebuild project dependencies.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--all</option>
            </term>
            <listitem>
                <para>Shows additional detail in the task listing. See <xref linkend="sec:listing_tasks"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-b</option>, <option>--build-file</option>
            </term>
            <listitem>
                <para>Specifies the build file. See <xref linkend="sec:selecting_build"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-c</option>, <option>--settings-file</option>
            </term>
            <listitem>
                <para>Specifies the settings file.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--console</option>
            </term>
            <listitem>
                <para>Specifies which type of console output to generate.</para>
                <para>Set to <literal>plain</literal> to generate plain text only. This option disables all color and other rich output in the console output.</para>
                <para>Set to <literal>auto</literal> (the default) to enable color and other rich output in the console output when
                    the build process is attached to a console, or to generate plain text only when not attached to a console.</para>
                <para>Set to <literal>rich</literal> to enable color and other rich output in the console output,
                    regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control
                    characters to generate the rich output.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--continue</option>
            </term>
            <listitem>
                <para>Continues task execution after a task failure.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--configure-on-demand (incubating)</option>
            </term>
            <listitem>
                <para>Only relevant projects are configured in this build run. This means faster builds for large multi-projects.
                    See <xref linkend="sec:configuration_on_demand"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-D</option>, <option>--system-prop</option>
            </term>
            <listitem>
                <para>Sets a system property of the JVM, for example <literal>-Dmyprop=myvalue</literal>.
                    See <xref linkend="sec:gradle_properties_and_system_properties"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-d</option>, <option>--debug</option>
            </term>
            <listitem>
                <para>Log in debug mode (includes normal stacktrace). See <xref linkend="logging"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-g</option>, <option>--gradle-user-home</option>
            </term>
            <listitem>
                <para>Specifies the Gradle user home directory. The default is the
                    <filename>.gradle</filename>
                    directory in the user's home directory.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--gui</option>
            </term>
            <listitem>
                <para>Launches the Gradle GUI. See <xref linkend="tutorial_gradle_gui"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-I</option>, <option>--init-script</option>
            </term>
            <listitem>
                <para>Specifies an initialization script. See <xref linkend="init_scripts"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-i</option>, <option>--info</option>
            </term>
            <listitem>
                <para>Set log level to info. See <xref linkend="logging"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-m</option>, <option>--dry-run</option>
            </term>
            <listitem>
                <para>Runs the build with all task actions disabled. See <xref linkend="sec:dry_run"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--offline</option>
            </term>
            <listitem>
                <para>Specifies that the build should operate without accessing network resources. See <xref linkend="sec:cache_command_line_options"/>.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-P</option>, <option>--project-prop</option>
            </term>
            <listitem>
                <para>Sets a project property of the root project, for example
                    <literal>-Pmyprop=myvalue</literal>. See <xref linkend="sec:gradle_properties_and_system_properties"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-p</option>, <option>--project-dir</option>
            </term>
            <listitem>
                <para>Specifies the start directory for Gradle. Defaults to current directory.
                    See <xref linkend="sec:selecting_build"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--parallel (incubating)</option>
            </term>
            <listitem>
                <para>
                    Build projects in parallel. Gradle will attempt to determine the optimal number of executor threads to use.
                    This option should only be used with decoupled projects (see <xref linkend="sec:decoupled_projects"/>).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--max-workers (incubating)</option>
            </term>
            <listitem>
                <para>
                    Sets the maximum number of workers that Gradle may use. For example<literal>--max-workers=3</literal>.  The default is the number of processors.
                    This option replaces <literal>--parallel-threads</literal> when used in conjuction with <literal>--parallel</literal>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--profile</option>
            </term>
            <listitem>
                <para>Profiles build execution time and generates a report in the
                    <filename><replaceable>buildDir</replaceable>/reports/profile</filename>
                    directory. See <xref linkend="sec:profiling_build"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--project-cache-dir</option>
            </term>
            <listitem>
                <para>Specifies the project-specific cache directory. Default value is
                    <filename>.gradle</filename>
                    in the root project directory. See <xref linkend="sec:caching"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-q</option>, <option>--quiet</option>
            </term>
            <listitem>
                <para>Log errors only. See <xref linkend="logging"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--recompile-scripts</option>
            </term>
            <listitem>
                <para>Forces scripts to be recompiled, bypassing caching.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--refresh-dependencies</option>
            </term>
            <listitem>
                <para>Refresh the state of dependencies.
                    See <xref linkend="sec:cache_command_line_options"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>--rerun-tasks</option>
            </term>
            <listitem>
                <para>Specifies that any task optimization is ignored.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-S</option>, <option>--full-stacktrace</option>
            </term>
            <listitem>
                <para>Print out the full (very verbose) stacktrace for any exceptions. See <xref linkend="logging"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-s</option>, <option>--stacktrace</option>
            </term>
            <listitem>
                <para>Print out the stacktrace also for user exceptions (e.g. compile error). See <xref linkend="logging"/>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term>
                <option>-t</option>, <option>--continuous (incubating)</option>
            </term>
            <listitem>
                <para>Enables <link linkend="continuous_build">continuous building</link> - Gradle will automatically re-run when changes are detected.</para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-u</option>, <option>--no-search-upwards</option>
            </term>
            <listitem>
                <para>Don't search in parent directories for a
                    <filename>settings.gradle</filename>
                    file.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-v</option>, <option>--version</option>
            </term>
            <listitem>
                <para>Prints version info.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><option>-x</option>, <option>--exclude-task</option>
            </term>
            <listitem>
                <para>Specifies a task to be excluded from execution. See <xref linkend="sec:excluding_tasks_from_the_command_line"/>.
                </para>
            </listitem>
        </varlistentry>
    </variablelist>
    <para>The above information is printed to the console when you execute <userinput>gradle -h</userinput>.
    </para>

    <section>
        <title>Deprecated command-line options</title>
        <variablelist>
            <varlistentry>
                <term>
                    <option>--no-color</option>
                </term>
                <listitem>
                    <para>Do not use color in the console output. This option has been replaced by the <option>--console plain</option> option.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <option>--parallel-threads</option>
                </term>
                <listitem>
                    <para>
                        Build projects in parallel, using the specified number of executor threads.
                        For example<literal>--parallel-threads=3</literal>.
                        This option should only be used with decoupled projects (see <xref linkend="sec:decoupled_projects"/>).
                        This option has been replaced by <literal>--max-workers</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>

    <section id='daemon_cli'>
        <title>Daemon command-line options</title>
        <para>The
            <xref linkend="gradle_daemon"/>
            contains more information about the daemon.
            For example it includes information how to turn on the daemon by default
            so that you can avoid using
            <literal>--daemon</literal>
            all the time.
        </para>
        <variablelist>
            <varlistentry>
                <term>
                    <option>--daemon</option>
                </term>
                <listitem>
                    <para>Uses the Gradle daemon to run the build.
                        Starts the daemon if not running or existing daemon busy.
                        <xref linkend="gradle_daemon"/>
                        contains more detailed
                        information when new daemon processes are started.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <option>--foreground</option>
                </term>
                <listitem>
                    <para>Starts the Gradle daemon in the foreground. Useful for debugging or troubleshooting
                        because you can easily monitor the build execution.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <option>--no-daemon</option>
                </term>
                <listitem>
                    <para>Do not use the Gradle daemon to run the build.
                        Useful occasionally if you have configured Gradle to always run with the daemon by default.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <option>--stop</option>
                </term>
                <listitem>
                    <para>Stops the Gradle daemon if it is running.
                        You can only stop daemons that were started with
                        the Gradle version you use when running <literal>--stop</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>

    <section>
        <title>System properties</title>
        <para>The following system properties are available for the
            <command>gradle</command>
            command. Note that
            command-line options take precedence over system properties.
        </para>
        <varlistentry>
            <term>
                <literal>gradle.user.home</literal>
            </term>
            <listitem>
                <para>Specifies the Gradle user home directory.</para>
            </listitem>
        </varlistentry>
        <para>The
            <xref linkend="sec:gradle_configuration_properties"/>
            contains specific information about
            Gradle configuration available via system properties.
        </para>
    </section>

    <section>
        <title>Environment variables</title>
        <para>The following environment variables are available for the
            <command>gradle</command>
            command. Note that
            command-line options and system properties take precedence over environment variables.
        </para>
        <variablelist>
            <varlistentry>
                <term>
                    <literal>GRADLE_OPTS</literal>
                </term>
                <listitem>
                    <para>Specifies command-line arguments to use to start the JVM. This can be useful for setting
                        the system properties to use for running Gradle. For example you could set
                        <literal>GRADLE_OPTS="-Dorg.gradle.daemon=true"</literal>
                        to use the Gradle daemon without needing to use the
                        <option>--daemon</option>
                        option every time you
                        run Gradle.
                        <xref linkend="sec:gradle_configuration_properties"/>
                        contains more information about ways of configuring the daemon
                        without using environmental variables, e.g. in more maintainable and explicit way.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <literal>GRADLE_USER_HOME</literal>
                </term>
                <listitem>
                    <para>Specifies the Gradle user home directory (which defaults to “<literal>USER_HOME/.gradle</literal>” if not set).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>
                    <literal>JAVA_HOME</literal>
                </term>
                <listitem>
                    <para>Specifies the JDK installation directory to use.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </section>
</appendix>
