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:

You can specify a user name and password in the username and password parameters, and the location of the server in the weburl parameter, as shown in the following examples.
You can specify a user name and password in the DS_USERNAME and DS_PASSWORD system variables, and the location of the server in the DS_WEB_URL system variable.
You can specify a token in the authtoken parameter or in the DS_AUTH_TOKEN system variable.
You can use the login command to create a temporary authentication to the server.

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.

Table 1. Global parameters
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 Deploy 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.

Table 2. Global flags
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 Deploy. 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