# Building Quarkus apps with Quarkus Command Line Interface (CLI)

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

## Installing the CLI

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

- SDKMAN!

- Homebrew

- Chocolatey

- Scoop

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

JBang

The Quarkus CLI is available as a jar installable using 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)

    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:

    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:

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

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

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

    quarkus --version
    3.3.0

| 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`.

SDKMAN!

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.

| Make sure you have 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:

    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:

    quarkus --version
    3.3.0

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

    sdk upgrade quarkus

Homebrew

Homebrew is a package manager for macOS (and Linux).

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

| 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 the latest Java version, `brew install openjdk@17` for Java 17, or `brew install openjdk@11` for Java 11.

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

    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:

    quarkus --version
    3.3.0

You can upgrade the Quarkus CLI with:

    brew update (1)
    brew upgrade quarkus (2)

1 | Update all package definitions and Homebrew itself
2 | Upgrade Quarkus CLI to the latest version

Chocolatey

Chocolatey is a package manager for Windows.

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

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

    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:

    quarkus --version
    3.3.0

You can upgrade the Quarkus CLI with:

    choco upgrade quarkus

Scoop

Scoop is a package manager for Windows. You can use Scoop to install (and update) the Quarkus CLI.

| Make sure you have a JDK installed before installing the Quarkus CLI. You can install a JDK with `scoop install openjdk17` for Java 17 or `scoop install openjdk11` for Java 11.

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

    scoop install quarkus-cli

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:

    quarkus --version
    3.3.0

You can upgrade the Quarkus CLI with:

    scoop update quarkus-cli

## Using the CLI

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

    quarkus --help
    Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
                   [-D=<String=String>]... [COMMAND]
    Options:
          --refresh         Refresh the local Quarkus extension registry cache
          --config=CONFIG   Configuration file
      -h, --help            Display this help message.
      -v, --version         Print CLI version information and exit.
      -e, --errors          Display error messages.
          --verbose         Verbose mode.
      -D=<String=String>    Java properties

    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.
      test                    Run the current project in continuous testing 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.
      image                   Build or push project container image.
        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.
      deploy                  Deploy application.
        kubernetes            Perform the deploy action on kubernetes.
        openshift             Perform the deploy action on openshift.
        knative               Perform the deploy action on knative.
        kind                  Perform the deploy action on minikube.
        minikube              Perform the deploy action on minikube.
      registry                Configure Quarkus registry client
        list                  List enabled Quarkus registries
        add                   Add a Quarkus extension registry
        remove                Remove a Quarkus extension registry
      info                    Display project information and verify versions
                                health (platform and extensions).
      update, up, upgrade     Suggest recommended project updates with the
                                possibility to apply them.
      version                 Display CLI version information.
      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)

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

### Creating a new project

To create a new project, 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'`).

| The emojis shown above may not match precisely. The appearance of emojis can vary with the font used or the terminal/environment. IntelliJ IDEA, for example, has several long-running issues open regarding the behavior/rendering of emojis in the terminal.

You can specify the `groupId`, `artifactId` and `version` using the `group:artifactId:version` coordinates syntax directly from the command line. You can selectively omit segments to use the 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 the options for creating projects:

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

### 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 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 with `quarkus create app --help`). If you specify only one segment (no `:`), it is assumed to be a version.

   `io.quarkus.platform` is the default `groupId`. Specifying `-P :quarkus-bom:` is equivalent to `-P io.quarkus.platform:quarkus-bom:3.3.0`. Note that you need to specify the `groupId` to work with a snapshot, e.g. `-P io.quarkus::999-SNAPSHOT` is equivalent to `-P io.quarkus:quarkus-bom:999-SNAPSHOT`.

   Default values are subject to change. Use the `--dry-run` option to see 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

    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

#### Adding extensions

The Quarkus CLI can add one or more extensions to your project with the `add` subcommand:

    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 extensions

The Quarkus CLI can remove one or more extensions from your project with the `remove`/`rm` subcommand:

    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), use the `build` command:

    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

To start dev mode from the Quarkus CLI, use the `dev` command:

    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.

## 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 the 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>

#### Pushing

The `image push` command is similar to `image build`, and surfaces some basic options required to push images to a target container registry.

    quarkus image push --registry=<image registry> --registry-username=<registry username> --registry-password-stdin

## Extending the CLI

The Quarkus CLI embeds a plugin system that can be used to dynamically add commands and subcommands 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.

Plugins are classified as follows:

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

#### Extensions

A Quarkus extension may define a list of `cli-plugins` as part of its metadata. The list may contain GACTV string pointing to executable jars.

| At the moment, the CLI is able to obtain the list of available extensions, but is not very accurate on the exact version of the extension (it uses the version found in the extension catalog).

#### Local path scanning

Scan the path elements 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 with `quarkus-`.

| Uses the JBang binary. If missing, it will be automatically installed under `.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 plugins:

    quarkus plugin list
    No plugins installed!
    To include the installable plugins in the list, append --installable to the command.

To list the available/installable plugins:

    quarkus plugin 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' subcommand 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.

For instance, to list all the installable plugins starting with the letter `k`, use the following command:

    quarkus plugin list --installable -s "k*"
        Name             Type                Scope          Location                                   Description
        kill             jbang               user           quarkus-kill@quarkusio

    Use the 'plugin add' subcommand 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 plugin add <name or location>`:

    quarkus plugin 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 plugin list --installable`.

The installed command can be now executed using `quarkus kill`.

| Users are not limited to the plugins discovered by `quarkus plug list --installable`. Users may install plugins as long as they provide the URL or the Maven coordinates pointing to an executable jar or Java file.

You can install an executable jar as a plugin via Maven coordinates.

For instance, let’s use `io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0` which is a real executable jar that provides a CLI utility for the `quarkus-authzed` extension.

    quarkus plugin 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

| It is also possible to set a description that will appear in the help output.

    quarkus --help

    Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
                   [-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>/.quarkus/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 always be preferred, unless explicitly specified with the `--user` flag.

The column `scope` of the plugins table indicates where the plugin is/will be added.

#### Removing plugins

Plugins are removed using `quarkus plugin remove <plugin name>`.

    quarkus plugin 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` command is available. With this command binaries and JBang aliases that are added to the catalog but are no longer available will be purged.

| Remote plugins that are explicitly added by the user using URL/Maven coordinates are excluded from the removal.

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