catocli 3.0.14__py3-none-any.whl → 3.0.22__py3-none-any.whl

catocli/parsers/query_eventsTimeSeries/README.md

@@ -38,25 +38,305 @@ catocli query eventsTimeSeries '{
 }'
 ```
 
+## Advanced Usage
+### Additional Examples
+- Weekly break down by hour of Internet Firewall events by rule_name
+- Weekly hourly breakdown by hour of sum of site events
+- 1 hour in 5 min increments of sum of site events used for detecting throttling
+- Basic Event Count Query with enhanced formatting
+- Basic Event Count Query - Returns formatted JSON with granularity-adjusted values
+- Security Events Analysis
+- Security Events Analysis - Daily breakdown of security events
+- Connectivity Events by Country
+- Connectivity Events by Country - Weekly breakdown with country dimensions
+- Threat Analysis with Trend
+- Threat Analysis with Trend - Monthly threat score analysis
+- Socket Connectivity Analysis
+- Socket Connectivity Analysis - Connection events by socket interface
+
+# Weekly break down by hour of Internet Firewall events by rule_name
+
+```bash
+# Weekly break down by hour of Internet Firewall events by rule_name
+catocli query eventsTimeSeries '{
+    "buckets": 168,
+    "eventsDimension": [
+        {
+            "fieldName": "rule_name"
+        }
+    ],
+    "eventsFilter": [
+        {
+            "fieldName": "event_sub_type",
+            "operator": "is",
+            "values": [
+                "Internet Firewall"
+            ]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "last.P7D"
+}'
+```
+
+# Weekly hourly breakdown by hour of sum of site events
+
+```bash
+# Weekly hourly breakdown by hour of sum of site events
+catocli query eventsTimeSeries -accountID=15412 '{
+    "buckets": 168,
+    "eventsDimension": [],
+    "eventsFilter": [
+        {
+            "fieldName": "src_is_site_or_vpn",
+            "operator": "is",
+            "values": [
+                "Site"
+            ]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "last.P7D"
+}'
+```
+
+
+# 1 hour in 5 min increments of sum of site events used for detecting throttling
+
+```bash
+# 1 hour in 5 min increments of sum of site events used for detecting throttling
+catocli query eventsTimeSeries -accountID=15412 '{
+    "buckets": 12,
+    "eventsDimension": [],
+    "eventsFilter": [
+        {
+            "fieldName": "src_is_site_or_vpn",
+            "operator": "is",
+            "values": [
+                "Site"
+            ]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "last.P1D"
+}'
+```
+
+
+
+
+# Basic Event Count Query with enhanced formatting
+
+```bash
+# Basic Event Count Query - Returns formatted JSON with granularity-adjusted values
+catocli query eventsTimeSeries '{
+    "buckets": 4,
+    "eventsDimension": [],
+    "eventsFilter": [],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}"
+}'
+```
+
+# Security Events Analysis
+
+```bash
+# Security Events Analysis - Daily breakdown of security events
+catocli query eventsTimeSeries '{
+    "buckets": 24,
+    "eventsDimension": [],
+    "eventsFilter": [
+        {
+            "fieldName": "event_type",
+            "operator": "is",
+            "values": ["Security"]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}"
+}'
+```
+
+# Connectivity Events by Country
+
+```bash
+# Connectivity Events by Country - Weekly breakdown with country dimensions
+catocli query eventsTimeSeries '{
+    "buckets": 7,
+    "eventsDimension": [
+        {
+            "fieldName": "src_country"
+        }
+    ],
+    "eventsFilter": [
+        {
+            "fieldName": "event_type",
+            "operator": "is",
+            "values": ["Connectivity"]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "utc.2023-03-{01/00:00:00--07/23:59:59}"
+}'
+```
+
+# Threat Analysis with Trend
+
+```bash
+# Threat Analysis with Trend - Monthly threat score analysis
+catocli query eventsTimeSeries '{
+    "buckets": 31,
+    "eventsDimension": [],
+    "eventsFilter": [
+        {
+            "fieldName": "event_type",
+            "operator": "is",
+            "values": ["Security"]
+        },
+        {
+            "fieldName": "threat_score",
+            "operator": "gt",
+            "values": ["50"]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "avg",
+            "fieldName": "threat_score"
+        }
+    ],
+    "timeFrame": "utc.2023-01-{01/00:00:00--31/23:59:59}"
+}'
+```
+
+# Socket Connectivity Analysis
+
+```bash
+# Socket Connectivity Analysis - Connection events by socket interface
+catocli query eventsTimeSeries '{
+    "buckets": 28,
+    "eventsDimension": [
+        {
+            "fieldName": "socket_interface"
+        }
+    ],
+    "eventsFilter": [
+        {
+            "fieldName": "event_type",
+            "operator": "is",
+            "values": ["Connectivity"]
+        },
+        {
+            "fieldName": "event_sub_type",
+            "operator": "in",
+            "values": ["Connected", "Disconnected"]
+        }
+    ],
+    "eventsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "event_count"
+        }
+    ],
+    "timeFrame": "utc.2023-02-{01/00:00:00--28/23:59:59}"
+}'
+```
+
+## Output Format Options
+
+The eventsTimeSeries query supports multiple output formats:
+
+### Enhanced JSON Format (default)
+Returns formatted JSON with granularity multiplication applied to sum aggregations when appropriate:
+```bash
+catocli query eventsTimeSeries '{...}'
+```
+
+### Raw JSON Format
+Returns the original API response without formatting:
+```bash
+catocli query eventsTimeSeries '{...}' -raw
+```
+
+### CSV Format
+Exports data to CSV file with granularity-adjusted values:
+```bash
+catocli query eventsTimeSeries '{...}' -f csv
+```
+
+### Custom CSV filename with timestamp
+```bash
+catocli query eventsTimeSeries '{...}' -f csv --csv-filename "my_events" --append-timestamp
+```
+
+## Granularity Multiplication
+
+When using sum aggregations on count fields like `event_count`, the formatter automatically multiplies fractional values by the granularity period to provide meaningful totals. This is especially useful for time-series data where the API returns normalized values that need to be scaled to the actual time period.
+
+**Example:**
+- Original API value: 0.096 events per period
+- Granularity: 3600 seconds (1 hour)
+- Computed value: 0.096 × 3600 = 345.6 total events
+
+Use the `-raw` flag to see the original unprocessed values if needed.
+
+## Additional Resources
+
+- [Cato API Documentation](https://api.catonetworks.com/documentation/#query-eventsTimeSeries)
+
+
+
+
+
 
 #### TimeFrame Parameter Examples
 
 The `timeFrame` parameter supports both relative time ranges and absolute date ranges:
 
 **Relative Time Ranges:**
-- `"last.PT5M"` = Previous 5 minutes
-- `"last.PT1H"` = Previous 1 hour  
-- `"last.P1D"` = Previous 1 day
-- `"last.P14D"` = Previous 14 days
-- `"last.P1M"` = Previous 1 month
+- "last.PT5M" = Previous 5 minutes
+- "last.PT1H" = Previous 1 hour  
+- "last.P1D" = Previous 1 day
+- "last.P14D" = Previous 14 days
+- "last.P1M" = Previous 1 month
 
 **Absolute Date Ranges:**
 Format: `"utc.YYYY-MM-{DD/HH:MM:SS--DD/HH:MM:SS}"`
 
-- Single day: `"utc.2023-02-{28/00:00:00--28/23:59:59}"`
-- Multiple days: `"utc.2023-02-{25/00:00:00--28/23:59:59}"`  
-- Specific hours: `"utc.2023-02-{28/09:00:00--28/17:00:00}"`
-- Across months: `"utc.2023-{01-28/00:00:00--02-03/23:59:59}"`
+- Single day: "utc.2023-02-{28/00:00:00--28/23:59:59}"  
+- Multiple days: "utc.2023-02-{25/00:00:00--28/23:59:59}"  
+- Specific hours: "utc.2023-02-{28/09:00:00--28/17:00:00}"
+- Across months: "utc.2023-{01-28/00:00:00--02-03/23:59:59}"
 
 
 #### Operation Arguments for query.eventsTimeSeries ####

catocli/parsers/query_eventsTimeSeries/__init__.py

@@ -16,4 +16,10 @@ def query_eventsTimeSeries_parse(query_subparsers):
     query_eventsTimeSeries_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
     query_eventsTimeSeries_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
     query_eventsTimeSeries_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
+
+
+    query_eventsTimeSeries_parser.add_argument('-f', '--format', choices=['json', 'csv'], help='Output format (default: formatted json, use -raw for original json)')
+    query_eventsTimeSeries_parser.add_argument('-raw', '--raw', dest='raw_output', action='store_true', help='Return raw/original JSON format (bypasses default formatting)')
+    query_eventsTimeSeries_parser.add_argument('--csv-filename', dest='csv_filename', help='Override CSV file name (default: eventstimeseries.csv)')
+    query_eventsTimeSeries_parser.add_argument('--append-timestamp', dest='append_timestamp', action='store_true', help='Append timestamp to the CSV file name')
     query_eventsTimeSeries_parser.set_defaults(func=createRequest,operation_name='query.eventsTimeSeries')

catocli/parsers/query_policy/__init__.py

@@ -30,27 +30,6 @@ def query_policy_parse(query_subparsers):
     query_policy_antiMalwareFileHash_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
     query_policy_antiMalwareFileHash_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.antiMalwareFileHash.policy')
 
-    query_policy_dynamicIpAllocation_parser = query_policy_subparsers.add_parser('dynamicIpAllocation', 
-            help='dynamicIpAllocation() policy operation', 
-            usage=get_help("query_policy_dynamicIpAllocation"))
-
-    query_policy_dynamicIpAllocation_subparsers = query_policy_dynamicIpAllocation_parser.add_subparsers()
-
-    query_policy_dynamicIpAllocation_policy_parser = query_policy_dynamicIpAllocation_subparsers.add_parser('policy', 
-            help='policy() dynamicIpAllocation operation', 
-            usage=get_help("query_policy_dynamicIpAllocation_policy"))
-
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('json', nargs='?', default='{}', help='Variables in JSON format (defaults to empty object if not provided).')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-accountID', help='The cato account ID to use for this operation. Overrides the account_id value in the profile setting.  This is use for reseller and MSP accounts to run queries against cato sub accounts from the parent account.')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-t', const=True, default=False, nargs='?', help='Print GraphQL query without sending API call')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-v', const=True, default=False, nargs='?', help='Verbose output')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-p', const=True, default=False, nargs='?', help='Pretty print')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-n', '--stream-events', dest='stream_events', help='Send events over network to host:port TCP')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
-    query_policy_dynamicIpAllocation_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
-    query_policy_dynamicIpAllocation_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.dynamicIpAllocation.policy')
-
     query_policy_socketLan_parser = query_policy_subparsers.add_parser('socketLan', 
             help='socketLan() policy operation', 
             usage=get_help("query_policy_socketLan"))
@@ -72,27 +51,6 @@ def query_policy_parse(query_subparsers):
     query_policy_socketLan_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
     query_policy_socketLan_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.socketLan.policy')
 
-    query_policy_terminalServer_parser = query_policy_subparsers.add_parser('terminalServer', 
-            help='terminalServer() policy operation', 
-            usage=get_help("query_policy_terminalServer"))
-
-    query_policy_terminalServer_subparsers = query_policy_terminalServer_parser.add_subparsers()
-
-    query_policy_terminalServer_policy_parser = query_policy_terminalServer_subparsers.add_parser('policy', 
-            help='policy() terminalServer operation', 
-            usage=get_help("query_policy_terminalServer_policy"))
-
-    query_policy_terminalServer_policy_parser.add_argument('json', nargs='?', default='{}', help='Variables in JSON format (defaults to empty object if not provided).')
-    query_policy_terminalServer_policy_parser.add_argument('-accountID', help='The cato account ID to use for this operation. Overrides the account_id value in the profile setting.  This is use for reseller and MSP accounts to run queries against cato sub accounts from the parent account.')
-    query_policy_terminalServer_policy_parser.add_argument('-t', const=True, default=False, nargs='?', help='Print GraphQL query without sending API call')
-    query_policy_terminalServer_policy_parser.add_argument('-v', const=True, default=False, nargs='?', help='Verbose output')
-    query_policy_terminalServer_policy_parser.add_argument('-p', const=True, default=False, nargs='?', help='Pretty print')
-    query_policy_terminalServer_policy_parser.add_argument('-n', '--stream-events', dest='stream_events', help='Send events over network to host:port TCP')
-    query_policy_terminalServer_policy_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
-    query_policy_terminalServer_policy_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
-    query_policy_terminalServer_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
-    query_policy_terminalServer_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.terminalServer.policy')
-
     query_policy_wanNetwork_parser = query_policy_subparsers.add_parser('wanNetwork', 
             help='wanNetwork() policy operation', 
             usage=get_help("query_policy_wanNetwork"))
@@ -239,3 +197,45 @@ def query_policy_parse(query_subparsers):
     query_policy_tlsInspect_policy_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
     query_policy_tlsInspect_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
     query_policy_tlsInspect_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.tlsInspect.policy')
+
+    query_policy_dynamicIpAllocation_parser = query_policy_subparsers.add_parser('dynamicIpAllocation', 
+            help='dynamicIpAllocation() policy operation', 
+            usage=get_help("query_policy_dynamicIpAllocation"))
+
+    query_policy_dynamicIpAllocation_subparsers = query_policy_dynamicIpAllocation_parser.add_subparsers()
+
+    query_policy_dynamicIpAllocation_policy_parser = query_policy_dynamicIpAllocation_subparsers.add_parser('policy', 
+            help='policy() dynamicIpAllocation operation', 
+            usage=get_help("query_policy_dynamicIpAllocation_policy"))
+
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('json', nargs='?', default='{}', help='Variables in JSON format (defaults to empty object if not provided).')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-accountID', help='The cato account ID to use for this operation. Overrides the account_id value in the profile setting.  This is use for reseller and MSP accounts to run queries against cato sub accounts from the parent account.')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-t', const=True, default=False, nargs='?', help='Print GraphQL query without sending API call')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-v', const=True, default=False, nargs='?', help='Verbose output')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-p', const=True, default=False, nargs='?', help='Pretty print')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-n', '--stream-events', dest='stream_events', help='Send events over network to host:port TCP')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
+    query_policy_dynamicIpAllocation_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
+    query_policy_dynamicIpAllocation_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.dynamicIpAllocation.policy')
+
+    query_policy_terminalServer_parser = query_policy_subparsers.add_parser('terminalServer', 
+            help='terminalServer() policy operation', 
+            usage=get_help("query_policy_terminalServer"))
+
+    query_policy_terminalServer_subparsers = query_policy_terminalServer_parser.add_subparsers()
+
+    query_policy_terminalServer_policy_parser = query_policy_terminalServer_subparsers.add_parser('policy', 
+            help='policy() terminalServer operation', 
+            usage=get_help("query_policy_terminalServer_policy"))
+
+    query_policy_terminalServer_policy_parser.add_argument('json', nargs='?', default='{}', help='Variables in JSON format (defaults to empty object if not provided).')
+    query_policy_terminalServer_policy_parser.add_argument('-accountID', help='The cato account ID to use for this operation. Overrides the account_id value in the profile setting.  This is use for reseller and MSP accounts to run queries against cato sub accounts from the parent account.')
+    query_policy_terminalServer_policy_parser.add_argument('-t', const=True, default=False, nargs='?', help='Print GraphQL query without sending API call')
+    query_policy_terminalServer_policy_parser.add_argument('-v', const=True, default=False, nargs='?', help='Verbose output')
+    query_policy_terminalServer_policy_parser.add_argument('-p', const=True, default=False, nargs='?', help='Pretty print')
+    query_policy_terminalServer_policy_parser.add_argument('-n', '--stream-events', dest='stream_events', help='Send events over network to host:port TCP')
+    query_policy_terminalServer_policy_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
+    query_policy_terminalServer_policy_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
+    query_policy_terminalServer_policy_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
+    query_policy_terminalServer_policy_parser.set_defaults(func=createRequest,operation_name='query.policy.terminalServer.policy')

catocli/parsers/query_socketPortMetrics/README.md

@@ -40,25 +40,69 @@ catocli query socketPortMetrics '{
 }'
 ```
 
+## Advanced Usage
+### Additional Examples
+- 1 Day sum of traffic by site, socket_interface, device_id
+
+# 1 Day sum of traffic by site, socket_interface, device_id
+
+```bash
+# 1 Day sum of traffic by site, socket_interface, device_id
+catocli query socketPortMetrics '{
+    "socketPortMetricsDimension": [
+        {
+            "fieldName": "socket_interface"
+        },
+        {
+            "fieldName": "device_id"
+        },
+        {
+            "fieldName": "site_id"
+        },
+        {
+            "fieldName": "site_name"
+        }
+    ],
+    "socketPortMetricsFilter": [],
+    "socketPortMetricsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_upstream"
+        },
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_downstream"
+        },
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_total"
+        }
+    ],
+    "socketPortMetricsSort": [],
+    "timeFrame": "last.P1D"
+}'
+```
+
+
 
 #### TimeFrame Parameter Examples
 
 The `timeFrame` parameter supports both relative time ranges and absolute date ranges:
 
 **Relative Time Ranges:**
-- `"last.PT5M"` = Previous 5 minutes
-- `"last.PT1H"` = Previous 1 hour  
-- `"last.P1D"` = Previous 1 day
-- `"last.P14D"` = Previous 14 days
-- `"last.P1M"` = Previous 1 month
+- "last.PT5M" = Previous 5 minutes
+- "last.PT1H" = Previous 1 hour  
+- "last.P1D" = Previous 1 day
+- "last.P14D" = Previous 14 days
+- "last.P1M" = Previous 1 month
 
 **Absolute Date Ranges:**
 Format: `"utc.YYYY-MM-{DD/HH:MM:SS--DD/HH:MM:SS}"`
 
-- Single day: `"utc.2023-02-{28/00:00:00--28/23:59:59}"`
-- Multiple days: `"utc.2023-02-{25/00:00:00--28/23:59:59}"`  
-- Specific hours: `"utc.2023-02-{28/09:00:00--28/17:00:00}"`
-- Across months: `"utc.2023-{01-28/00:00:00--02-03/23:59:59}"`
+- Single day: "utc.2023-02-{28/00:00:00--28/23:59:59}"  
+- Multiple days: "utc.2023-02-{25/00:00:00--28/23:59:59}"  
+- Specific hours: "utc.2023-02-{28/09:00:00--28/17:00:00}"
+- Across months: "utc.2023-{01-28/00:00:00--02-03/23:59:59}"
 
 
 #### Operation Arguments for query.socketPortMetrics ####

catocli/parsers/query_socketPortMetrics/__init__.py

@@ -16,4 +16,10 @@ def query_socketPortMetrics_parse(query_subparsers):
     query_socketPortMetrics_parser.add_argument('-z', '--sentinel', dest='sentinel', help='Send events to Sentinel customerid:sharedkey')
     query_socketPortMetrics_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
     query_socketPortMetrics_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
+
+
+    query_socketPortMetrics_parser.add_argument('-f', '--format', choices=['json', 'csv'], help='Output format (default: formatted json, use -raw for original json)')
+    query_socketPortMetrics_parser.add_argument('-raw', '--raw', dest='raw_output', action='store_true', help='Return raw/original JSON format (bypasses default formatting)')
+    query_socketPortMetrics_parser.add_argument('--csv-filename', dest='csv_filename', help='Override CSV file name (default: socketportmetrics.csv)')
+    query_socketPortMetrics_parser.add_argument('--append-timestamp', dest='append_timestamp', action='store_true', help='Append timestamp to the CSV file name')
     query_socketPortMetrics_parser.set_defaults(func=createRequest,operation_name='query.socketPortMetrics')

catocli/parsers/query_socketPortMetricsTimeSeries/README.md

@@ -38,25 +38,108 @@ catocli query socketPortMetricsTimeSeries '{
 }'
 ```
 
+## Advanced Usage
+### Additional Examples
+- 1 Day sum of traffic by site, socket_interface, device_id
+- 1 Day sum of traffic by site, socket_interface, device_id as csv
+
+# 1 Day sum of traffic by site, socket_interface, device_id
+
+```bash
+# 1 Day sum of traffic by site, socket_interface, device_id as csv
+catocli query socketPortMetricsTimeSeries
+    "buckets": 24,
+    "socketPortMetricsDimension": [
+        {
+            "fieldName": "socket_interface"
+        },
+        {
+            "fieldName": "device_id"
+        },
+        {
+            "fieldName": "site_id"
+        },
+        {
+            "fieldName": "site_name"
+        }
+    ],
+    "socketPortMetricsFilter": [],
+    "socketPortMetricsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_downstream"
+        },
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_upstream"
+        },
+        {
+            "aggType": "sum",
+            "fieldName": "bytes_total"
+        }
+    ],
+    "timeFrame": "last.P1D"
+}' -f csv
+```
+
+# 1 Day sum of traffic by site, socket_interface, device_id
+
+```bash
+# 1 Day sum of traffic by site, socket_interface, device_id
+catocli query socketPortMetricsTimeSeries '{
+    "buckets": 120,
+    "socketPortMetricsDimension": [
+        {
+            "fieldName": "socket_interface"
+        },
+        {
+            "fieldName": "device_id"
+        },
+        {
+            "fieldName": "site_id"
+        },
+        {
+            "fieldName": "site_name"
+        }
+    ],
+    "socketPortMetricsFilter": [],
+    "socketPortMetricsMeasure": [
+        {
+            "aggType": "sum",
+            "fieldName": "throughput_downstream"
+        },
+        {
+            "aggType": "sum",
+            "fieldName": "throughput_upstream"
+        }
+    ],
+    "timeFrame": "last.P2M"
+}'
+```
+
+
+
+
+
 
 #### TimeFrame Parameter Examples
 
 The `timeFrame` parameter supports both relative time ranges and absolute date ranges:
 
 **Relative Time Ranges:**
-- `"last.PT5M"` = Previous 5 minutes
-- `"last.PT1H"` = Previous 1 hour  
-- `"last.P1D"` = Previous 1 day
-- `"last.P14D"` = Previous 14 days
-- `"last.P1M"` = Previous 1 month
+- "last.PT5M" = Previous 5 minutes
+- "last.PT1H" = Previous 1 hour  
+- "last.P1D" = Previous 1 day
+- "last.P14D" = Previous 14 days
+- "last.P1M" = Previous 1 month
 
 **Absolute Date Ranges:**
 Format: `"utc.YYYY-MM-{DD/HH:MM:SS--DD/HH:MM:SS}"`
 
-- Single day: `"utc.2023-02-{28/00:00:00--28/23:59:59}"`
-- Multiple days: `"utc.2023-02-{25/00:00:00--28/23:59:59}"`  
-- Specific hours: `"utc.2023-02-{28/09:00:00--28/17:00:00}"`
-- Across months: `"utc.2023-{01-28/00:00:00--02-03/23:59:59}"`
+- Single day: "utc.2023-02-{28/00:00:00--28/23:59:59}"  
+- Multiple days: "utc.2023-02-{25/00:00:00--28/23:59:59}"  
+- Specific hours: "utc.2023-02-{28/09:00:00--28/17:00:00}"
+- Across months: "utc.2023-{01-28/00:00:00--02-03/23:59:59}"
 
 
 #### Operation Arguments for query.socketPortMetricsTimeSeries ####

catocli/parsers/query_socketPortMetricsTimeSeries/__init__.py

@@ -17,7 +17,9 @@ def query_socketPortMetricsTimeSeries_parse(query_subparsers):
     query_socketPortMetricsTimeSeries_parser.add_argument('-H', '--header', action='append', dest='headers', help='Add custom headers in "Key: Value" format. Can be used multiple times.')
     query_socketPortMetricsTimeSeries_parser.add_argument('--headers-file', dest='headers_file', help='Load headers from a file. Each line should contain a header in "Key: Value" format.')
 
-    query_socketPortMetricsTimeSeries_parser.add_argument('-f', '--format', choices=['json', 'csv'], default='json', help='Output format (default: json)')
-    query_socketPortMetricsTimeSeries_parser.add_argument('--csv-filename', dest='csv_filename', help='Override CSV file name (default: accountmetrics.csv)')
+
+    query_socketPortMetricsTimeSeries_parser.add_argument('-f', '--format', choices=['json', 'csv'], help='Output format (default: formatted json, use -raw for original json)')
+    query_socketPortMetricsTimeSeries_parser.add_argument('-raw', '--raw', dest='raw_output', action='store_true', help='Return raw/original JSON format (bypasses default formatting)')
+    query_socketPortMetricsTimeSeries_parser.add_argument('--csv-filename', dest='csv_filename', help='Override CSV file name (default: socketportmetricstimeseries.csv)')
     query_socketPortMetricsTimeSeries_parser.add_argument('--append-timestamp', dest='append_timestamp', action='store_true', help='Append timestamp to the CSV file name')
     query_socketPortMetricsTimeSeries_parser.set_defaults(func=createRequest,operation_name='query.socketPortMetricsTimeSeries')

{catocli-3.0.14.dist-info → catocli-3.0.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: catocli
-Version: 3.0.14
+Version: 3.0.22
 Summary: Cato Networks cli wrapper for the GraphQL API.
 Home-page: https://github.com/Cato-Networks/cato-cli
 Author: Cato Networks