Payara Cloud CLI User Guide

Introduction

pcl is command line utility for managing Payara Cloud namespaces and applications. It is distributed as executable jar file. It requires Java Runtime, version 8 or newer.

Documentation Structure

User Guide demonstrates the concept and usage of pcl mainly through examples. Command Reference then lists all options and sub-commands supported by the client. The content of reference is equivalent to output provided by option --help.

Notation used

Examples in this guide use the following convention:

command input in bold, using $var for user-specific input
stderr output in italics
stdout output

Getting started

Command Line Client prerequisities

Command Line Client is distributed as a zip package containing the client, shell wrappers for Windows and Unix-like systems and documentation package just like this one.

The client itself is an executable .jar file, that requires at least Java 8 to be available on the system.

Downloading the Commnand Line Client

Client is distributed over Payara’s Nexus Repository under following coordinates:

<dependency>
  <groupId>fish.payara.cloud</groupId>
  <artifactId>pcl</artifactId>
  <version>1.1.0</version>
</dependency>
Maven Repository Settings
<repository>
  <releases><enabled>true</enabled></releases>
  <snapshots><enabled>false</enabled></snapshots>
  <id>payara-artifacts</id>
  <name>Payara Artifacts</name>
  <url>https://nexus.payara.fish/repository/payara-artifacts/</url>
</repository>

Logging in

pcl uses OAuth Device Authentication flow to establish its identity to Payara Cloud. It will generate a confirmation code, which you use to log in to Payara Cloud web interface via browser.

pcl login
[INFO] In order to log in follow following link: https://login.payara.cloud/activate
[INFO] Your confirmation code is KKMD-STTF

The client will also open the browser for you if your environment permits it. In case you follow link manually you’ll need to enter the confirmation code on first page:

login 01 enter code

After that a confirmation page is displayed:

login 02 confirmation

Only confirm this page if you knowingly initiated login flow via pcl login, payara-cloud-maven-plugin or Payara IDE plugins. Payara Cloud will never ask you to authenticate via this flow via any other channel or under any other circumstance, such as solving a support issue.

If you are logging in for the first time the authentication service will ask you to authorize Payara Cloud CLI to perform application management tasks with your identity:

login 03 authorize

After confirming this, the authentication process is completed and you may close the browser window:

login 04 success

Managing tokens

After login is complete the relevant token is stored in $HOME/.payara/manage.payara.cloud. The token does not have any expiration time, so you will not need to log in again for when using pcl. Tokens can be invalidated remotely via User Preferences screen in Payara Cloud Web UI.

Non-interactive usage

Login only works for interactive sessions. In order to be able to perform pcl commands in non-interactive environments such as CI pcl login offers option --print-token.

pcl login --print-token
[INFO] In order to log in follow following link: https://login.payara.cloud/activate
[INFO] Your confirmation code is CVJF-XKGH
[SUCCESS] Token for environment-based login:
PCL_AUTH_TOKEN=eyJyZWZyZXNoX3Rva2VuIjoiWktMTFVQaUVIeEZ3c2JfOGNXSzFILUdnaUR1OVlXZUdDR3h3TUVFUlVrM3VLIn0=

The output of the command is the environment to use in order to establish the identity in a script.

In Github Actions the token can be used in following way:

Set secret PCL_AUTH_TOKEN for the repository to eyJyZWZyZXNoX3Rva2VuIjoiWktMTFVQaUVIeEZ3c2JfOGNXSzFILUdnaUR1OVlXZUdDR3h3TUVFUlVrM3VLIn0=.

In the workflow file refer to the secret like this:

    - name: Deploy new version
      env:
        PCL_AUTH_TOKEN: ${{ secrets.PCL_AUTH_TOKEN }}
      run: pcl -n project-head -a main-app upload target/app.war --deploy

Common options

Obtaining help

Option --help will provide with same content as Command Reference does, listing all available options and a short description of the command.

pcl --help
Payara Cloud Command Line.
Usage: pcl [-hqV] [-a=<applicationName>] [-n=<namespaceName>]
           [-o=<outputFormat>] [-s=<subscriptionName>] [COMMAND]
Payara Cloud Command Line Interface allows remote operations over Payara
Cloud's namespaces and application via command line.
In order to sign in, use the command `pcl login` interactively. This will allow
the client to obtain credentials that are either stored in home directory or
can be provided via environment variable `PCL_AUTH_TOKEN`. See `pcl login
--help` for details.
  -a, --application=<applicationName>
                  Name of application to manage.
                  Not required for commands listed by `-n` option, as well as
                    `list-applications` and `upload`.
  -h, --help      Show this help message and exit.
  -n, --namespace=<namespaceName>
                  Name of namespace to manage.
                  Required for all commands except `login`, `list-namespaces`
                    and `create-namespace`.
  -o, --output=<outputFormat>
                  Output format. Allowed values: TEXT, JSON.
  -q, --quiet     Quiet output.
                  Only result of operations will be displayed to `stdout`, or
                    error message to `stderrr`.
  -s, --subscription=<subscriptionName>
                  Name of subscription to use. Only necessary when account has
                    access to multiple subscriptions.
  -V, --version   Print version information and exit.
Commands:
  login               Log in to Payara Cloud instance.
  list-subscriptions  Get list of subscriptions available to user.
  list-namespaces     List namespaces available in a subscription.
  list-applications   List applications present in a namespace.
  upload              Upload application binary
  deploy              Deploy an existing application.
  start               Start an application
  stop                Stop an application
  create-namespace    Create new namespace
  delete-namespace    Deletes a namespace.
  delete-application  Delete an application.
  configure           Change configuration of an application
  scale               Scale an application

To find out about specific commands put --help after the command:

pcl upload --help
Usage: pcl upload [-ehqV] [--deploy] [-a=<applicationName>]
                  [-n=<namespaceName>] [-o=<outputFormat>]
                  [-s=<subscriptionName>] [-t=<timeout>] <file>
Upload application binary
Use to either provide new binary for existing application by specifying option
`-a` / `--application`, or to upload new application into a namespace.
      <file>                Application archive file (.war) to be uploaded
  -a, --application=<applicationName>
                            Name of application to manage.
                            Not required for commands listed by `-n` option, as
                              well as `list-applications` and `upload`.
      --deploy              Deploy application immediately.
                            Application will be immediately deployed after
                              upload if its default configuration is complete,
                              i. e. all required option have default values.
  -e, --fail-early          Fail command immediately after first deployment
                              problem instead of waiting for timeout on client
                              or backend side
                            There are certain scenarios when deployment can
                              succeed despite deployment problems reported.
                            It is therefore not guaranteed that application
                              deployment that failed with early warning will
                              not start up later.
  -h, --help                Show this help message and exit.
  -n, --namespace=<namespaceName>
                            Name of namespace to manage.
                            Required for all commands except `login`,
                              `list-namespaces` and `create-namespace`.
  -o, --output=<outputFormat>
                            Output format. Allowed values: TEXT, JSON.
  -q, --quiet               Quiet output.
                            Only result of operations will be displayed to
                              `stdout`, or error message to `stderrr`.
  -s, --subscription=<subscriptionName>
                            Name of subscription to use. Only necessary when
                              account has access to multiple subscriptions.
  -t, --timeout=<timeout>   Duration in seconds specifying how long to wait for
                              deployment to complete
                            This is client side timeout which doesn't affect
                              deployment process in Payara Cloud. It is
                              therefore not guaranteed that application
                              deployment that failed due to this time out will
                              not eventually start up later.
  -V, --version             Print version information and exit.

Determining version

This prints helpful information to determine the version and environment the command runs in.

pcl -V
pcl version: development-snapshot
Java version: 11.0.13, Vendor: Eclipse Adoptium, Platform encoding: UTF-8
OS: Windows 10, Version: 10.0, Arch: amd64

Output options

Option -o json can be used to force output to be JSON only, including error messages. Even though many commands return json in current version, it is possible that default console output will change in future versions. Output of -o json is planned to remain stable. Compare json output to those console outputs shown in Listing Namespaces and Creating a Namespace below:

pcl -o json list-namespaces
[{"href":"https://manage.payara.cloud/application/4727ef01-7811-4e5d-be9e-0847017bfc87/n/cli:clitest:efacd05c/","rel":"https://api.payara.cloud/entity/namespace","name":"cli-clitest","liveURI":"https://cli-clitest-xxxxxxxx.payara.app/","title":"cli-clitest"},{"href":"https://manage.payara.cloud/application/4727ef01-7811-4e5d-be9e-0847017bfc87/n/start:dev:85cafb11/","rel":"https://api.payara.cloud/entity/namespace","name":"start-dev","liveURI":"https://start-dev-xxxxxxxx.payara.app/","title":"start-dev"}]
pcl -o json create-namespace --project cli --stage clitest
{"timestamp":"2023-01-13T16:57:43.854254200Z","kind":"error","message":"Backend rejected the request: Namespace with this project / stage combination already exists (diagnostic id https://api.payara.cloud/error-instance/lcurj8l3)"}

Option -q will suppress all progress and warning messages, puting just the output onto stdout or error messages to stderr.

Namespace Management

Basic namespace operations are available via CLI. Other use cases, such as set up of custom domains or monitoring are only available via GUI.

Listing Namespaces

Use list-namespaces to see namespaces available to you:

pcl list-namespaces
[SUCCESS] Namespaces:
cli-clitest
    name: cli-clitest
    liveURI: https://cli-clitest-xxxxxxxx.payara.app/
start-dev
    name: start-dev
    liveURI: https://start-dev-xxxxxxxx.payara.app/

For all other commands that operate on namespace, you must supply the value of name (e. g. start-dev) as option -n.

Creating a Namespace

Creating namespace with create-namespace takes exact same input as GUI — project and stage the namespace should represent:

pcl create-namespace --project cli --stage clitest
[SUCCESS] Namespace was created

{
    "name": "cli-clitest",
    "cluster": {
        "name": "Azure, West Europe"
    },
    "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/"
}

Additionally, one can specify the provider and region namespace will be provisioned via option --region:

Region value Provider Region

azure-westeurope

Azure

West Europe (default)

azure-eastus

Azure

East US

pcl create-namespace --project cli --stage clitest --region azure-eastus
[SUCCESS] Namespace was created

{
    "name": "cli-clitest",
    "cluster": {
        "name": "Azure, East US"
    },
    "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/"
}

Payara Cloud can extend to support more regions and providers. The value is therefore checked after submission. If an invalid value is provided valid values for region will be provided in a warning message:

pcl create-namespace --project cli --stage clitest --region unsupported
[FAILURE] Backend rejected the request: Applicable values for region are: azure-westeurope (Azure, West Europe), azure-eastus (Azure, East US) (diagnostic id https://api.payara.cloud/error-instance/lcurjko0)

Project and stage need to be unique within your subscription. An error is reported when you attempt to create a namespace with same project/stage combination:

pcl create-namespace --project cli --stage clitest
[FAILURE] Backend rejected the request: Namespace with this project / stage combination already exists (diagnostic id https://api.payara.cloud/error-instance/lcurj5vw)

Deleting a Namespace

Namespace can be deleted by using delete-namespace command:

pcl delete-namespace --namespace $namespace -y
[SUCCESS] Namespace has been deleted

Deleting the namespace permanently removes all applications and their configurations. Option -y is required to confirm this step, otherwise a warning is displayed:

pcl delete-namespace -n $namespace
[WARN] To confirm you are sure about deleting this namespace, pass option -y on the command line

{
    "name": "cli-clitest",
    "cluster": {
        "name": "Azure, West Europe"
    },
    "liveURI": "https://cli-clitest-xxxxxxxx.payara.app/"
}

Application Management

CLI supports all usecases related to uploading a war file, configuring it and starting the revision.

Uploading .war File

A new application can be created within a namespace by uploading its binary artifact using the upload command:

pcl upload -n $namespace $warFile
[UPDATE] State of inspection process is CREATED
[SUCCESS] Application uploaded

{
    "name": "game-demo",
    "pendingChanges": true,
    "status": "PENDING"
}

Uploading an artifact starts an inspection process, which performs scanning of the .war file whilst identifying microprofile config properties, persistence units and datasources the application might require.

The application name is determined from Maven metadata in META-INF/maven by default. Should you want to override that, provide option -a/--application:

pcl upload -n $namespace -a $appName $warFile
[UPDATE] State of inspection process is CREATED
[SUCCESS] Application uploaded

{
    "name": "pass-deploy",
    "pendingChanges": true,
    "status": "PENDING"
}

Status PENDING signifies that application has not been deployed yet. Deployment can be either performed by the deploy command, or by providing option --deploy to the upload command.

pcl upload -n $namespace $warFile --deploy
[UPDATE] State of inspection process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYED
[SUCCESS] Deployment completed

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "RUNNING",
    "liveRuntimeSize": "QUARTER_CORE"
}

Here we see that inspection process is immediately followed by deployment process that starts up the application in target provisioning cluster.

Uploading a new .war for an existing application doesn’t immediately deploy it. The information that the newest state of the application is different from deployed state is represented by attribute pendingChanges, which is true in such case.

pcl upload -n $namespace -a $appName $warFile
[UPDATE] State of inspection process is CREATED
[SUCCESS] Application uploaded

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": true,
    "status": "RUNNING",
    "liveRuntimeSize": "QUARTER_CORE"
}

Deploying Application

To deploy an application as a separate step (for example after configuring it) use the deploy command:

pcl deploy -n $namespace -a $appName
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYED
[SUCCESS] Deployment completed

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "RUNNING",
    "liveRuntimeSize": "QUARTER_CORE"
}

Payara Cloud will keep retrying deployment for up to 10 minutes before it pronounces deployment failed. There are two switches to enable CLI terminate before the 10 minutes, in the scenario of deployment failure.

Note that in either of these cases backend deployment is not cancelled. This is intentionally designed that way, because application deployment could be fail due to some external service not being available at startup.

First option is to set client-side timeout for deployment with --timeout. Exit code in such case is 3.

pcl -n $namespace -a $appName deploy --timeout 35
[UPDATE] State of deployment process is DEPLOYING
[WARN] Exception while loading the app
[WARN] Exception during lifecycle processing
[WARN] org.glassfish.deployment.common.DeploymentException: CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)],
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)]
[WARN]  -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)],
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)]
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateInjectionPointForDeploymentProblems(Validator.java:378)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateInjectionPoint(Validator.java:290)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateGeneralBean(Validator.java:143)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateRIBean(Validator.java:164)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateBean(Validator.java:526)
[WARN] 	at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:64)
[WARN] 	at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:62)
[WARN] 	at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:62)
[WARN] 	at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:55)
[WARN] 	at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123)
[WARN] 	at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123)
[WARN] 	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
[WARN] 	at org.glassfish.enterprise.concurrent.internal.ManagedFutureTask.run(ManagedFutureTask.java:143)
[WARN] 	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
[WARN] 	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
[WARN] 	at java.base/java.lang.Thread.run(Thread.java:829)
[WARN] 	at org.glassfish.enterprise.concurrent.ManagedThreadFactoryImpl$ManagedThread.run(ManagedThreadFactoryImpl.java:250)
[WARN] Exception while loading the app : CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers
[WARN]  @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)],
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)]
[WARN]  -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)],
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)]
[FAILURE] Timed out waiting for deployment to finish

Another option is to fail immediately after deployment problem is identified by using the option --fail-early. Exit code in such case is 2.

pcl -n $namespace -a $appName deploy --fail-early
[UPDATE] State of deployment process is DEPLOYING
[WARN] Exception while loading the app
[WARN] Exception during lifecycle processing
[WARN] org.glassfish.deployment.common.DeploymentException: CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)],
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)]
[WARN]  -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)],
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)]
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateInjectionPointForDeploymentProblems(Validator.java:378)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateInjectionPoint(Validator.java:290)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateGeneralBean(Validator.java:143)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateRIBean(Validator.java:164)
[WARN] 	at org.jboss.weld.bootstrap.Validator.validateBean(Validator.java:526)
[WARN] 	at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:64)
[WARN] 	at org.jboss.weld.bootstrap.ConcurrentValidator$1.doWork(ConcurrentValidator.java:62)
[WARN] 	at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:62)
[WARN] 	at org.jboss.weld.executor.IterativeWorkerTaskFactory$1.call(IterativeWorkerTaskFactory.java:55)
[WARN] 	at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123)
[WARN] 	at org.glassfish.weld.services.ExecutorServicesImpl.lambda$inContextClassloader$0(ExecutorServicesImpl.java:123)
[WARN] 	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
[WARN] 	at org.glassfish.enterprise.concurrent.internal.ManagedFutureTask.run(ManagedFutureTask.java:143)
[WARN] 	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
[WARN] 	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
[WARN] 	at java.base/java.lang.Thread.run(Thread.java:829)
[WARN] 	at org.glassfish.enterprise.concurrent.ManagedThreadFactoryImpl$ManagedThread.run(ManagedThreadFactoryImpl.java:250)
[WARN] Exception while loading the app : CDI deployment failure:WELD-001408: Unsatisfied dependencies for type String with qualifiers
[WARN]  @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)],
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)]
[WARN]  -- WELD-001408: Unsatisfied dependencies for type String with qualifiers @Default
[WARN]   at injection point [BackedAnnotatedField] @Inject cloud.payara.fail.injection.FailingServlet.notAvailable
[WARN]   at cloud.payara.fail.injection.FailingServlet.notAvailable(FailingServlet.java:0)
[WARN] WELD-001475: The following beans match by type, but none have matching qualifiers:
[WARN]   - Producer Method [String] with qualifiers [@BatchProperty @Any] declared as [[UnbackedAnnotatedMethod] @Produces @Dependent @BatchProperty public com.ibm.jbatch.container.cdi.BatchProducerBean.produceProperty(InjectionPoint)],
[WARN]   - Producer Method [String] with qualifiers [@JaxRsParamQualifier @Any] declared as [[UnbackedAnnotatedMethod] @Produces @JaxRsParamQualifier public org.glassfish.jersey.ext.cdi1x.internal.CdiComponentProviderServerRuntimeSpecifics$JaxRsParamProducer.getParameterValue(InjectionPoint, BeanManager)]
[FAILURE] Failing early due to reported deployment problem

These both options are also available to other commands that might trigger deployment — upload and configure.

Listing Applications

In order to list applications within a namespace use command list-applications, that shows application names and their basic properties:

pcl list-applications -n $namespace
[SUCCESS] Applications:
game-demo
    name: game-demo
    applicationEndpoint: https://cli-clitest-xxxxxxxx.payara.app/
    status: RUNNING
other-app
    name: other-app
    applicationEndpoint: https://cli-clitest-xxxxxxxx.payara.app/other/
    status: RUNNING

Stopping an Application

A running application can be stopped with stop, providing the application name.

pcl stop -n $namespace -a $appName
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is STOPPED
[SUCCESS] Deployment completed

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "STOPPED",
    "liveRuntimeSize": "QUARTER_CORE"
}

A warning is displayed when application is in a state that doesn’t permit stopping it:

pcl stop -n $namespace -a $appName
[FAILURE] Application cannot be stopped

Starting an Application

A stopped application can be started again by using the start command.

pcl start -n $namespace -a $appName
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYED
[SUCCESS] Deployment completed

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "RUNNING",
    "liveRuntimeSize": "QUARTER_CORE"
}

If the application is not stopped, the command fails.

pcl start -n $namespace -a $appName
[FAILURE] Application cannot be started

Configuring an Application

The most dynamic command of cli is configure. Available sub-commands of configure depend on specific application and the configuration options it provides.

The configuration of an application consists of several partial configurations, that describe particular facets of that application. Semantics of partial configuration is represented by configuration kind, such as data source or context root configuration). Usually application has at most one partial configuration for each configuration kind, with only exception being data source, which has one configuration of kind dataSource for every data source identified.

Available configuration kinds can be seen by invoking detailed help of configure command while also specifying the target application:

pcl -n $namespace -a $appName configure --help
Usage: configure [-ehV] [--deploy] [-t=<timeout>] [<CONFIGURATION KIND>
                 key=value...]...
      --deploy              Deploy revision with updated configuration
                              immediately
  -e, --fail-early          Fail command immediately after first deployment
                              problem instead of waiting for timeout on client
                              or backend side
                            There are certain scenarios when deployment can
                              succeed despite deployment problems reported.
                            It is therefore not guaranteed that application
                              deployment that failed with early warning will
                              not start up later.
  -h, --help                Show this help message and exit.
  -t, --timeout=<timeout>   Duration in seconds specifying how long to wait for
                              deployment to complete
                            This is client side timeout which doesn't affect
                              deployment process in Payara Cloud. It is
                              therefore not guaranteed that application
                              deployment that failed due to this time out will
                              not eventually start up later.
  -V, --version             Print version information and exit.
Configuration kinds:
  microprofileConfig
  appRuntime
  contextRoot
pcl -n $namespace -a $appName configure contextRoot --help
Usage: configure contextRoot [-ehV] [--deploy] [-t=<timeout>]
                             [--add=<key>=<value>]...
                             [--reset=<removedParameters>]... [<key>=<value>...]
      [<key>=<value>...]    Property to set in a configuration
      --add=<key>=<value>   Properties to add to configuration
      --deploy              Deploy revision with updated configuration
                              immediately
  -e, --fail-early          Fail command immediately after first deployment
                              problem instead of waiting for timeout on client
                              or backend side
                            There are certain scenarios when deployment can
                              succeed despite deployment problems reported.
                            It is therefore not guaranteed that application
                              deployment that failed with early warning will
                              not start up later.
  -h, --help                Show this help message and exit.
      --reset=<removedParameters>
                            Properties to reset to default value or remove
  -t, --timeout=<timeout>   Duration in seconds specifying how long to wait for
                              deployment to complete
                            This is client side timeout which doesn't affect
                              deployment process in Payara Cloud. It is
                              therefore not guaranteed that application
                              deployment that failed due to this time out will
                              not eventually start up later.
  -V, --version             Print version information and exit.
Recognized configuration parameters:
  exposedPaths
  appName
  contextRoot

Recognized configuration parameters are keys that are known to exist for that particular configuration kind, and are reconfigured using syntax <parameter>=<value> after specifyig the configuration kind.

When reconfiguration succeeds full configuration of the application as well as metadata about the keys is returned as result

pcl -n $namespace -a $appName configure contextRoot contextRoot=/game
[SUCCESS] Revision reconfigured

{
    "kind": {
        "microprofileConfig": {
            "pass-deploy.war": {
                "values": {
                    "mp.jwt.verify.issuer": "fish.payara.demo",
                    "quiz.lockout": "1500",
                    "mp.jwt.verify.publickey.location": "publickey.pem",
                    "maths.duration": "20",
                    "quiz.duration": "20"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "quiz.lockout",
                        "required": false,
                        "default": "1500"
                    },
                    {
                        "name": "mp.jwt.verify.issuer",
                        "required": false,
                        "default": "fish.payara.demo"
                    },
                    {
                        "name": "mp.jwt.verify.publickey.location",
                        "required": false,
                        "default": "publickey.pem"
                    },
                    {
                        "name": "maths.duration",
                        "required": false,
                        "default": "20"
                    },
                    {
                        "name": "quiz.duration",
                        "required": false,
                        "default": "20"
                    }
                ]
            }
        },
        "appRuntime": {
            "pass-deploy.war": {
                "values": {
                    "runtimeSize": "QUARTER_CORE",
                    "scalabilityType": "ROLLING_UPGRADE"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "runtimeSize",
                        "required": false
                    },
                    {
                        "name": "scalabilityType",
                        "required": false
                    }
                ]
            }
        },
        "contextRoot": {
            "pass-deploy.war": {
                "values": {
                    "exposedPaths": "/*",
                    "appName": "game-demo",
                    "contextRoot": "/game"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "exposedPaths",
                        "required": false
                    },
                    {
                        "name": "contextRoot",
                        "required": true,
                        "default": "/"
                    },
                    {
                        "name": "appName",
                        "required": true,
                        "default": "game-demo"
                    }
                ]
            }
        }
    }
}

Changes are not immediately deployed. Command deploy needs to be invoked to make them live. Alternatively option --deploy can be passed to configure to trigger deployment immediately after reconfiguring. In such case output of the configure command matches output of deploy command.

pcl -n $namespace -a $appName configure microprofileConfig quiz.lockout=10 --deploy
[WARN] Revision reconfigured
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYED
[SUCCESS] Deployment completed

{
    "name": "config-with-deploy",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "RUNNING",
    "liveRuntimeSize": "QUARTER_CORE"
}

If provided parameter does not meet the syntax requirements or the entire configuration is not consistent the commands ends with a failure.

pcl -n $namespace -a $appName configure contextRoot contextRoot=game
[FAILURE] Backend rejected the request: 1 configurations are invalid
in contextRoot --id=pass-deploy.war:
	contextRoot: Value must start with a slash

Client will prevent to define configuration keys, that are not known.

pcl -n $namespace -a $appName configure contextRoot ctxRoot=game
[FAILURE] ctxRoot is not a valid option. If you want to add new property use --add ctxRoot=game

But it is valid use case to add a new property for microprofileConfig, in which case option --add needs to be used.

pcl -n $namespace -a $appName configure microprofileConfig --add new.app.config.property=value quiz.lockout=15
[SUCCESS] Revision reconfigured

{
    "kind": {
        "microprofileConfig": {
            "pass-deploy.war": {
                "values": {
                    "new.app.config.property": "value",
                    "mp.jwt.verify.issuer": "fish.payara.demo",
                    "quiz.lockout": "15",
                    "mp.jwt.verify.publickey.location": "publickey.pem",
                    "maths.duration": "20",
                    "quiz.duration": "20"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "quiz.lockout",
                        "required": false,
                        "default": "1500"
                    },
                    {
                        "name": "new.app.config.property",
                        "required": false
                    },
                    {
                        "name": "mp.jwt.verify.issuer",
                        "required": false,
                        "default": "fish.payara.demo"
                    },
                    {
                        "name": "mp.jwt.verify.publickey.location",
                        "required": false,
                        "default": "publickey.pem"
                    },
                    {
                        "name": "maths.duration",
                        "required": false,
                        "default": "20"
                    },
                    {
                        "name": "quiz.duration",
                        "required": false,
                        "default": "20"
                    }
                ]
            }
        },
        "appRuntime": {
            "pass-deploy.war": {
                "values": {
                    "runtimeSize": "QUARTER_CORE",
                    "scalabilityType": "ROLLING_UPGRADE"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "runtimeSize",
                        "required": false
                    },
                    {
                        "name": "scalabilityType",
                        "required": false
                    }
                ]
            }
        },
        "contextRoot": {
            "pass-deploy.war": {
                "values": {
                    "appName": "game-demo",
                    "contextRoot": "/"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "exposedPaths",
                        "required": false
                    },
                    {
                        "name": "contextRoot",
                        "required": true,
                        "default": "/"
                    },
                    {
                        "name": "appName",
                        "required": true,
                        "default": "game-demo"
                    }
                ]
            }
        }
    }
}

Multiple configurations and their attributes can be set at same time:

pcl -n $namespace -a $appName configure contextRoot contextRoot=/cr exposedPaths=/ui/* microprofileConfig quiz.lockout=12
[SUCCESS] Revision reconfigured

{
    "kind": {
        "microprofileConfig": {
            "pass-deploy.war": {
                "values": {
                    "mp.jwt.verify.issuer": "fish.payara.demo",
                    "quiz.lockout": "12",
                    "mp.jwt.verify.publickey.location": "publickey.pem",
                    "maths.duration": "20",
                    "quiz.duration": "20"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "quiz.lockout",
                        "required": false,
                        "default": "1500"
                    },
                    {
                        "name": "mp.jwt.verify.issuer",
                        "required": false,
                        "default": "fish.payara.demo"
                    },
                    {
                        "name": "mp.jwt.verify.publickey.location",
                        "required": false,
                        "default": "publickey.pem"
                    },
                    {
                        "name": "maths.duration",
                        "required": false,
                        "default": "20"
                    },
                    {
                        "name": "quiz.duration",
                        "required": false,
                        "default": "20"
                    }
                ]
            }
        },
        "appRuntime": {
            "pass-deploy.war": {
                "values": {
                    "runtimeSize": "QUARTER_CORE",
                    "scalabilityType": "ROLLING_UPGRADE"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "runtimeSize",
                        "required": false
                    },
                    {
                        "name": "scalabilityType",
                        "required": false
                    }
                ]
            }
        },
        "contextRoot": {
            "pass-deploy.war": {
                "values": {
                    "exposedPaths": "/ui/*",
                    "appName": "game-demo",
                    "contextRoot": "/cr"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "exposedPaths",
                        "required": false
                    },
                    {
                        "name": "contextRoot",
                        "required": true,
                        "default": "/"
                    },
                    {
                        "name": "appName",
                        "required": true,
                        "default": "game-demo"
                    }
                ]
            }
        }
    }
}

A configuration key can be reset to its default value, or removed if it doesn’t have default value and is not required. This can be achieved with option --reset <key>.

pcl -n $namespace -a $appName configure contextRoot --reset exposedPaths
[SUCCESS] Revision reconfigured

{
    "kind": {
        "microprofileConfig": {
            "pass-deploy.war": {
                "values": {
                    "mp.jwt.verify.issuer": "fish.payara.demo",
                    "quiz.lockout": "12",
                    "mp.jwt.verify.publickey.location": "publickey.pem",
                    "maths.duration": "20",
                    "quiz.duration": "20"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "quiz.lockout",
                        "required": false,
                        "default": "1500"
                    },
                    {
                        "name": "mp.jwt.verify.issuer",
                        "required": false,
                        "default": "fish.payara.demo"
                    },
                    {
                        "name": "mp.jwt.verify.publickey.location",
                        "required": false,
                        "default": "publickey.pem"
                    },
                    {
                        "name": "maths.duration",
                        "required": false,
                        "default": "20"
                    },
                    {
                        "name": "quiz.duration",
                        "required": false,
                        "default": "20"
                    }
                ]
            }
        },
        "appRuntime": {
            "pass-deploy.war": {
                "values": {
                    "runtimeSize": "QUARTER_CORE",
                    "scalabilityType": "ROLLING_UPGRADE"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "runtimeSize",
                        "required": false
                    },
                    {
                        "name": "scalabilityType",
                        "required": false
                    }
                ]
            }
        },
        "contextRoot": {
            "pass-deploy.war": {
                "values": {
                    "appName": "game-demo",
                    "contextRoot": "/cr"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "exposedPaths",
                        "required": false
                    },
                    {
                        "name": "contextRoot",
                        "required": true,
                        "default": "/"
                    },
                    {
                        "name": "appName",
                        "required": true,
                        "default": "game-demo"
                    }
                ]
            }
        }
    }
}

To enable horizontal scaling, add a new property for appRuntime to your configuration. Set the value of the scalabilityType parameter to HORIZONTAL_SCALING and specify the desired number of replicas.

pcl -n $namespace -a $appName configure appRuntime scalabilityType=HORIZONTAL_SCALING --add numberOfReplicas=4
[SUCCESS] Revision reconfigured

{
    "kind": {
        "appRuntime": {
            "petclinic.war": {
                "values": {
                    "numberOfReplicas": "4",
                    "runtimeSize": "QUARTER_CORE",
                    "runtimeType": "PAYARA6_JDK11",
                    "dataGridMode": "ENABLED",
                    "scalabilityType": "HORIZONTAL_SCALING"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "dataGridMode",
                        "required": false
                    },
                    {
                        "name": "numberOfReplicas",
                        "required": false
                    },
                    {
                        "name": "runtimeSize",
                        "required": false
                    },
                    {
                        "name": "runtimeType",
                        "required": false
                    },
                    {
                        "name": "scalabilityType",
                        "required": false
                    }
                ]
            }
        },
        "contextRoot": {
            "petclinic.war": {
                "values": {
                    "exposedPaths": "/*",
                    "appName": "petclinic-jakartaee",
                    "contextRoot": "/game"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "exposedPaths",
                        "required": false
                    },
                    {
                        "name": "contextRoot",
                        "required": true,
                        "default": "/petclinic-jakartaee"
                    },
                    {
                        "name": "appName",
                        "required": true,
                        "default": "petclinic-jakartaee"
                    }
                ]
            }
        },
        "dataSource": {
            "java:comp/DefaultDataSource": {
                "values": {
                    "datasourceClass": "org.h2.jdbcx.JdbcDataSource",
                    "steadyPoolSize": "1",
                    "maxWaitTime": "30000",
                    "jdbcUrl": "<default>",
                    "maxPoolSize": "10",
                    "resourceType": "javax.sql.DataSource",
                    "poolName": "java_comp_DefaultDataSource"
                },
                "complete": true,
                "keys": [
                    {
                        "name": "steadyPoolSize",
                        "required": true,
                        "default": "1"
                    },
                    {
                        "name": "maxPoolSize",
                        "required": true,
                        "default": "10"
                    },
                    {
                        "name": "maxWaitTime",
                        "required": true,
                        "default": "30000"
                    },
                    {
                        "name": "jdbcUrl",
                        "required": true,
                        "default": "<default>"
                    },
                    {
                        "name": "datasourceClass",
                        "required": true,
                        "default": "org.h2.jdbcx.JdbcDataSource"
                    },
                    {
                        "name": "resourceType",
                        "required": true,
                        "default": "javax.sql.DataSource"
                    },
                    {
                        "name": "user",
                        "required": false
                    },
                    {
                        "name": "password",
                        "required": false
                    },
                    {
                        "name": "poolName",
                        "required": true,
                        "default": "java_comp_DefaultDataSource"
                    }
                ]
            }
        }
    }
}

Logs can be seen in console with deployment progress.

pcl deploy -n $namespace -a $appName
[UPDATE] State of deployment process is DEPLOYING [0/2]
[UPDATE] State of deployment process is DEPLOYING [1/3]
[UPDATE] State of deployment process is DEPLOYING [2/4]
[UPDATE] State of deployment process is DEPLOYED [4/4]
[SUCCESS] Deployment completed

{
    "name": "petclinic-jakartaee",
    "applicationEndpoint": "https://start.zeromagic.io/game/",
    "pendingChanges": false,
    "status": "RUNNING",
    "horizontalScaling": true,
    "numberOfReplicas": 4,
    "liveRuntimeSize": "QUARTER_CORE"
}

If the application is configured for horizontal scaling, you can scale it directly by specifying the desired number of instances.

pcl -n $namespace -a $appName scale --instances=4
[UPDATE] State of deployment process is DEPLOYING
[UPDATE] State of deployment process is DEPLOYED
[SUCCESS] Deployment completed

{
    "name": "game-demo",
    "applicationEndpoint": "https://cli-clitest-xxxxxxxx.payara.app/",
    "pendingChanges": false,
    "status": "RUNNING",
    "numberOfReplicas": 4,
    "liveRuntimeSize": "QUARTER_CORE",
    "horizontalScaling": true
}