The Quarkus CLI, quarkus, lets you create projects, manage extensions and do essential build and dev commands using the underlying project’s build tool.

This technology is considered experimental.

In experimental mode, early feedback is requested to mature the idea. There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker.

For a full list of possible extension statuses, check our FAQ entry.

Installing the CLI

The Quarkus CLI is currently available as a jar installable using jbang.

On Linux, macOS, and Windows (using WSL or bash compatible shell like cygwin or mingw)

curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio

On Windows using Powershell:

iex "& { $(iwr https://ps.jbang.dev) } app install --fresh --force quarkus@quarkusio"

If jbang has already been installed, you can it directly:

# This can also be used to update to the latest version
$ jbang app install --fresh --force quarkus@quarkusio
# Use the latest (or locally built) snapshot (with qss as an alias)
$ jbang app install --force --name qss io.quarkus:quarkus-cli:999-SNAPSHOT:runner

Note: 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.

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

$ quarkus --version
Client Version {quarkus-version}

Using the CLI

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

$ quarkus --help
Usage: quarkus [-ehV] [--verbose] [COMMAND]
  -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.
  build            Build the current project.
  dev              Run the current project in dev (live coding) mode.
  extension, ext   List, add, and remove extensions of an existing project.
    add            Extension(s) to add to this project.
    list, ls       List platforms and extensions for this project.
    remove, rm     Remove extension(s) from this project.
  completion       bash/zsh completion:  source <(quarkus completion)
  version          Display version information

Creating a new project

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

$ 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').

To specify the groupId, artifactId and version values, use the '--group-id', '--artifact-id' and '--version' options:

$ quarkus create app --group-id com.foo --artifact-id bar --version 1.0
version 1.0
-----------

applying codestarts...
🔠 java
🧰 maven
🗃 quarkus
📜 config-properties
🛠 dockerfiles
🛠 maven-wrapper
🐒 resteasy-codestart

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

-g,-a,-v are short hand options for the full name counterparts: --group-id,--artifact-id and --version. We use both short and full names in this guide interchangeably.

Use the help option to display options for creating projects:

$ quarkus create app --help
$ quarkus create cli --help

Note: Use --platform-bom=groupId:artifactId:version to target a specific version of quarkus

Dealing with extensions

$ quarkus ext --help

The Quarkus CLI can obtain a list of the extensions in the project:

$ quarkus ext ls

To get a list of available extensions to install use --installable or -i.

You can combine that with a search (--search or -s) and get a concise list including description with --concise.

$ quarkus ext list -i --concise -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:

$ 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 add Quarkus one or more extensions to your project with the 'add' command:

$ 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):

$ 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:

$ quarkus dev                                                                 ??return_code?
[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).