Skip to content

App Factory Command-line Interface

From V9 ServicePack 4, App Factory has added a command-line Interface, which is designed by extending the existing Jenkins CLI. The App Factory Command-line Interface, or AFCLI, can be used to script routine tasks, bulk updates, troubleshooting, and other actions for your App Factory projects. You can use AFCLI to manage the project creation and configuration from your own systems and to minimize interaction with the Jenkins console.

Prerequisites

  • An App Factory user account with the Overall/Read permission

  • The jenkins-cli.jar file, which is used to run commands that are related to App Factory.

    To download the JAR file, click Download AFCLI on the left panel of the App Factory Console. Alternatively, you can use the following URL: <appfactory_url>/jnlpJars/jenkins-cli.jar.
    Make sure that you replace <appfactory_url> with the URL of your App Factory Console, for example: https://a12345.ci.hcl-cloud.com/jnlpJars/jenkins-cli.jar.

  • An App Factory API Token
    This is applicable only if you want to run Jenkins commands by using AFCLI.
    For more information, refer to Generating an API Token in App Factory.

Authentication

To perform actions on your project by using AFCLI, you need to add authentication to your App Factory commands. For more information about the App Factory commands, refer to AFCLI Commands.

The user account that is used for authentication with the Jenkins controller must have the Overall/Read permission to access AFCLI. The account may also require additional permissions for specific commands. For information about the different types of authentication, refer to the following sections.

Authentication with API TokenAuthentication with an API token uses the global option -auth, which requires an argument in the user:apitoken format. This authentication mechanism works for App Factory commands and Jenkins commands. For information about API tokens, refer to Generating an API Token in App Factory.

Note: Even if you use -auth for authentication, some commands might require the Foundry password to perform specific operations.

Syntax

For in-line arguments, the syntax is as follows:

java -jar jenkins-cli.jar [-s JENKINS_URL] -auth <username>:<api-token> [command] [command_arguments] [command_options]

To load the arguments from a file, the syntax is as follows:

java -jar jenkins-cli.jar [-s JENKINS_URL] -auth @/path/to/credentials [command] [command_arguments] [command_options]

Make sure that you provide the complete path of your credentials file, for example: @/home/username/.jenkins-cli.

Note:

You can also specify the username and the apitoken arguments by configuring the following environment variables:

  • username: $JENKINS_USER_ID
  • apitoken: $JENKINS_API_TOKEN

Make sure that both the variables are set simultaneously.

Example

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" -auth username:123456 fetch-build-result MyProject25 iris 19 --password "foundry_password"

Generating an API Token in App Factory

An API token can be generated by using the me/configuration endpoint in your App Factory instance. To access the configuration page and generate an API token, follow these steps:

  1. Sign-in to your App Factory console.
  2. On the upper-right corner, click the email address of your account.
  3. On the left panel of the App Factory User page, click Configure.
  4. On the user configuration page, under API Token, click ADD NEW TOKEN.
  5. Type a name for the token, and then click GENERATE. An API Token is generated with the specified name.
  6. Copy the API Token by clicking the copy icon, and then save the token. You can also revoke the token by clicking the revoke icon.

Important: Make sure that you save the token value because it will not be visible after you navigate away from the configuration page.

  1. Click APPLY, and then click SAVE.

After saving the user configuration, you can use the API token with the -auth option in AFCLI.

Authentication with User Credentials

Authentication with user credentials uses the command options --username and --password, which require your VoltMX Foundry credentials as arguments. Alternatively, you can use the -u and -p command options for the credentials This mechanism only works with App Factory commands and cannot be used with Jenkins commands.

Syntax

java -jar jenkins-cli.jar [-s JENKINS_URL] [global options] [command] --username '<username>' --password '<password>'

java -jar jenkins-cli.jar [-s JENKINS_URL] [global options] [command] -u '<username>' -p '<password>'

Example

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" fetch-build-result MyProject25 iris 19  --username 'user.name@hcl.com' --password 'foundry_password'

AFCLI Commands

The general syntax to run commands is as follows:

java -jar jenkins-cli.jar [-s JENKINS_URL] [global options] command [command options] [arguments]

The JENKINS_URL parameter can be specified by using the environment variable $JENKINS_URL. You can view the summaries of other general options by running the client without any arguments.

AFCLI provides commands that are specific to your App Factory instance. AFCLI also supports built-in Jenkins CLI commands, such as build or list-jobs. To view the full list of commands that are available in your environment, use the help command, which is a Jenkins command that requires authentication with an API token (-auth). For example:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" -auth username:123456 help

To view information about an App Factory command, type the command name after help. For example:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" -auth username:123456 help create-project

For information about the different App Factory commands, refer to the following sections.

create-project

This command is used to create a project on App Factory. Based on the specified options, the output is the project name and the project type.

Syntax

create-project <appfactory_project> <project_type> [-f] [-s] [-w]

create-project <appfactory_project> <project_type> [--follow] [--sync] [--wait]

Arguments

ArgumentDescription

appfactory_project

Specifies the name of the project.

For example: MyProject25

project_type

Specifies the type of project that you want to create. The possible values are as follows:

  • VoltMX Project
  • HCL MicroServices Project

Options

Command OptionDescription

-f

OR

--follow

Follows the build progress and modifies the exit code based on the outcome of the build. Interrupts are not passed through to the build, therefore, the job will not be interrupted.

The build will continue even if you close the command-line interface (terminal).

-s

OR

--sync

Waits until the command is completed or aborted. Interrupts are passed through to the build, therefore, the job can be interrupted.

-w

OR

--wait

Waits till the start of the command.

Example

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" create-project MyProject25 "MicroServices Project" --username 'user.name@hcl.com' --password 'foundry_password'

fetch-project-settings

This command is used to retrieve the current project settings for the specified App Factory project in a JSON format.

The JSON format can be used as a template to update the settings by using the update-project-settings command. For new projects, the JSON keys in the template contain default values or null.

Syntax

fetch-project-settings <appfactory_project> <appfactory_service>

Arguments

ArgumentDescription

appfactory_project

Specifies the name of the project.

For example: MyProject25

appfactory_service

Specifies the service for which you want to fetch the details. Supports the following values:

  • Iris
  • Foundry

Example

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" fetch-project-settings MyProject25 iris --username 'user.name@hcl.com' --password 'foundry_password'

Sample Output

{
"sourceControl":{},
"internationalization":{},
"scans":
{
    "sonar":
    {
        "runSonar":false,
        "failBuildOnQualityGateStatus":false,
        "isDebugEnabled":false
    }
},
"notification":{},
"android":{},
"ios":
{
    "signingMethod":"API Key"
},
"models":
{
    "cleanAndRegenerate":true
}
}

update-project-settings

This command is used to configure the project settings of the specified project. The command requires the -j or --json option followed by a JSON string.

  • From the V9 ServicePack 5 release, the Foundry Project Settings can be fetched and configured.
  • In V9 ServicePack 4, only the Iris Project Settings can be fetched and configured.
  • For the shell input, HCL recommends using single quotes (') or proper escaping to specify the JSON string.

Syntax

For shell terminals:

update-project-settings <appfactory_project> <appfactory_service> [-j] '{"abc":"xyz"}'

update-project-settings <appfactory_project> <appfactory_service> [--json] '{"abc":"xyz"}'

For Windows command prompt:

update-project-settings <appfactory_project> <appfactory_service> [-j] "{\"abc\":\"xyz\"}"

update-project-settings <appfactory_project> <appfactory_service> [--json] "{\"abc\":\"xyz\"}"

Arguments

ArgumentDescription

appfactory_project

Specifies the name of the project.

For example: MyProject25

appfactory_service

Specifies the service that you want to update. Supports the following values:

  • Iris
  • Foundry

Options

Command OptionDescription

-j

OR

--json

Specifies that the input is in a JSON format. As an argument, this option requires a JSON string inside single quotes (') for a shell terminal; or a pre-escaped JSON wrapped in double quotes(") for Windows command prompt.

For simpler handling of JSON inputs, HCL recommends using a shell terminal.

This option is mandatory.

For example: '{"abc":"xyz"}' or "{\"abc\":\"xyz\"}"

Example

For shell terminals:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" update-project-settings MyProject25 iris -j   
'{"sourceControl":{"projectPath":"","scmVendor":"GitHub","scmCredentials":"MyGitCreds",  
"repositoryURL":"https://github.com/MyAppFactoryGit/MyProject25.git"},"ios ":{}}' --username 'user.lastname@hcl.com' --password 'foundry_password'

For Windows command prompt:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" update-project-settings MyProject25 iris -j   
"{\"sourceControl\":{\"projectPath\":\"\",\"scmVendor\":\"GitHub\",\"scmCredentials\":\"MyGitCreds\",  
\"repositoryURL\":\"https://github.com/MyAppFactoryGit/MyProject25.git\"},\"ios\":{}}" --username 'user.lastname@hcl.com' --password 'foundry_password'

build-project

This command is used to run the build job of the specified App Factory project. Based on the specified options, the output is either the build number or the queue ID of the job.

Syntax

build-project <appfactory_project> <appfactory_service> [-s] [-f] [-p] [-v] [-w]

build-project <appfactory_project> <appfactory_service> [--sync] [--follow] [--parameter] [--verbose] [--wait]

Arguments

ArgumentDescription

appfactory_project

Specifies the project that contains the build job.

For example: MyProject25

appfactory_service

Specifies the service for which you want to run the build job. Supports the following values:

  • Iris
  • Foundry

Options

Command OptionDescription

-s

OR

--sync

Waits until the command is completed or aborted. Interrupts are passed through to the build, therefore, the job can be interrupted.

This option provides the Build_Id and the final result as the output.

-f

OR

--follow

Follows the build progress and modifies the exit code based on the outcome of the build. Interrupts are not passed through to the build, therefore, the job will not be interrupted.

This option provides the Build_Id and the final result as the output.

The build will continue even if you close the command-line interface (terminal).

-param

OR

--parameter

Specifies a build parameter in the "key=value" format.

You can specify multiple parameters by separating them with a space. For example: -param"Key1=Value1" -param"Key=Value2"

For more information about the build parameters, refer to the following docs:

-v

OR

--verbose

Prints the console output of the build. This option must be used with the -s option.

-w

OR

--wait

Waits till the start of the command.

This option provides the Build_Id as the output.

Example

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" build-project MyProject25 iris -param"Key1=Value1" -param"Key=Value2" --username 'user.name@hcl.com' --password 'foundry_password'

fetch-build-result

This command is used to fetch the results of the specified build job in an App Factory project. Based on your inputs to the command, the output is either the result or the status of the job.

Important: This command requires a Foundry password to fetch information about the build and the artifacts from the Foundry Console (or the S3 storage).

If you are using authentication with an API token, make sure that you include the --password option in the command.

Syntax

fetch-build-result <appfactory_project> <appfactory_service> <build_number> --password "foundry_password"

fetch-build-result <appfactory_project> <appfactory_service> <queue_id> --password "foundry_password"

Arguments

ArgumentDescription

appfactory_project

Specifies the project that contains the build job.

For example: MyProject25

appfactory_service

Specifies the service for which you want to run the build job. Supports the following values:

  • Iris
  • Foundry

build_number

OR

queue_id

Specifies the build number or the queue ID of the job for which you want to fetch the results.

For example: 19

The queue ID is not valid to fetch the result if the job has already started.

Example

Using Foundry credentials for authentication:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" fetch-build-result MyProject25 iris 19  --username 'user.name@hcl.com' --password 'foundry_password'

Using API token for authentication:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" -auth username:123456 fetch-build-result MyProject25 iris 19  --password 'foundry_password'

Sample Output (if the build is running)

{
"ciURL": "https://a12345.ci.hcl-cloud.com",
"project": "MyProject25",
"status": "RUNNING",
"buildJob":
{
    "jobName": "buildIrisApp",
    "buildid": 19,
    "queueid": 0,
    "durationms": 0,
}
}

Sample output (if the build is complete)

{
"ciURL": "https://a12345.ci.hcl-cloud.com",
"project": "MyProject25",
"status": "COMPLETED",
"buildJob":
{
    "jobName": "buildIrisApp",
    "buildUrl": "job/MyProject25/job/Iris/job/Builds/job/buildIrisApp/19/",
    "buildid": 19,
    "queueid": 0,
    "duration": "3 min, 1 sec",
    "result": "SUCCESS",
    "buildCause": "Started by user.name@hcl.com",
    "durationms": 181205,
    "artifacts":
    [
        "\"12345/MyProject25/Builds/buildIrisApp/19/buildResults-PASS.html\""
    ]
},
"channels":
[
{
    "jobName": "buildAndroid",
    "buildUrl": "job/MyProject25/job/MyProject25/job/Iris/job/Builds/job/Channels/job/buildAndroid/176/"
    "buildid": 176,
    "queueid": 0,
    "duration": "2 min, 41 sec",
    "result": "SUCCESS",
    "buildCause": "Started by upstream project \"MyProject25/Iris/Builds/buildIrisApp\" build number 19",
    "durationms": 163812,
    "artifacts":
    [
        "\"12345/MyProject25/Builds/AppFactoryServer/Android/Mobile/Native/176/MyProject25_176.apk\""
    ]
}
]
}

fetch-download-url

This command is used to fetch a URL to download the build artifacts. The artifacts contain details about the binaries of the specified build. The output is the download URL in a JSON format.

Important: This command requires a Foundry password to fetch information about the build and the artifacts from the Foundry Console (or the S3 storage).

If you are using authentication with an API token, make sure that you include the --password option in the command.

Syntax

fetch-download-url <artifact_type> <appfactory_project> <appfactory_service> <build_number> --password "foundry_password"

Arguments

ArgumentDescription

appfactory_project

Specifies the project that contains the build job.

For example: MyProject25

appfactory_service

Specifies the service for which you want to run the build job. Supports the following values:

  • Iris
  • Foundry

build_number

Specifies the number of the build job for which you want to fetch the download URL.

For example: 19

Example

Using Foundry credentials for authentication:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" fetch-download-url test MyProject25 iris 19 --username 'user.name@hcl.com' --password 'foundry_password'

Using API token for authentication:

java -jar jenkins-cli.jar -s "https://a12345.ci.hcl-cloud.com" -auth username:123456 fetch-download-url test MyProject25 iris 19 --password 'foundry_password'

Sample Output

{
"artifacts":
[
    "https://a12345-builds.s3.amazonaws/%2212345/MyProject25/Builds/buildIrisApp/25/buildResults-PASS.html%22?AWSAccessKeyId=1A2B3C4D5E&amp;Signature=abcd1234%2FPQRS7890",
    "https://a12345-builds.s3.amazonaws/%2212345/MyProject25/Builds/AppFactoryServer/Android/Mobile/Native/176/MyProject25_176.apk%22?AWSAccessKeyId=1A2B3C4D5E&amp;Signature=PQRS7890%2Fabcd1234"
]
}