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.

Commands have the following format:

udclient [global-args...] [global-flags...] <command> [args...]

Note: You must enter CLI commands on one line.

Note: CLI commands and parameters are case-sensitive.

Note: Using CLI commands requires the same permissions as using the web interface. For information about permissions, see Roles and permissions.

Authenticating#

You can authenticate to the server in any of the following ways:

Passing parameters#

Most commands require one or more parameters. Parameters can change how the server interprets the command.

For example, if you do not pass any parameters to the getResources command (except the required global parameters), the server lists the top-level resources:

udclient -weburl http://ucdserver.example.com:8080 
  -username admin 
  -password admin 
  getResources

However, if you pass the path or ID of a resource in the parent parameter, the command returns the resources that are under that resource, as in the following example:

udclient -weburl http://ucdserver.example.com:8080 
  -username admin 
  -password admin 
  getResources
  -parent "/My Agents"

Passing JSON strings#

Some commands require a JSON string or file instead of or in addition to the parameters.

For example, the createApplication command creates an application. To use this command, you must pass a valid JSON string that specifies the name, description, and some properties of the new application. The JSON string for this command must follow this template:

{
  "description": "Description",
  "enforceCompleteSnapshots": "Specify true to require 
     an explicit version for each component",
  "name": "Application name or ID",
  "notificationScheme": "Notification scheme"
}

Note: To see the JSON template that a command requires, run the command with the -t switch, as in the following example:

udclient -weburl http://ucdserver.example.com:8080 
  -username admin 
  -password admin 
  createApplication
  -t

This template is also listed in the reference information for the command; see createApplication.

For example, the following JSON string represents an application that is named My Application:

{
  "description": "My new application",
  "enforceCompleteSnapshots": "false",
  "name": "My Application",
  "notificationScheme": "Default Notification Scheme"
}

To pass this JSON string, save the string to a file and pass the file to the command. For example, if you save the string to a file that is named newApplication.json, the command looks like the following example:

udclient -weburl http://ucdserver.example.com:8080 
  -username admin 
  -password admin 
  createApplication
  newApplication.json

Note: The string that you pass to the command must be a valid JSON string.

Global parameters and flags#

The following table lists the global parameters for the commands. These global parameters are listed as [global-args...] in code examples.

Argument Description
-authtoken, --authtoken Optional. Can be set with the DS_AUTH_TOKEN environment variable. An authentication token (authtoken) that is generated by the server. Either an authtoken or a user name and password are required.
-password, --password Optional. Can be set with the DS_PASSWORD environment variable. A password to authenticate with the server. Either an authtoken or a user name and password are required.
-proxyHost, --proxyHost Optional. Can be set with the proxyHost environment variable. The host name of a proxy (for example, an agent relay) to use instead of a direct connection to the server.
-proxyPassword, --proxyPassword Optional. Can be set with the proxyPassword environment variable. A password to use to authenticate with the proxy.
-proxyPort, --proxyPort Optional. Can be set with the proxyPort environment variable. The proxy port to use if a proxy host name is specified.
-proxyUser, --proxyUser Optional. Can be set with the proxyUser environment variable. A user name to use to authenticate with the proxy.
-username, --username Optional. Can be set with the DS_USERNAME environment variable. A user name to authenticate with the server. Either an authtoken or a user name and password are required.
-weburl, --weburl Required. Can be set with the DS_WEB_URL environment variable. The base URL of the HCL Launch server. For example, http://ds.example.com:8585.

The following table shows the global flags. These global flags are listed as [global-flags...] in code examples.

Flag Description
-t, --getTemplate Show the JSON template for the command instead of running the command. If a file argument is provided, the template is output to the specified file.
-h, --help Print the full description and help of the command instead of running the command.
-v, --verbose Print extra information.

When you specify objects such as applications, components, agents, and resources on the command line, you can use the name of the object or the object ID. The ID of an object is part of the URL that is displayed when you inspect the object in HCL Launch. For example, if you browse to a specific component and the URL is https://ucdeploy.example.com:8443/#component/2f153e93-00c3-44ef-a7fd-87e544e698d4, then the ID of the component is 2f153e93-00c3-44ef-a7fd-87e544e698d4.

This example shows the getResources command:

udclient -weburl http://localhost:8080 -username admin -password admin getResources

Parent topic: Command-line client (CLI) reference