ℹ️ Skipped - page is already crawled
| Filter | Status | Condition | Details |
|---|---|---|---|
| HTTP status | PASS | download_http_code = 200 | HTTP 200 |
| Age cutoff | PASS | download_stamp > now() - 6 MONTH | 1 months ago |
| History drop | PASS | isNull(history_drop_reason) | No drop reason |
| Spam/ban | PASS | fh_dont_index != 1 AND ml_spam_score = 0 | ml_spam_score=0 |
| Canonical | PASS | meta_canonical IS NULL OR = '' OR = src_unparsed | Not set |
| Property | Value |
|---|---|
| URL | https://quarkus.io/guides/picocli |
| Last Crawled | 2026-03-09 02:17:32 (29 days ago) |
| First Indexed | 2020-06-04 03:14:46 (5 years ago) |
| HTTP Status Code | 200 |
| Meta Title | Command Mode with Picocli - Quarkus |
| Meta Description | Quarkus: Supersonic Subatomic Java |
| Meta Canonical | null |
| Boilerpipe Text | Edit this Page
Picocli
is an open source tool for creating rich command line applications.
Quarkus provides support for using Picocli. This guide contains examples of
picocli
extension usage.
Extension
Once you have your Quarkus project configured you can add the
picocli
extension
to your project by running the following command in your project base directory.
CLI
quarkus extension add picocli
Maven
./mvnw quarkus:add-extension -Dextensions='picocli'
Gradle
./gradlew addExtension --extensions='picocli'
This will add the following to your build file:
pom.xml
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-picocli</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-picocli")
Building a command line application
Simple application
A simple Picocli application with only one
Command
can be created as follows:
package com.acme.picocli;
import picocli.CommandLine;
import jakarta.enterprise.context.Dependent;
import jakarta.inject.Inject;
@CommandLine.Command
(1)
public class HelloCommand implements Runnable {
@CommandLine.Option(names = {"-n", "--name"}, description = "Who will we greet?", defaultValue = "World")
String name;
private final GreetingService greetingService;
public HelloCommand(GreetingService greetingService) {
(2)
this.greetingService = greetingService;
}
@Override
public void run() {
greetingService.sayHello(name);
}
}
@Dependent
class GreetingService {
void sayHello(String name) {
System.out.println("Hello " + name + "!");
}
}
1
If there is only one class annotated with
picocli.CommandLine.Command
, it will be used automatically as the entry point of the command line application.
2
All classes annotated with
picocli.CommandLine.Command
are registered as CDI beans.
Beans annotated with
@CommandLine.Command
should not use proxied scopes (e.g. do not use
@ApplicationScoped
)
because Picocli will not be able to set field values in such beans.
By default, this Picocli extension registers classes annotated with
@CommandLine.Command
with the
@Dependent
scope. If you need to use a proxied scope, then annotate the setters and not the fields, for example:
@CommandLine.Command
@ApplicationScoped
public class EntryCommand {
private String name;
@CommandLine.Option(names = "-n")
public void setName(String name) {
this.name = name;
}
}
Command line application with multiple Commands
When multiple classes have the
picocli.CommandLine.Command
annotation, then one of them needs to be also annotated with
io.quarkus.picocli.runtime.annotations.TopCommand
.
This can be overwritten with the
quarkus.picocli.top-command
property.
package com.acme.picocli;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
@TopCommand
@CommandLine.Command(mixinStandardHelpOptions = true, subcommands = {HelloCommand.class, GoodByeCommand.class})
public class EntryCommand {
}
@CommandLine.Command(name = "hello", description = "Greet World!")
class HelloCommand implements Runnable {
@Override
public void run() {
System.out.println("Hello World!");
}
}
@CommandLine.Command(name = "goodbye", description = "Say goodbye to World!")
class GoodByeCommand implements Runnable {
@Override
public void run() {
System.out.println("Goodbye World!");
}
}
Customizing Picocli CommandLine instance
You can customize CommandLine classes used by the
picocli
extension by producing your own bean instance:
package com.acme.picocli;
import io.quarkus.picocli.runtime.PicocliCommandLineFactory;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;
@TopCommand
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Spec
CommandLine.Model.CommandSpec spec;
@Override
public void run() {
System.out.println("My name is: " + spec.name());
}
}
@ApplicationScoped
class CustomConfiguration {
@Produces
CommandLine customCommandLine(PicocliCommandLineFactory factory) {
(1)
return factory.create().setCommandName("CustomizedName");
}
}
1
PicocliCommandLineFactory
will create an instance of CommandLine with
TopCommand
and
CommandLine.IFactory
injected.
Different entry command for each profile
It is possible to create different entry command for each profile, using
@IfBuildProfile
:
@ApplicationScoped
public class Config {
@Produces
@TopCommand
@IfBuildProfile("dev")
public Object devCommand() {
return DevCommand.class;
(1)
}
@Produces
@TopCommand
@IfBuildProfile("prod")
public Object prodCommand() {
return new ProdCommand("Configured by me!");
}
}
1
You can return instance of
java.lang.Class
here. In such case
CommandLine
will try to instantiate this class using
CommandLine.IFactory
.
Configure CDI Beans with parsed arguments
You can use
Event<CommandLine.ParseResult>
or just
CommandLine.ParseResult
to configure CDI beans based on arguments parsed by Picocli.
This event will be generated in
QuarkusApplication
class created by this extension. If you are providing your own
@QuarkusMain
this event will not be raised.
CommandLine.ParseResult
is created from default
CommandLine
bean.
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Option(names = "-c", description = "JDBC connection string")
String connectionString;
@Inject
DataSource dataSource;
@Override
public void run() {
try (Connection c = dataSource.getConnection()) {
// Do something
} catch (SQLException throwables) {
// Handle error
}
}
}
@ApplicationScoped
class DatasourceConfiguration {
@Produces
@ApplicationScoped
(1)
DataSource dataSource(CommandLine.ParseResult parseResult) {
PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setURL(parseResult.matchedOption("c").getValue().toString());
return ds;
}
}
1
@ApplicationScoped
used for lazy initialization
Providing your own QuarkusMain
You can also provide your own application entry point annotated with
QuarkusMain
(as described in
Command Mode reference guide
).
package com.acme.picocli;
import io.quarkus.runtime.QuarkusApplication;
import io.quarkus.runtime.annotations.QuarkusMain;
import picocli.CommandLine;
import jakarta.inject.Inject;
@QuarkusMain
@CommandLine.Command(name = "demo", mixinStandardHelpOptions = true)
public class ExampleApp implements Runnable, QuarkusApplication {
@Inject
CommandLine.IFactory factory;
(1)
@Override
public void run() {
// business logic
}
@Override
public int run(String... args) throws Exception {
return new CommandLine(this, factory).execute(args);
}
}
1
Quarkus-compatible
CommandLine.IFactory
bean created by
picocli
extension.
Development Mode
In the development mode, i.e. when running
mvn quarkus:dev
, the application is executed and restarted every time the
Space bar
key is pressed. You can also pass arguments to your command line app via the
quarkus.args
system property, e.g.
mvn quarkus:dev -Dquarkus.args='--help'
and
mvn quarkus:dev -Dquarkus.args='-c -w --val 1'
.
For Gradle projects, arguments can be passed using
--quarkus-args
.
If you’re creating a typical Quarkus application (e.g., HTTP-based services) that includes command-line functionality, you’ll need to handle the application’s lifecycle differently. In the
Runnable.run()
method of your command, make sure to use
Quarkus.waitForExit()
or
Quarkus.asyncExit()
. This will prevent the application from shutting down prematurely and ensure a proper shutdown process.
Packaging your application
A Picocli command line application can be packaged in multiple formats (e.g. a JAR, a native executable) and can be published to various repositories (e.g. Homebrew, Chocolatey, SDKMAN!).
As a jar
A Picocli command line application is a standard Quarkus application and as such can be published as a JAR in various packaging formats (e.g. fast-jar, uber-jar).
In the context of a command line application, building an uber-jar is more practical if you plan on publishing the JAR as is.
For more information about how to build an uber-jar, see our documentation:
For
Maven
For
Gradle
You can then execute the application by using the standard
java -jar your-application.jar
command.
As a native executable
You can also build a
native executable
but keep in mind that native executables are not portable and that you need one binary per supported platform.
Publishing the application
Publishing your command line application to a repository makes it a lot easier to consume.
Various application repositories are available depending on your requirements such as
SDKMAN!
,
Homebrew
for macOS, or
Chocolatey
for Windows.
To publish to these repositories, we recommend the usage of
JReleaser
.
JReleaser adds executable wrappers around your JAR for your application to be easily executable.
Kubernetes support
Once you have your command line application, you can also generate the resources necessary to install and use this application in Kubernetes by adding the
kubernetes
extension. To install the
kubernetes
extension, run the following command in your project base directory.
CLI
quarkus extension add kubernetes
Maven
./mvnw quarkus:add-extension -Dextensions='kubernetes'
Gradle
./gradlew addExtension --extensions='kubernetes'
This will add the following to your
pom.xml
:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-kubernetes</artifactId>
</dependency>
And, next, build the application with:
CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build
The Kubernetes extension will detect the presence of the Picocli extension and hence generate a
Job
resource instead of a
Deployment
resource in the
target/kubernetes/
directory.
If you don’t want to generate a Job resource, you can specify the resource you want to generate using the property
quarkus.kubernetes.deployment-kind
. For example, if you want to generate a Deployment resource, use
quarkus.kubernetes.deployment-kind=Deployment
.
Moreover, you can provide the arguments that will be used by the Kubernetes job via the property
quarkus.kubernetes.arguments
. For example, after adding the property
quarkus.kubernetes.arguments=A,B
and building your project, the following Job resource will be generated:
apiVersion: batch/v1
kind: Job
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
name: app
spec:
completionMode: NonIndexed
suspend: false
template:
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
spec:
containers:
- args:
- A
- B
env:
- name: KUBERNETES_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
image: docker.io/user/app:0.1-SNAPSHOT
imagePullPolicy: Always
name: app
ports:
- containerPort: 8080
name: http
protocol: TCP
restartPolicy: OnFailure
terminationGracePeriodSeconds: 10
Finally, the Kubernetes job will be launched every time it is installed in Kubernetes. You can know more about how to run Kubernetes jobs in this
document
.
Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type
Default
quarkus.picocli.top-command
Name of bean annotated with
io.quarkus.picocli.runtime.annotations.TopCommand
or FQCN of class which will be used as entry point for Picocli CommandLine instance. This class needs to be annotated with
picocli.CommandLine.Command
.
Environment variable:
QUARKUS_PICOCLI_TOP_COMMAND
Show more
string |
| Markdown | [](https://quarkus.io/)
- Why
- [WHAT IS QUARKUS?](https://quarkus.io/about)
- [DEVELOPER JOY](https://quarkus.io/developer-joy)
- [PERFORMANCE](https://quarkus.io/performance)
- [KUBERNETES NATIVE](https://quarkus.io/kubernetes-native)
- [STANDARDS](https://quarkus.io/standards)
- [VERSATILITY](https://quarkus.io/versatility)
- [CONTAINER FIRST](https://quarkus.io/container-first)
- [USING SPRING?](https://quarkus.io/spring)
- AI
- [AI OVERVIEW](https://quarkus.io/ai)
- [JAVA FOR AI](https://quarkus.io/java-for-ai)
- [WHY QUARKUS FOR AI](https://quarkus.io/quarkus-for-ai)
- [AI BLUEPRINTS](https://quarkus.io/ai-blueprints)
- Learn
- [GET STARTED](https://quarkus.io/get-started)
- [DOCUMENTATION](https://quarkus.io/guides)
- [USER STORIES](https://quarkus.io/userstories/)
- ["Q" TIP VIDEOS](https://quarkus.io/qtips)
- [BOOKS](https://quarkus.io/books)
- Extensions
- [BROWSE EXTENSIONS](https://quarkus.io/extensions/)
- [USE EXTENSIONS](https://quarkus.io/faq/#what-is-a-quarkus-extension)
- [CREATE EXTENSIONS](https://quarkus.io/guides/writing-extensions)
- [SHARE EXTENSIONS](https://hub.quarkiverse.io/)
- Community
- [SUPPORT](https://quarkus.io/support/)
- [BLOG](https://quarkus.io/blog)
- [DISCUSSION](https://quarkus.io/discussion)
- [WORKING GROUPS](https://quarkus.io/working-groups)
- [PODCAST](https://quarkus.io/insights)
- [EVENTS](https://quarkus.io/events)
- [NEWSLETTER](https://quarkus.io/newsletter)
- [ROADMAP](https://github.com/orgs/quarkusio/projects/13/views/1)
- [BENEFACTORS](https://quarkus.io/benefactors)
- [START CODING](https://code.quarkus.io/)
- - [OFFICIAL (ENGLISH)](https://quarkus.io/guides/picocli)
- [PORTUGUĂŠS (BR)](https://pt.quarkus.io/guides/picocli)
- [ESPAĂ‘OL](https://es.quarkus.io/guides/picocli)
- [简体ä¸ć–‡](https://cn.quarkus.io/guides/picocli)
- [日本語](https://ja.quarkus.io/guides/picocli)
[Back to Guides](https://quarkus.io/guides/)
By Version
[Edit this Page](https://github.com/quarkusio/quarkus/edit/main/docs/src/main/asciidoc/picocli.adoc)
# Command Mode with Picocli
[Picocli](https://picocli.info/) is an open source tool for creating rich command line applications.
Quarkus provides support for using Picocli. This guide contains examples of `picocli` extension usage.
| | |
|---|---|
| | If you are not familiar with the Quarkus Command Mode, consider reading the [Command Mode reference guide](https://quarkus.io/guides/command-mode-reference) first. |
## Extension
Once you have your Quarkus project configured you can add the `picocli` extension to your project by running the following command in your project base directory.
CLI
```
quarkus extension add picocli
```
Maven
```
./mvnw quarkus:add-extension -Dextensions='picocli'
```
Gradle
```
./gradlew addExtension --extensions='picocli'
```
This will add the following to your build file:
pom.xml
```
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-picocli</artifactId>
</dependency>
```
build.gradle
```
implementation("io.quarkus:quarkus-picocli")
```
## Building a command line application
### Simple application
A simple Picocli application with only one `Command` can be created as follows:
```
package com.acme.picocli;
import picocli.CommandLine;
import jakarta.enterprise.context.Dependent;
import jakarta.inject.Inject;
@CommandLine.Command (1)
public class HelloCommand implements Runnable {
@CommandLine.Option(names = {"-n", "--name"}, description = "Who will we greet?", defaultValue = "World")
String name;
private final GreetingService greetingService;
public HelloCommand(GreetingService greetingService) { (2)
this.greetingService = greetingService;
}
@Override
public void run() {
greetingService.sayHello(name);
}
}
@Dependent
class GreetingService {
void sayHello(String name) {
System.out.println("Hello " + name + "!");
}
}
```
| | |
|---|---|
| **1** | If there is only one class annotated with `picocli.CommandLine.Command`, it will be used automatically as the entry point of the command line application. |
| **2** | All classes annotated with `picocli.CommandLine.Command` are registered as CDI beans. |
| | |
|---|---|
| | Beans annotated with `@CommandLine.Command` should not use proxied scopes (e.g. do not use `@ApplicationScoped`) because Picocli will not be able to set field values in such beans. By default, this Picocli extension registers classes annotated with `@CommandLine.Command` with the `@Dependent` scope. If you need to use a proxied scope, then annotate the setters and not the fields, for example: |
```
@CommandLine.Command
@ApplicationScoped
public class EntryCommand {
private String name;
@CommandLine.Option(names = "-n")
public void setName(String name) {
this.name = name;
}
}
```
### Command line application with multiple Commands
When multiple classes have the `picocli.CommandLine.Command` annotation, then one of them needs to be also annotated with `io.quarkus.picocli.runtime.annotations.TopCommand`. This can be overwritten with the `quarkus.picocli.top-command` property.
```
package com.acme.picocli;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
@TopCommand
@CommandLine.Command(mixinStandardHelpOptions = true, subcommands = {HelloCommand.class, GoodByeCommand.class})
public class EntryCommand {
}
@CommandLine.Command(name = "hello", description = "Greet World!")
class HelloCommand implements Runnable {
@Override
public void run() {
System.out.println("Hello World!");
}
}
@CommandLine.Command(name = "goodbye", description = "Say goodbye to World!")
class GoodByeCommand implements Runnable {
@Override
public void run() {
System.out.println("Goodbye World!");
}
}
```
### Customizing Picocli CommandLine instance
You can customize CommandLine classes used by the `picocli` extension by producing your own bean instance:
```
package com.acme.picocli;
import io.quarkus.picocli.runtime.PicocliCommandLineFactory;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;
@TopCommand
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Spec
CommandLine.Model.CommandSpec spec;
@Override
public void run() {
System.out.println("My name is: " + spec.name());
}
}
@ApplicationScoped
class CustomConfiguration {
@Produces
CommandLine customCommandLine(PicocliCommandLineFactory factory) { (1)
return factory.create().setCommandName("CustomizedName");
}
}
```
| | |
|---|---|
| **1** | `PicocliCommandLineFactory` will create an instance of CommandLine with `TopCommand` and `CommandLine.IFactory` injected. |
### Different entry command for each profile
It is possible to create different entry command for each profile, using `@IfBuildProfile`:
```
@ApplicationScoped
public class Config {
@Produces
@TopCommand
@IfBuildProfile("dev")
public Object devCommand() {
return DevCommand.class; (1)
}
@Produces
@TopCommand
@IfBuildProfile("prod")
public Object prodCommand() {
return new ProdCommand("Configured by me!");
}
}
```
| | |
|---|---|
| **1** | You can return instance of `java.lang.Class` here. In such case `CommandLine` will try to instantiate this class using `CommandLine.IFactory`. |
### Configure CDI Beans with parsed arguments
You can use `Event<CommandLine.ParseResult>` or just `CommandLine.ParseResult` to configure CDI beans based on arguments parsed by Picocli. This event will be generated in `QuarkusApplication` class created by this extension. If you are providing your own `@QuarkusMain` this event will not be raised. `CommandLine.ParseResult` is created from default `CommandLine` bean.
```
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Option(names = "-c", description = "JDBC connection string")
String connectionString;
@Inject
DataSource dataSource;
@Override
public void run() {
try (Connection c = dataSource.getConnection()) {
// Do something
} catch (SQLException throwables) {
// Handle error
}
}
}
@ApplicationScoped
class DatasourceConfiguration {
@Produces
@ApplicationScoped (1)
DataSource dataSource(CommandLine.ParseResult parseResult) {
PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setURL(parseResult.matchedOption("c").getValue().toString());
return ds;
}
}
```
| | |
|---|---|
| **1** | `@ApplicationScoped` used for lazy initialization |
### Providing your own QuarkusMain
You can also provide your own application entry point annotated with `QuarkusMain` (as described in [Command Mode reference guide](https://quarkus.io/guides/command-mode-reference)).
```
package com.acme.picocli;
import io.quarkus.runtime.QuarkusApplication;
import io.quarkus.runtime.annotations.QuarkusMain;
import picocli.CommandLine;
import jakarta.inject.Inject;
@QuarkusMain
@CommandLine.Command(name = "demo", mixinStandardHelpOptions = true)
public class ExampleApp implements Runnable, QuarkusApplication {
@Inject
CommandLine.IFactory factory; (1)
@Override
public void run() {
// business logic
}
@Override
public int run(String... args) throws Exception {
return new CommandLine(this, factory).execute(args);
}
}
```
| | |
|---|---|
| **1** | Quarkus-compatible `CommandLine.IFactory` bean created by `picocli` extension. |
## Development Mode
In the development mode, i.e. when running `mvn quarkus:dev`, the application is executed and restarted every time the `Space bar` key is pressed. You can also pass arguments to your command line app via the `quarkus.args` system property, e.g. `mvn quarkus:dev -Dquarkus.args='--help'` and `mvn quarkus:dev -Dquarkus.args='-c -w --val 1'`. For Gradle projects, arguments can be passed using `--quarkus-args`.
| | |
|---|---|
| | If you’re creating a typical Quarkus application (e.g., HTTP-based services) that includes command-line functionality, you’ll need to handle the application’s lifecycle differently. In the `Runnable.run()` method of your command, make sure to use `Quarkus.waitForExit()` or `Quarkus.asyncExit()`. This will prevent the application from shutting down prematurely and ensure a proper shutdown process. |
## Packaging your application
A Picocli command line application can be packaged in multiple formats (e.g. a JAR, a native executable) and can be published to various repositories (e.g. Homebrew, Chocolatey, SDKMAN!).
### As a jar
A Picocli command line application is a standard Quarkus application and as such can be published as a JAR in various packaging formats (e.g. fast-jar, uber-jar).
In the context of a command line application, building an uber-jar is more practical if you plan on publishing the JAR as is.
For more information about how to build an uber-jar, see our documentation:
- For [Maven](https://quarkus.io/guides/maven-tooling#uber-jar-maven)
- For [Gradle](https://quarkus.io/guides/gradle-tooling#building-uber-jars)
You can then execute the application by using the standard `java -jar your-application.jar` command.
Using plugins such as the [really-executable-jar-maven-plugin](https://github.com/brianm/really-executable-jars-maven-plugin) can be handy to simplify the execution of your command line application.
### As a native executable
You can also build a [native executable](https://quarkus.io/guides/building-native-image) but keep in mind that native executables are not portable and that you need one binary per supported platform.
### Publishing the application
Publishing your command line application to a repository makes it a lot easier to consume. Various application repositories are available depending on your requirements such as [SDKMAN\!](https://sdkman.io/), [Homebrew](https://brew.sh/) for macOS, or [Chocolatey](https://chocolatey.org/) for Windows.
To publish to these repositories, we recommend the usage of [JReleaser](https://jreleaser.org/).
JReleaser adds executable wrappers around your JAR for your application to be easily executable.
### More information
You can also consult the [Picocli official documentation](https://picocli.info/#_packaging_your_application) for more general information about how to package Picocli applications.
## Kubernetes support
Once you have your command line application, you can also generate the resources necessary to install and use this application in Kubernetes by adding the `kubernetes` extension. To install the `kubernetes` extension, run the following command in your project base directory.
CLI
```
quarkus extension add kubernetes
```
Maven
```
./mvnw quarkus:add-extension -Dextensions='kubernetes'
```
Gradle
```
./gradlew addExtension --extensions='kubernetes'
```
This will add the following to your `pom.xml`:
```
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-kubernetes</artifactId>
</dependency>
```
And, next, build the application with:
CLI
```
quarkus build
```
Maven
```
./mvnw install
```
Gradle
```
./gradlew build
```
The Kubernetes extension will detect the presence of the Picocli extension and hence generate a [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) resource instead of a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resource in the `target/kubernetes/` directory.
| | |
|---|---|
| | If you don’t want to generate a Job resource, you can specify the resource you want to generate using the property `quarkus.kubernetes.deployment-kind`. For example, if you want to generate a Deployment resource, use `quarkus.kubernetes.deployment-kind=Deployment`. |
Moreover, you can provide the arguments that will be used by the Kubernetes job via the property `quarkus.kubernetes.arguments`. For example, after adding the property `quarkus.kubernetes.arguments=A,B` and building your project, the following Job resource will be generated:
```
apiVersion: batch/v1
kind: Job
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
name: app
spec:
completionMode: NonIndexed
suspend: false
template:
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
spec:
containers:
- args:
- A
- B
env:
- name: KUBERNETES_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
image: docker.io/user/app:0.1-SNAPSHOT
imagePullPolicy: Always
name: app
ports:
- containerPort: 8080
name: http
protocol: TCP
restartPolicy: OnFailure
terminationGracePeriodSeconds: 10
```
Finally, the Kubernetes job will be launched every time it is installed in Kubernetes. You can know more about how to run Kubernetes jobs in this [document](https://kubernetes.io/docs/concepts/workloads/controllers/job/#running-an-example-job).
## Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
| Configuration property | Type | Default |
|---|---|---|
| [`quarkus.picocli.top-command`](https://quarkus.io/guides/picocli#quarkus-picocli_quarkus-picocli-top-command) Name of bean annotated with `io.quarkus.picocli.runtime.annotations.TopCommand` or FQCN of class which will be used as entry point for Picocli CommandLine instance. This class needs to be annotated with `picocli.CommandLine.Command`. Environment variable: `QUARKUS_PICOCLI_TOP_COMMAND` Show more | string | |
- [Extension](https://quarkus.io/guides/picocli#extension)
- [Building a command line application](https://quarkus.io/guides/picocli#building-a-command-line-application)
- [Simple application](https://quarkus.io/guides/picocli#simple-application)
- [Command line application with multiple Commands](https://quarkus.io/guides/picocli#command-line-application-with-multiple-commands)
- [Customizing Picocli CommandLine instance](https://quarkus.io/guides/picocli#customizing-picocli-commandline-instance)
- [Different entry command for each profile](https://quarkus.io/guides/picocli#different-entry-command-for-each-profile)
- [Configure CDI Beans with parsed arguments](https://quarkus.io/guides/picocli#configure-cdi-beans-with-parsed-arguments)
- [Providing your own QuarkusMain](https://quarkus.io/guides/picocli#providing-your-own-quarkusmain)
- [Development Mode](https://quarkus.io/guides/picocli#development-mode)
- [Packaging your application](https://quarkus.io/guides/picocli#packaging-your-application)
- [As a jar](https://quarkus.io/guides/picocli#as-a-jar)
- [As a native executable](https://quarkus.io/guides/picocli#as-a-native-executable)
- [Publishing the application](https://quarkus.io/guides/picocli#publishing-the-application)
- [More information](https://quarkus.io/guides/picocli#more-information)
- [Kubernetes support](https://quarkus.io/guides/picocli#kubernetes-support)
- [Configuration Reference](https://quarkus.io/guides/picocli#configuration-reference)
## Related content
### On the same topics
- [Command Mode Applications](https://quarkus.io/guides/command-mode-reference)
- [Building Quarkus apps with Quarkus Command Line Interface (CLI)](https://quarkus.io/guides/cli-tooling)
- [Using gRPC CLI](https://quarkus.io/guides/grpc-cli)
[](https://quarkus.io/)
Quarkus is open. All dependencies of this project are available under the [Apache Software License 2.0](https://www.apache.org/licenses/LICENSE-2.0) or compatible license. [CC by 3.0](https://creativecommons.org/licenses/by/3.0/)
This website was built with [Jekyll](https://jekyllrb.com/), is hosted on [GitHub Pages](https://pages.github.com/) and is completely open source. If you want to make it better, [fork the website](https://github.com/quarkusio/quarkusio.github.io) and show us what you’ve got.
Navigation
- [Home](https://quarkus.io/)
- [About](https://quarkus.io/about)
- [Blog](https://quarkus.io/blog)
- [Podcast](https://quarkus.io/insights)
- [Events](https://quarkus.io/events)
- [Newsletter](https://quarkus.io/newsletter)
- [User Stories](https://quarkus.io/userstories)
- [Roadmap](https://github.com/orgs/quarkusio/projects/13/views/1)
- [Security policy](https://quarkus.io/security)
- [Usage](https://quarkus.io/usage)
- [Brand](https://github.com/commonhaus/artwork/tree/main/projects/quarkus)
- [Wallpapers](https://quarkus.io/desktopwallpapers)
- [Privacy Policy](https://www.redhat.com/en/about/privacy-policy)
Follow Us
- [X](https://x.com/quarkusio)
- [Bluesky](https://bsky.app/profile/quarkus.io)
- [Mastodon](https://fosstodon.org/@quarkusio)
- [Threads](https://www.threads.com/@quarkusio)
- [Facebook](https://www.facebook.com/quarkusio)
- [Linkedin](https://www.linkedin.com/company/quarkusio/)
- [Youtube](https://www.youtube.com/channel/UCaW8QG_QoIk_FnjLgr5eOqg)
- [GitHub](https://github.com/quarkusio)
Get Help
- [Support](https://quarkus.io/support)
- [Guides](https://quarkus.io/guides)
- [FAQ](https://quarkus.io/faq)
- [Get Started](https://quarkus.io/get-started)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/quarkus)
- [Discussions](https://github.com/quarkusio/quarkus/discussions)
- [Development mailing list](https://groups.google.com/forum/#!forum/quarkus-dev)
- [Quarkus Service Status](https://stats.uptimerobot.com/ze1PfweT2p)
Languages
- [English](https://quarkus.io/)
- [PortuguĂŞs (Brasileiro)](https://pt.quarkus.io/)
- [Español](https://es.quarkus.io/)
- [简体ä¸ć–‡](https://cn.quarkus.io/)
- [日本語](https://ja.quarkus.io/)
Quarkus is made of community projects
- [Eclipse Vert.x](https://vertx.io/)
- [SmallRye](https://smallrye.io/)
- [Hibernate](https://hibernate.org/)
- [Netty](https://netty.io/)
- [RESTEasy](https://resteasy.github.io/)
- [Apache Camel](https://camel.apache.org/)
- [Eclipse MicroProfile](https://microprofile.io/)
- [And many more...](https://code.quarkus.io/)
[](https://www.commonhaus.org/)
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our [Trademark Policy](https://www.commonhaus.org/policies/trademark-policy/) and [Trademark List](https://www.commonhaus.org/trademarks/). Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association. |
| Readable Markdown | [Edit this Page](https://github.com/quarkusio/quarkus/edit/main/docs/src/main/asciidoc/picocli.adoc)
[Picocli](https://picocli.info/) is an open source tool for creating rich command line applications.
Quarkus provides support for using Picocli. This guide contains examples of `picocli` extension usage.
## Extension
Once you have your Quarkus project configured you can add the `picocli` extension to your project by running the following command in your project base directory.
CLI
```
quarkus extension add picocli
```
Maven
```
./mvnw quarkus:add-extension -Dextensions='picocli'
```
Gradle
```
./gradlew addExtension --extensions='picocli'
```
This will add the following to your build file:
pom.xml
```
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-picocli</artifactId>
</dependency>
```
build.gradle
```
implementation("io.quarkus:quarkus-picocli")
```
## Building a command line application
### Simple application
A simple Picocli application with only one `Command` can be created as follows:
```
package com.acme.picocli;
import picocli.CommandLine;
import jakarta.enterprise.context.Dependent;
import jakarta.inject.Inject;
@CommandLine.Command (1)
public class HelloCommand implements Runnable {
@CommandLine.Option(names = {"-n", "--name"}, description = "Who will we greet?", defaultValue = "World")
String name;
private final GreetingService greetingService;
public HelloCommand(GreetingService greetingService) { (2)
this.greetingService = greetingService;
}
@Override
public void run() {
greetingService.sayHello(name);
}
}
@Dependent
class GreetingService {
void sayHello(String name) {
System.out.println("Hello " + name + "!");
}
}
```
| | |
|---|---|
| **1** | If there is only one class annotated with `picocli.CommandLine.Command`, it will be used automatically as the entry point of the command line application. |
| **2** | All classes annotated with `picocli.CommandLine.Command` are registered as CDI beans. |
| | |
|---|---|
| | Beans annotated with `@CommandLine.Command` should not use proxied scopes (e.g. do not use `@ApplicationScoped`) because Picocli will not be able to set field values in such beans. By default, this Picocli extension registers classes annotated with `@CommandLine.Command` with the `@Dependent` scope. If you need to use a proxied scope, then annotate the setters and not the fields, for example: |
```
@CommandLine.Command
@ApplicationScoped
public class EntryCommand {
private String name;
@CommandLine.Option(names = "-n")
public void setName(String name) {
this.name = name;
}
}
```
### Command line application with multiple Commands
When multiple classes have the `picocli.CommandLine.Command` annotation, then one of them needs to be also annotated with `io.quarkus.picocli.runtime.annotations.TopCommand`. This can be overwritten with the `quarkus.picocli.top-command` property.
```
package com.acme.picocli;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
@TopCommand
@CommandLine.Command(mixinStandardHelpOptions = true, subcommands = {HelloCommand.class, GoodByeCommand.class})
public class EntryCommand {
}
@CommandLine.Command(name = "hello", description = "Greet World!")
class HelloCommand implements Runnable {
@Override
public void run() {
System.out.println("Hello World!");
}
}
@CommandLine.Command(name = "goodbye", description = "Say goodbye to World!")
class GoodByeCommand implements Runnable {
@Override
public void run() {
System.out.println("Goodbye World!");
}
}
```
### Customizing Picocli CommandLine instance
You can customize CommandLine classes used by the `picocli` extension by producing your own bean instance:
```
package com.acme.picocli;
import io.quarkus.picocli.runtime.PicocliCommandLineFactory;
import io.quarkus.picocli.runtime.annotations.TopCommand;
import picocli.CommandLine;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;
@TopCommand
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Spec
CommandLine.Model.CommandSpec spec;
@Override
public void run() {
System.out.println("My name is: " + spec.name());
}
}
@ApplicationScoped
class CustomConfiguration {
@Produces
CommandLine customCommandLine(PicocliCommandLineFactory factory) { (1)
return factory.create().setCommandName("CustomizedName");
}
}
```
| | |
|---|---|
| **1** | `PicocliCommandLineFactory` will create an instance of CommandLine with `TopCommand` and `CommandLine.IFactory` injected. |
### Different entry command for each profile
It is possible to create different entry command for each profile, using `@IfBuildProfile`:
```
@ApplicationScoped
public class Config {
@Produces
@TopCommand
@IfBuildProfile("dev")
public Object devCommand() {
return DevCommand.class; (1)
}
@Produces
@TopCommand
@IfBuildProfile("prod")
public Object prodCommand() {
return new ProdCommand("Configured by me!");
}
}
```
| | |
|---|---|
| **1** | You can return instance of `java.lang.Class` here. In such case `CommandLine` will try to instantiate this class using `CommandLine.IFactory`. |
### Configure CDI Beans with parsed arguments
You can use `Event<CommandLine.ParseResult>` or just `CommandLine.ParseResult` to configure CDI beans based on arguments parsed by Picocli. This event will be generated in `QuarkusApplication` class created by this extension. If you are providing your own `@QuarkusMain` this event will not be raised. `CommandLine.ParseResult` is created from default `CommandLine` bean.
```
@CommandLine.Command
public class EntryCommand implements Runnable {
@CommandLine.Option(names = "-c", description = "JDBC connection string")
String connectionString;
@Inject
DataSource dataSource;
@Override
public void run() {
try (Connection c = dataSource.getConnection()) {
// Do something
} catch (SQLException throwables) {
// Handle error
}
}
}
@ApplicationScoped
class DatasourceConfiguration {
@Produces
@ApplicationScoped (1)
DataSource dataSource(CommandLine.ParseResult parseResult) {
PGSimpleDataSource ds = new PGSimpleDataSource();
ds.setURL(parseResult.matchedOption("c").getValue().toString());
return ds;
}
}
```
| | |
|---|---|
| **1** | `@ApplicationScoped` used for lazy initialization |
### Providing your own QuarkusMain
You can also provide your own application entry point annotated with `QuarkusMain` (as described in [Command Mode reference guide](https://quarkus.io/guides/command-mode-reference)).
```
package com.acme.picocli;
import io.quarkus.runtime.QuarkusApplication;
import io.quarkus.runtime.annotations.QuarkusMain;
import picocli.CommandLine;
import jakarta.inject.Inject;
@QuarkusMain
@CommandLine.Command(name = "demo", mixinStandardHelpOptions = true)
public class ExampleApp implements Runnable, QuarkusApplication {
@Inject
CommandLine.IFactory factory; (1)
@Override
public void run() {
// business logic
}
@Override
public int run(String... args) throws Exception {
return new CommandLine(this, factory).execute(args);
}
}
```
| | |
|---|---|
| **1** | Quarkus-compatible `CommandLine.IFactory` bean created by `picocli` extension. |
## Development Mode
In the development mode, i.e. when running `mvn quarkus:dev`, the application is executed and restarted every time the `Space bar` key is pressed. You can also pass arguments to your command line app via the `quarkus.args` system property, e.g. `mvn quarkus:dev -Dquarkus.args='--help'` and `mvn quarkus:dev -Dquarkus.args='-c -w --val 1'`. For Gradle projects, arguments can be passed using `--quarkus-args`.
| | |
|---|---|
| | If you’re creating a typical Quarkus application (e.g., HTTP-based services) that includes command-line functionality, you’ll need to handle the application’s lifecycle differently. In the `Runnable.run()` method of your command, make sure to use `Quarkus.waitForExit()` or `Quarkus.asyncExit()`. This will prevent the application from shutting down prematurely and ensure a proper shutdown process. |
## Packaging your application
A Picocli command line application can be packaged in multiple formats (e.g. a JAR, a native executable) and can be published to various repositories (e.g. Homebrew, Chocolatey, SDKMAN!).
### As a jar
A Picocli command line application is a standard Quarkus application and as such can be published as a JAR in various packaging formats (e.g. fast-jar, uber-jar).
In the context of a command line application, building an uber-jar is more practical if you plan on publishing the JAR as is.
For more information about how to build an uber-jar, see our documentation:
- For [Maven](https://quarkus.io/guides/maven-tooling#uber-jar-maven)
- For [Gradle](https://quarkus.io/guides/gradle-tooling#building-uber-jars)
You can then execute the application by using the standard `java -jar your-application.jar` command.
### As a native executable
You can also build a [native executable](https://quarkus.io/guides/building-native-image) but keep in mind that native executables are not portable and that you need one binary per supported platform.
### Publishing the application
Publishing your command line application to a repository makes it a lot easier to consume. Various application repositories are available depending on your requirements such as [SDKMAN\!](https://sdkman.io/), [Homebrew](https://brew.sh/) for macOS, or [Chocolatey](https://chocolatey.org/) for Windows.
To publish to these repositories, we recommend the usage of [JReleaser](https://jreleaser.org/).
JReleaser adds executable wrappers around your JAR for your application to be easily executable.
## Kubernetes support
Once you have your command line application, you can also generate the resources necessary to install and use this application in Kubernetes by adding the `kubernetes` extension. To install the `kubernetes` extension, run the following command in your project base directory.
CLI
```
quarkus extension add kubernetes
```
Maven
```
./mvnw quarkus:add-extension -Dextensions='kubernetes'
```
Gradle
```
./gradlew addExtension --extensions='kubernetes'
```
This will add the following to your `pom.xml`:
```
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-kubernetes</artifactId>
</dependency>
```
And, next, build the application with:
CLI
```
quarkus build
```
Maven
```
./mvnw install
```
Gradle
```
./gradlew build
```
The Kubernetes extension will detect the presence of the Picocli extension and hence generate a [Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/) resource instead of a [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resource in the `target/kubernetes/` directory.
| | |
|---|---|
| | If you don’t want to generate a Job resource, you can specify the resource you want to generate using the property `quarkus.kubernetes.deployment-kind`. For example, if you want to generate a Deployment resource, use `quarkus.kubernetes.deployment-kind=Deployment`. |
Moreover, you can provide the arguments that will be used by the Kubernetes job via the property `quarkus.kubernetes.arguments`. For example, after adding the property `quarkus.kubernetes.arguments=A,B` and building your project, the following Job resource will be generated:
```
apiVersion: batch/v1
kind: Job
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
name: app
spec:
completionMode: NonIndexed
suspend: false
template:
metadata:
labels:
app.kubernetes.io/name: app
app.kubernetes.io/version: 0.1-SNAPSHOT
spec:
containers:
- args:
- A
- B
env:
- name: KUBERNETES_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
image: docker.io/user/app:0.1-SNAPSHOT
imagePullPolicy: Always
name: app
ports:
- containerPort: 8080
name: http
protocol: TCP
restartPolicy: OnFailure
terminationGracePeriodSeconds: 10
```
Finally, the Kubernetes job will be launched every time it is installed in Kubernetes. You can know more about how to run Kubernetes jobs in this [document](https://kubernetes.io/docs/concepts/workloads/controllers/job/#running-an-example-job).
## Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
| | Type | Default |
|---|---|---|
| [`quarkus.picocli.top-command`](https://quarkus.io/guides/picocli#quarkus-picocli_quarkus-picocli-top-command) Name of bean annotated with `io.quarkus.picocli.runtime.annotations.TopCommand` or FQCN of class which will be used as entry point for Picocli CommandLine instance. This class needs to be annotated with `picocli.CommandLine.Command`. Environment variable: `QUARKUS_PICOCLI_TOP_COMMAND` Show more | string | | |
| Shard | 106 (laksa) |
| Root Hash | 3107096317879824306 |
| Unparsed URL | io,quarkus!/guides/picocli s443 |