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

Criar aplicações Quarkus com a interface de linha de comandos (CLI) do Quarkus

O comando quarkus permite que você crie projetos, gerencie extensões e realize tarefas essenciais de criação e desenvolvimento usando a ferramenta de criação de projetos subjacente.

Instalação do CLI

O Quarkus CLI está disponível em vários gestores de pacotes orientados para o desenvolvedor, tais como:

Se você já utiliza (ou pretende utilizar) uma destas ferramentas, esta é a forma mais simples de instalar o Quarkus CLI e de o manter atualizado.

Além desses gestores de pacotes, o Quarkus CLI também pode ser instalado via JBang. Escolha a alternativa que for mais prática para você:

  • JBang - para Linux, macOS e Windows

  • SDKMAN! - para Linux e macOS

  • Homebrew - para Linux e macOS

  • Chocolatey - para Windows

  • Scoop - para Windows

JBang

O Quarkus CLI está disponível como um jar instalável usando o JBang .

O JBang utilizará o Java existente ou instalará um para você, se necessário.

No Linux, macOS e Windows (usando WSL ou shell compatível com bash como Cygwin ou 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

No Windows, usando o 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"

Se o JBang já tiver sido instalado, você pode utilizá-lo diretamente:

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

Se pretender utilizar uma versão específica, você pode definir diretamente uma versão como alvo:

# 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

Se você tiver criado o Quarkus localmente, poderá usar essa versão:

# 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

Uma vez instalado, o quarkus estará no seu $PATH e se você executar quarkus --version ele mostrará a versão instalada:

quarkus --version
3.10.2
Use uma versão recente do JBang

Se você encontrar um erro sobre app não ser legível (app not being readable), então você provavelmente tem uma versão do JBang mais antiga que a v0.56.0 instalada. Por favor, remova ou atualize-a para uma versão mais recente.

Se você está instalando o JBang pela primeira vez, inicie uma nova sessão para atualizar seu PATH.

SDKMAN!

SDKMAN! pode ser usado para gerir ambientes de desenvolvimento. Ele pode gerenciar versões paralelas de múltiplos SDKs (Software Development Kits) na maioria dos sistemas baseados em Unix, tornando-o uma alternativa muito boa para manter várias versões do JDK à mão.

Com o SDKMAN!, você também pode instalar ferramentas Java populares, incluindo o Quarkus CLI.

Certifique-se de que você tenha um JDK instalado antes de instalar o Quarkus CLI.

Para listar as versões disponíveis do Java, use sdk list java. Você pode instalar a versão do OpenJDK que preferir com sdk install java x.y.z-open (ou o JDK de outro fornecedor se for de sua preferência).

Para instalar o Quarkus CLI usando o SDKMAN!, execute o seguinte comando:

sdk install quarkus

Ele instalará a versão mais recente do Quarkus CLI.

Uma vez instalado, o quarkus estará no seu $PATH e se você executar quarkus --version ele mostrará a versão instalada:

quarkus --version
3.10.2

SDKMAN! irá informá-lo quando novas versões estiverem disponíveis para que as atualizações sejam simples:

sdk upgrade quarkus
Homebrew

Homebrew é um gerenciador de pacotes para macOS (e Linux).

Você pode usar o Homebrew para instalar (e atualizar) o CLI do Quarkus.

Certifique-se de que você tenha um JDK instalado antes de instalar o Quarkus CLI. Não adicionamos uma dependência específica porque visamos garantir que você possa usar sua versão preferida do JDK.

Você pode instalar um JDK com brew install openjdk para a última versão do Java, brew install openjdk@17 para Java 17, ou brew install openjdk@21 para Java 21.

Para instalar o Quarkus CLI usando o Homebrew, execute o seguinte comando:

brew install quarkusio/tap/quarkus

Ele instalará a versão mais recente do Quarkus CLI. Esse comando também pode ser usado para atualizar o Quarkus CLI.

Uma vez instalado, o quarkus estará no seu $PATH e se você executar quarkus --version ele mostrará a versão instalada:

quarkus --version
3.10.2

Você pode atualizar o Quarkus CLI com:

brew update (1)
brew upgrade quarkus (2)
1 Atualiza todas as definições de pacotes e o próprio Homebrew
2 Atualiza o Quarkus CLI para a versão mais recente
Chocolatey

Chocolatey é um gestor de pacotes para Windows.

Você pode usar o Chocolatey para instalar (e atualizar) o Quarkus CLI.

Certifique-se de que você tenha um JDK instalado antes de instalar o Quarkus CLI.

Você pode instalar um JDK com choco install temurin17 para Java 17 ou choco install temurin21 para Java 21.

Para instalar o Quarkus CLI usando o Chocolatey, execute o seguinte comando:

choco install quarkus

Ele instalará a versão mais recente do Quarkus CLI.

Uma vez instalado, o quarkus estará no seu $PATH e se você executar quarkus --version ele mostrará a versão instalada:

quarkus --version
3.10.2

Você pode atualizar o Quarkus CLI com:

choco upgrade quarkus
Scoop

Scoop é um gestor de pacotes para Windows. Você pode usar o Scoop para instalar (e atualizar) o Quarkus CLI.

Certifique-se de que você tenha um JDK instalado antes de instalar o Quarkus CLI. Você pode instalar um JDK com scoop install openjdk17 para Java 17 ou scoop install openjdk21 para Java 21.

Para instalar o Quarkus CLI usando o Scoop, execute o seguinte comando:

scoop install quarkus-cli

Ele instalará a versão mais recente do Quarkus CLI. Uma vez instalado, o quarkus estará no seu $PATH e se você executar quarkus --version ele mostrará a versão instalada:

quarkus --version
3.10.2

Você pode atualizar o Quarkus CLI com:

scoop update quarkus-cli

Usando o CLI

Use --help para exibir informações de ajuda com todos os comandos disponíveis:

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.

Se você não visualizar o resultado esperado, use --help para verificar se está invocando o comando com os argumentos corretos.

Criando um novo projeto

Para criar um novo projeto, use o comando create (o subcomando app estará implícito quando não é especificado):

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

Isso criará uma pasta chamada code-with-quarkus em seu diretório de trabalho atual usando os valores padrão groupId , artifactId e version ( groupId='org.acme' , artifactId='code-with-quarkus' e version='1.0.0-SNAPSHOT' ).

Os emojis mostrados acima podem não corresponder exatamente. A aparência dos emojis pode variar de acordo com a fonte usada ou com o terminal/ambiente. O IntelliJ IDEA, por exemplo, tem vários problemas de longa data em aberto com relação ao comportamento/renderização de emojis no terminal.

Você pode especificar groupId , artifactId e version usando a sintaxe de coordenadas group:artifactId:version diretamente da linha de comando. Você pode omitir segmentos seletivamente para usar os valores padrão:

# 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

A saída mostrará seu projeto sendo criado:

-----------

applying codestarts...
📚  java
🔨  maven
📦  quarkus
📝  config-properties
🔧  dockerfiles
🔧  maven-wrapper
🚀  resteasy-codestart

-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/bar
-----------

Use a opção --help para exibir as opções de criação de projetos:

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

Especificando a versão do Quarkus

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

  1. Forneça um Platform Release BOM específico

    Um Quarkus Platform Release BOM é identificado pelas coordenadas groupId:artifactId:version (GAV). Quando especificado um platform release BOM, você pode usar segmentos vazios para usar os valores padrões (mostrados com quarkus create app --help). Se você especificar apenas um segmento (sem :), ele será considerado uma versão.

    io.quarkus.platform é o groupId padrão. Especificando -P :quarkus-bom: é equivalente a -P io.quarkus.platform:quarkus-bom:3.10.2. Note que é necessário especificar o groupId para trabalhar com um snapshot, por exemplo, -P io.quarkus::999-SNAPSHOT é equivalente a -P io.quarkus:quarkus-bom:999-SNAPSHOT.

    Os valores padrão estão sujeitos a alterações. Use a opção --dry-run para ver o valor computado.

  2. Forneça um Plataform Stream

    Um platform stream opera em um registro remoto. Cada registro define um ou mais platform stream, e cada fluxo define um ou mais arquivos do platform release BOM que definem como os projetos que usam esse fluxo devem ser configurados.

    Streams são identificados usando a sintaxe platformKey:streamId. Um stream específico pode ser especificado usando -S platformKey:streamId. Ao especificar um stream, os segmentos vazios serão substituídos por valores padrões descobertos, com base nas regras de resolução de recursos stream.

Trabalhando com extensões

quarkus ext --help

Listando extensões

The Quarkus CLI can be used to list Quarkus extensions.

quarkus ext ls

O formato do resultado pode ser controlado com uma das quatro opções:

  • --name Exibir apenas o nome (artifactId)

  • --concise Exibir o nome (artifactId) e a descrição

  • --full Exibe o formato conciso e as colunas relacionadas à versão/status.

  • --origins Exibe informação concisa segundo a origem da extensão na plataforma Quarkus.

O comportamento do quarkus ext ls varia de acordo com o contexto.

Listando extensões para uma versão do 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.

Você também pode listar as extensões de uma versão específica do Quarkus usando -P ou -S , conforme descrito em Especificando a versão do Quarkus .

This mode uses the --origins format by default.

Listando extensões para um projeto 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

Adicionando extensões

O Quarkus CLI pode adicionar uma ou mais extensões ao seu projeto com o subcomando add:

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

Removendo extensões

O Quarkus CLI pode remover uma ou mais extensões do seu projeto com o subcomando remove/ rm:

quarkus ext rm kubernetes
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been uninstalled

Build your project

Para compilar seu projeto usando o Quarkus CLI (usando a configuração padrão neste exemplo), use o comando build:

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] ------------------------------------------------------------------------
A saída varia de acordo com a ferramenta de compilação que seu projeto está usando (Maven, Gradle ou JBang).
Execute quarkus build --clean para efetuar a limpeza como parte da compilação.

Modo de desenvolvimento

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
A saída varia de acordo com a ferramenta de compilação que seu projeto está usando (Maven, Gradle ou JBang).
Execute quarkus build --clean para efetuar a limpeza como parte da compilação.

Autocompletar e atalhos do terminal

Automatic command completion is available for Bash and Zsh:

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

Se você optar por usar um atalho (alias) para o comando quarkus, ajuste a terminação do comando da seguinte forma:

# 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

Imagens de Contêiner

A CLI do Quarkus permite criar imagens de containers sem interferir na configuração do projeto (adicionar/remover extensões de imagens de containers). Para criar a imagem do seu projeto:

quarkus image build

O comando image build pode ser usado diretamente ou um subcomando pode ser adicionado. Os subcomandos disponíveis são:

  • docker

  • buildpacks

  • jib

  • openshift

Cada subcomando corresponde a uma ferramenta de criação de imagens compatível com o Quarkus e dá acesso a opções de configuração específicas.

Por exemplo, para usar um Cloud Native Buildpack com uma imagem personalizada, use o seguinte:

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

Transmitindo

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

Ampliando o CLI

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

O que é um 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 executados via terminal

  • executável (qualquer executável precedido de quarkus- encontrado localmente)

  • Plugins executados via jbang

  • jar (qualquer executável jar encontrado localmente)

  • jbang alias (qualquer atalho jbang precedido de quarkus- instalado localmente ou via catálogo quarkusio)

  • maven (qualquer coordenada maven no formato GACTV apontando para um jar executável)

Como obter plugins

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

Extensões

Uma extensão Quarkus pode definir uma lista de cli-plugins como parte de seus metadados. A lista pode conter uma cadeia de caracteres GACTV que aponta para jars executáveis.

No momento, o CLI pode obter a lista de extensões disponíveis, mas não é muito preciso quanto à versão exata da extensão (ele usa a versão encontrada no catálogo de extensões).

Varredura local

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

Usando atalhos do JBang

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

Usando o catálogo JBang do quarkusio

Scan the quarkusio catalog for aliases prefixed with quarkus-.

Usa o binário JBang. Se estiver ausente, ele será instalado automaticamente em .jbang.

Usando especificamente os comandos do plugin

See quarkus plugin add below

Gerenciando plugins

Plugins are managed using the following commands.

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

Para listar os plugins disponíveis/instaláveis:

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.

A saída do comando list pode ser filtrada por tipo usando -t ou por nome usando a flag -s e um padrão de pesquisa.

Por exemplo, para listar todos os plugins instaláveis que começam com a letra k, use o seguinte comando:

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.

Adicionando 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

O comando acima instalou um plugin usando o name conforme listado por quarkus plugin list --installable.

O comando instalado agora pode ser executado usando o quarkus kill.

Os usuários não estão limitados aos plugins encontrados pelo quarkus plug list --installable. Os usuários podem instalar plugins desde que forneçam o URL ou as coordenadas Maven que apontem para um arquivo jar ou Java executável.

Você pode instalar um jar executável como um plugin via coordenadas Maven.

Por exemplo, vamos usar io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0, que é um jar executável real que fornece um recurso CLI para a extensão quarkus-authzed.

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
É possível também definir uma descrição que será exibida na saída do help.
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
...

Onde os plugins são instalados?

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.

Removendo 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

Sincronizando plugins

Para remover plugins obsoletos ou descobrir novos plugins fornecidos por extensões, está disponível o comando quarkus plugin sync. Com este comando, os binários e atalhos do JBang adicionados ao catálogo, mas que não estão mais disponíveis, serão eliminados.

Os plugins remotos que são explicitamente adicionados pelo usuário usando URL/coordenadas Maven são excluídos da remoção.

The command is also executed implicitly through any of the CLI commands:

  • Semanalmente

  • Se os arquivos do projeto tiverem sido atualizados desde a última atualização do catálogo (limitado ao módulo).

Conteúdo Relacionado