Cumulocity CLI 2.7.0

Change log

Breaking changes

Renamed c8y devices setRequiredAvailability

c8y devices setRequiredAvailability => c8y devices availability set

New Commands

c8y alarms count

New command to get the total count of alarms matching a given criteria

$ c8y alarms count --severity MAJOR
Get number of active alarms with the severity set to MAJOR

$ c8y alarms count --dateFrom "-10m" --status ACTIVE
Get number of active alarms which occurred in the last 10 minutes

$ c8y alarms count --dateFrom "-10m" --status ACTIVE --device 12345
Get number of active alarms which occurred in the last 10 minutes on a device

$ c8y devices list --type linuxA | c8y alarms count --dateFrom "-10m"
Get number of alarms from a list of devices using pipeline

c8y devices availability get

Retrieve the date when a specific managed object (by a given ID) sent the last message to Cumulocity IoT.

$ c8y devices availability get --id 12345
Get a device's availability by id

$ c8y devices availability get --id device01
Get a device's availability by name

$ c8y devices get --id device01 --dry=false | c8y devices availability get
Get a device's availability using a pipeline

c8y devices user get - Get device user related to a managed object

$ c8y devices user get --id 12345
Get device user by id

$ c8y devices user get --id device01
Get device user by name

c8y devices user update - Update device user related to a managed object

$ c8y devices user update --id 12345 --enabled
Enable a device user by name

$ c8y devices user update --id device01 --enabled=false
Disable a device user

c8y devices statistics list

Retrieve device statistics from a specific tenant (by a given ID). Either daily or monthly.

$ c8y devices statistics list
Get daily (default) device statistics for all devices in the current tenant

$ c8y devices statistics list --date "-7d" --type daily
Get daily device statistics for all devices in the current tenant 7 days ago

$ c8y devices statistics list --date "-30d" --device 12345
Get daily device statistics for all devices in the current tenant 30 days ago

$ c8y devices statistics list --date 2022-01-01 --type monthly
Get monthly device statistics for all devices for a specific month (day is ignored)

c8y inventory count

Retrieve the total number of managed objects (e.g. devices, assets, etc.) registered in your tenant, or a subset based on queries.

$ c8y inventory count
Get count of managed objects

$ c8y inventory count --text myname
Get count of managed objects matching text (using Cumulocity text search algorithm)

$ c8y inventory count --type "c8y_Sensor"
Get count of managed objects with a specific type value

$ c8y inventory count --type "c8y_Sensor" --owner "device_mylinuxbox01"
Get count of managed objects with a specific type value and owner

$ c8y inventory count --fragmentType "c8y_IsDevice"
Get total number of devices

Improvements

c8y alarms list and c8y alarms deleteCollection

• status can be defined multiple times rather than only just using csv e.g. --status ACTIVE --status ACKNOWLEDGED. This improves tab-completion compatibility

  c8y alarms list --status ACTIVE --status ACKNOWLEDGED --dry

c8y applications delete

Added the following flags:

• unsubscribeAll (force query parameter) - Force deletion by unsubscribing all tenants from the application first and then deleting the application itself.

c8y applications list and c8y microservices list

Added the following flags:

• name - The name of the application.
• owner - The ID of the tenant that owns the applications.
• providedFor - The ID of a tenant that is subscribed to the applications but doesn't own them.
• subscriber - The ID of a tenant that is subscribed to the applications.
• user - The ID of a user that has access to the applications.

c8y binaries list

Added the following flags:

• ids - The managed object IDs to search for.
• type - The type of managed object to search for.
• owner - Username of the owner of the managed objects.
• text - Search for managed objects where any property value is equal to the given one. Only string values are supported.
• childAdditionId - Search for a specific child addition and list all the groups to which it belongs.
• childAssetId - Search for a specific child asset and list all the groups to which it belongs.
• childDeviceId - Search for a specific child device and list all the groups to which it belongs.

c8y devices listChildren

• withChildren - Determines if children with ID and name should be returned when fetching the managed object. Set it to false to improve query performance.

c8y events deleteCollection

Added the following flags:

• createdFrom - Start date or date and time of the event's creation (set by the platform during creation).
• createdTo - End date or date and time of the event's creation (set by the platform during creation).

c8y events list

Added the following flags:

• fragmentValue - Allows filtering events by the fragment's value, but only when provided together with fragmentType.
• createdFrom - Start date or date and time of the event's creation (set by the platform during creation).
• createdTo - End date or date and time of the event's creation (set by the platform during creation).
• lastUpdatedFrom - Start date or date and time of the last update made.
• lastUpdatedTo - End date or date and time of the last update made.
• withSourceAssets - When set to true also events for related source assets will be included in the request. When this parameter is provided a source must be specified.
• withSourceDevices - When set to true also events for related source devices will be included in the request. When this parameter is provided a source must be specified.

c8y inventory get

Added the following flags:

• skipChildrenNames - Don't include the child devices names in the response. This can improve the API response because the names don't need to be retrieved
• withChildren - Determines if children with ID and name should be returned when fetching the managed object. Set it to false to improve query performance.

c8y inventory list

Added the following flags:

• owner - List of managed objects that are owned by the given username.
• onlyRoots - When set to true it returns managed objects which don't have any parent. If the current user doesn't have access to the parent, this is also root for the user
• childAdditionId - Search for a specific child addition and list all the groups to which it belongs.
• childAssetId - Search for a specific child asset and list all the groups to which it belongs.
• childDeviceId - Search for a specific child device and list all the groups to which it belongs.
• withChildren - Determines if children with ID and name should be returned when fetching the managed object. Set it to false to improve query performance.
• withGroups - When set to true it returns additional information about the groups to which the searched managed object belongs. This results in setting the assetParents property with additional information about the groups.

c8y inventory additions list and c8y inventory assets list

Added the following flags:

• withChildren - Determines if children with ID and name should be returned when fetching the managed object. Set it to false to improve query performance.

Fixes

c8y inventory assert exist and c8y inventory assert fragments

• A non-zero exit code and log output is only printed when using the --strict flag. This aligns with the c8y devices assert commands.

  c8y inventory assert exists --id 0
  => Exit Code: 112
  => Stderr: No Output
  
  c8y inventory assert exists --id 0 --strict
  => Exit Code: 112
  => Stderr: 2022-02-08T20:23:41.519Z        ERROR   assertionError: managedObject - wanted: Found, got: NotFound, context: {ID:0}

Cumulocity CLI 2.6.2

Changelog

Fixes

• c8y realtime: fixes handling of random min and max delays (#100)

Cumulocity CLI 2.6.1

Changelog

Fixes

c8y util repeat: fixes handling of random min and max delays (#100)

• fix handling of random min and max delay flags to be respected even if they are equal
• --randomDelayMax can be used without having to set --randomDelayMin

Examples

$ echo "test" | c8y util repeat 5 --randomDelayMax 10000ms -v
# Print "test" 5 times waiting between 0s and 10s after each line

$ echo "test" | c8y util repeat 5 --randomDelayMin 5s -v
# Print "test" 5 times waiting exactly 5 seconds after each line

Cumulocity CLI 2.6.0

Changelog

New Commands

c8y util repeatfile #98

• Iterator over each line of a file X number of times
• Loop over file contents forever using --infinite flag which is useful for generating large amounts of data

Examples

$ c8y util repeatfile myfile.txt
Repeat each line of the file contents

$ c8y util repeatfile myfile.txt --times 2
Loop over the file twice. The file contents will be outputed from first list to last line, then read again.

$ c8y util repeatfile myfile.txt --infinite --delay 500ms
Loop over the file contents forever and delaying 500ms after each line is printed

$ c8y util repeatfile *.list --randomSkip 0.5
Loop over the files matching the "*.list" in the current directory (uses shell expansion), but randomly
skip lines at a probability of 50 percent.

Improvements/Changes

c8y template execute support non-json output #99

Support for non-json output which allows more use-cases to generate output using the extensive jsonnet templating language.

Examples

# Generate random integer
$ c8y template execute --template "_.Int(10,20)"
14

# Use to get relative date times using go-c8y-cli functions
$ c8y template execute --template "_.Now('-30d')"
2021-12-23T21:15:59.618Z

# Create ini format
$ c8y template execute --template "std.manifestIni({sections: {main: {one:1,two:'2'}}})"
[main]
one = 1
two = 2

c8y util repeat improvements #97

• add --infinite flag to create a never ending repeater
• --randomDelayMin and --randomDelayMax flags now support duration syntax, e.g. 10ms, 10s, 1m. If no unit is supplied then it assumes milliseconds
• empty input is now passed down the pipeline instead of being ignored

  # Following produces 10 lines
  c8y util repeat 10 | wc -l
  
  # Send the same request 10 times waiting 1 second after each request
  c8y util repeat 10 | c8y api --url /inventory/managedObjects --delay 1s

c8y firmware versions install #96

• Added support for --description flag. By default the description will be automatically generated in the following format:

  # If a version is specified
  Install firmware: "{name}" ({version})
  
  # With an empty version
  Install firmware: "{name}"

• Url field is automatically added if the matching firmware name/version is found in the Cumulocity firmware repository

  # Create a firmware and version
  c8y firmware create --name iot-linux |
      c8y firmware versions create --version 1.0.0 --url "https://example.com/image.tar.gz"
  
  # Install the firmware by referencing name/version
  c8y firmware versions install --device 12345 --firmware iot-linux --version 1.0.0

  The above c8y firmware versions install command produces the following operation body:

  // POST /devicecontrol/operations
  {
      "c8y_Firmware": {
          "name": "iot-linux",
          "url": "https://example.com/image.tar.gz",
          "version": "1.0.0"
      },
      "description": "Update firmware to: \"iot-linux\" (1.0.0)",
      "deviceId": "12345"
  }

c8y software versions install #96

• Ignore software version lookup when software, version and url are provided

c8y configuration list

• added --configurationType <string> flag to filter by configuration type

  c8y configuration list --configurationType "AGENT_CONFIG"
  
  # => Cumulocity inventory query
  # => GET /inventory/managedObjects?query=$filter=(type eq 'c8y_ConfigurationDump') and (configurationType eq 'AGENT_CONFIG') $orderby=name

Cumulocity CLI 2.5.2

Changelog

Fix

• build: fix publishing of linuxbrew artifact

Cumulocity CLI 2.5.1

Changelog

Fixes

• c8y applications deleteApplicationBinary the binaryId flag accepts pipeline input via standard input (#94, #93)

  c8y applications listApplicationBinaries --id mywebapp |
      c8y applications deleteApplicationBinary --application mywebapp

Cumulocity CLI 2.5.0

Changelog

Bugfixes

• c8y software/firmware Fix software management examples (#88)
• c8y software versions install Allow empty version field (#83)

Features

• Support duration in days for cacheTTL option and subscribe commands. Previously only h, m, s and ms were supported (#88)
• Add support for template and data parameters in software version install/uninstall and firmware version install (#84)

Build

• Only publish Debian package to stable distribution
• Fix homebrew publishing (#86)

Docs

• Fix asciinema iframe links
• Update online doc dependencies
• Update installation instructions to use new repositories
• Add missing quote when setting up zsh shell profile (#82)

Cumulocity CLI 2.4.5

Changelog

Bugfixes

Removed brackets around queryTemplate input string (#81)

Fix bug where the piped input to a query was being wrapped with braces (<input>).

Example

echo "c8y_Linux" | c8y devices list --queryTemplate "type eq '%s'" --dry

# Incorrect query with extra brackets
# => /inventory/managedObjects?q=$filter=type eq '(c8y_Linux)' $orderby=name

# Corrected query
# => /inventory/managedObjects?q=$filter=type eq 'c8y_Linux' $orderby=name

Affected Commands

The following command were affected by the bug when the --queryTemplate option was used.

• c8y agents list
• c8y devices list
• c8y devicegroups list
• c8y smartgroups list

Cumulocity CLI 2.4.4

Changelog

Bug fixes

Support multiline matching with filter operators match and like

Example

input.json
Some multi line json input (or response from c8y) which contains newline chars \n

{"failureReason": "some\ncomplex\nmultiline\njson"}

Then it can be filtered using the --filter parameter.

cat input.json | c8y util show --filter "failureReason like *complex*" -o json

Cumulocity CLI 2.4.0

Breaking Changes

Default enabling of ssl verify

SSL verify is enabled by default to prevent man-in-the-middle attacks when using go-c8y-cli.

This means if you were previously using go-c8y-cli against a Cumulocity IoT Edge using a self-signed certificate, then you will need to disable ssl verification for the session or for individual commands.

Disabling SSL Verify for individual commands

c8y devices list --insecure

# or using an shortform 
c8y devices list -k

Disabling SSL Verify for your session

Please only disable SSL verify if you fully trust the server/network you are working with, and have no other option!

c8y settings update defaults.insecure true

# Or using environment variables
export C8Y_SETTINGS_DEFAULTS_INSECURE=true

New Features

Request caching (#79)

Adding optional local client side caching feature which provides:

• Reduce number of requests sent to the server
• Improve performance by reusing responses across different commands, also when trying out new commands
• Provide way to dedupe POST/PUT requests docs

Caching is turned off by default, and can be opted for single commands or activated globally for specific HTTP methods (i.e. GET, PUT, POST etc.)

Example

c8y devices list --type "c8y_Linux" --cache
# => Sends a request to the server the first time

c8y devices list --type "c8y_Linux" --cache
# => A cached response is used as the same command is being used within the cache TTL

echo agent01 | c8y util repeat 2 | c8y devices get --cache --cacheTTL 60s -v
# => Control time-to-live for single commands 

Checkout the new caching concept docs for more details and examples.