Home
Extending product function
Learn how to extend the function of HCL Launch.
Command-line client (CLI) reference
CLI is a command-line interface that provides access to the HCL Launch server. It can be used to find or set properties and to run numerous functions.
CLI Commands
The following list shows the commands that are available.
upgradeAgent
Upgrade an agent

Extending product function
Learn how to extend the function of HCL Launch.
- Plug-ins
  The HCL plug-ins provide tools for creating component processes and integrations. HCL plug-ins provides plug-ins for several common deployment processes, and others are available to integrate with a wide variety of tools, such as middleware tools, databases, and servers.
- Creating notification templates
  Notification templates are the basis for emails that the server sends to users after an event occurs on the server. You can create customized notification templates by modifying the default templates provided, or by creating new templates of your own.
- REST API reference
  You can use these REST interfaces to automate tasks.
- Command-line client (CLI) reference
  CLI is a command-line interface that provides access to the HCL Launch server. It can be used to find or set properties and to run numerous functions.
  - Installing the command-line client
    The command-line client is available in an archive file that you can download from the server.
  - Command format
    To run a command, open a command-line window and specify the command and its parameters. In some cases, you must pass a JSON string with information for a command.
  - CLI Commands
    The following list shows the commands that are available.
    - addAgentPoolToTeam
      Add an agent pool to a team
    - addAgentToPool
      Add an agent to an agent pool
    - addAgentToTeam
      Add an agent to a team
    - addApplicationToTeam
      Add an application to a team
    - addComponentResourcePropDef
      Create a component resource property definition
    - addComponentTemplateToTeam
      Add a component template to a team
    - addComponentToApplication
      Add a component to an application.
    - addComponentToTeam
      Add a component to a team
    - addEnvironmentBaseResource
      Add a base resource to an environment
    - addEnvironmentProperty
      Create a component environment property
    - addEnvironmentToTeam
      Add an environment to a team
    - addGroupToTeam
      Add a group to a role on a team
    - addJavaPackage
      Upload a Java package.
    - addPostProcessingScriptToTeam
      Add a post processing script to a team
    - addProcessToTeam
      Add a process to a team
    - addResourceToTeam
      Add a resource to a team
    - addStatusToSnapshot
      Add a status to a snapshot
    - addTagToAgent
      Add a tag to an agent
    - addTagToApplication
      Add a tag to an application
    - addTagToComponent
      Add a tag to a component
    - addTagToResource
      Add a tag to a resource
    - addUserToGroup
      Add a user to a group
    - addUserToTeam
      Add a user to a role on a team
    - addVersionFiles
      Upload files to a version
    - addVersionLink
      Add a link on a version
    - addVersionLinkWithName
      Add a link on a version
    - addVersionStatus
      Add a status to a version
    - addVersionToSnapshot
      Add a component version to a snapshot
    - addWebhookToApplication
      Add a webhook to an application
    - addWebhookToProcess
      Add a webhook to a process
    - archiveVersion
      Archive the given versions of a component
    - autoDiscoverResource
    - bulkGetAgentJavaHomes
      Get list of managed Java installations in bulk
    - bulkGetPreferredJavaPackageForAgent
      Get the preferred Java packages compatible with agents in bulk.
    - bulkInstallAgentJava
      Install Java packages as a new managed Java installations in bulk
    - bulkSetAgentJavaHome
      Set the configured JAVA_HOME of agents in bulk
    - bulkUninstallAgentJava
      Uninstall a managed Java installations in bulk
    - cancelWorkflow
      Cancel a workflow in progress
    - closeTask
      Approve or reject an approval task
    - copyResource
      Copy a resource into a new parent
    - copyVersion
      Copy a component version with all of its properties
    - createAgentPool
      Create an agent pool
    - createApplication
      Create an application from a JSON file
    - createApplicationFromTemplate
      Create an application with components from a JSON file
    - createApplicationProcess
      Create an application process
    - createApplicationTemplate
      Create an application template from a JSON file
    - createAuthToken
      Create an authorization token
    - createComponent
      Create a component
    - createComponentProcess
      Create a new component process
    - createComponentTemplate
      Create a component template from a JSON file
    - createDeploymentTrigger
      Create a deployment trigger.
    - createEnvironment
      Create a new environment
    - createEnvironmentFromTemplate
      Create a new environment from template
    - createEnvironmentTemplate
      Create a new environment template
    - createGenericProcess
      Create a generic process
    - createGroup
      Create an empty group
    - createMaintenanceBlackout
      Create a Maintenance Blackout for the given date range. The date range cannot overlap with any existing Maintenance Blackout date ranges
    - createManyVersions
      Create multiple component versions
    - createPostProcessingScript
      Create a post processing script from a JSON file
    - createResource
      Create a resource
    - createResourceTemplate
      Create a resource template from a JSON file
    - createResourceTemplateWithAgentPrototypes
      Create a resource template with agent prototypes from a JSON file
    - createSnapshot
      Create a snapshot
    - createSnapshotOfEnvironment
      Take a snapshot of an environment
    - createStatus
      Create a status
    - createTeam
      Create a team
    - createUser
      Create a user
    - createVaultAppRole
      Create a new Vault App Role
    - createVaultSecretStore
      Create a secret store.
    - createVersion
      Create a component version
    - createWebhookTemplate
      Create a new webhook template
    - deleteAgent
      Delete an agent
    - deleteAgentPool
      Delete an agent pool
    - deleteAgentProperty
      Remove a property from an agent
    - deleteAllDesiredInventoryVersions
      Delete all versions for a component in an environment
    - deleteApplication
      Delete an application
    - deleteApplicationProcess
    - deleteApplicationTemplate
      Delete an application template
    - deleteComponent
      Delete a component
    - deleteComponentVersionPropDef
      Delete a component version property
    - deleteDeploymentTrigger
      Delete a deployment trigger.
    - deleteEnvironment
      Delete an environment
    - deleteEnvironmentTemplate
      Delete an environment template
    - deleteFrontendServer
      Delete a frontend server.
    - deleteGroup
      Delete a group
    - deleteJavaPackage
      Delete a java package.
    - deleteMaintenanceBlackout
      Delete the given maintenance blackout
    - deletePostProcessingScript
      Delete a post processing script.
    - deleteRedundantDesiredInventoryVersions
      Delete all redundant versions for a component in an environment
    - deleteResource
      Delete a resource
    - deleteResourceProperty
      Delete a resource property
    - deleteSecretStore
      Delete a secret store.
    - deleteSnapshot
      Delete a snapshot
    - deleteStatus
      Delete a status
    - deleteTeam
      Delete a team
    - deleteUser
      Delete a user
    - deleteVaultAppRole
      Delete a Vault AppRole
    - deleteVersion
      Delete a version from a component
    - deleteWebhookTemplate
      Delete a webhook template
    - downloadVersionArtifacts
      Download the artifacts of a component version
    - exportApplication
      Export an application to a json file.
    - exportComponent
      Export a component to a json file.
    - exportComponentTemplate
      Export a component template to a json file.
    - exportDetailedGroup
      List the members of a group (detailed)
    - exportGenericProcess
      Export a process to a json file
    - exportGroup
      List the members of a group
    - exportSnapshot
      Export a snapshot to a zip file.
    - finishedImporting
      Mark a version as completed importing
    - forceCancelWorkflow
      Force cancel a workflow in progress
    - forceRenameAgent
      Rename an agent
    - getAgent
      Get information about an agent
    - getAgentJavaHomes
      Get list of managed Java installations
    - getAgentMaintenanceTask
    - getAgentMaintenanceTasks
    - getAgentPool
      Get information about an agent pool
    - getAgentPools
      Get information about all agent pools
    - getAgentProperty
      Get the value of a property on an agent
    - getAgentPrototypes
      Get all agent prototypes with this resource template as their ancestor
    - getAgentStatuses
      Returns a JSONObject with count of agents to status. Expected format: { "ONLINE":4, "UPGRADE_RECOMMENDED":1 } Requires Settings Tab permission
    - getAgents
      Get information about all agents
    - getAllApplicationProcessesForApplication
      Get all application processes of an application
    - getAllComponentProcessRequestCount
      Get all component process requests submitted after a certain time
    - getAllComponentsForTemplate
      Get a list of all components using this template
    - getAllLatestDesiredInventory
      Get all of the latest desired inventory for an environment.
    - getAllProcesses
      Get information on all generic processes
    - getAllTeams
      List teams
    - getAllUsersInRoleForTeam
      List all users with a given role on a team
    - getAllUsersWithEmail
      Get all users with a given e-mail address
    - getApplication
      Get information about an application
    - getApplicationProcess
      Get information about an application process
    - getApplicationProcessExecution
      Get an application process request's activity trace.
    - getApplicationProcessRequest
      Get information about a specific application process request
    - getApplicationProcessRequestProperties
    - getApplicationProcessRequestStatus
      Request the status of an application process request
    - getApplicationProcessUnfilledProperties
      List properties that must be specified for a process
    - getApplicationProperties
      Get all application properties and their values.
    - getApplicationProperty
      Get the value of a custom property on a application
    - getApplicationTemplate
      Get information about an application template
    - getApplicationTemplatePropDefs
      Get information about the property definitions for the application template
    - getApplicationTemplates
      Get information about all application templates on the server
    - getApplications
      Get information about all applications on the server
    - getApplicationsProcessRequests
      Get information about all application process requests on the server
    - getApplicationsProcessRequestsCount
      Count all application process requests
    - getApprovalTasks
      List recent approval tasks
    - getAuthenticationRealms
      Get information about all authentication realms on the server
    - getComponent
      Get information about a component
    - getComponentEnvironmentProperties
      Get component environment properties for an environment
    - getComponentProcess
      Get information about a component process
    - getComponentProcessRequest
      Get information about a specific component process request
    - getComponentProcessRequestCount
      Get the number of component process requests submitted after a certain time given a specified component
    - getComponentProcessRequests
      Get information about all component process requests
    - getComponentProperties
      Get values for component properties
    - getComponentProperty
      Get the value of a property on a component. Property names can be prefixed to specify which set of propertieswill be searched. Unprefixed properties will search custom 'Component Properties' on a component while a propertynamed such as template/propertyName will search the properties inherited from a component templates property definitions.
    - getComponentTemplatePropDefs
      Get information about the property definitions for the component template
    - getComponentTemplates
      Get information about all component templates on the server
    - getComponentVersionPropDefs
      List the version property definitions for a component
    - getComponentVersions
      Get the versions of a component
    - getComponents
      Get information about all components on the server
    - getComponentsInApplication
      Get all components in an application
    - getCurrentActivityList
      Returns all child workflows of a parent request id if specified else returns all running workflow activities.
    - getDeploymentTrigger
      Get information about a single deployment trigger.
    - getDeploymentTriggers
      Get information about all deployment triggers for an environment.
    - getEnvironment
      Get information about an environment
    - getEnvironmentBaseResources
      Get all base resources for an environment
    - getEnvironmentProperties
      Get environment property values
    - getEnvironmentProperty
      Get the value of a custom property on an environment.
    - getEnvironmentResourceTree
      Get resource tree for an environment
    - getEnvironmentTemplate
      Get information about an environment template
    - getEnvironmentTemplatePropDefs
      Get information about the property definitions for the environment template
    - getEnvironmentsInApplication
      Get information about all environments in an application
    - getFirstUserWithEmail
      Get the first user with a given e-mail address
    - getFrontendServers
      Get a list of frontend servers.
    - getHighWatermarks
      Return high watermarks for agent usage
    - getInventoryChangesForSnapshot
      Get inventory changes for application process run with snapshot in environment
    - getJavaPackage
      Get available Java packages.
    - getJavaPackages
      Get available Java packages.
    - getJavaPackagesForAgent
      Get Java packages compatible with a specific agent.
    - getLatestDesiredInventory
      Get the latest desired inventory for an environment.
    - getLatestSnapshotForEnvironment
      Get the latest snapshot deployed to an environment
    - getMaintenanceBlackouts
      Returns a list of all Maintenance Blackouts that start or end within the specified range. If no range is provided then all Maintenance Blackouts will be returned
    - getOverlappingArtifacts
      Get all artifacts overlapped in the given version
    - getPostProcessingScript
      Get information about a post processing script
    - getPostProcessingScripts
      Get a list of post processing scripts.
    - getPreferredJavaPackageForAgent
      Get the preferred Java package compatible with an agent.
    - getProcessRequest
    - getProcessRequests
      Get information about all generic process requests on the server
    - getRelayStatuses
      Returns a JSONObject with count of agent relays to status. Expected format: { "ONLINE":4, "OFFLINE":1, } Requires Settings Tab permission.
    - getRelays
      Get information about all relays a user has access to.
    - getResource
      Get information about a resource
    - getResourceInventoryEntriesForComponent
      Get current resource inventory entries for a component
    - getResourceProperties
      List resource properties
    - getResourceProperty
      Get a resource property
    - getResourceTemplate
      Get a resource template
    - getResourceTemplateChildren
      Get all children or descendants of a resource template
    - getResources
      List resources
    - getResourcesWithComponentVersion
      List resources that have a specified component version
    - getSecretStore
      Get information about a secret store.
    - getSecretStores
      Get information about all secret stores.
    - getSnapshot
      Get information about a snapshot
    - getSnapshotConfiguration
      Get the list of configuration objects in a snapshot
    - getSnapshotVersions
      Get the list of versions in a snapshot
    - getSnapshotsInApplication
      Get information about snapshots in an application
    - getStatus
      Get information about a status
    - getStatusList
      Get a list of statuses on a snapshot
    - getStatuses
      List statuses
    - getSystemConfiguration
      List system configuration properties
    - getSystemProperties
      List system properties
    - getSystemProperty
      Get the value of a system property
    - getTagsForType
      Get the Tags for an object type.
    - getTagsOnAgent
      List all tags on an agent
    - getTagsOnApplication
      List all tags on an application
    - getTagsOnComponent
      Return all tags on a component
    - getTagsOnResource
      List the tags on a resource
    - getTasksForUser
      Return all approval tasks and manual tasks assigned to the user
    - getTeam
      List information about a team
    - getUser
      List information about a user
    - getUserByEmail
      Get the user or users with a given e-mail address
    - getUsersThatCanRunDeploymentTriggers
      Get all users that can run deployment triggers.
    - getVaultAppRole
      Get information about a Vault AppRole
    - getVaultAppRoles
      List the Vault AppRoles for a Vault store
    - getVersionId
      Get a version ID
    - getVersionLink
      Get a link on a component version
    - getVersionLinks
      List links on a version
    - getVersionProperties
      List the properties on a component version
    - getWebhookTemplate
      Get information about a webhook template
    - getWebhookTemplates
      List the viewable webhook templates
    - getWorkflowTraceLogs
      Returns full workflow trace with execution logs as a zip file in the current directory.If the underlying workflow is not complete, an HTTP 412 response is returned.
    - importApplication
      Import application from json file.
    - importComponent
      Import component from json file.
    - importComponentTemplate
      Import component template from json file.
    - importGenericProcess
      Import process from json file.
    - importGroup
      Import a group
    - importLdapUser
      Import a user from LDAP
    - importSnapshot
      Import snapshot from zip file.
    - importVersions
      Import new component versions
    - installAgent
      Install an agent
    - installAgentJava
      Install a Java package as a new managed Java installation
    - listArtifacts
      Get the list of artifacts for a version
    - lockSnapshotConfiguration
      Lock a snapshot's configuration
    - lockSnapshotVersions
      Lock a snapshot's version list
    - login
      Log in to the server
    - logout
      Log out of the server
    - moveResource
      Update a resource's parent
    - pauseWorkflow
      Pause a workflow in progress
    - provisionEnvironment
      Provision a cloud environment
    - removeAgentFromPool
      Remove an agent from an agent pool
    - removeAgentFromTeam
      Remove an agent from a team
    - removeAgentPoolFromTeam
      Remove an agent pool from a team
    - removeApplicationFromTeam
      Remove an application from a team
    - removeComponentFromTeam
      Remove a component from a team
    - removeComponentResourcePropDef
      Delete a component resource property definition
    - removeComponentTemplateFromTeam
      Remove a component template from a team
    - removeEnvironmentBaseResource
      Remove a base resource from an environment
    - removeEnvironmentFromTeam
      Remove an environment from a team
    - removeEnvironmentProperty
      Delete a component environment property
    - removeGroupFromRoleOnTeam
      Remove a group from a role on a team
    - removeProcessFromTeam
      Remove a process from a team
    - removeResourceFromTeam
      Remove a resource from a team
    - removeTagFromAgent
      Delete a tag from an agent
    - removeTagFromApplication
      Remove a tag from an application
    - removeTagFromComponent
      Delete a tag from a component
    - removeTagFromResource
      Remove a tag from a resource
    - removeUserFromGroup
      Remove a user from a group
    - removeUserFromRoleOnTeam
      Remove a user from a role on a team
    - removeVersionFromSnapshot
      Remove a component version from a snapshot
    - removeVersionLink
      Remove a link from a version
    - removeVersionLinkByName
      Remove a link from a version
    - removeVersionStatus
      Remove a status from a version
    - removeWebhookFromApplication
      Removes a webhook from a process
    - removeWebhookFromProcess
      Removes a webhook from a process
    - repeatApplicationProcessRequest
      Repeat an application process request
    - requestApplicationProcess
      Run an application process
    - requestProcess
      Executes new generic process request(s) for resource(s)
    - restartAgent
      Restart an agent
    - restoreArtifacts
      Restore artifacts of an archived version
    - resumeWorkflow
      Resume a workflow in progress
    - savePostProcessingScript
      Get information about a post processing script
    - setAgentJavaHome
      Set the configured JAVA_HOME of an agent
    - setAgentProperty
      Set a property on a agent
    - setApplicationProperty
      Set a property on an application
    - setComponentEnvironmentProperty
      Set a component environment property value
    - setComponentProperty
      Set a property on a component
    - setComponentVersionPropDef
      Set a version property for a component
    - setEnvironmentProperty
      Set a property on environment
    - setPreferredJavaPackage
      Sets a package as preferred for its OS and CPU, unsetting the previously preferred package if there was one.
    - setResourceProperty
      Set a property on a resource
    - setSystemConfiguration
      Update the system configuration
    - setSystemProperty
      Set a system property
    - setVersionProperty
      Set a property on a component version
    - shutdownAgent
      Shut down an agent
    - testAgent
      Test the connection from an agent to the server
    - uninstallAgentJava
      Uninstall a managed Java installation
    - unsetPreferredJavaPackage
      Unsets a package as preferred for its OS and CPU, leaving no package as preferred.
    - updateAgent
      Update agent settings
    - updateApplicationTemplate
      Update an application template
    - updateApplicationTemplatePropDefs
      Update an application template prop sheet def from a JSON file.
    - updateComponent
      Update a component
    - updateComponentResourcePropDef
      Update a component resource property definition
    - updateComponentTemplatePropDefs
      Update a component template prop-def sheet from a JSON file. Replaces the property definitions.
    - updateEnvironment
      Update an environment
    - updateEnvironmentProperty
      Update a component environment property
    - updateEnvironmentTemplate
      Update the basic settings of an environment template
    - updateEnvironmentTemplatePropDefs
      Update an environment template prop sheet def from a JSON file.
    - updateMaintenanceBlackout
      Modifies the time range for the given Maintenance Blackout. A date cannot be modified if it has already occurred
    - updateResource
      Update a resource
    - updateResourceTemplate
      Update a resource template from a JSON file
    - updateTeam
      Update a team
    - updateUser
      Update a user
    - updateUsersInAuthRealm
      Update all users in an authentication realm
    - updateVaultAppRole
      Update a Vault AppRole
    - updateVaultSecretStore
      Update a secret store.
    - updateWebhookForApplication
      Update an application webhook
    - updateWebhookForProcess
      Updates a webhook for a process
    - updateWebhookTemplate
      Update a webhook template
    - upgradeAgent
      Upgrade an agent
- Process-as-code feature
  Programmatically manage processes with PAC language.

upgradeAgent

Upgrade an agent

The agent will be upgraded to the agent version corresponding with the UrbanCode Deploy server version.

Format

udclient [global-args...] [global-flags...]
  upgradeAgent [parameters]

Parameters

Table 1. Parameters
Parameter	Type	Required	Description
agent	string	true	Name or ID of the agent

Example

udclient -username jsmith -password passwd 
  -weburl https://myserver.example.com:8443
  upgradeAgent
  -agent Agent1

Related REST command: Upgrade an agent.