The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Quarkus コマンドラインインターフェイス (CLI) を使用した Quarkus アプリの構築

quarkus コマンドを使用すると、プロジェクトの作成、エクステンションの管理、基盤となるプロジェクトビルドツールを使用したビルドと開発の必須タスクを行うことができます。

CLI のインストール

Quarkus CLI は、以下のようないくつかの開発者向けのパッケージマネージャーで利用できます。

これらのツールのいずれかをすでに使用している (または使用したい) 場合、これは Quarkus CLI をインストールして最新の状態に保つ最も簡単な方法です。

これらのパッケージマネージャーに加えて、Quarkus CLI は JBang からもインストールできます。最も実用的な方法を選択してください。

  • JBang - Linux、macOS、および Windows 向け

  • SDKMAN! - Linux および macOS 向け

  • Homebrew - Linux および macOS 向け

  • Chocolatey - Windows 向け

  • Scoop - Windows 向け

JBang

Quarkus CLI は、 JBang を使用してインストール可能な jar として利用できます。

JBang は、既存の Java を使用するか、必要に応じて Java をインストールします。

Linux、macOS、および Windows (WSL または Cygwin や MinGW などの bash 互換シェルを使用) の場合

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

Powershell を使用する Windows の場合:

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 がすでにインストールされている場合は、直接使用できます。

# This can also be used to update to the latest version
jbang app install --fresh --force quarkus@quarkusio

特定のバージョンを使用したい場合は、直接バージョンを指定することができます。

# 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

Quarkus をローカルでビルドしている場合は、そのバージョンを使用できます。

# 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 を実行すると、インストールされているバージョンが出力されます。

quarkus --version
3.8.3
最近の JBang バージョンを使用する

app が読み取れないというエラーが発生した場合は、v0.56.0 より古いバージョンの JBang がインストールされている可能性があります。削除するか、最新バージョンにアップグレードしてください。

JBang を初めてインストールする場合は、新しいセッションを開始して PATH を更新してください。

SDKMAN!

SDKMAN! を使用して、開発環境を管理できます。ほとんどの Unix ベースのシステムで複数のソフトウェア開発キットの並列バージョンを管理できるため、複数の JDK バージョンを便利に使う場合に非常に良い代替手段となります。

SDKMAN! を使用すると、Quarkus CLI などの一般的な Java ツールをインストールすることもできます。

Quarkus CLI をインストールする前に、 JDK がインストールされていることを確認してください。

使用可能な Java のバージョンを一覧表示するには、sdk list java を使用します。続いて、sdk install java x.y.z-open (または、必要に応じて別のベンダーの JDK) を使用して、必要なバージョンの OpenJDK をインストールできます。

SDKMAN! を使用して Quarkus CLI をインストールするには、次のコマンドを実行します。

sdk install quarkus

Quarkus CLI の最新バージョンがインストールされます。

インストールされると、quarkus$PATH にあり、quarkus --version を実行すると、インストールされているバージョンが出力されます。

quarkus --version
3.8.3

SDKMAN! は、新しいバージョンが利用可能になると通知するので、更新は簡単です。

sdk upgrade quarkus
Homebrew

Homebrew は、macOS (および Linux) 向けのパッケージマネージャーです。

Homebrew を使用して、Quarkus CLI をインストール (および更新) できます。

Quarkus CLI をインストールする前に、JDK がインストールされていることを確認してください。お好みの JDK バージョンを使用できるようにするため、明示的な依存関係は追加していません。

最新のJavaバージョンの場合、 brew install openjdk 、Java 17用の場合、 brew install openjdk@17 、Java 21用の場合、 brew install openjdk@21 でJDKをインストールすることが出来ます。

Homebrew を使用して Quarkus CLI をインストールするには、次のコマンドを実行します。

brew install quarkusio/tap/quarkus

Quarkus CLI の最新バージョンがインストールされます。このコマンドを使用して、Quarkus CLI を更新することもできます。

インストールされると、quarkus$PATH にあり、quarkus --version を実行すると、インストールされているバージョンが出力されます。

quarkus --version
3.8.3

以下の方法で、Quarkus CLI をアップグレードできます。

brew update (1)
brew upgrade quarkus (2)
1 すべてのパッケージ定義と Homebrew 自体を更新します
2 QuarkusCLI を最新バージョンにアップグレードします
Chocolatey

Chocolatey は、Windows 向けのパッケージマネージャーです。

Chocolatey を使用して、Quarkus CLI をインストール (および更新) できます。

Quarkus CLI をインストールする前に、JDK がインストールされていることを確認してください。

Java 17の場合、 choco install temurin17 あるいはJava 21の場合、 choco install temurin21 でJDKをインストールできます。

Chocolatey を使用して Quarkus CLI をインストールするには、次のコマンドを実行します。

choco install quarkus

Quarkus CLI の最新バージョンがインストールされます。

インストールされると、quarkus$PATH にあり、quarkus --version を実行すると、インストールされているバージョンが出力されます。

quarkus --version
3.8.3

以下の方法で、Quarkus CLI をアップグレードできます。

choco upgrade quarkus
Scoop

Scoop は、Windows 向けのパッケージマネージャーです。Scoop を使用して、Quarkus CLI をインストール (および更新) できます。

Quarkus CLIをインストールする前に、JDKがインストールされていることを確認してください。 Java 17の場合、 scoop install openjdk17 あるいはJava 21の場合、 scoop install openjdk21 でJDKをインストールできます。

Scoop を使用して QuarkusCLI をインストールするには、次のコマンドを実行します。

scoop install quarkus-cli

Quarkus CLI の最新バージョンがインストールされます。インストールされると、quarkus は$PATH` にあり、quarkus --version を実行すると、インストールされているバージョンが出力されます。

quarkus --version
3.8.3

以下の方法で、Quarkus CLI をアップグレードできます。

scoop update quarkus-cli

CLI の使用

--help を使用して、使用可能なすべてのコマンドと共にヘルプ情報を表示します。

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)

このドキュメントは便利なリファレンスですが、最も信頼のおける情報源はクライアントヘルプです。

期待する出力が表示されない場合は、 --help を使用して、正しい引数を使用してコマンドを呼び出していることを確認してください。

新規プロジェクトの作成

新しいプロジェクトを作成するには、 create コマンドを使用します( app サブコマンドは、指定しない場合は暗黙で適用されます):

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

これにより、現在の作業ディレクトリに、デフォルトの groupIdartifactIdversion の値( groupId='org.acme'artifactId='code-with-quarkus'version='1.0.0-SNAPSHOT' )を使用して、 code-with-quarkus というフォルダが作成されます。

上記の絵文字は、正確に一致しない場合があります。絵文字の見え方は、使用するフォントや端末・環境によって異なる場合があります。例えば、IntelliJ IDEAでは、ターミナルでの絵文字の動作やレンダリングに関して、いくつかの長期にわたる問題が残されています。

コマンドラインから直接、 groupIdartifactIdversiongroup:artifactId:version の構文を使用して指定することができます。セグメントを選択的に省略して、デフォルト値を使用することができます:

# 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

出力には、プロジェクトが作成されていることが表示されます。

-----------

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

Quarkus バージョンの指定

Both quarkus create and quarkus extension list allow you to explicitly specify a version of Quarkus in one of two ways:

  1. 特定のプラットフォーム・リリース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.8.3. 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. プラットフォーム・ストリームの指定

    プラットフォーム・ストリームは、リモート・レジストリに対して動作します。各レジストリは1つ以上のプラットフォーム・ストリームを定義し、各ストリームは、そのストリームを使用するプロジェクトの設定方法を定義する1つ以上のプラットフォーム・リリースBOMファイルを定義します。

    ストリームは、 platformKey:streamId 構文を使用して識別されます。特定のストリームを指定するには -S platformKey:streamId を使用します。ストリームを指定する際、空のセグメントはストリームリソースの解決ルールに 基づき、 発見された デフォルトに置き換えられます。

エクステンションの使用

quarkus ext --help

エクステンションの一覧表示

The Quarkus CLI can be used to list Quarkus extensions.

quarkus ext ls

結果のフォーマットは、4つのオプションのいずれかで制御できます:

  • --name Display the name (artifactId) only

  • --concise 名前(artifactId)と説明を表示します

  • --full Display concise format and version/status-related columns.

  • --origins conciseフォーマットと共に、エクステンションのQuarkusプラットフォームリリースオリジンを表示します。

quarkus ext ls の動作はコンテキストによって異なります。

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.

You can also list extensions for a specific release of Quarkus using -P or -S, as described in Quarkus バージョンの指定.

This mode uses the --origins format by default.

Quarkusプロジェクトのエクステンションのリストアップ

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

エクステンションの追加

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

You can install all extensions which match a glob pattern:

quarkus ext add smallrye-*

エクステンションの削除

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

プロジェクトのビルド

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)によって異なります。
Run quarkus build --clean to perform clean as part of the build.

開発モード

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
出力は、プロジェクトが使用しているビルドツール(Maven、Gradle、またはJBang)によって異なります。
Run quarkus dev --clean to perform clean as part of the build.

シェルのオートコンプリートとエイリアス

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

コンテナイメージ

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

各サブコマンドは、Quarkusがサポートしているイメージビルドツールに対応しており、特定の設定オプションにアクセスできます。

たとえば、 Cloud Native Buildpack をカスタムビルダーイメージで使用するには、次のようにします:

quarkus image build buildpack --builder-image <your builder image>

プッシュ

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

CLIの拡張

The Quarkus CLI embeds a plugin system that can be used to dynamically add commands and subcommands to the CLI.

プラグインとは

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)

プラグインの入手方法

Plugins can be found via multiple sources that are described below.

エクステンション

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

ローカルパススキャン

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

JBangのエイリアスの使用

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

JBangのquarkusioカタログの使用

Scan the quarkusio catalog for aliases prefixed with quarkus-.

JBangバイナリを使用します。もし見つからない場合、自動的に .jbang にインストールされます。

プラグインコマンドの明示的な使用

See quarkus plugin add below

プラグインの管理

Plugins are managed using the following commands.

プラグインをリストアップ

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.

利用可能/インストール可能なプラグインを一覧表示します:

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.

プラグインの追加

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

プラグインはどこに追加されるのですか?

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.

プラグインの削除

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

プラグインの同期

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

  • 最後のカタログ更新以降にプロジェクトファイルが更新されている場合(モジュールに限定)。

関連コンテンツ