@tsuga/cli 1.89.0 → 1.90.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +15 -149
  2. package/dist/cli.js +68 -68
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -50,13 +50,6 @@ Fish loads it automatically in new shells.
50
50
 
51
51
  All authentication lives under `tsuga auth`.
52
52
 
53
- `tsuga auth status` reads the saved credential locally. To ask Tsuga which credential the CLI actually authenticates as, and what it is allowed to do:
54
-
55
- ```bash
56
- tsuga auth whoami
57
- tsuga auth whoami -o json
58
- ```
59
-
60
53
  ### Log in as a user (recommended)
61
54
 
62
55
  For interactive use, log in as a user with a browser authorization flow:
@@ -68,19 +61,17 @@ tsuga auth login
68
61
  # Print the saved user access token
69
62
  tsuga auth token
70
63
 
71
- # Show the current authentication method, and when the session expires or expired
64
+ # Show the saved authentication method, and when the session expires or expired
72
65
  tsuga auth status
73
66
 
74
- # Ask Tsuga who this CLI authenticates as
67
+ # Ask Tsuga which credential this CLI authenticates as, and what it is allowed to do
75
68
  tsuga auth whoami
76
69
 
77
70
  # Clear the saved user session
78
71
  tsuga auth logout
79
72
  ```
80
73
 
81
- After `tsuga auth login`, commands work without an Operation API key.
82
-
83
- Sessions renew themselves: the login also saves a refresh token, and the CLI exchanges it for a new access token when the current one is within five minutes of expiry. You log in again when the refresh token expires, when it is revoked, or when the session has no refresh token.
74
+ After `tsuga auth login`, commands work without an Operation API key. Sessions renew themselves until the refresh token expires or is revoked.
84
75
 
85
76
  ### Operation API key
86
77
 
@@ -181,17 +172,10 @@ tsuga <RESOURCE> update <ID> -f payload.json
181
172
  tsuga <RESOURCE> delete <ID>
182
173
  ```
183
174
 
184
- Read-only resources (for example `services`) support only:
185
-
186
- ```bash
187
- tsuga services list
188
- tsuga services get <ID>
189
- ```
190
-
191
175
  You can also pass JSON inline with `-d`:
192
176
 
193
177
  ```bash
194
- tsuga teams create -d '{"name": "Platform", "visibility": "public"}'
178
+ tsuga teams create -d '{"name": "platform", "visibility": "public"}'
195
179
  ```
196
180
 
197
181
  ### Pagination
@@ -225,9 +209,6 @@ For resources with server-side filters, narrowing the query beats paging through
225
209
  > - `services` is read-only (`list`, `get`).
226
210
  > - `cloud-resources` is read-only and only supports `list`.
227
211
  > - `quality-reports` is read-only and supports `list` plus `examples <ID>`.
228
- > - For `quality-reports list`, pass `--cluster <CLUSTER_ID>` (or set `TSUGA_CLUSTER_ID` / saved default) when the org has more than one cluster.
229
- > - Pass `--team <TEAM_NAME>` to `quality-reports list` to scope the response to a single team by name (omits cluster-wide global rows).
230
- > - `quality-reports examples <ID>` pages the examples stored for one row, with `--limit` / `--offset` and `-o json|tsv|csv`. JSON output is an array of example rows. Tabular output defaults to the `type,label` columns; `--fields` picks others (e.g. `link.to`).
231
212
  > - `investigations` is beta: it requires an operation API key with the `investigations` permission and the API may change.
232
213
  > - `public-tokens` manages the RUM public tokens configured in browser and mobile SDKs. It requires an operation API key with the **RUM public tokens** (`rum-public-token`) permission.
233
214
 
@@ -255,34 +236,6 @@ tsuga monitors create --generate-skeleton > monitor.json
255
236
  tsuga monitors create -f monitor.json
256
237
  ```
257
238
 
258
- ### Examples
259
-
260
- ```bash
261
- # List all monitors
262
- tsuga monitors list
263
-
264
- # Get a specific dashboard
265
- tsuga dashboards get abc-123
266
-
267
- # List dashboards filtered by owner
268
- tsuga dashboards list -d '{"filters":{"owners":{"values":["team-1","team-2"]}}}'
269
-
270
- # List prod services of a team whose name contains "checkout"
271
- tsuga services list --envs prod --teams payments --search-query checkout
272
-
273
- # Get a specific service
274
- tsuga services get abc-123
275
-
276
- # Create a notification rule from a file
277
- tsuga notification-rules create -f rule.json
278
-
279
- # Update a log route
280
- tsuga log-routes update abc-123 -d '{"name": "Updated log route"}'
281
-
282
- # Delete a retention policy
283
- tsuga retention-policies delete abc-123
284
- ```
285
-
286
239
  ## Telemetry
287
240
 
288
241
  ### Time formats
@@ -304,13 +257,9 @@ Start with a narrow window and widen it step by step only when the result is emp
304
257
 
305
258
  ```bash
306
259
  tsuga logs search --from=-1h --query 'level:ERROR'
307
- tsuga logs search --from 1704067200 --to 1704153600 --query 'service:api'
260
+ tsuga logs search --from 1704067200 --to 1704153600 --query 'context.service.name:api'
308
261
  ```
309
262
 
310
- Field lists trim whitespace and skip empty comma-separated entries; an explicitly
311
- empty or comma-only `--fields` is rejected. Omitting it preserves complete JSON rows
312
- or the default TSV/CSV columns.
313
-
314
263
  ```bash
315
264
  # JSON array projected to selected fields (preserves nested objects)
316
265
  tsuga logs search --from=-10m \
@@ -392,12 +341,6 @@ is attributed to the services with active leaf spans, with per-service totals:
392
341
 
393
342
  ```bash
394
343
  tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m
395
-
396
- # Per-service totals only, without the range timeline
397
- tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m --no-ranges
398
-
399
- # Collapse timeline ranges shorter than 50ms (0 disables collapsing)
400
- tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m --min-range-duration-ms 50
401
344
  ```
402
345
 
403
346
  ### Contrast sets
@@ -406,60 +349,17 @@ Compares a target group of spans against a baseline and returns the attribute
406
349
  values that are over-represented in the target — what those spans have in common
407
350
  that the baseline ones do not. Each group carries its own filter and time range.
408
351
 
409
- Filters are written in TQL, the same query language as `--query` elsewhere: terms
410
- are ANDed by whitespace, `span_attributes.*` addresses span attributes, and
411
- `duration` is in milliseconds. Run `tsuga docs get explore/query-syntax` for the
412
- full syntax.
413
-
414
- ```bash
415
- tsuga traces contrast-sets --generate-skeleton > groups.json
416
- tsuga traces contrast-sets -f groups.json
417
- ```
418
-
419
- Time ranges are Unix seconds, and unlike `--from` / `--to` they are not resolved
420
- from relative strings — the body takes numbers. The skeleton and the examples
421
- below carry a fixed window that is long past, so substitute your own:
422
-
423
- ```bash
424
- TO=$(date +%s)
425
- FROM=$((TO - 3600))
426
- ```
427
-
428
- Erroring spans against healthy ones, for one service in one window:
429
-
430
- ```bash
431
- cat > groups.json <<EOF
432
- {
433
- "targetGroup": {"filter": "context.service.name:checkout status_code:error", "timeRange": {"from": $FROM, "to": $TO}},
434
- "baselineGroup": {"filter": "context.service.name:checkout NOT status_code:error", "timeRange": {"from": $FROM, "to": $TO}}
435
- }
436
- EOF
437
- tsuga traces contrast-sets -f groups.json
438
- ```
439
-
440
- Slow spans against normal-latency ones:
441
-
442
- ```bash
443
- tsuga traces contrast-sets -d '{
444
- "targetGroup": {"filter": "context.service.name:checkout duration:>2000", "timeRange": {"from": 1704067200, "to": 1704070800}},
445
- "baselineGroup": {"filter": "context.service.name:checkout duration:<500", "timeRange": {"from": 1704067200, "to": 1704070800}}
446
- }'
447
- ```
448
-
449
- Before and after a deployment — same filter, two windows:
352
+ Filters are written in TQL, the same query language as `--query`. Time ranges are Unix seconds.
353
+ Erroring spans against healthy ones:
450
354
 
451
355
  ```bash
452
356
  tsuga traces contrast-sets -d '{
453
- "targetGroup": {"filter": "context.service.name:checkout", "timeRange": {"from": 1704070800, "to": 1704074400}},
454
- "baselineGroup": {"filter": "context.service.name:checkout", "timeRange": {"from": 1704063600, "to": 1704067200}}
357
+ "targetGroup": {"filter": "context.service.name:checkout status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}},
358
+ "baselineGroup": {"filter": "context.service.name:checkout NOT status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}}
455
359
  }'
456
360
  ```
457
361
 
458
- Each returned value reports `targetSupport` and `baselineSupport` (the percentage
459
- of each group carrying it), `lift` (`targetSupport / baselineSupport`, omitted
460
- when the value never appears in the baseline), and `pValue`. Narrow the findings
461
- with `topK`, `minLift`, and `minSupport`; restrict the attributes tested with
462
- `candidateAttrs`.
362
+ Run `tsuga traces contrast-sets --generate-skeleton` for the full request body.
463
363
 
464
364
  ### Metrics
465
365
 
@@ -568,25 +468,6 @@ tsuga profiles query -d '{"service":"api","type":"cpu","timeRange":{"from":17040
568
468
 
569
469
  `--type` is a pprof sample type such as `cpu`, `samples`, `wall`, `off_cpu`, `alloc_space`, `inuse_space`, `alloc_objects`, `inuse_objects`, or `goroutine`. `--filter` takes a Tsuga query over the profile labels; only label equality, negation, and wildcards are accepted.
570
470
 
571
- ## Experimental
572
-
573
- Commands under `tsuga experimental` may change or be removed without notice.
574
-
575
- ### Sandbox agent runs
576
-
577
- ```bash
578
- # Latest runs (no prompt or output), then one run with its prompt and output
579
- tsuga experimental sandbox-runs list
580
- tsuga experimental sandbox-runs get <RUN_ID>
581
-
582
- # The Claude Code memory files (MEMORY.md and the files it links) that runs of a configuration keep
583
- tsuga experimental sandbox-memory get <CONFIGURATION_ID>
584
- tsuga experimental sandbox-memory set <CONFIGURATION_ID> -d '{"memory":{"MEMORY.md":"- Deploys go through the release branch."}}'
585
- tsuga experimental sandbox-memory clear <CONFIGURATION_ID>
586
- ```
587
-
588
- Admins see every run; other users and operation API keys see the runs their user started. The memory commands need a user login (`tsuga auth login`), since operation API keys cannot hold sandbox configuration permissions.
589
-
590
471
  ## LLM telemetry
591
472
 
592
473
  Configure local Claude Code (`~/.claude/settings.json`) or Codex (`~/.codex/config.toml`) to ship OpenTelemetry data to your Tsuga cluster. Needs an OTLP base URL and an [ingestion API key](https://app.tsuga.com/settings/api-keys?ingestion=true) (not the same as your operation API key).
@@ -596,7 +477,7 @@ tsuga setup claude-code --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTIO
596
477
  tsuga setup codex --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTION_API_KEY>
597
478
  ```
598
479
 
599
- Both options also read from env (`TSUGA_OTLP_ENDPOINT`, `TSUGA_INGESTION_API_KEY`). Pass `--no-include-prompts` to strip user prompts from telemetry (default: include); for `claude-code` this also strips tool content, but `codex` only strips user prompts. The previous config is saved alongside the file as `.bak.<ISO>`; restart any running `claude` / `codex` sessions afterward.
480
+ Both options also read from env (`TSUGA_OTLP_ENDPOINT`, `TSUGA_INGESTION_API_KEY`). Pass `--no-include-prompts` to strip user prompts from telemetry (default: include); for `claude-code` this also strips tool content, but `codex` only strips user prompts. The previous config is backed up next to the file; restart any running `claude` / `codex` sessions afterward.
600
481
 
601
482
  ## LLM plugins
602
483
 
@@ -605,7 +486,7 @@ tsuga install plugin claude-code
605
486
  tsuga install plugin codex
606
487
  ```
607
488
 
608
- Adds the `tsuga` marketplace (`tsuga-dev/agent-plugins`) and installs the `tsuga` plugin via the target CLI (`claude` / `codex` must be on `PATH`). For Claude Code, marketplace auto-update is enabled by patching `~/.claude/settings.json` with `extraKnownMarketplaces.tsuga.autoUpdate = true`; pass `--no-auto-update` to skip. Restart any running `claude` / `codex` sessions afterward.
489
+ Adds the `tsuga` marketplace (`tsuga-dev/agent-plugins`) and installs the `tsuga` plugin via the target CLI (`claude` / `codex` must be on `PATH`). For Claude Code, it also turns on marketplace auto-update; pass `--no-auto-update` to skip. Restart any running `claude` / `codex` sessions afterward.
609
490
 
610
491
  ## Shared links
611
492
 
@@ -617,8 +498,6 @@ tsuga unshorten https://api.tsuga.com/v0/widget-shares/<ORG_ID>/<CODE>
617
498
  tsuga unshorten 'https://app.tsuga.com/logs?query=level%3AERROR'
618
499
  ```
619
500
 
620
- Malformed URL encoding or out-of-range timestamps produce a usage error (exit `2`). Exit `4` means the API returned an error; check the reported HTTP status. A `404` means the code is unknown, expired, or belongs to another organization.
621
-
622
501
  ## Documentation
623
502
 
624
503
  Search Tsuga documentation and the full API reference, then fetch a page by path:
@@ -649,22 +528,9 @@ tsuga monitors list | jq '.[] | select(.priority == 1)'
649
528
  Read from stdin with `-f -`:
650
529
 
651
530
  ```bash
652
- echo '{"name": "My Team"}' | tsuga teams create -f -
531
+ echo '{"name": "my-team", "visibility": "public"}' | tsuga teams create -f -
653
532
  ```
654
533
 
655
- ## Implementation
656
-
657
- The CLI uses Effect v4 services for HTTP, configuration, filesystem access, subprocesses, and
658
- command parsing. Command folders mirror tadmin: each group has a composition `index.ts` and one
659
- file per action, with nearby tests. Cross-directory application imports use `@cli/*`. `packages/common-cli` shares OAuth token exchange, browser callbacks, macOS
660
- keychain access, output, and closed-pipe handling with tadmin. The CLIs retain separate credential
661
- namespaces and authentication policies. Generic field projection lives in `common`.
662
-
663
- Run `yarn lint`, `yarn typecheck`, `yarn test`, and `yarn build` from `packages/cli` to verify
664
- changes. Lint includes Effect language-service diagnostics.
665
-
666
- ### Command schema
667
-
668
- `tsuga schema` prints the command tree as JSON, including command paths, descriptions, positional arguments, and declared flags. Shared flags are included on descendant commands; hidden commands and flags are omitted.
534
+ ## Command schema
669
535
 
670
- Each command’s `arguments` array follows positional declaration order. Entries include `name`, `type`, `description`, `required`, `variadic`, `minCount`, and `maxCount`. `maxCount` is omitted for unbounded variadic arguments; optional and defaulted single arguments have `minCount: 0`.
536
+ `tsuga schema` prints the command tree as JSON: command paths, descriptions, positional arguments, and flags.