@tailglow/cli 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailglow/cli",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "type": "module",
   "description": "The Tailglow command line. Every command is generated from the Tailglow API reference, so the CLI and the documentation can never describe different APIs.",
   "bin": {

package/src/commands.generated.js

@@ -463,6 +463,97 @@ export const CLI_COMMANDS = [
     "query_params": [],
     "body_fields": []
   },
+  {
+    "resource": "projects",
+    "command": "usage",
+    "operation_id": "getProjectUsage",
+    "summary": "Retrieve Project Usage",
+    "description": "Retrieve how much the project stored over a time range.",
+    "method": "GET",
+    "path": "/v1/projects/:project_id/usage",
+    "alternate_paths": [],
+    "scopes": [
+      "projects:read"
+    ],
+    "notes": [
+      "Readings are taken hourly and are the same measurements the project is billed on. Gigabytes are logical (uncompressed) bytes.",
+      "`interval=day` returns the last reading of each UTC day rather than an average, so a row is what the project held when the day closed. Its `sampled_at` is that reading's own hour.",
+      "Readings start when Tailglow began recording them, so a range reaching further back returns nothing for the hours before that.",
+      "`start_at` must be earlier than `end_at`, and the range cannot be longer than 400 days."
+    ],
+    "path_params": [
+      {
+        "name": "project_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the project.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ],
+    "query_params": [
+      {
+        "name": "start_at",
+        "type": "ISODateString",
+        "required": true,
+        "description": "Start of the range, inclusive (ISO format).",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "end_at",
+        "type": "ISODateString",
+        "required": false,
+        "description": "End of the range, inclusive (ISO format, default: now). Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "interval",
+        "type": "string",
+        "required": false,
+        "description": "Reading cadence returned: every hourly reading, or one reading per UTC day. Optional. Defaults to `\"hour\"`.",
+        "allowed_values": [
+          "hour",
+          "day"
+        ],
+        "deprecated": null
+      }
+    ],
+    "body_fields": []
+  },
+  {
+    "resource": "projects",
+    "command": "attention",
+    "operation_id": "getProjectAttention",
+    "summary": "Retrieve Project Attention",
+    "description": "Retrieve everything in the project that is asking for a human right now.",
+    "method": "GET",
+    "path": "/v1/projects/:project_id/attention",
+    "alternate_paths": [],
+    "scopes": [
+      "projects:read"
+    ],
+    "notes": [
+      "An item appears only when Tailglow entered a state on its own. Anything a project chose, such as a paused pull, a paused drain, or a paused monitor, is never reported here.",
+      "`tier` orders the list. `losing_data` means requests are being refused right now, within the last 5 minutes: for a reason a retry cannot fix, or for capacity after at least 5 minutes of unbroken refusals. `firing` means a monitor or check the project set up is currently triggered, or a server has run under sustained heavy load. `stalled` means a pipeline stopped making progress and its data is going stale. `suspended` means Tailglow switched something off and it stays off until it is fixed. `resolved` means refusals that lost data have stopped; `ended_at` says when.",
+      "Items disappear the moment their condition clears, with one exception so a loss is not missed: refusals that stop stay as `resolved`, for up to 24 hours for a key or payload refusal and up to an hour for capacity. A refusal item's `count` covers that whole window, not only the current spell. Refusals only count as stopped once every running server that was refusing has reported since; until then the item stays `losing_data`. Readings from the project's servers are cached briefly, so a condition that just started can take up to a minute to appear.",
+      "Items cover only resources the caller's key or role can read: without a resource's read permission, its conditions are left out. Refusal and server load items need `servers:read`, and firing monitors need `alerts:read`.",
+      "Items are already ranked, most urgent first. One item covers each firing monitor, and each view's failing transforms, joins, or shape waits. The response is capped per condition so a project in a bad state returns a readable list rather than every affected resource."
+    ],
+    "path_params": [
+      {
+        "name": "project_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the project.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ],
+    "query_params": [],
+    "body_fields": []
+  },
   {
     "resource": "sources",
     "command": "list",
@@ -3014,7 +3105,7 @@ export const CLI_COMMANDS = [
         "name": "preview_token",
         "type": "string",
         "required": false,
-        "description": "The `edit_report.preview_token` from this edit's dry run. Required to save: it pins the save to the set of schema versions the preview reported on, so a version promoted or reassigned in between is rejected instead of silently included. Optional. Minimum length: `1`. Maximum length: `128`.",
+        "description": "The `edit_report.preview_token` from this edit's dry run. Required to save: it pins the save to the set of schema versions the preview reported on, so a version assigned or reassigned in between is rejected instead of silently included. Optional. Minimum length: `1`. Maximum length: `128`.",
         "allowed_values": [],
         "deprecated": null
       }
@@ -4713,9 +4804,10 @@ export const CLI_COMMANDS = [
     "notes": [
       "The monitor starts evaluating on its schedule as soon as it is created.",
       "`scope` decides how many alerts a monitor can raise at once: `any_series` fires once for the metric as a whole, `each_series` tracks every series separately.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
       "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
       "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
-      "`schedule_cron` must be a valid cron expression.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
       "A monitor cannot be created active with an `expires_at` already in the past."
     ],
     "path_params": [
@@ -4800,9 +4892,223 @@ export const CLI_COMMANDS = [
       },
       {
         "name": "time_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "condition_type",
+        "type": "MonitorConditionType",
+        "required": false,
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional. Defaults to `\"threshold\"`.",
+        "allowed_values": [
+          "threshold",
+          "sustained",
+          "existence",
+          "absence"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "operator",
+        "type": "MonitorOperator",
+        "required": false,
+        "description": "How the metric value is compared against the threshold. Optional. Defaults to `\"gt\"`.",
+        "allowed_values": [
+          "gt",
+          "gte",
+          "lt",
+          "lte",
+          "eq",
+          "neq"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "threshold_value",
         "type": "number | null",
         "required": false,
-        "description": "How far back each evaluation looks when it reads the metric. Optional.",
+        "description": "The value the metric is compared against. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "sustained_minutes",
+        "type": "number | null",
+        "required": false,
+        "description": "How long the condition must hold before the monitor fires. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "schedule_cron",
+        "type": "string",
+        "required": false,
+        "description": "Cron expression, in UTC, setting how often the monitor evaluates. Optional. Defaults to `\"* * * * *\"`. Minimum length: `1`. Maximum length: `128`.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "alert_mode",
+        "type": "MonitorAlertMode",
+        "required": false,
+        "description": "Whether an alert stays open until the condition clears, or opens and ends in one moment. Optional. Defaults to `\"spanning\"`.",
+        "allowed_values": [
+          "spanning",
+          "instant"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "expires_at",
+        "type": "ISODateString | null",
+        "required": false,
+        "description": "When the monitor stops evaluating. Leave null for no expiry. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "series_filters",
+        "type": "object | null",
+        "required": false,
+        "description": "Narrows which of the metric's series this monitor watches. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "min_occurrences",
+        "type": "integer | null",
+        "required": false,
+        "description": "How many times the condition must be met before the monitor fires. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "occurrence_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "The window those occurrences have to fall within. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "metric_id",
+        "type": "string",
+        "required": false,
+        "description": "Metric to watch. Optional when using the /metrics/:metric/monitors route. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ]
+  },
+  {
+    "resource": "monitors",
+    "command": "preview",
+    "operation_id": "previewMonitor",
+    "summary": "Preview Monitor",
+    "description": "Preview a monitor condition over its current evaluation window without saving or raising alerts.",
+    "method": "POST",
+    "path": "/v1/projects/:project_id/metrics/:metric_id/monitors/preview",
+    "alternate_paths": [],
+    "scopes": [
+      "monitors:read"
+    ],
+    "notes": [
+      "Uses the same series filtering and condition evaluation as scheduled monitors. This is a condition preview, not a simulation of cron timing, sustained duration, or occurrence counting.",
+      "An incomplete window returns ready=false with no verdicts. No-data conditions count observations across the whole window, including when the chart displays missing buckets as gaps.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
+      "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
+      "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
+      "A monitor cannot be created active with an `expires_at` already in the past."
+    ],
+    "path_params": [
+      {
+        "name": "project_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the project.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "metric_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the metric.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ],
+    "query_params": [],
+    "body_fields": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": false,
+        "description": "Name shown for this monitor. Optional. Minimum length: `2`. Maximum length: `64`.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "description",
+        "type": "string | null",
+        "required": false,
+        "description": "What this monitor watches for. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "status",
+        "type": "string",
+        "required": false,
+        "description": "Whether the monitor starts evaluating immediately or switched off. `disabled` is not accepted: the system uses it to record that it stopped the monitor itself. Optional. Defaults to `\"active\"`.",
+        "allowed_values": [
+          "active",
+          "paused"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "chart_value",
+        "type": "MetricChartValue",
+        "required": false,
+        "description": "Which value of the metric is compared against the threshold. Optional. Defaults to `\"sum\"`.",
+        "allowed_values": [
+          "count",
+          "average",
+          "min",
+          "max",
+          "sum",
+          "last",
+          "cumulative_count",
+          "cumulative_sum",
+          "p50",
+          "p95",
+          "p99",
+          "count_unique"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "scope",
+        "type": "MonitorScope",
+        "required": false,
+        "description": "Whether the monitor fires once for the metric as a whole, or tracks each series separately. Optional. Defaults to `\"total\"`.",
+        "allowed_values": [
+          "total",
+          "any_series",
+          "each_series"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "time_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
         "allowed_values": [],
         "deprecated": null
       },
@@ -4810,11 +5116,12 @@ export const CLI_COMMANDS = [
         "name": "condition_type",
         "type": "MonitorConditionType",
         "required": false,
-        "description": "Whether the condition is a plain threshold or one that must hold for a duration. Optional. Defaults to `\"threshold\"`.",
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional. Defaults to `\"threshold\"`.",
         "allowed_values": [
           "threshold",
           "sustained",
-          "existence"
+          "existence",
+          "absence"
         ],
         "deprecated": null
       },
@@ -4927,9 +5234,10 @@ export const CLI_COMMANDS = [
       "Changing what the monitor MEANS (its condition, scope, series filters or alert mode) ends any period currently firing, because the old alert no longer describes the new rule.",
       "`metric_id` cannot be changed. Create a new monitor against the other metric instead.",
       "The metric a monitor watches cannot be changed. Create a second monitor instead.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
       "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
       "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
-      "`schedule_cron` must be a valid cron expression.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
       "`status` is not editable here. Use the pause and resume operations, which is also what keeps a customer from writing the `disabled` the system uses for expiry.",
       "Moving `expires_at` is rejected when that would leave an active monitor with an expiry already in the past. Editing a monitor that has already expired is allowed, including the update that extends its expiry.",
       "Conditions are checked against the monitor as it will be stored, not against the fields you send, so a change that would leave the monitor in an invalid combination is rejected even when the conflicting value is one you did not send."
@@ -5013,9 +5321,9 @@ export const CLI_COMMANDS = [
       },
       {
         "name": "time_window_minutes",
-        "type": "number | null",
+        "type": "integer | null",
         "required": false,
-        "description": "How far back each evaluation looks when it reads the metric. Optional.",
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
         "allowed_values": [],
         "deprecated": null
       },
@@ -5023,11 +5331,12 @@ export const CLI_COMMANDS = [
         "name": "condition_type",
         "type": "MonitorConditionType",
         "required": false,
-        "description": "Whether the condition is a plain threshold or one that must hold for a duration. Optional.",
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional.",
         "allowed_values": [
           "threshold",
           "sustained",
-          "existence"
+          "existence",
+          "absence"
         ],
         "deprecated": null
       },
@@ -6531,6 +6840,7 @@ export const CLI_COMMANDS = [
       "At least one field must be provided.",
       "Only team Owners can change billing, security, or account settings. Other members can update `name` and `logo_url` only.",
       "`status`, `max_servers_per_project`, and `deleted_at` are managed by Tailglow and cannot be set by team members.",
+      "`status` requires `expected_status`, the status you loaded; the change is refused with a conflict if the team's status has changed since.",
       "Changing `is_mfa_required` requires a recently verified multi-factor sign-in.",
       "Moving to a plan that bills a payment method requires a valid payment method on the team.",
       "`billing_email` cannot use the `@tailglow.io` domain.",
@@ -6588,6 +6898,19 @@ export const CLI_COMMANDS = [
         ],
         "deprecated": null
       },
+      {
+        "name": "expected_status",
+        "type": "TeamStatus",
+        "required": false,
+        "description": "The status the team had when you loaded it. Required with `status`; the change is refused if the status has changed since. Optional.",
+        "allowed_values": [
+          "active",
+          "restricted",
+          "delinquent",
+          "blocked"
+        ],
+        "deprecated": null
+      },
       {
         "name": "is_mfa_required",
         "type": "boolean",
@@ -10156,7 +10479,8 @@ export const CLI_COMMANDS = [
     "alternate_paths": [],
     "scopes": [],
     "notes": [
-      "You can retrieve your own authentication logs without `logs:read`. All other log reads require `logs:read`.",
+      "You can retrieve your own authentication logs without `logs:read`. Billing logs require `billing:read`; all other log reads require `logs:read`.",
+      "Without `type`, the list includes every type you can read. `admin_auth` logs exist only on Tailglow's own admin team.",
       "`after` and `before` are mutually exclusive."
     ],
     "path_params": [],
@@ -10211,7 +10535,8 @@ export const CLI_COMMANDS = [
         "allowed_values": [
           "auth",
           "admin_auth",
-          "audit"
+          "audit",
+          "billing"
         ],
         "deprecated": null
       },