Skip to end of metadata
Go to start of metadata

Topics marked with * relate to HQ Enterprise-only features.

Feedback is welcome. Click Add Comment at the bottom of the page.

Command-Line Tools Overview

This table lists the command-line tools:

Tool Functionality
agent List the agents registered with the HQ Server.
alertdefinition List, update, create, and delete resource and resource type alert definitions. An alert definition specifies the alert details and the resource or resource type to which it is assigned.
alert List, acknowledge, fix, and delete fired alerts.
application Create, list, and update applications configured in HQ.
autodiscovery List the platforms in the autodiscovery queue and approve them for import to inventory.
control List supported control actions for a resource, list control action history for a resource, and perform issue a control action to a resource.
dependency* List and manage dependency relationships between network or virtual hosts and platforms.
escalation List and update Escalations.
event List information about events – alerts, resource control actions, log events, or configuration events – that have been logged for a resource, or for all resources.
group List resource group definitions, create or update groups, and delete groups.
maintenance* Specify downtime periods for a compatible group, during which alerts on group members will not fire. Supported in HQ Enterprise only.
metric List and update the metric collection configuration for individual resources.
metricData List the measurements for a particular metric for a particular resource.
metricTemplate Output metric collection configuration for a specified resource type.
resource Output resource data, create or update resources, and delete resources.
role List, update, and create non-system roles.
serverConfig List and update selected HQ Server configuration properties,
user List, update, and create users.

Invoking Command-Line Tools

To invoke the command-line tools from shell, you run the script in the /bin directory of the client download, supplying the name of the tool you want to run. All commands have the following syntax:

./bin/ <top-level-command> <sub-command> <options>


  • <top-level-command> is the command-line tool name, for instance agent or resource.
  • <sub-command> is a supported command option, for instance list, sync, or delete.
  • <options> are one or more supported command qualifiers Supported options vary by command and subcommand, for example resource list supports the --prototype qualifier. See documentation for each command-line tool for supported command qualifiers.

This command returns a list of resources whose type is "MacOSX".

./bin/ resource list --prototype="MacOSX"

In the case of an error, the reason for the error will be printed to stderr and the process will exit with a negative return code.

A full listing of supported options can be obtained by passing the -h flag to any command.

Common Subcommands

Each command-line tool has one or more command options. The most common are described below.


list returns an XML object that describes one or more instances of the type of object you're working with - for instance, agents, resources, or roles. You can write the XML output to a file, and pipe it to the sync command to update the corresponding data in the HQ database. For example:

./bin/ resource list --prototype="HTTP" > http-resources.xml


sync takes a valid XML object that describes items in HQ - for instance, platforms, servers, or services - and updates the HQ database accordingly.

For some command-line tools, sync can create new items in HQ; for others, sync only updates items that already exist in HQ.

Note: When you use sync to create a new item, do not specify the id attribute for the new item.

To update an item, typically you write the XML object to a file using the list option, edit the contents as desired, and then use sync to update attributes for an existing item in HQ.

By default, sync reads the XML over stdin. For example:

cat http-resources.xml | ./bin/ resource sync

As desired, you can specify the location of the file with the --file command qualifier.

./bin/ resource sync --file=http-resources.xml


delete removes an item from the HQ database. The delete option supports only "one-at-a-time" deletions. You supply the name or ID of the item to delete.

Required Command Qualifiers and How to Supply Them

For each command line tool there is a set of required and optional command qualifiers.

The optional qualifiers usually set the scope of a command, for example, tell it to list a single resource instead of all the resources on a platform. Scoping qualifiers vary by command and are documented in the each command's reference documentation.

The qualifiers that every command requires are the parameters that specify how to connect to the HQ Server:

--host HQ server hostname
--port HQ server port
--user user to connect as
--password password for the given user
--secure Flag to indicate if SSL should be used.

The optional qualifiers that every command supports are:

--properties Supplies the path to a properties file that sets the values of the server connection settings listed above. Not necessary if you define the properties in the default location — ~/.hq/ — as described below in Define a Connection Properties File

Define a Connection Properties File

To avoid specifying the connection parameters each time you run a command, you can specify them in ~/.hq/ (create the directory and file if they do not already exist). Under Windows, you can create the .hq directory from a DOS shell. Use the mkdir command to create .hq under your home home directory.

For example:

Supply Properties File Path on Command Line

New in 3.0
This feature was introduced in HQApi v3.0,available in HQ v4.3.

By default, the APIs look for server connection properties in ~/.hq/ If you want to put in a different location, you can do so, and then supply the path to the file on the command line, using the --properties command qualifier.

The ability to specify the location of from the command line is useful if you use HQApi to administer multiple HQ Server instances. You can create a properties file for each HQ Server instance — after than, when you run an API from the command line, you can specify the location of the file with the appropriate connection properties.

Tips and Reminders for CLI Tools

Sync with Caution

There is no un-do command for updates you make with the API command line tools. Carefully review the XML you supply to a command line tool's sync method.

How to Find a Resource ID

When you run an HQ API command that operates on a particular resource you must identify the resource by its internal HQ ID. To obtain the ID for a resource, you can run the resource list command to find it. The resource list command returns inventory and configuration properties for one or more resources. For example, this command:

returns the results shown below; the third line defines the internal HQ ID for the resource: Resource id="27054"

You can use resource list to query by:

  • resource name - regex for resource name
  • platform name - to get properties for it and optionally, its child resources.
  • resource type - by query by platform name and get properties for it, and optionally, the resources running on it.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.