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

include::./attributes.adoc[]

The `quarkus` command lets you create projects, manage extensions and
do essential build and dev commands using the underlying project build tool.

include::./status-include.adoc[]

== Installing the CLI

The Quarkus CLI is available in several developer-oriented package managers such as:

* https://sdkman.io[SDKMAN!]
* https://brew.sh[Homebrew]
* https://community.chocolatey.org/packages/quarkus[Chocolatey]

If you already use (or want to use) one of these tools, it is the simplest way to install the Quarkus CLI and keep it updated.

In addition to these package managers, the Quarkus CLI is also installable via https://www.jbang.dev[JBang].
Choose the alternative that is the most practical for you:

* JBang - for Linux, macOS and Windows
* SDKMAN! - for Linux and macOS
* Homebrew - for Linux and macOS
* Chocolatey - for Windows

[role="primary asciidoc-tabs-sync-jbang"]
.JBang
****
The Quarkus CLI is available as a jar installable using https://jbang.dev[JBang]. 

JBang will use your existing Java or install one for you if needed.

On Linux, macOS, and Windows (using WSL or bash compatible shell like Cygwin or MinGW)
[source,bash]
----
curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio
----

On Windows using Powershell:
[source,powershell]
----
iex "& { $(iwr https://ps.jbang.dev) } trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/"
iex "& { $(iwr https://ps.jbang.dev) } app install --fresh --force quarkus@quarkusio"
----

If JBang has already been installed, you can directly use it:
[source,bash]
----
# This can also be used to update to the latest version
jbang app install --fresh --force quarkus@quarkusio
----

If you want to use a specific version, you can directly target a version:
[source,bash]
----
# Create an alias in order to use a specific version
jbang app install --name qs2.2.5 io.quarkus:quarkus-cli:2.2.5.Final:runner
----

If you have built Quarkus locally, you can use that version:
[source,bash]
----
# Use the latest (or locally built) snapshot (with qss as an alias)
jbang app install --force --name qss ~/.m2/repository/io/quarkus/quarkus-cli/999-SNAPSHOT/quarkus-cli-999-SNAPSHOT-runner.jar
----

Once installed `quarkus` will be in your `$PATH` and if you run `quarkus --version` it will print the installed version:

[source,shell,subs=attributes+]
----
quarkus --version
{quarkus-version}
----

[CAUTION]
.Use a recent JBang version
====
If you get an error about `app` not being readable then you probably
have a JBang version older than v0.56.0 installed. Please remove or upgrade it to a recent version.

If you are installing JBang for the first time, start a new session to update your `PATH`.
====
****

[role="secondary asciidoc-tabs-sync-sdkman"]
.SDKMAN!
****
https://sdkman.io/[SDKMAN!] can be used to manage development environments.
It can manage parallel versions of multiple Software Development Kits on most Unix based systems,
making it a very good alternative to keep multiple JDK versions handy.

With SDKMAN!, you can also install popular Java tools, including the Quarkus CLI.

[NOTE]
====
Make sure you have https://sdkman.io/jdks[a JDK installed] before installing the Quarkus CLI.

To list the available versions of Java, use `sdk list java`.
You can then install the version of OpenJDK you want with `sdk install java x.y.z-open`
(or the JDK of another vendor if it is your preference).
====

To install the Quarkus CLI using SDKMAN!, run the following command:

[source,shell]
----
sdk install quarkus
----

It will install the latest version of the Quarkus CLI.

Once installed `quarkus` will be in your `$PATH` and if you run `quarkus --version` it will print the installed version:

[source,shell,subs=attributes+]
----
quarkus --version
{quarkus-version}
----

SDKMAN! will let you know when new versions are available so updates will be straightforward:

[source,shell]
----
sdk upgrade quarkus
----
****

[role="secondary asciidoc-tabs-sync-homebrew"]
.Homebrew
****
https://brew.sh[Homebrew] is a package manager for macOS (and Linux).

You can use Homebrew to install (and update) the Quarkus CLI.

[NOTE]
====
Make sure you have a JDK installed before installing the Quarkus CLI.
We haven't added an explicit dependency as we wanted to make sure you could use your preferred JDK version.

You can install a JDK with `brew install openjdk` for Java 17 or `brew install openjdk@11` for Java 11.
====

To install the Quarkus CLI using Homebrew, run the following command:

[source,shell]
----
brew install quarkusio/tap/quarkus
----

It will install the latest version of the Quarkus CLI.
This command can also be used to update the Quarkus CLI.

Once installed `quarkus` will be in your `$PATH` and if you run `quarkus --version` it will print the installed version:

[source,shell,subs=attributes+]
----
quarkus --version
{quarkus-version}
----

You can upgrade the Quarkus CLI with:

[source,shell]
----
brew update <1>
brew upgrade quarkus <2>
----
<1> Update all package definitions and Homebrew itself
<2> Upgrade Quarkus CLI to the latest version
****

[role="secondary asciidoc-tabs-sync-chocolatey"]
.Chocolatey
****
https://chocolatey.org[Chocolatey] is a package manager for Windows.

You can use Chocolatey to install (and update) the Quarkus CLI.

[NOTE]
====
Make sure you have a JDK installed before installing the Quarkus CLI.

You can install a JDK with `choco install ojdkbuild17` for Java 17 or `choco install ojdkbuild11` for Java 11.
====

To install the Quarkus CLI using Chocolatey, run the following command:

[source,shell]
----
choco install quarkus
----

It will install the latest version of the Quarkus CLI.

Once installed `quarkus` will be in your `$PATH` and if you run `quarkus --version` it will print the installed version:

[source,shell,subs=attributes+]
----
quarkus --version
{quarkus-version}
----

You can upgrade the Quarkus CLI with:

[source,shell]
----
choco upgrade quarkus
----
****

== Using the CLI

Use `--help` to display help information with all the available commands:

[source,shell]
----
quarkus --help
Usage: quarkus [-ehv] [--verbose] [-D=<String=String>]... [COMMAND]

Options:
  -D=<String=String>    Java properties
  -e, --errors          Display error messages.
  -h, --help            Show this help message and exit.
  -v, --version         Print version information and exit.
      --verbose         Verbose mode.

Commands:
  create                  Create a new project.
    app                   Create a Quarkus application project.
    cli                   Create a Quarkus command-line project.
    extension             Create a Quarkus extension project
  build                   Build the current project.
  dev                     Run the current project in dev (live coding) mode.
  extension, ext          Configure extensions of an existing project.
    list, ls              List platforms and extensions.
    categories, cat       List extension categories.
    add                   Add extension(s) to this project.
    remove, rm            Remove extension(s) from this project.
  registry                Configure Quarkus registry client
    list                  List enabled Quarkus registries
    add                   Add a Quarkus extension registry
    remove                Remove a Quarkus extension registry
  version                 Display version information.
----

[TIP]
====
While this document is a useful reference, the client help is the definitive source.

If you don't see the output you expect, use `--help` to verify that you are invoking the command with the right arguments.
====

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

To create a new project we use the `create` command
(the `app` subcommand is implied when not specified):

[source,shell]
----
quarkus create
-----------

applying codestarts...
📚  java
🔨  maven
📦  quarkus
📝  config-properties
🔧  dockerfiles
🔧  maven-wrapper
🚀  resteasy-codestart

-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/code-with-quarkus
----

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

Note: the emoji shown above may not match precisely. The appearance of emoji can vary by font, and terminal/environment. IntelliJ IDEA, for example, has several long-running issues open regarding the behavior/rendering of emoji in the terminal.

As of 2.0.2.Final, you should specify the groupId, artifactId and version using group:artifactId:version coordinate syntax directly on the command line. You can selectively omit segments to use default values:

[source,shell]
----
# Create a project with groupId=org.acme, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app bar

# Create a project with groupId=com.foo, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app com.foo:bar

# Create a project with groupId=com.foo, artifactId=bar, and version=1.0
quarkus create app com.foo:bar:1.0
----

The output will show your project being created:

[source,shell]
----
-----------

applying codestarts...
📚  java
🔨  maven
📦  quarkus
📝  config-properties
🔧  dockerfiles
🔧  maven-wrapper
🚀  resteasy-codestart

-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/bar
-----------
----

Use the help option to display options for creating projects:

[source,shell]
----
quarkus create app --help
quarkus create cli --help
----

[WARNING]
====
Previous versions of the CLI used options `--group-id` (`-g`),`--artifact-id` (`-a`) and `--version` (`-v`) to specify the groupId, artifactId, and version. If the output isn't what you expect, double check your client version `quarkus version` and help `quarkus create app --help`.
====

[[specifying-quarkus-version]]
=== Specifying the Quarkus version

Both `quarkus create` and `quarkus extension list` allow you to explicitly specify a version of Quarkus in one of two ways:

1. Specify a specific Platform Release BOM
+
A https://quarkus.io/guides/platform#quarkus-platform-bom[Quarkus Platform release BOM] is identified by `groupId:artifactId:version` (GAV) coordinates. When specifying a platform release BOM, you may use empty segments to fallback to default values (shown with `quarkus create app --help`). If you specify only one segment (no `:`), it is assumed to be a version.
+
For example:
+
- With the `2.0.0.Final` version of the CLI, specifying `-P :quarkus-bom:` is equivalent to `-P io.quarkus:quarkus-bom:2.0.0.Final`. Specifying `-P 999-SNAPSHOT` is equivalent to `-P io.quarkus:quarkus-bom:999-SNAPSHOT`.
- With the `2.1.0.Final` version of the CLI, `io.quarkus.platform` is the default group id. Specifying `-P :quarkus-bom:` is equivalent to `-P io.quarkus.platform:quarkus-bom:2.1.0.Final`. Note that you need to specify the group id to work with a snapshot, e.g `-P io.quarkus::999-SNAPSHOT` is equivalent to `-P io.quarkus:quarkus-bom:999-SNAPSHOT`.
+
Note: default values are subject to change. Using the `--dry-run` option will show you the computed value.

2. Specify a Platform Stream
+
A platform stream operates against a remote registry. Each registry defines one or more platform streams, and each stream defines one or more platform release BOM files that define how projects using that stream should be configured.
+
Streams are identified using `platformKey:streamId` syntax. A specific stream can be specified using `-S platformKey:streamId`. When specifying a stream, empty segments will be replaced with _discovered_ defaults, based on stream resource resolution rules.

=== Working with extensions

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

==== Listing extensions

The Quarkus CLI can be used to list Quarkus extensions.

[source,shell]
----
quarkus ext ls
----

The format of the result can be controlled with one of four options: 

- `--name`    Display the name (artifactId) only
- `--concise` Display the name (artifactId) and description
- `--full`    Display concise format and version/status-related columns.
- `--origins` Display concise information along with the Quarkus platform release origin of the extension.

The behavior of `quarkus ext ls` will vary depending on context.

===== Listing Extensions for a Quarkus release

If you invoke the Quarkus CLI from outside of a project, Quarkus will list all of the extensions available for the Quarkus release used by the CLI itself.

You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in <<specifying-quarkus-version,Specifying the Quarkus version>>.

This mode uses the `--origins` format by default.

===== Listing Extensions for a Quarkus project

When working with a Quarkus project, the CLI will list the extensions the current project has installed, using the `--name` format by default.

Use the `--installable` or `-i` option to list extensions that can be installed from the Quarkus platform the project is using.

You can narrow or filter the list using search (`--search` or `-s`).

[source,shell]
----
quarkus ext list --concise -i -s jdbc
JDBC Driver - DB2                                  quarkus-jdbc-db2
JDBC Driver - PostgreSQL                           quarkus-jdbc-postgresql
JDBC Driver - H2                                   quarkus-jdbc-h2
JDBC Driver - MariaDB                              quarkus-jdbc-mariadb
JDBC Driver - Microsoft SQL Server                 quarkus-jdbc-mssql
JDBC Driver - MySQL                                quarkus-jdbc-mysql
JDBC Driver - Oracle                               quarkus-jdbc-oracle
JDBC Driver - Derby                                quarkus-jdbc-derby
Elytron Security JDBC                              quarkus-elytron-security-jdbc
Agroal - Database connection pool                  quarkus-agroal
----


==== Adding extension(s)

The Quarkus CLI can add Quarkus one or more extensions to your project with the 'add'
command:

[source,shell]
----
quarkus ext add kubernetes health
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been installed
[SUCCESS] ✅ Extension io.quarkus:quarkus-smallrye-health has been installed
----

==== Removing extension(s)

The Quarkus CLI can remove one or more extensions from your project with the 'remove'
command:

[source,shell]
----
quarkus ext rm kubernetes
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been uninstalled
----

=== Build your project

To build your project using the Quarkus CLI (using the default configuration in this example):

[source,shell]
----
quarkus build
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.331 s
[INFO] Finished at: 2021-05-27T10:13:28-04:00
[INFO] ------------------------------------------------------------------------
----

NOTE: Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang).

=== Development mode

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

To start dev mode from the Quarkus CLI do:

[source,shell]
----
quarkus dev
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >---------------------
[INFO] Building code-with-quarkus 1.0.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
...
Listening for transport dt_socket at address: 5005
__  ____  __  _____   ___  __ ____  ______
--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2021-05-27 10:15:56,032 INFO  [io.quarkus] (Quarkus Main Thread) code-with-quarkus 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.387s. Listening on: http://localhost:8080
2021-05-27 10:15:56,035 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2021-05-27 10:15:56,035 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, resteasy, smallrye-context-propagation]

--
Tests paused, press [r] to resume
----

NOTE: Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang).


[[quarkus-version-compatibility]]
[WARNING]
.Compatibility with Quarkus 1.x
====
The version 2 Quarkus CLI can not be used with 1.x Quarkus projects or releases. Use the Maven/Gradle plugins when working with Quarkus 1.x projects.
====

== Shell autocomplete and aliases

Automatic command completion is available for Bash and Zsh:

[source,shell]
----
# Setup autocompletion in the current shell
source <(quarkus completion)
----

If you choose to use an alias for the quarkus command, adjust command completion with the following commands:

[source,shell]
----
# Add an alias for the quarkus command
alias q=quarkus
# Add q to list of commands included in quarkus autocompletion
complete -F _complete_quarkus q
----
