The quarkus
command lets you create projects, manage extensions and
do essential build and dev commands using the underlying project build tool.
This technology is considered preview. In preview, backward compatibility and presence in the ecosystem is not guaranteed. Specific improvements might require changing configuration or APIs, and plans to become stable are under way. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker. For a full list of possible statuses, check our FAQ entry. |
Installing the CLI
The Quarkus CLI is available in several developer-oriented package managers such as:
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 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
-
Scoop - for Windows
Using the CLI
Use --help
to display help information with all the available commands:
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.
image Perform a container image operation.
build Build a container image.
docker Build a container image using Docker.
buildpack Build a container image using Buildpack.
jib Build a container image using Jib.
openshift Build a container image using Openshift.
push Push a container image.
completion bash/zsh completion: source <(quarkus completion)
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 fall back to default values (shown withquarkus 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.
-
-
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
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 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] ------------------------------------------------------------------------
Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang). |
Run quarkus build --clean to perform clean as part of the build.
|
Development mode
quarkus dev --help
To start dev mode from the Quarkus CLI do:
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-reactive, smallrye-context-propagation]
--
Tests paused, press [r] to resume
Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang). |
Run quarkus dev --clean to perform clean as part of the build.
|
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:
# 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:
# 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
Container images
The Quarkus CLI allows building container images without tampering with your project configuration (adding / removing container image extensions). To build the image for your project:
quarkus image build
The image build
command can be used directly, or a subcommand can be selected. The available subcommands are:
-
docker
-
buildpacks
-
jib
-
openshift
Each subcommand corresponds to an image building tool supported by Quarkus and gives access to specific configuration options.
For example, to use a Cloud Native Buildpack with a custom builder image, use the following:
quarkus image build buildpack --builder-image <your builder image>
Extending the CLI
The pull request introduces a plugin mechanism for the Quarkus CLI. This allows to dynamically add commands / subcommand to the CLI.
What is a Plugin
A plugin can be any executable, jar or java command that can be found locally or obtained remotely. So plugins are classified in the following types:
-
Plugins executed via shell
-
executable (any executable prefixed with
quarkus-
found locally) -
Plugins executed via jbang
-
jar (any runnable jar found locally)
-
jbang alias (any jbang alias prefixed with
quarkus-
installed locally or through the quarkusio catalog) -
maven (any maven coordinate in GACTV form pointing to a runnable jar)
How to obtain plugins
Plugins can be found via multiple sources that are described below.
Extension(s)
A quarkus extension may define list of cli-plugins
as part of its metadata. The list may contains GACTV string pointing to executable jars.
Limitations: At the moment the cli is able to obtain the list of available extensions, without being very accurate on the exact version of the extension (it uses the version found in the extension catalog).
Local path scanning
Scan the path item for executable files prefixed with quarkus
.
==== Using JBang aliases
Scan the local or project jbang catalog for aliases prefixed with quarkus-
.
==== Using the JBang quarkusio catalog
Scan the quarkusio catalog for aliases prefixed wtih quarkus-
.
Note: uses the jbang binary. If missing it will be automatically installed unser .jbang
.
==== Explicitly using the plugin commands
See quarkus plugin add
below
Managing plugins
Plugins are managed using the following commands:
Listing plugins
The following command lists the installed add plugins.
quarkus plug list
No plugins installed!
To include the installable plugins in the list, append --installable to the command.
To list available / installable plugins:
❯ quarkus plug list --installable
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
* fmt jbang user quarkus-fmt@quarkusio
greeter executable user /home/iocanel/bin/quarkus-greeter
Use the 'plugin add' sub command and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.
The output of the list
command may be filtered by type
using -t
or by name using -s
flag and a search pattern.
Example: To list all installable plugins that start with the letter k
:
quarkus plug list --installable -s "k*"
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
Use the 'plugin add' sub command and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.
Adding plugins
To add any of the installable plugins, use quarkus plug add <name or location>
:
quarkus plug add kill
Added plugin:
Name Type Scope Location Description
* kill jbang user quarkus-kill@quarkusio
The command above installed a plugin by name
using the name as listed by quarkus plug list --installable
.
The command can be now executed using quarkus kill
.
Note: Users are not limited to the plugins discovered by quarkus plug list --installable
. Users may install plugins as long as the provide the URL or the Maven coordinates pointing to an executable jar or java file.
Example: Installing an executable jar as a plugin via maven coordinates
For this example will use: io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0
which is a a real executable jar that provide a cli utility for the quarkus-authzed
extension.
quarkus plug add io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 -d "Authzed CLI"
Added plugin:
Name Type Location Description
* authzed maven io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 Authzed CLI
Note: It’s also possible to set a description that will appear to the help messages.
quarkus --help
Usage: quarkus [-ehv] [--verbose] [-D=<String=String>]... [COMMAND]
...
Commands:
...
plugin, plug Configure plugins of the Quarkus CLI.
list, ls List CLI plugins.
add Add plugin(s) to the Quarkus CLI.
remove Remove plugin(s) to the Quarkus CLI.
sync Sync (discover / purge) CLI Plugins.
completion bash/zsh completion: source <(quarkus completion)
authzed Authzed CLI
...
Where are the plugins added?
Plugins are added in the plugin catalog that lives at: <user home>/.quakrus/cli/plugins/quarkus-cli-catalog.json
.
There is a second plugin catalog that is relative to the current project (if available): <project root>/.quarkus/cli/plugins/quarkus-cli-catalog.json
.
The effective catalog is the combination of both the user
and project
catalogs with the latter being able to override entries of the former (e.g. use a different version or location for a plugin).
If the project catalog is available it will allways be prefered, unless explicitly specified with the user of --user
flag.
The column scope
the plugin table indicates where the plugin is/will be added.
Removing plugins
Plugins are removed using quarkus plug remove <plugin name>
.
quarkus plug remove kill
Removed plugin:
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
Syncing plugins
To remove stale plugins or discover new plugins provided by extensions the quarkus plugin sync
is available.
With this command binaries and jbang aliases that are added to the catalog but are not longer available will be purged.
Note: Remote plugins that are explicitly added by the user using URL / Maven coordinates are excluded.
The command is also executed implicitly through any of the CLI commands: * Weekly * If the project files have been updated since the last catalog update (limited to the module).