Bill's Quarkus CLI Scenarios

Quarkus CLI Scenarios

This page is a rough draft on how we want Quarkus CLI to work.

Installation

Name of bundle? 'quarkus-cli' might be the best as I don't know if 'quarkus' will ever want to mean something else?

Support for all package managers:

brew install quarkus-cli
yum install quarkus-cli
etc...

Commands

We want commands to be as short and concise as possible.

$ quarkus version # print version
$ quarkus upgrade [version] # upgrade to latest or a specific quarkus version.  This might turn into a verb that extensions can implement.
$ quarkus generate [extensions] # generate an example project based on extensions listed or added with quarkus add.  Prompt if a project already exists.
$ quarkus add <identifier>  # add a dependency, can be a short name i.e. 'jaxrs', an artifact idi.e `quarkus-amazon-lambda`, or a fully qualified maven artifact i.e. `io.quarkus:quarkus-amazon-lambda:1.0`.  Tab may offer you choices.
$ quarkus rm <identifier> # remove a dependency
$ quarkus list [extensions|dependencies] # list things added
$ quarkus ide [idea|eclipse|vsc] # launches IDE like jbang does
$ quarkus build # java build
$ quarkus native build # native build
$ quarkus deploy
$ quarkus dev # dev mode
$ quarkus run # run the target, but not in dev mode
$ quarkus test # Dev mode on steroids, automatically runs tests and watches test sources.  Auto compiles and reruns changed/added tests.

$ quarkus native build deploy # example of doing a build and deploy with a native target

Another approach is to scope commands based on their target:

$ quarkus extension add
$ quarkus extension list

IMO, this just adds to verbosity.

Should also think about custom extension commands too and if its something we want to support and how it effects the api. Might want something like this:

$ quarkus amazon-lambda invoke --payload payload.json

Implementation

The binary download will be limited on what it actually does. It will delegate to the quarkus maven/gradle plugin for anything that might require extension interaction. It will mostly exist to manage the pom.xml and to keep tract of things added via the command line.

Another thought is to split up the binary into a small installation download. The binary would just be a thin shell that was responsible for downloading and executing the actual quarkus cli engine based on the version of quarkus the user wants. The only thing I worry about this is that you would have 3 process forks quarkus -> cli engine -> maven/gradle. Not sure if this would be too slow.

In the tiny scenario, the binary will check to see Java/Maven/Gradle is installed add prompt user if they want to download it.

Quarkus Verb support

The Quarkus build system will need to support multiple different verbs that extensions can implement: deploy, upgrade, and generate come to mind as possible first verbs. Verbs are going to need access to configuration like @BuildSteps do. I also foresee the need for verb implementations to want to set up ordering when multiple extensions are involved with a single operation. An example is deploy where a Kubernetes extension might require the name of an image and that the image is already built and pushed before it can set up a Kubernetes endpoint.

We will need to decide on an extension API for verbs. The @BuildStep style isn't a bad idea as it would keep things consistent. You'd then have @DeployStep, @UpgradeStep, etc. If we make the engine generic enough, then we could make it easy to define new verbs with a meta-annotation i.e.

@QuarkusVerb("deploy")
@interface DeployStep {} 

Criteria for initial release

The initial release of the CLI should have at least a core set of functionality. Should also decide on whether we want a thin binary with a download cli engine. This will add to scope of initial release.

• process/scripts for setting up brew/yum/etc. installation
• version
• upgrade - just a simple toggle of the pom property is ok for release
• add/rm
• list
• [native] build
• dev/run
• ide - This may be easy to pull in as Max already did it for jbang.

Next tier:

• verb support in quarkus core, maven, gradle. IMO, generate should be a part of this verb support too and any code generation efforts refactored to this approach.
• generate implementations for each extension
• Some initial deploy extension implementions: funqy knative events, docker, kubernetes see logical choices

Final tier:

• test - This would be such a cool feature