////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Building Quarkus apps with Quarkus Command Line Interface (CLI)

include::./attributes.adoc[]

== Installing the CLI

The Quarkus CLI is provided as a native binary for Linux and macOS or as a jar-file for
all operating systems.

=== Native CLI

Download the binaries here:

* https://coming-soon[Linux Binary] (coming soon)
* https://coming-soon[macOS Binary] (coming soon)

We recommend that you create a specific Quarkus folder, eg '~/quarkus' and move the 
binary there. 
Then in your shell profile (for Bash shell edit '~/.bash_profile'), export the 'QUARKUS_HOME' 
folder and add that to your 'PATH':

[source,bash]
----
export QUARKUS_HOME=/path/to/quarkus-cli
export PATH="$PATH:$QUARKUS_HOME"
----

Reload your terminal or do:

[source,bash]
----
source ~/.bash_profile
----

Now you can run the Quarkus CLI:

[source,shell]
----
$ quarkus --help
----

This will display the help information with all the available commands.

[source,shell]
----
$ quarkus -i
----

This will start the Quarkus CLI in interactive mode.

=== Jar CLI

Download the jar-file here:
* https://coming-soon[jar-file] (coming soon)

As with the native CLI we recommend that you copy the binary to a specific folder, eg '~/quarkus'.
The jar file requires Java 8 or newer to run. To start the CLI:

[source,shell]
----
$ java -jar quarkus-cli.jar
----

The jar file CLI accepts all the same options and commands as the native binary.

Note: In the examples below switch out 'quarkus' with 'java -jar quarkus-cli.jar'.


[[project-creation]]
== Creating a new project

To create a new project we use the create-project command:

[source,shell]
----
$ quarkus create-project hello-world
----

This will create a folder called 'hello-world' in your current working directory using default
groupId, artifactId and version values 
(groupId='org.acme', artifactId='quarkus' and version='1.0.0-SNAPSHOT').

To specify the groupId, artifactId and version values, 
use the '--groupid', '--artifactid' and '--version' options:

[source,shell]
----
$ quarkus create-project --groupid=com.foo --artifactId=bar --version=1.0  hello-world
----


Use the help option to display all the possible options:

[source,shell]
----
$ quarkus create-project --help
----

== Dealing with extensions

The Quarkus CLI can obtain a list of the available extensions with:

[source,shell]
----
$ quarkus list-extensions
----

To more easily get an overview and only display the extension names:

[source,shell]
----
$ quarkus list-extensions -n
----


== Adding extension(s)

The Quarkus CLI can add Quarkus extensions to your project with the 'add-extension'
command:

[source,shell]
----
$ quarkus add-extension --extension=hibernate-validator /path/to/my/project
----

The argument path either needs to be the base folder for the project or a direct path to the 
build file.

== Development mode

To start dev mode from the Quarkus CLI do:

[source,shell]
----
$ quarkus dev /path/to/my/project
----

As with 'add-extension' the argument path needs to be the base folder for the project or a 
direct path to the build file.


