Building Quarkus apps with Quarkus Command Line Interface (CLI)

你可以使用 `quarkus`命令创建项目、管理扩展,并使用基础项目构建工具执行必要的构建和开发任务。

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

Quarkus CLI 可在多个面向开发者的包管理器中使用,例如:

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

如果你已经使用(或希望使用)上述工具之一,这是安装 Quarkus CLI 并使其保持更新的最简单的方式。

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.

除了这些包管理器之外,还可以通过 JBang 安装 Quarkus CLI。选择对你来说最实用的工具:

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

Quarkus CLI 以 jar 的形式提供,可以使用 JBang 进行安装。

The Quarkus CLI is available as a jar installable using JBang.

JBang 将使用你现有的 Java,如果需要,还可以为你安装一个 Java。

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

在 Linux、macOS 和 Windows 上(使用 WSL 或与 bash 兼容的外壳,如 Cygwin 或 MinGW)

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

在 Windows 上使用 Powershell:

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"

如果已经安装了 JBang,你可以直接使用它:

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 qs3.5.0 https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/3.5.0/quarkus-cli-3.5.0-runner.jar

如果你已经在本地构建了 Quarkus,你可以使用该版本:

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

安装后,quarkus 将会出现在你的 $PATH 中,如果你运行 quarkus --version,它将打印已安装的版本:

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

quarkus --version
{quarkus-version}
Example 1. Use a recent JBang version

如果你收到了一个有关 app 不可读的错误,则你可能安装了低于 v0.56.0 的 JBang 版本。请将其移除或升级到最新版本。

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.

如果你正在第一次安装 JBang,则开始一个新的会话来更新你的 PATH

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

SDKMAN!

SDKMAN! 可用于管理开发环境。它可以在大多数基于 Unix 的系统上管理多个软件开发工具包的并行版本,这使得它成为了非常好的选择,可以方便地使用多个 JDK 版本。

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.

使用 SDKMAN!,你还可以安装流行的 Java 工具,包括 Quarkus CLI。

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

在安装 Quarkus CLI 之前,请确保你拥有 a JDK installed

Make sure you have a JDK installed before installing the Quarkus CLI.

若要列出可用 Java 版本,请使用 sdk list java。然后,可以使用 sdk install java x.y.z-open(或您偏好的另一供应商的 JDK)安装所需的 OpenJDK 版本。

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

若要使用 SDKMAN! 安装 Quarkus CLI,请运行以下命令:

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

sdk install quarkus

它将安装 Quarkus CLI 的最新版本。

It will install the latest version of the Quarkus CLI.

安装后,quarkus 将会出现在你的 $PATH 中,如果你运行 quarkus --version,它将打印已安装的版本:

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

quarkus --version
{quarkus-version}

SDKMAN! 会在有新版本时通知,以便轻松更新:

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

sdk upgrade quarkus
Homebrew

Homebrew是面向 macOS(和 Linux)的包管理器。

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

您可以使用 Homebrew 安装(和更新)Quarkus CLI。

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

在安装 Quarkus CLI 之前,请确保安装 JDK。我们尚未添加显式依赖项,因为我们希望确保您可以使用您偏好的 JDK 版本。

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.

您可以使用 `brew install openjdk`为最新 Java 版本、`brew install openjdk@17`为 Java 17 或 `brew install openjdk@21`为 Java 21 安装 JDK。

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@21 for Java 21.

若要使用 Homebrew 安装 Quarkus CLI,请运行以下命令:

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

brew install quarkusio/tap/quarkus

它将安装 Quarkus CLI 的最新版本。 此命令还可以用来更新 Quarkus CLI。

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

安装后,quarkus 将会出现在你的 $PATH 中,如果你运行 quarkus --version,它将打印已安装的版本:

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

quarkus --version
{quarkus-version}

您可以使用以下方式升级 Quarkus CLI:

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是针对 Windows 的程序包管理器。

Chocolatey is a package manager for Windows.

您可以使用 Chocolatey 安装(和更新)Quarkus CLI。

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

在安装 Quarkus CLI 之前,请确保安装 JDK。

Make sure you have a JDK installed before installing the Quarkus CLI.

您可以使用 `choco install temurin17`为 Java 17 或 `choco install temurin21`为 Java 21 安装 JDK。

You can install a JDK with choco install temurin17 for Java 17 or choco install temurin21 for Java 21.

若要使用 Chocolatey 安装 Quarkus CLI,请运行以下命令:

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

choco install quarkus

它将安装 Quarkus CLI 的最新版本。

It will install the latest version of the Quarkus CLI.

安装后,quarkus 将会出现在你的 $PATH 中,如果你运行 quarkus --version,它将打印已安装的版本:

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

quarkus --version
{quarkus-version}

您可以使用以下方式升级 Quarkus CLI:

You can upgrade the Quarkus CLI with:

choco upgrade quarkus
Scoop

Scoop 是一个适用于 Windows 的软件包管理器。你可以使用 Scoop 来安装(以及更新)Quarkus CLI。

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

在安装 Quarkus CLI 之前请确保你已安装了 JDK。你可以通过 scoop install openjdk17 安装适用于 Java 17 的 JDK,也可以通过 scoop install openjdk21 安装适用于 Java 21 的 JDK。

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 openjdk21 for Java 21.

若要使用 Scoop 安装 Quarkus CLI,请运行以下命令:

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

scoop install quarkus-cli

它将安装 Quarkus CLI 的最新版本。安装完成,quarkus 将位于你的 $PATH,且如果你运行 quarkus --version,它将打印已安装的版本:

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
{quarkus-version}

您可以使用以下方式升级 Quarkus CLI:

You can upgrade the Quarkus CLI with:

scoop update quarkus-cli

Using the CLI

使用 --help 以显示所有可用命令的帮助信息:

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

如果你没有看到预期输出,请使用 --help 验证你是否已使用正确的参数调用命令。

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

要创建新项目,请使用 create 命令(如果没有指定,则隐含 app 子命令):

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

这将在你的当前工作目录中创建一个名为 code-with-quarkus 的文件夹,并使用默认的 groupIdartifactIdversion 值(groupId='org.acme'artifactId='code-with-quarkus'version='1.0.0-SNAPSHOT')。

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

上面显示的表情可能不完全匹配。表情的外观会随着所使用的字体或终端/环境而有所不同。例如,IntelliJ IDEA 有几个长期未解决的问题,涉及到终端中表情的行为/呈现。

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.

你可以使用 group:artifactId:version 坐标语法直接从命令行中指定 groupIdartifactIdversion。你可以有选择地省略片段以使用默认值:

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

使用 --help 选项显示创建项目的选项:

Use the --help option to display the options for creating projects:

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

Specifying the Quarkus version

quarkus createquarkus extension list 都允许你以两种方式之一明确指定 Quarkus 版本:

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[.iokays-translated-be7d1f3d373f874cf3a76359338e11d0] Quarkus Platform release BOMgroupId:artifactId:version (GAV)坐标标识。在指定平台发布 BOM 时,你可以使用空片段回退到默认值(用 quarkus create app --help 显示)。如果你仅指定一个片段(没有 :),则假定为一个版本。

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.

{quarkus-platform-groupid} 是默认 groupId。指定 -P :quarkus-bom: 等同于 -P {quarkus-platform-groupid}:quarkus-bom:{quarkus-version}。请注意,你必须指定 groupId 才能配合使用快照,例如,-P io.quarkus::999-SNAPSHOT 等同于 -P io.quarkus:quarkus-bom:999-SNAPSHOT

{quarkus-platform-groupid} is the default groupId. Specifying -P :quarkus-bom: is equivalent to -P {quarkus-platform-groupid}:quarkus-bom:{quarkus-version}. 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.

默认值可能会更改。使用 --dry-run 选项查看已计算的值。

Default values are subject to change. Use the --dry-run option to see the computed value. 1. Specify a Platform Stream[.iokays-translated-cbaca7b71ca79c9b4617480a09a0e237] 平台流针对远程注册表进行操作。每个注册表定义了一个或多个平台流,每个流定义了一个或多个平台发布 BOM 文件,其中定义了使用该流的项目应如何配置。

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.

使用 platformKey:streamId 语法标识流。可以使用 -S platformKey:streamId 指定特定流。在指定流时,基于流资源解析规则,将用 discovered 默认值替换空段。

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

Quarkus CLI 可用于列出 Quarkus 扩展。

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.

quarkus ext ls 的行为会因上下文而异。

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

Listing extensions for a Quarkus release

如果从项目外部调用 Quarkus CLI,Quarkus 将列出 CLI 本身所用的 Quarkus 版本中可用的所有扩展。

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.

你还可以使用 -P-S 列出 Quarkus 的特定版本扩展,如 Specifying the Quarkus version 中所述。

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

此模式默认使用 --origins 格式。

This mode uses the --origins format by default.

Listing extensions for a Quarkus project

在使用 Quarkus 项目时,CLI 将列出当前项目安装的扩展,默认使用 --name 格式。

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

使用 --installable-i 选项列出可从项目使用的 Quarkus 平台安装的扩展。

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

你可以使用搜索(--search-s)缩小或筛选列表。

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

Quarkus CLI 可通过 add 子命令向项目中添加一个或多个扩展:

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

你可以安装与 glob 模式匹配的所有扩展:

You can install all extensions which match a glob pattern:

quarkus ext add smallrye-*

Removing extensions

使用 Gemin,可通过 remove/rm 子命令从项目中删除一个或多个扩展:

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

要使用 Quarkus CLI 构建项目(在本示例中使用默认配置),请使用 build 命令:

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

输出会根据项目使用的构建工具(Maven、Gradle 或 JBang)而有所不同。

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

运行 quarkus build --clean,以作为构建的一部分执行清理。

Run quarkus build --clean to perform clean as part of the build.

Development mode

要从 Quarkus CLI 启动开发模式,请使用 dev 命令:

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, rest, smallrye-context-propagation]

--
Tests paused, press [r] to resume

输出会根据项目使用的构建工具(Maven、Gradle 或 JBang)而有所不同。

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

运行 quarkus dev --clean,以作为构建的一部分执行清理。

Run quarkus dev --clean to perform clean as part of the build.

Shell autocomplete and aliases

Bash 和 Zsh 提供自动命令补全:

Automatic command completion is available for Bash and Zsh:

# Setup autocompletion in the current shell
source <(quarkus completion)

如果您选择对 quarkus 命令使用别名,请使用以下命令调整命令补全:

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

Quarkus CLI 允许构建容器映像,而不改动项目配置(添加/移除容器映像扩展)。要构建项目映像:

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

image build 命令可以直接使用,也可以选择子命令。可用的子命令包括:

The image build command can be used directly, or a subcommand can be selected. The available subcommands are:

  • docker

  • buildpacks

  • jib

  • openshift

每个子命令都对应于由 Quarkus 支持的映像构建工具,并可以访问特定配置选项。

Each subcommand corresponds to an image building tool supported by Quarkus and gives access to specific configuration options.

例如,要将 Cloud Native Buildpack 与自定义构建器映像一起使用,请使用以下命令:

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

image push 命令类似于 image build,提供了一些将映像推送至目标容器注册表所需的基本选项。

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

Quarkus CLI 嵌入了一个插件系统,可用于向 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

插件可以是任何可执行文件、jar 或 Java 命令,可以在本地找到或远程获取。

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

Quarkus 扩展可以将 `cli-plugins`列表定义为其元数据的一部分。该列表可能包含指向可执行 jar 的 GACTV 字符串。

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.

目前,CLI 能够获取可用扩展列表,但对于扩展的确切版本不是非常准确(它使用扩展目录中找到的版本)。

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

扫描以 `quarkus-`为前缀的可执行文件路径元素。

Scan the path elements for executable files prefixed with quarkus-.

Using JBang aliases

扫描本地或项目 jbang 目录以查找以 `quarkus-`为前缀的别名。

Scan the local or project jbang catalog for aliases prefixed with quarkus-.

Using the JBang quarkusio catalog

扫描 `quarkusio`目录以查找以 `quarkus-`为前缀的别名。

Scan the quarkusio catalog for aliases prefixed with quarkus-.

使用 JBang 二进制文件。如果缺少,它将在 `.jbang`下自动安装。

Uses the JBang binary. If missing, it will be automatically installed under .jbang.

Explicitly using the plugin commands

请参见下面的 quarkus plugin add

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.

`list`命令的输出可以使用 `type`使用 `-t`进行过滤,或使用 `-s`标志和搜索模式按名称过滤。

The output of the list command may be filtered by type using -t or by name using -s flag and a search pattern.

例如,要列出所有以字母 `k`开头的可安装插件,请使用以下命令:

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

要添加任何可安装插件,请使用 quarkus plugin add <name or location>

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

上面的命令通过 `name`安装了一个插件,使用 `quarkus plugin list --installable`列出的名称。

The command above installed a plugin by name using the name as listed by quarkus plugin list --installable.

现在可以使用 `quarkus kill`执行已安装的命令。

The installed command can be now executed using quarkus kill.

用户并不局限于 `quarkus plug list --installable`发现的插件。只要用户提供指向可执行 jar 或 Java 文件的 URL 或 Maven 坐标,用户就可以安装插件。

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.

您可以通过 Maven 坐标将可执行 jar 安装为插件。

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

例如,我们使用 io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 ,这是一个真正的可执行 jar,可为 quarkus-authzed 扩展提供 CLI 实用程序。

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?

将插件添加到插件目录中,该目录位于: <user home>/.quarkus/cli/plugins/quarkus-cli-catalog.json

Plugins are added in the plugin catalog that lives at: <user home>/.quarkus/cli/plugins/quarkus-cli-catalog.json.

有一个第二个插件目录相对于当前项目(如果可用): <project root>/.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.

有效目录是 userproject 目录的组合,后者可以覆盖前者的条目(例如,为插件使用不同的版本或位置)。

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

如果项目目录可用,它将始终得到优先考虑,除非使用 --user 标志明确指定。

If the project catalog is available, it will always be preferred, unless explicitly specified with the --user flag.

插件表的 scope 列指示插件位于/将被添加到哪里。

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

Removing plugins

使用 quarkus plugin remove <plugin name> 删除插件。

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

若要删除过时的插件或发现扩展提供的新的插件,可以使用 quarkus plugin sync 命令。此命令将清除添加到目录中但不再可用的二进制文件和 JBang 别名。

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.

用户使用 URL/Maven 坐标明确添加的远程插件从删除中排除。

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

还可通过任何 CLI 命令隐式执行此命令:

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