@tsuga/cli 1.38.0 → 1.40.0

package/README.md

@@ -30,10 +30,10 @@ For `bash` and `zsh`, add the matching line to your shell startup file:
 
 ```bash
 # ~/.bashrc
-eval "$(tsuga completion bash)"
+eval "$(tsuga --completions bash)"
 
 # ~/.zshrc
-eval "$(tsuga completion zsh)"
+eval "$(tsuga --completions zsh)"
 ```
 
 Then open a new shell (or `source` the file).
@@ -41,7 +41,7 @@ Then open a new shell (or `source` the file).
 For `fish`, write the script to your completions directory:
 
 ```fish
-tsuga completion fish > ~/.config/fish/completions/tsuga.fish
+tsuga --completions fish > ~/.config/fish/completions/tsuga.fish
 ```
 
 Fish loads it automatically in new shells.
@@ -80,7 +80,7 @@ tsuga auth logout
 
 After `tsuga auth login`, commands work without an Operation API key.
 
-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 predates refresh support.
+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.
 
 ### Operation API key
 
@@ -117,11 +117,11 @@ Commands have built-in defaults so you can omit common flags:
 | `--query`       | `*`     |
 | `--max-results` | `100`   |
 
-Override defaults persistently:
+Override defaults persistently. The value is given with `--value`:
 
 ```bash
-tsuga config set default from -1h
-tsuga config set default query 'level:ERROR'
+tsuga config set default from --value=-1h
+tsuga config set default query --value 'level:ERROR'
 ```
 
 Current defaults are listed by `tsuga config` (custom overrides marked with `*`).
@@ -135,7 +135,7 @@ tsuga config reset defaults
 Clear a single default by setting it to an empty value:
 
 ```bash
-tsuga config set default cluster ''
+tsuga config set default cluster --value ''
 ```
 
 ## Clusters
@@ -149,7 +149,7 @@ tsuga clusters list
 Pick the cluster you want to use by default via the defaults mechanism:
 
 ```bash
-tsuga config set default cluster <CLUSTER_ID>
+tsuga config set default cluster --value <CLUSTER_ID>
 ```
 
 Override per-command without persisting:
@@ -209,15 +209,17 @@ For resources with server-side filters, narrowing the query beats paging through
 
 ### Explaining a call with `--rationale`
 
-API-calling commands accept an optional `--rationale` flag to record why they are being run.
-It does not change the result; the text is sent as a request header and recorded in the
-backend request log, which is useful for understanding agent behavior. `feedback` is excluded
-since its message already explains why it's being sent.
+Every command accepts an optional `--rationale` flag to record why it is being run. It does not
+change the result; the text is sent as a request header on any API call the command makes, and
+recorded in the backend request log, which is useful for understanding agent behavior.
 
 ```bash
 tsuga logs patterns --rationale "exploring telemetry to investigate prod outage"
 ```
 
+`--rationale`, `--cluster` and `--operation-api-key` are shared flags: they may be given before
+or after the subcommand, and are inherited by every subcommand.
+
 ### Available resources
 
 `cloud-resources`, `dashboard-folders`, `dashboards`, `ingestion-api-keys`, `investigations`, `monitors`, `notification-integrations`, `notification-rules`, `notification-silences`, `public-tokens`, `quality-reports`, `retention-policies`, `log-routes`, `services`, `slos`, `tag-policies`, `teams`
@@ -285,6 +287,8 @@ tsuga retention-policies delete abc-123
 
 ### Time formats
 
+Use an equals sign for negative offsets, such as `--from=-1h`.
+
 `--from` and `--to` accept any of:
 
 | Format       | Example                      |
@@ -297,7 +301,7 @@ tsuga retention-policies delete abc-123
 ### Search logs
 
 ```bash
-tsuga logs search --from -1h --query 'level:ERROR'
+tsuga logs search --from=-1h --query 'level:ERROR'
 tsuga logs search --from 1704067200 --to 1704153600 --query 'service:api'
 ```
 
@@ -306,49 +310,70 @@ dot-paths from each log, and `-o tsv|csv` for tabular output:
 
 ```bash
 # JSON projected to selected fields (preserves the {logs: [...]} envelope and nesting)
-tsuga logs search --from -10m \
+tsuga logs search --from=-10m \
   --fields timestamp,level,message,context.k8s.pod.name
 
 # TSV with default columns: timestamp, level, message
-tsuga logs search --from -10m --query 'level:ERROR' -o tsv
+tsuga logs search --from=-10m --query 'level:ERROR' -o tsv
 
 # CSV with custom columns
-tsuga logs search --from -10m -o csv \
+tsuga logs search --from=-10m -o csv \
   --fields timestamp,level,message,context.k8s.pod.name
 ```
 
 ### Log attributes
 
 ```bash
-tsuga logs attributes --from -1h
+tsuga logs attributes --from=-1h
 ```
 
 ### Log patterns
 
 ```bash
 # Group recent logs into patterns
-tsuga logs patterns --from -1h --query 'level:ERROR'
+tsuga logs patterns --from=-1h --query 'level:ERROR'
 
 # List new error patterns observed in the time range
-tsuga logs new-error-patterns --from -24h --team my-team --service api --env prod
+tsuga logs new-error-patterns --from=-24h --team my-team --service api --env prod
 
 # List error patterns whose volume increased for a team
-tsuga logs error-pattern-increases --from -24h --team my-team --env prod
+tsuga logs error-pattern-increases --from=-24h --team my-team --env prod
 ```
 
 ### Search traces
 
 ```bash
-tsuga traces search --from -30m --query 'span_name:GET'
+tsuga traces search --from=-30m --query 'span_name:GET'
+```
+
+### Search RUM events
+
+Prefix query fields with the stream they belong to (`measurements.`, `events.`, or
+`exceptions.`), and filter on one stream per query. A query without a prefixed field, including
+the default `*`, searches the `events` stream:
+
+```bash
+tsuga rum search --from=-1h --query 'events.view.name:/checkout'
+tsuga rum search --from=-1h --query 'exceptions.exception.type:*' --max-results 20
+```
+
+### RUM attributes
+
+Lists every RUM attribute you can query:
+
+```bash
+tsuga rum attributes
 ```
 
+Both RUM commands require an operation API key with the **RUM events** (`rum`) read permission.
+
 ### Summarize a trace
 
 Aggregates groups of similar spans into synthetic summary spans (marked with
 `spanAttributes.aggregation.is_summary`) for a compact view of large traces:
 
 ```bash
-tsuga traces summarize --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from -30m
+tsuga traces summarize --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m
 ```
 
 ### Trace latency summary
@@ -357,13 +382,13 @@ Summarizes where wall-clock time is spent in a trace: each slice of the timeline
 is attributed to the services with active leaf spans, with per-service totals:
 
 ```bash
-tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from -30m
+tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m
 
 # Per-service totals only, without the range timeline
-tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from -30m --no-ranges
+tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m --no-ranges
 
 # Collapse timeline ranges shorter than 50ms (0 disables collapsing)
-tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from -30m --min-range-duration-ms 50
+tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m --min-range-duration-ms 50
 ```
 
 ### Contrast sets
@@ -431,10 +456,10 @@ with `topK`, `minLift`, and `minSupport`; restrict the attributes tested with
 
 ```bash
 # List all metrics
-tsuga metrics list --from -1h
+tsuga metrics list --from=-1h
 
 # Get a specific metric
-tsuga metrics get my.metric.name --from -1h
+tsuga metrics get my.metric.name --from=-1h
 
 # List dashboards and monitors that use a metric
 tsuga metrics assets-usage my.metric.name
@@ -460,7 +485,7 @@ tsuga aggregation scalar --generate-skeleton > query.json
 Inspect service dependency graphs:
 
 ```bash
-tsuga service-graph get <SERVICE_ID> --from -1h --query 'env:prod'
+tsuga service-graph get <SERVICE_ID> --from=-1h --query 'env:prod'
 ```
 
 ## Kubernetes
@@ -513,11 +538,11 @@ Commands under `tsuga experimental` may change or be removed without notice.
 
 ```bash
 # Rank functions by self (flat) and inclusive (cum) sample value, like `go tool pprof -top`
-tsuga experimental profiles top --service api --type cpu --from -1h
-tsuga experimental profiles top --service api --type alloc_space --from -1h --limit 10 -o tsv
+tsuga experimental profiles top --service api --type cpu --from=-1h
+tsuga experimental profiles top --service api --type alloc_space --from=-1h --limit 10 -o tsv
 
 # Download the merged profile as raw pprof protobuf and open it with pprof
-tsuga experimental profiles pprof --service api --type cpu --from -1h -O cpu.pb
+tsuga experimental profiles pprof --service api --type cpu --from=-1h -O cpu.pb
 go tool pprof -http=: cpu.pb
 
 # Raw folded stacks (`root;...;leaf` with a value), with the usual -f / -d / --generate-skeleton
@@ -578,3 +603,14 @@ Read from stdin with `-f -`:
 ```bash
 echo '{"name": "My Team"}' | tsuga teams create -f -
 ```
+
+## Implementation
+
+The CLI uses Effect v4 services for HTTP, configuration, filesystem access, subprocesses, and
+command parsing. Command folders mirror tadmin: each group has a composition `index.ts` and one
+file per action, with nearby tests. Cross-directory application imports use `@cli/*`. `packages/common-cli` shares OAuth token exchange, browser callbacks, macOS
+keychain access, output, and closed-pipe handling with tadmin. The CLIs retain separate credential
+namespaces and authentication policies. Generic field projection lives in `common`.
+
+Run `yarn lint`, `yarn typecheck`, `yarn test`, and `yarn build` from `packages/cli` to verify
+changes. Lint includes Effect language-service diagnostics.