Note
This project is under active development. Please remember to check for new releases often.
Hyperview CLI (hvcli) is a command-line program for interacting with data in Hyperview.
Important Reminders
- Powerful Capabilities: This tool can modify data in Hyperview. Please take the time to familiarize yourself with its features.
- Check Twice, Act Once: Ensure that all your inputs are accurate. A small oversight can lead to unintended consequences.
- Test with a small sample first: Test and verify bulk changes with a small sample before making big changes.
Your success is important to us! Enjoy using the Hyperview CLI (hvcli), and remember to proceed with caution!
To use this tool, simply download a pre-built binary from the Releases section.
A valid Hyperview API client must be used. The API client must have the appropriate access. The configuration file must be placed in $HOME/.hyperview/hyperview.toml.
client_id = 'c33472d0-c66b-4659-a8f8-73c289ba4dbe'
client_secret = '2c239e21-f81b-472b-a8c3-82296d5f250d'
scope = 'HyperviewManagerApi'
auth_url = 'https://example.hyperviewhq.com/connect/authorize'
token_url = 'https://example.hyperviewhq.com/connect/token'
instance_url = 'https://example.hyperviewhq.com'Run the command with the --help option to get usage information.
hvcli --helpList all available properties for an asset identified by its unique id.
List all available custom properties for an asset identified by its unique id.
Search for assets in Hyperview. Also available as the alias list-assets.
List assets that match a specific set of property values. For example, a list of serial numbers. Please note that the matches are exact.
Update the display name of an asset identified by its unique id.
Update multiple assets from a CSV file. Example data is in the example_input folder.
Update the location of an asset identified by its unique id.
Update the location of multiple assets from a CSV file. Example data is in the example_input folder.
Update the serial number of an asset identified by its unique id. Applies to manually created assets and assets discovered without a serial number.
Update the serial numbers of multiple assets from a CSV file. Applies to manually created assets and assets discovered without a serial number. Example data is in the example_input folder.
Update the asset tag of an asset identified by its unique id.
Update the asset tag of multiple assets from a CSV file. Example data is in the example_input folder.
Update the power design value property of an asset identified by its unique id. This applies to Rack and Location asset types.
Update the power “design value” property of multiple assets from a CSV file. This applies to Rack and Location asset types. Example data is in the example_input folder.
List the physical network ports of an asset identified by its unique id.
Update the physical network port names of patch panel assets from a CSV file. Example data is in the example_input folder.
Update the physical network port names of other (non-patch-panel) assets from a CSV file, e.g. a network switch. Example data is in the example_input folder.
Update the value of a custom property of an asset identified by its unique id.
Update the custom property value of multiple assets using a CSV file. Example data is in the example_input folder.
List alarm events. By default, it will list active events. It can also list unacknowledged events via a command-line option.
Acknowledge or close alarm events using a CSV file generated by the list-alarms command. By default, this command closes the events; it can also acknowledge them via a command-line option.
Add a blanking panel or cable management panel to a rack identified by its unique id.
Add blanking panels or cable management panels to multiple racks using a CSV file. Example data is in the example_input folder.
List sensors for an asset identified by its unique id.
Update asset sensor name and/or access policy using a CSV file. IMPORTANT: Keep the access policy field empty to maintain the original and only change the name. Use a NIL UUID (00000000-0000-0000-0000-000000000000) to reset to the parent access policy. Example data is in the example_input folder.
List Rack PDU outlets for an asset identified by its unique id.
List busway tap-offs for an asset identified by its unique id.
List PDU/RPP Breakers for an asset identified by its unique id.
Add power association. Note that associations are asset-to-asset. For example, when associating with a specific outlet or tap-off, you need its id.
Add power associations between assets using a CSV. Example data is in the example_input folder.
Generate a monthly (or arbitrary date-range) report of daily-summary statistics (avg/max/min/last) for a named sensor across all assets of a given type. Optionally enrich each row with a custom-property value. Defaults to CSV output.
List current BACnet IP sensor definitions.
Add a new BACnet IP sensor definition.
List numeric sensors for a BACnet IP sensor definition.
List non-numeric sensors for a BACnet IP sensor definition.
Bulk create or update numeric sensors on a BACnet IP sensor definition from a CSV file. Rows with a blank id are created; rows with a valid UUID id are updated. Example data is in the example_input folder.
Bulk create or update non-numeric sensors on a BACnet IP sensor definition from a CSV file. Rows with a blank id are created; rows with a valid UUID id are updated. Example data is in the example_input folder.
List current Modbus TCP sensor definitions.
Add a new Modbus TCP sensor definition.
List numeric sensors for a Modbus TCP sensor definition.
List non-numeric sensors for a Modbus TCP sensor definition.
Bulk create or update numeric sensors on a Modbus TCP sensor definition from a CSV file. Rows with a blank id are created; rows with a valid UUID id are updated. Example data is in the example_input folder.
Bulk create or update non-numeric sensors on a Modbus TCP sensor definition from a CSV file. Rows with a blank id are created; rows with a valid UUID id are updated. Example data is in the example_input folder.
List valid sensor types for an asset type, optionally filtered by sensor class (numeric or enum).
List the components of a Modbus TCP sensor definition. Modbus sensors are grouped under components; a sensor references its component via the component_id column.
Add a new component to a Modbus TCP sensor definition. Prints the new component's id, which can then be used as the component_id for imported Modbus sensors.
Rename an existing component of a Modbus TCP sensor definition.
Delete a component from a Modbus TCP sensor definition.
Get a single BACnet IP sensor definition by its id.
Update the name, asset type, and (optional) description of a BACnet IP sensor definition.
Delete a BACnet IP sensor definition by its id.
Get a single Modbus TCP sensor definition by its id.
Update the name, asset type, and (optional) description of a Modbus TCP sensor definition.
Delete a Modbus TCP sensor definition by its id.
Delete a numeric sensor from a BACnet IP sensor definition.
Delete a non-numeric sensor from a BACnet IP sensor definition.
Delete a numeric sensor from a Modbus TCP sensor definition.
Delete a non-numeric sensor from a Modbus TCP sensor definition.
Note
The BACnet/Modbus numeric sensor import CSVs accept optional offset and order_of_operations (scaleThenOffset | offsetThenScale) columns, and the Modbus sensor import CSVs accept an optional component_id column. Leave any of these blank to let the server apply its default. The bulk-import commands also accept --create-as-new, which ignores the id column and creates every row as a new sensor — use it to clone an exported definition's sensors into a different definition. The associated assets shown when listing a definition is a read-only count of how many assets use it; the API provides no way to manage that association.
Note
Use --help to explore the various options available within the main command and each subcommand.
Every command has a --help option for more information.
$ hvcli list-alarms --help
List alarm events. By default, it will list active events. It can also list unacknowledged events via a command-line option
Usage: hvcli list-alarms [OPTIONS]
Options:
-s, --skip <SKIP> Number of records to skip (0 -> 1_000_000_000), e.g. 100 [default: 0]
-l, --limit <LIMIT> Record limit (1 -> 100_000), e.g. 100 [default: 100]
-a, --alarm-filter <ALARM_FILTER> Asset alarm event filter option, e.g. active [default: active] [possible values: unacknowledged, active]
-o, --output-type <OUTPUT_TYPE> Output type, e.g. csv-file [default: record] [possible values: csv-file, json, record]
-f, --filename <FILENAME> Output filename, e.g. output.csv
-h, --help Print help
-V, --version Print version
$ hvcli manage-alarms --help
Acknowledge or close alarm events using a CSV file generated by the list-alarms command. By default, this command closes the events; it can also acknowledge them via a command-line option
Usage: hvcli manage-alarms [OPTIONS] --filename <FILENAME>
Options:
-f, --filename <FILENAME> Input filename, e.g. input.csv
-m, --manage-action <MANAGE_ACTION> Manage action to use, e.g. close [default: close] [possible values: acknowledge, close]
-h, --help Print help
-V, --version Print versionFor troubleshooting, a master debug level can be set using -d or --debug-level. Accepted values are error (default), warn, info, debug, and trace.
Some commands allow the user to set the output to record, json, or csv-file. Refer to the command help for more information.
The following samples were captured against a live Hyperview instance and have been anonymized. Identifiers and hostnames are placeholders; brand names are preserved so the shape of a real response is easy to recognize.
$ hvcli search-assets -P serialNumber=SERIALNUMBEREXAMPLE1234 -o json
[
{
"id": "aaaaaaaa-0000-0000-0000-000000000001",
"name": "UpsExample",
"assetLifecycleState": "active",
"assetTypeId": "ups",
"manufacturerId": "bbbbbbbb-0000-0000-0000-000000000001",
"manufacturerName": "Liebert",
"monitoringState": "on",
"parentId": "cccccccc-0000-0000-0000-000000000001",
"parentName": "DatacenterExample",
"productId": "dddddddd-0000-0000-0000-000000000001",
"productName": "eXM",
"status": "normal",
"path": "All/DatacenterExample/",
"serialNumber": "[\"SERIALNUMBEREXAMPLE1234\"]",
"property": null
}
]$ hvcli search-assets -p "UpsExampl*"
---- [0] ----
id : aaaaaaaa-0000-0000-0000-000000000001
name : UpsExample
asset_lifecycle_state : active
asset_type_id : ups
manufacturer_id : bbbbbbbb-0000-0000-0000-000000000001
manufacturer_name : Liebert
monitoring_state : on
parent_id : cccccccc-0000-0000-0000-000000000001
parent_name : DatacenterExample
product_id : dddddddd-0000-0000-0000-000000000001
product_name : eXM
status : normal
path : All/DatacenterExample/
serial_number : ["SERIALNUMBEREXAMPLE1234"]
property :$ hvcli search-assets -p "UpsExample" --location-path "All/DatacenterExample/" -M "Liebert" -o json
[
{
"id": "aaaaaaaa-0000-0000-0000-000000000001",
"name": "UpsExample",
"assetLifecycleState": "active",
"assetTypeId": "ups",
"manufacturerId": "bbbbbbbb-0000-0000-0000-000000000001",
"manufacturerName": "Liebert",
"monitoringState": "on",
"parentId": "cccccccc-0000-0000-0000-000000000001",
"parentName": "DatacenterExample",
"productId": "dddddddd-0000-0000-0000-000000000001",
"productName": "eXM",
"status": "normal",
"path": "All/DatacenterExample/",
"serialNumber": "[]",
"property": null
}
]cargo build
The binary will be under target/debug/hvcli.
cargo build --release
The binary will be under target/release/hvcli.
Install the x86_64-unknown-linux-musl target and run the command to build a statically-linked version:
PKG_CONFIG_SYSROOT_DIR=/ RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-unknown-linux-musl --release
docker build --tag hvcli:latest -f docker/Dockerfile .
To run the Docker image generated, you need to:
- Map the application configuration directory to the container.
- Optional, map an output folder to the container.
Assuming the username is albert:
docker run -v /home/albert/.hyperview:/root/.hyperview hvcli search-assets
If you are planning to output to csv:
docker run -v /home/albert/.hyperview:/root/.hyperview -v /tmp:/output hvcli search-assets -o csv-file -f /output/assets.csv