@tsuga/cli 1.6.0 → 1.8.0

package/README.md

@@ -75,17 +75,17 @@ After `tsuga auth login`, commands work without an Operation API key.
 For non-interactive use (CI, scripts), authenticate with an Operation API key. Generate one from your [Tsuga account settings](https://app.tsuga.com/settings/api-keys?operation=true), then save it once:
 
 ```bash
-tsuga auth operation-key <operation-api-key>
+tsuga auth operation-key <OPERATION_API_KEY>
 ```
 
-This writes your operation-api-key to `$XDG_CONFIG_HOME/tsuga/config.json`, or `~/.config/tsuga/config.json` when `XDG_CONFIG_HOME` is unset. Alternatively, set it per-session without saving:
+This writes the operation API key to `$XDG_CONFIG_HOME/tsuga/config.json`, or `~/.config/tsuga/config.json` when `XDG_CONFIG_HOME` is unset. Alternatively, set it per-session without saving:
 
 ```bash
 # Environment variable
-export TSUGA_OPERATION_API_KEY=<operation-api-key>
+export TSUGA_OPERATION_API_KEY=<OPERATION_API_KEY>
 
 # CLI flag (highest priority)
-tsuga --operation-api-key <operation-api-key> dashboards list
+tsuga --operation-api-key <OPERATION_API_KEY> dashboards list
 ```
 
 A `--operation-api-key` flag or `TSUGA_OPERATION_API_KEY` env var overrides the saved credential for that one invocation.
@@ -141,17 +141,17 @@ tsuga cluster 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 <CLUSTER_ID>
 ```
 
 Override per-command without persisting:
 
 ```bash
 # Environment variable
-export TSUGA_CLUSTER_ID=<cluster-id>
+export TSUGA_CLUSTER_ID=<CLUSTER_ID>
 
 # CLI flag (highest priority)
-tsuga --cluster <cluster-id> logs search
+tsuga --cluster <CLUSTER_ID> logs search
 ```
 
 Priority order: `--cluster` flag → `TSUGA_CLUSTER_ID` env var → `defaults.cluster`. If unset, the backend falls back to the first cluster.
@@ -161,18 +161,18 @@ Priority order: `--cluster` flag → `TSUGA_CLUSTER_ID` env var → `defaults.cl
 Most resources follow the same CRUD pattern:
 
 ```bash
-tsuga <resource> list
-tsuga <resource> get <id>
-tsuga <resource> create -f payload.json
-tsuga <resource> update <id> -f payload.json
-tsuga <resource> delete <id>
+tsuga <RESOURCE> list
+tsuga <RESOURCE> get <ID>
+tsuga <RESOURCE> create -f payload.json
+tsuga <RESOURCE> update <ID> -f payload.json
+tsuga <RESOURCE> delete <ID>
 ```
 
 Read-only resources (for example `services`) support only:
 
 ```bash
 tsuga services list
-tsuga services get <id>
+tsuga services get <ID>
 ```
 
 You can also pass JSON inline with `-d`:
@@ -185,7 +185,8 @@ tsuga teams create -d '{"name": "Platform", "visibility": "public"}'
 
 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.
+backend request log, which is useful for understanding agent behavior. `feedback` is excluded
+since its message already explains why it's being sent.
 
 ```bash
 tsuga logs patterns --rationale "exploring telemetry to investigate prod outage"
@@ -197,11 +198,11 @@ tsuga logs patterns --rationale "exploring telemetry to investigate prod outage"
 
 > Notes:
 >
-> - `ingestion-api-keys` does not support `get <id>`.
+> - `ingestion-api-keys` does not support `get <ID>`.
 > - `services` is read-only (`list`, `get`).
 > - `cloud-resources` and `quality-reports` are read-only and only support `list`.
-> - For `quality-reports list`, pass `--cluster <id>` (or set `TSUGA_CLUSTER_ID` / saved default) when the org has more than one cluster.
-> - Pass `--team <name>` to `quality-reports list` to scope the response to a single team by name (omits cluster-wide global rows).
+> - For `quality-reports list`, pass `--cluster <CLUSTER_ID>` (or set `TSUGA_CLUSTER_ID` / saved default) when the org has more than one cluster.
+> - Pass `--team <TEAM_NAME>` to `quality-reports list` to scope the response to a single team by name (omits cluster-wide global rows).
 > - `investigations` is beta: it requires an operation API key with the `investigations` permission and the API may change.
 
 ### Generating a request skeleton
@@ -364,27 +365,45 @@ 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'
 ```
 
-## Experimental
+## Kubernetes
 
-Commands under `tsuga experimental` are unstable and may change or be removed without notice. Use them only if you accept that risk.
+Explore Kubernetes resources observed across the organization, inferred from your telemetry:
 
-### PromQL
+```bash
+tsuga kubernetes pods --search my-service
+tsuga kubernetes clusters
+tsuga kubernetes pod-details --k8s-cluster prod --k8s-namespace default --pod-name my-pod-abc123
+```
+
+Available resources: `pods`, `clusters`, `namespaces`, `deployments`, `statefulsets`, `daemonsets` (list, with an optional `--search`), and `pod-details`, `pod-manifest`, `deployment-details` (single-resource lookups, with required identifying flags).
+
+## Grok
+
+Test grok parsing rules against sample log lines before using them in a log route:
+
+```bash
+tsuga grok parse --generate-skeleton > grok-test.json
+# edit grok-test.json
+tsuga grok parse -f grok-test.json
+```
+
+## PromQL
 
 Run a PromQL query against the metrics backend. Returns a timeseries shape matching `tsuga aggregation timeseries`.
 
 ```bash
-tsuga experimental promql --generate-skeleton > query.json
+tsuga promql --generate-skeleton > query.json
 # edit query.json
-tsuga experimental promql -f query.json
+tsuga promql -f query.json
 ```
 
 Or inline:
 
 ```bash
-tsuga experimental promql -d '{"query":"sum by (\"context.service.name\") (sum_over_time({\"traces.span.metrics.calls\", \"span.kind\"=\"SPAN_KIND_SERVER\"}[5m]))","timeRange":{"from":1704067200,"to":1704070800},"step":"30s"}'
+tsuga promql -d '{"query":"sum by (\"context.service.name\") (sum_over_time({\"traces.span.metrics.calls\", \"span.kind\"=\"SPAN_KIND_SERVER\"}[5m]))","timeRange":{"from":1704067200,"to":1704070800},"step":"30s"}'
 ```
 
 `timeRange.from` / `timeRange.to` are Unix timestamps in seconds.
@@ -394,11 +413,11 @@ tsuga experimental promql -d '{"query":"sum by (\"context.service.name\") (sum_o
 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).
 
 ```bash
-tsuga setup claude-code --endpoint <otlp-base-url> --ingestion-api-key <key>
-tsuga setup codex --endpoint <otlp-base-url> --ingestion-api-key <key>
+tsuga setup claude-code --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTION_API_KEY>
+tsuga setup codex --endpoint <OTLP_ENDPOINT> --ingestion-api-key <INGESTION_API_KEY>
 ```
 
-Both options also read from env (`TSUGA_OTLP_ENDPOINT`, `TSUGA_INGESTION_API_KEY`). Pass `--no-include-prompts` to strip user prompts + tool content from telemetry (default: include). The previous config is saved alongside the file as `.bak.<ISO>`; restart any running `claude` / `codex` sessions afterward.
+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.
 
 ## LLM plugins