@tailglow/cli 0.8.1 → 0.9.5

package/README.md

@@ -10,7 +10,9 @@ tglow login
 tglow projects list
 ```
 
-Node 22 or newer. `bun add -g` and `pnpm add -g` work the same way.
+Node 22 or newer. `bun add -g` and `pnpm add -g` work the same way. Update with
+`npm install -g @tailglow/cli@latest`. When a newer version is out, `tglow` says so in one line on
+stderr; it asks npm at most once a day.
 
 Prefer a shorter name? Alias it rather than installing over one:
 
@@ -37,7 +39,7 @@ Field names are snake_case on the wire and kebab-case on the command line: `repe
 becomes `--repeat-window-minutes`. Object and array fields take JSON:
 
 ```bash
-tglow views create-join --project prj_x --joins '[{"view_id":"view_b","on":"user_id"}]'
+tglow views create --project prj_x --type join --base-view-id view_a --joins '[{"lookup_view_id":"view_b","alias":"b","base_field":"user_id","lookup_field":"id"}]'
 ```
 
 ## Credentials
@@ -151,7 +153,7 @@ Scan and validate locally without credentials:
 ```bash
 tglow import scan export.xml
 tglow import scan export.xml --record-path /HealthData/Record --full
-tglow import validate events.jsonl --timestamp-field /event/created_at
+tglow import validate events.jsonl
 ```
 
 Content detection supports XML, JSONL, JSON, CSV and TSV; use `--format` to resolve ambiguity.
@@ -194,11 +196,8 @@ graceful Ctrl-C. A cleanup failure is reported separately as `cleanup_error` and
 not change delivery status or acknowledged counts. Changes to the original after copying do not change the uploaded bytes. A failed
 full check sends no rows; successful checking cannot prevent a later delivery failure.
 
-`--timestamp-field` accepts a JSON pointer or an exact top-level field name. Source fields remain
-unchanged; the selected value sets request-level `ts`. Missing, invalid or timezone-ambiguous
-values fail validation. Selected dates must be between 1970-01-01 UTC and the current time, since earlier or future ingest timestamps cannot be preserved by the server. No timestamp field is selected automatically. Batches split whenever
-the exact parsed timestamp changes, which can produce one request per row, and otherwise stay
-within 500 rows and 1 MiB.
+Records keep their own fields, including their dates; Tailglow records when each batch arrived.
+Batches stay within 500 rows and 1 MiB.
 
 Only HTTP 202 acknowledges a batch. Upload stops on rejection or uncertain delivery and never
 retries automatically. The report includes `accepted_count` and the affected batch's inclusive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailglow/cli",
-  "version": "0.8.1",
+  "version": "0.9.5",
   "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": {
@@ -35,6 +35,6 @@
     "@clack/prompts": "^1.2.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.6"
+    "@types/bun": "^1.4.3"
   }
 }

package/src/commands.generated.js

@@ -248,13 +248,13 @@ export const CLI_COMMANDS = [
     "query_params": [],
     "body_fields": [
       {
-        "name": "tgl_authoring_mode",
-        "type": "TglAuthoringMode",
+        "name": "ambiguity_handling",
+        "type": "AmbiguityHandlingMode",
         "required": false,
-        "description": "Project-wide authoring behavior. Aggressive chooses a defensible mapping; normal requests clarification for competing meanings. Defaults to aggressive. Existing scripts are unchanged. Optional.",
+        "description": "What new mappings do when the source data allows more than one defensible reading. decide picks the most defensible one; ask requests a hint from you instead. Defaults to decide. Existing scripts are unchanged. Optional.",
         "allowed_values": [
-          "normal",
-          "aggressive"
+          "decide",
+          "ask"
         ],
         "deprecated": null
       },
@@ -1804,7 +1804,7 @@ export const CLI_COMMANDS = [
       "sources:read"
     ],
     "notes": [
-      "Documents are returned exactly as they were sent, minus Tailglow's own reserved envelope.",
+      "Documents are returned as they were sent, minus Tailglow's own reserved envelope. A value sent in a JSON array or JSONL that is not an object comes back as `{\"value\": ...}`.",
       "Paging is forward-only. Pass `pagination.next_cursor` back as `after` to get the next page; no `prev_cursor` is issued, and `before` returns the first page.",
       "While the project's server is stopped this answers 409 `server_stopped`. Start the server and try again.",
       "`after` and `before` are mutually exclusive."
@@ -2013,7 +2013,7 @@ export const CLI_COMMANDS = [
     "command": "create",
     "operation_id": "createView",
     "summary": "Create View",
-    "description": "Create a view that transforms records from a collection or another view.",
+    "description": "Create a view: a transform over one collection or view, or a join of a base view with lookups.",
     "method": "POST",
     "path": "/v1/projects/:project_id/views",
     "alternate_paths": [],
@@ -2021,15 +2021,19 @@ export const CLI_COMMANDS = [
       "views:write"
     ],
     "notes": [
-      "A view reads from exactly one source: a collection, or another view to derive from.",
       "The output schema defines the fields the view produces. A transform is created alongside the view to populate them.",
       "Leaving the transform script empty queues it for generation instead of rejecting it, so a view can be created before its TGL is written.",
       "Backfilling existing records starts shortly after creation and runs in the background. The view reports its progress while it catches up.",
-      "A view reads from exactly one place: set `collection_id` to derive from raw ingested records, or `parent_view_id` to derive from another view. Setting both, or neither, is rejected.",
+      "A join's base view and lookup views must all be views in this project.",
+      "A join whose inputs lead back to the join itself, directly or through other views, is rejected.",
+      "A `transform` view reads from exactly one place: set `collection_id` to derive from raw ingested records, or `parent_view_id` to derive from another view. Setting both, or neither, is rejected, and so are `base_view_id` and `joins`.",
+      "A `join` view requires `base_view_id` and `joins` (one to ten clauses), and rejects `collection_id` and `parent_view_id`. Join a collection by creating a view over it first.",
+      "Each join clause's `alias` must be lowercase letters, digits and underscores, and start with a letter. It is how the clause's fields are addressed in the transform script.",
+      "A join enriches each record with each joined view's latest value, by record timestamp, at the time the record is processed. Records already produced are not revisited.",
       "There is no `source_id` on this endpoint. One source can hold many collections, and the collection is what owns the schema and the records a view transforms. List a source's collections with `GET /v1/projects/:project/collections?source_id=...` and pass the one you want.",
       "`output_schema` field names must be unique by name, cannot conflict on type, and cannot collide with a reserved query key such as `limit` or `cursor`.",
-      "`transform_script` cannot be whitespace-only. Supplying one activates the view's first transform immediately and skips automatic TGL generation.",
-      "Use `hint` for rules the generator cannot read off the field names: a formatting rule (\"display_name should be Name (Type)\"), a business threshold (\"classify as high above 500\"), or a disambiguation when a source field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles."
+      "`transform_script` cannot be whitespace-only. Supplying one skips automatic TGL generation; omit it entirely to have one generated.",
+      "Use `hint` for rules the generator cannot read off the field names: a formatting rule (\"display_name should be Name (Type)\"), a business threshold (\"classify as high above 500\"), or a disambiguation when an input field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles."
     ],
     "path_params": [
       {
@@ -2043,6 +2047,17 @@ export const CLI_COMMANDS = [
     ],
     "query_params": [],
     "body_fields": [
+      {
+        "name": "type",
+        "type": "ViewType",
+        "required": false,
+        "description": "How the view's records are produced: `transform` reads one collection or view through a script; `join` starts from a base view and attaches lookup rows. Fixed at creation. Optional. Defaults to `\"transform\"`.",
+        "allowed_values": [
+          "transform",
+          "join"
+        ],
+        "deprecated": null
+      },
       {
         "name": "name",
         "type": "string",
@@ -2166,89 +2181,19 @@ export const CLI_COMMANDS = [
         "allowed_values": [],
         "deprecated": null
       },
-      {
-        "name": "transform_script",
-        "type": "string",
-        "required": false,
-        "description": "TGL transform script. When set, the view skips automatic TGL generation. Optional. Minimum length: `1`. Maximum length: `65536`.",
-        "allowed_values": [],
-        "deprecated": null
-      },
-      {
-        "name": "transform_mode",
-        "type": "string",
-        "required": false,
-        "description": "Whether a new schema version that no existing transform covers gets a script generated for it, or waits for you to write one. Defaults to auto. Optional.",
-        "allowed_values": [
-          "auto",
-          "manual"
-        ],
-        "deprecated": null
-      }
-    ]
-  },
-  {
-    "resource": "views",
-    "command": "create-join",
-    "operation_id": "createJoinView",
-    "summary": "Create Join View",
-    "description": "Create a view that joins two existing views on a shared key.",
-    "method": "POST",
-    "path": "/v1/projects/:project_id/views/join",
-    "alternate_paths": [],
-    "scopes": [
-      "views:write"
-    ],
-    "notes": [
-      "Both sides must be views in this project. Join a collection by creating a view over it first.",
-      "The join key must exist in the output schema of both sides.",
-      "A join view rebuilds when either side produces new records, so it trails its inputs rather than updating in the same instant.",
-      "Records are enriched with each joined view's latest value, by record timestamp, at the time they are processed. Records already produced are not revisited.",
-      "Each join clause's `alias` must be lowercase letters, digits and underscores, and start with a letter. It is how the clause's fields are addressed in the transform script.",
-      "`transform_script` cannot be whitespace-only. Omit it entirely to have one generated.",
-      "Use `hint` for rules the generator cannot read off the field names: a formatting rule (\"display_name should be Name (Type)\"), a business threshold (\"classify as high above 500\"), or a disambiguation when an input field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles."
-    ],
-    "path_params": [
-      {
-        "name": "project_id",
-        "type": "string",
-        "required": true,
-        "description": "Unique identifier of the project.",
-        "allowed_values": [],
-        "deprecated": null
-      }
-    ],
-    "query_params": [],
-    "body_fields": [
-      {
-        "name": "name",
-        "type": "string",
-        "required": true,
-        "description": "Name shown for this join view. Minimum length: `1`. Maximum length: `128`.",
-        "allowed_values": [],
-        "deprecated": null
-      },
-      {
-        "name": "project_id",
-        "type": "string",
-        "required": false,
-        "description": "Project the join view belongs to. Optional.",
-        "allowed_values": [],
-        "deprecated": null
-      },
       {
         "name": "base_view_id",
         "type": "string",
-        "required": true,
-        "description": "View every output record starts from. Minimum length: `1`.",
+        "required": false,
+        "description": "View every output record of a join starts from. Optional. Minimum length: `1`.",
         "allowed_values": [],
         "deprecated": null
       },
       {
         "name": "joins",
         "type": "object[]",
-        "required": true,
-        "description": "Views joined onto the base view, each with its own match fields.",
+        "required": false,
+        "description": "Views joined onto the base view, each with its own match fields. Optional.",
         "allowed_values": [],
         "deprecated": null,
         "fields": [
@@ -2315,61 +2260,23 @@ export const CLI_COMMANDS = [
           }
         ]
       },
-      {
-        "name": "output_schema",
-        "type": "object[]",
-        "required": false,
-        "description": "Fields the join produces. Leave empty to have one inferred. Optional. Defaults to `[]`.",
-        "allowed_values": [],
-        "deprecated": null,
-        "fields": [
-          {
-            "name": "name",
-            "type": "string",
-            "required": true,
-            "description": "Field name as it appears on the view's records. Minimum length: `1`. Maximum length: `128`.",
-            "allowed_values": [],
-            "deprecated": null
-          },
-          {
-            "name": "type",
-            "type": "string",
-            "required": true,
-            "description": "Value type the field holds.",
-            "allowed_values": [
-              "string",
-              "number",
-              "boolean",
-              "date",
-              "array",
-              "null"
-            ],
-            "deprecated": null
-          },
-          {
-            "name": "description",
-            "type": "string",
-            "required": false,
-            "description": "What the field means. Used as guidance when a transform script is generated. Optional. Maximum length: `512`.",
-            "allowed_values": [],
-            "deprecated": null
-          }
-        ]
-      },
       {
         "name": "transform_script",
         "type": "string",
         "required": false,
-        "description": "TGL transform script. Omit to have one generated. Optional. Minimum length: `1`. Maximum length: `65536`.",
+        "description": "TGL transform script. When set, the view skips automatic TGL generation. Optional. Minimum length: `1`. Maximum length: `65536`.",
         "allowed_values": [],
         "deprecated": null
       },
       {
-        "name": "hint",
+        "name": "transform_mode",
         "type": "string",
         "required": false,
-        "description": "Instructions the generator cannot infer from field names alone, such as a formatting rule or a business threshold. Optional. Maximum length: `4096`.",
-        "allowed_values": [],
+        "description": "Whether a new schema version that no existing transform covers gets a script generated for it, or waits for you to write one. Defaults to auto. Optional.",
+        "allowed_values": [
+          "auto",
+          "manual"
+        ],
         "deprecated": null
       }
     ]
@@ -7432,10 +7339,10 @@ export const CLI_COMMANDS = [
     "notes": [
       "Teams cannot be created with an API key. Use a signed-in user session.",
       "`name` defaults to `Team` and `billing_email` defaults to the authenticated user's email address when they are omitted.",
+      "`billing_email` cannot use the `@tailglow.io` domain.",
       "The team starts on the `pro_v1` plan with a generated logo. `billing_plan`, `status`, `logo_url`, `is_mfa_required`, `billing_address`, and `max_servers_per_project` are ignored on create. Send them to the update endpoint instead.",
       "There is a maximum number of teams a single user can create.",
       "The authenticated user is added to the new team as its Owner.",
-      "`billing_email` cannot use the `@tailglow.io` domain.",
       "`logo_url` must be a JPEG or PNG base64 data URI of at most 5 MB."
     ],
     "path_params": [],
@@ -7587,7 +7494,7 @@ export const CLI_COMMANDS = [
       "Teams cannot be updated with an API key. Use a signed-in user session.",
       "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`, `max_servers_per_project`, and `deleted_at` are managed by Tailglow and cannot be set by team members, with one exception: an Owner restores a team scheduled for deletion by sending only `deleted_at` set to null.",
       "`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.",
@@ -7761,7 +7668,7 @@ export const CLI_COMMANDS = [
         "name": "deleted_at",
         "type": "ISODateString | null",
         "required": false,
-        "description": "Date and time when the team is scheduled to be permanently deleted. Optional.",
+        "description": "Set to null, as the only field, to restore a team scheduled for deletion. Only Tailglow can set a date. Optional.",
         "allowed_values": [],
         "deprecated": null
       }
@@ -7781,7 +7688,8 @@ export const CLI_COMMANDS = [
       "Teams cannot be deleted with an API key. Use a signed-in user session.",
       "Only the team Owner can delete a team.",
       "The team must be active. Contact support to delete a suspended or blocked team.",
-      "Deletion is scheduled, not immediate. Permanent removal happens 40 days later, the team's projects and API keys are cancelled, and every signed-in member is signed out. An owner who signs back in before then cancels the deletion."
+      "Deletion is scheduled, not immediate. Permanent removal happens 40 days later. The team's API keys are deleted, its ingest keys are revoked, and its servers are scaled to zero.",
+      "Members lose access to the team at once but stay signed in to their other teams. Until permanent removal, an Owner can restore the team by updating it with `deleted_at` set to null."
     ],
     "path_params": [
       {
@@ -8337,6 +8245,17 @@ export const CLI_COMMANDS = [
         ],
         "deprecated": null
       },
+      {
+        "name": "timezone_display",
+        "type": "TimezoneDisplay",
+        "required": false,
+        "description": "How the user reads times in the dashboard and in emails: `local` in the time zone their browser reports, `utc` in UTC. Optional.",
+        "allowed_values": [
+          "local",
+          "utc"
+        ],
+        "deprecated": null
+      },
       {
         "name": "default_ai_model",
         "type": "AiChatSelection",
@@ -9254,6 +9173,9 @@ export const CLI_COMMANDS = [
     "notes": [
       "A server is a dedicated machine that receives and processes the project's data. Every project runs its own fleet.",
       "A server that is still coming up is returned with a status of `provisioning`, and a server on its way out with a status of `terminating`.",
+      "During a platform update, the server being replaced is returned with a status of `upgrading`. The `status` filter matches the status stored before the update, so it finds that server under `active`.",
+      "A platform update also adds a temporary server that takes each server's records while that server is replaced. It is not billed and is left out of this list; `is_deploy_surge=true` lists it instead.",
+      "`is_deploy_surge` accepts `true`, `false`, `1` or `0`.",
       "`after` and `before` are mutually exclusive."
     ],
     "path_params": [
@@ -9293,6 +9215,19 @@ export const CLI_COMMANDS = [
         ],
         "deprecated": null
       },
+      {
+        "name": "is_deploy_surge",
+        "type": "string",
+        "required": false,
+        "description": "Set true to list the temporary server a platform update adds instead of the project's own servers. Optional.",
+        "allowed_values": [
+          "true",
+          "false",
+          "1",
+          "0"
+        ],
+        "deprecated": null
+      },
       {
         "name": "limit",
         "type": "number",

package/src/config.js

@@ -17,7 +17,14 @@ export const CLI_CONFIGS = {
   DIRECTORY_MODE: 0o700,
   LOCK_RETRY_MS: 50,
   // The lock covers one small read and write, so waiting this long means its holder stopped.
-  LOCK_TIMEOUT_MS: 10_000
+  LOCK_TIMEOUT_MS: 10_000,
+  UPDATE_CHECK_URL: "https://registry.npmjs.org/@tailglow/cli/latest",
+  UPDATE_CHECK_PATH: join(homedir(), ".tailglow", "update-check.json"),
+  UPDATE_CHECK_INTERVAL_MS: 24 * 60 * 60 * 1_000,
+  // The check runs alongside the command, so this only delays a command that finishes sooner.
+  UPDATE_CHECK_TIMEOUT_MS: 1_500,
+  // Caps the stored check and npm's answer, which is about 2 KB.
+  UPDATE_CHECK_MAX_BYTES: 65_536
 };
 
 export const LOGIN_CONFIGS = {