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 ~/.m2/repository/io/quarkus/quarkus-cli/999-SNAPSHOT/quarkus-cli-999-SNAPSHOT-runner.jar
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 Add extension(s) 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
While this document is a useful reference, the client help is the definitive source. If you don’t see the output you expect, use |
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').
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:
# 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:
-----------
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:
quarkus create app --help
quarkus create cli --help
Previous versions of the CLI used options |
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:
-
Specify a specific Platform Release BOM
A 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 (groupId:io.quarkus
, artifactId:quarkus-bom
, version: cli version). If you specify only one segment (no:
), it is assumed to be a version.For example:
-
Given the
2.0.0.Final
version of the CLI, specifying-P :quarkus-universe-bom:
is equivalent to-P io.quarkus:quarkus-universe-bom:2.0.0.Final
. -
Specifying
-P 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.
-
-
Specify a Platform Stream
Platform streams are new in Quarkus 2.0.
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.For
2.0.0.Final
, you must enable the registry client (--registry-client
) explicitly to specify a stream. This is not required for2.1.0.Final
or later releases.
Dealing with extensions
quarkus ext --help
Listing extensions
The Quarkus CLI can be used to list Quarkus extensions.
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 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
).
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
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
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
).
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. |