@tsuga/cli 1.88.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.
- package/README.md +15 -149
- package/dist/cli.js +69 -69
- 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
|
|
64
|
+
# Show the saved authentication method, and when the session expires or expired
|
|
72
65
|
tsuga auth status
|
|
73
66
|
|
|
74
|
-
# Ask Tsuga
|
|
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": "
|
|
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
|
|
410
|
-
|
|
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":
|
|
454
|
-
"baselineGroup": {"filter": "context.service.name:checkout", "timeRange": {"from":
|
|
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
|
-
|
|
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
|
|
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
|
|
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": "
|
|
531
|
+
echo '{"name": "my-team", "visibility": "public"}' | tsuga teams create -f -
|
|
653
532
|
```
|
|
654
533
|
|
|
655
|
-
##
|
|
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
|
-
|
|
536
|
+
`tsuga schema` prints the command tree as JSON: command paths, descriptions, positional arguments, and flags.
|