@dataworks-technology/cli 1.4.0 → 1.5.0

package/oclif.manifest.json

@@ -189,6 +189,10 @@
         {
           "description": "Replace a stale Dataworks marketplace registration",
           "command": "dw agents install codex --force"
+        },
+        {
+          "description": "Update clients that already have Dataworks, and skip the rest",
+          "command": "dw agents install --refresh"
         }
       ],
       "flags": {
@@ -198,6 +202,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "refresh": {
+          "description": "Only update clients that already have Dataworks installed; configure nothing new",
+          "name": "refresh",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Emit stable JSON output",
           "name": "json",
@@ -3732,24 +3742,10 @@
         "update.js"
       ]
     },
-    "data:data-explorer:execute": {
+    "data:composable-engine-type:get": {
       "aliases": [],
       "args": {},
-      "description": "Query Data Explorer metrics with explicit columns, optional filters, ordering, aggregation, and row limits.",
-      "examples": [
-        {
-          "description": "Run a complete query from a reusable input file",
-          "command": "dw data data-explorer execute --input @data-explorer-query.json --json"
-        },
-        {
-          "description": "Return the latest 30 rows from a metric category",
-          "command": "dw data data-explorer execute --columns '[\"timestamp\",\"athletepublicid\",\"metric\",\"current\"]' --metric-category METRICS_TYPE_A --limit 30 --order-by timestamp --order-direction DESC --json"
-        },
-        {
-          "description": "Return the latest 30 GPS positions for one athlete",
-          "command": "dw data data-explorer execute --input @gps-query.json --json"
-        }
-      ],
+      "description": "Run the getComposableEngineType GraphQL query",
       "flags": {
         "input": {
           "description": "Input JSON, @file, or - for stdin",
@@ -3791,72 +3787,9 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "aggregate": {
-          "description": "GraphQL aggregate",
-          "name": "aggregate",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "aggregate-field": {
-          "description": "GraphQL aggregateField",
-          "name": "aggregate-field",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "columns": {
-          "description": "Required JSON array of category columns; base columns are timestamp, datasetdatasourcepublicid, eventpublicid, athletepublicid, metric, and current",
-          "name": "columns",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "filter-rules": {
-          "description": "AWSJSON string shaped as {combinator,rules:[{field,operator,value}]}; operators include =, !=, >, <, >=, <=, contains, and in",
-          "name": "filter-rules",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "group-by": {
-          "description": "GraphQL groupBy",
-          "name": "group-by",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "limit": {
-          "description": "Maximum number of rows to return",
-          "name": "limit",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "metric-category": {
-          "description": "Metric category: METRICS_TYPE_A for GPS/position/timing, METRICS_TYPE_B for speed/altitude/cadence, or METRICS_TYPE_C for heart rate/power/zones",
-          "name": "metric-category",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "order-by": {
-          "description": "Column used to order rows",
-          "name": "order-by",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "order-direction": {
-          "description": "Sort direction: ASC or DESC",
-          "name": "order-direction",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "query-execution-id": {
-          "description": "Existing asynchronous query execution ID to poll",
-          "name": "query-execution-id",
+        "public-id": {
+          "description": "GraphQL publicId",
+          "name": "public-id",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -3864,7 +3797,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "data:data-explorer:execute",
+      "id": "data:composable-engine-type:get",
       "pluginAlias": "@dataworks-technology/cli",
       "pluginName": "@dataworks-technology/cli",
       "pluginType": "core",
@@ -3874,14 +3807,14 @@
         "dist",
         "commands",
         "data",
-        "data-explorer",
-        "execute.js"
+        "composable-engine-type",
+        "get.js"
       ]
     },
-    "data:composable-engine-type:get": {
+    "data:composable-engine-type:list": {
       "aliases": [],
       "args": {},
-      "description": "Run the getComposableEngineType GraphQL query",
+      "description": "Run the listComposableEngineTypes GraphQL query",
       "flags": {
         "input": {
           "description": "Input JSON, @file, or - for stdin",
@@ -3923,9 +3856,23 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "public-id": {
-          "description": "GraphQL publicId",
-          "name": "public-id",
+        "filter": {
+          "description": "GraphQL filter",
+          "name": "filter",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "description": "GraphQL limit",
+          "name": "limit",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "next-token": {
+          "description": "GraphQL nextToken",
+          "name": "next-token",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -3933,7 +3880,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "data:composable-engine-type:get",
+      "id": "data:composable-engine-type:list",
       "pluginAlias": "@dataworks-technology/cli",
       "pluginName": "@dataworks-technology/cli",
       "pluginType": "core",
@@ -3944,13 +3891,27 @@
         "commands",
         "data",
         "composable-engine-type",
-        "get.js"
+        "list.js"
       ]
     },
-    "data:composable-engine-type:list": {
+    "data:data-explorer:execute": {
       "aliases": [],
       "args": {},
-      "description": "Run the listComposableEngineTypes GraphQL query",
+      "description": "Query Data Explorer metrics with explicit columns, optional filters, ordering, aggregation, and row limits.",
+      "examples": [
+        {
+          "description": "Run a complete query from a reusable input file",
+          "command": "dw data data-explorer execute --input @data-explorer-query.json --json"
+        },
+        {
+          "description": "Return the latest 30 rows from a metric category",
+          "command": "dw data data-explorer execute --columns '[\"timestamp\",\"athletepublicid\",\"metric\",\"current\"]' --metric-category METRICS_TYPE_A --limit 30 --order-by timestamp --order-direction DESC --json"
+        },
+        {
+          "description": "Return the latest 30 GPS positions for one athlete",
+          "command": "dw data data-explorer execute --input @gps-query.json --json"
+        }
+      ],
       "flags": {
         "input": {
           "description": "Input JSON, @file, or - for stdin",
@@ -3992,23 +3953,72 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "filter": {
-          "description": "GraphQL filter",
-          "name": "filter",
+        "aggregate": {
+          "description": "GraphQL aggregate",
+          "name": "aggregate",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "aggregate-field": {
+          "description": "GraphQL aggregateField",
+          "name": "aggregate-field",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "columns": {
+          "description": "Required JSON array of category columns; base columns are timestamp, datasetdatasourcepublicid, eventpublicid, athletepublicid, metric, and current",
+          "name": "columns",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "filter-rules": {
+          "description": "AWSJSON string shaped as {combinator,rules:[{field,operator,value}]}; operators include =, !=, >, <, >=, <=, contains, and in",
+          "name": "filter-rules",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "group-by": {
+          "description": "GraphQL groupBy",
+          "name": "group-by",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "limit": {
-          "description": "GraphQL limit",
+          "description": "Maximum number of rows to return",
           "name": "limit",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "next-token": {
-          "description": "GraphQL nextToken",
-          "name": "next-token",
+        "metric-category": {
+          "description": "Metric category: METRICS_TYPE_A for GPS/position/timing, METRICS_TYPE_B for speed/altitude/cadence, or METRICS_TYPE_C for heart rate/power/zones",
+          "name": "metric-category",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "order-by": {
+          "description": "Column used to order rows",
+          "name": "order-by",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "order-direction": {
+          "description": "Sort direction: ASC or DESC",
+          "name": "order-direction",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "query-execution-id": {
+          "description": "Existing asynchronous query execution ID to poll",
+          "name": "query-execution-id",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -4016,7 +4026,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "data:composable-engine-type:list",
+      "id": "data:data-explorer:execute",
       "pluginAlias": "@dataworks-technology/cli",
       "pluginName": "@dataworks-technology/cli",
       "pluginType": "core",
@@ -4026,8 +4036,8 @@
         "dist",
         "commands",
         "data",
-        "composable-engine-type",
-        "list.js"
+        "data-explorer",
+        "execute.js"
       ]
     },
     "data:dataset:create": {
@@ -11709,5 +11719,5 @@
       ]
     }
   },
-  "version": "1.4.0"
+  "version": "1.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataworks-technology/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "The official command-line interface for the Dataworks Data Engine",
   "type": "module",
   "license": "MIT",

package/plugins/dataworks/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dataworks",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
   "author": { "name": "Dataworks Technology" },
   "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",

package/plugins/dataworks/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dataworks",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Query athlete metrics from Dataworks using the authenticated local CLI session.",
   "author": { "name": "Dataworks Technology", "url": "https://dataworks.live/" },
   "homepage": "https://github.com/Dataworks-Technology/Dataworks-CLI",

package/plugins/dataworks/skills/query-dataworks-metrics/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: query-dataworks-metrics
-description: Query historical Dataworks athlete metrics such as GPS, heart rate, speed, altitude, cadence, power, timing, or custom metrics. Use when a user asks for latest, last, recent, or time-bounded metric values for an athlete by ID or name.
+description: Query historical Dataworks metrics such as GPS, heart rate, speed, altitude, cadence, power, timing, or custom metrics, for one athlete or across a whole event. Use when a user asks for latest, last, recent, or time-bounded metric values, or needs to find an athlete or event ID.
 ---
 
 # Query Dataworks metrics
 
-Use the `query_metrics` tool. It is read-only and uses the current authenticated
-`dw` session and selected tenant.
+Three read-only tools use the current authenticated `dw` session and tenant:
+
+- `query_metrics` — metric values, scoped to an athlete, an event, or a datasource.
+- `list_athletes` — find an athlete ID, or confirm someone is not in this tenant.
+- `list_events` — find an event ID for a race.
 
 If `query_metrics` is unavailable, tell the user to run `dw agents install`
 once in their terminal, then start a new Codex thread or run `/reload-plugins`
@@ -14,16 +17,23 @@ in Claude Code. Do not substitute raw GraphQL or guess that setup succeeded.
 
 ## Construct the request
 
-- Pass `athlete_id` when the user provides a Dataworks athlete public ID.
-- Otherwise pass `athlete_name`; let the tool resolve it and surface ambiguity.
+- Scope every query. Pass at least one of `athlete_id`, `athlete_name`,
+  `event_id`, or `dataset_datasource_id`; the tool refuses an unscoped query
+  rather than sweeping the tenant.
+- For a question about a person, pass `athlete_id` when the user gives an ID,
+  otherwise `athlete_name` and let the tool resolve it.
+- For a question about a race or feed — "the latest heart rate at T100 San
+  Francisco" — omit the athlete entirely and pass `event_id`. Do not invent an
+  athlete to satisfy the call. Rows still carry `athlete_id` per value.
 - Map the user's wording onto a canonical metric name from the catalogue below.
   Case, spaces, hyphens and underscores are ignored, so "Heart Rate" resolves to
   `heartrate`. Do not invent a metric name.
 - Default to `limit: 30` and `order: newest` only when the user did not specify
   a count or order.
 - Preserve explicit `from` and `to` times as ISO 8601 date-times.
-- Pass `event_id`, `dataset_datasource_id`, or `tenant_id` only when explicitly
-  supplied or already resolved. Never guess an ID.
+- Never guess or infer an ID. Resolve one with `list_athletes` or `list_events`,
+  or use an ID the user supplied. An ID inferred from a shared prefix, a naming
+  pattern, or a row count is a guess: say you could not resolve it instead.
 - For a genuinely custom metric absent from the catalogue, pass its exact name
   and an explicit `metric_category`.
 
@@ -55,6 +65,9 @@ Haigh"`, `metric: "GPS"`, `limit: 30`, `order: "newest"`.
   `metric: "heartrate"`, then take the maximum over the returned rows.
 - “Cadence for Sam since noon” → `athlete_name: "Sam"`, `metric: "cadence"`,
   `from: <the unambiguous ISO 8601 time requested>`.
+- “Latest 10 heart rate values for T100 San Francisco” → `list_events` with
+  `search: "T100 San Francisco"` to get the ID, then `query_metrics` with
+  `event_id: <that ID>`, `metric: "heartrate"`, `limit: 10`, and no athlete.
 
 ## Handle results
 
@@ -63,8 +76,19 @@ environment, tenant, canonical metric, order, and returned count. GPS rows inclu
 decoded `position.latitude` and `position.longitude`; heart-rate values are
 numeric with unit `bpm` when the source value is valid.
 
-If the tool reports `ATHLETE_AMBIGUOUS`, present its candidates and ask the user
-to choose. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
+Every error carries a `recovery` field. Follow it rather than improvising, and
+never fall back to raw GraphQL or `dw data ...` to work around a failure.
+
+- `ATHLETE_AMBIGUOUS` — present the candidates and ask the user to choose.
+- `ATHLETE_NOT_FOUND` — the athlete is not in this tenant. Do not retry with
+  name variations. Call `list_athletes` once to check, then tell the user.
+- `QUERY_SCOPE_REQUIRED` — add an athlete, `event_id`, or
+  `dataset_datasource_id`.
+- `METRIC_CATEGORY_REQUIRED` — retry with one of the returned `suggestions`.
+
+If `list_events` returns `unavailable: true`, the event API returned nothing for
+this session. That is a permissions problem, not proof that no events exist.
+Report it and stop; do not identify an event by any other route. For `AUTH_REQUIRED` or `TENANT_REQUIRED`, follow the recovery command
 in the error and retry. For `METRIC_CATEGORY_REQUIRED`, the error's `suggestions`
 list the closest canonical names — retry with one rather than asking the user to
 spell the metric. Never expose credentials or session material.