# @tsuga/cli 中文文档

规范地址：https://npmcn.com/package/%40tsuga/cli/

版本：1\.121\.0
npm 元数据更新时间：2026-11-02T17:07:11.751Z
中文译文更新时间：2026-11-02T18:05:29.829Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40tsuga/cli
原文对照：https://npmcn.com/package/%40tsuga/cli/?lang=original
项目主页：https://tsuga.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，4 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-02-24T10:20:00.336Z
- 最新版本发布：2026-11-02T17:07:11.541Z
- 已发布版本数：141（近 12 个月 141 个）

## 中文简介

Tsuga CLI -从命令行管理资源

## 安装

```sh
npm install @tsuga/cli
```

也可以使用：`pnpm add @tsuga/cli`、`yarn add @tsuga/cli`、`bun add @tsuga/cli`

## README

# @tsuga / cli

用于管理Tsuga资源的命令行接口。

## 安装

```bash
npm install -g @tsuga/cli
```

```bash
tsuga --help
```

## 更新

更新至最新发布的版本：

```bash
tsuga self-update
```

这个运行 `npm install -g @tsuga/cli@latest`。CLI还每天检查一次新版本，并在有新版本可用时打印通知。

## 壳完成

用制表符完成命令和标记 `bash`， `zsh`，或者 `fish`.

为 `bash` 和 `zsh`，将匹配的行添加到shell启动文件中：

```bash
# ~/.bashrc
eval "$(tsuga --completions bash)"

# ~/.zshrc
eval "$(tsuga --completions zsh)"
```

然后打开一个新的shell(或 `source` 文件)。

为 `fish`，将脚本写入完成目录：

```fish
tsuga --completions fish > ~/.config/fish/completions/tsuga.fish
```

鱼会自动把它装进新壳里。

## 身份验证

所有身份验证都在 `tsuga auth`.

### 以用户身份登录（推荐）

对于交互式使用，使用浏览器授权流程以用户身份登录：

```bash
# Opens your browser to an authorization URL, or prints the URL if it can't be opened.
tsuga auth login

# Print the saved user access token
tsuga auth token

# Show the saved authentication method, and when the session expires or expired
tsuga auth status

# Ask Tsuga which credential this CLI authenticates as, and what it is allowed to do
tsuga auth whoami

# Clear the saved user session
tsuga auth logout
```

后 `tsuga auth login`，命令在没有操作API密钥的情况下工作。会话更新自己，直到刷新令牌过期或被撤销。

### 操作API密钥

对于非交互式使用（CI、脚本），使用操作API密钥进行身份验证。从你的 [Tsuga帐户设置](https://app.tsuga.com/settings/api-keys?operation=true)，然后保存一次：

```bash
tsuga auth operation-key <OPERATION_API_KEY>
```

这将操作API密钥写入 `$XDG_CONFIG_HOME/tsuga/config.json`，或者 `~/.config/tsuga/config.json` 当 `XDG_CONFIG_HOME` 是设置。或者，每个会话设置它而不保存：

```bash
export TSUGA_OPERATION_API_KEY=<OPERATION_API_KEY>
```

一、 `TSUGA_OPERATION_API_KEY` Env var覆盖为该调用保存的凭据。

## 配置

显示当前配置（包括默认值）：

```bash
tsuga config
```

### 使用数据

在交互式终端中，命令第一次执行成功时，CLI会询问是否发送使用情况数据。 用 `tsuga config set telemetry on` (或 `off`）。 `TSUGA_TELEMETRY=1` (或 `0`)将覆盖已保存的答案。

## 违约

命令具有内置默认值，因此您可以忽略常见标志：

| 国旗 | 默认的 |
| --- | --- |
| `--from` | `-30m` |
| `--to` | `now` |
| `--query` | `*` |
| `--max-results` | `100` |

持久覆盖默认值。给出的值是 `--value`：

```bash
tsuga config set default from --value=-1h
tsuga config set default query --value 'level:ERROR'
```

默认值存在于 `from`， `to`， `query`， `max-results` 和 `cluster` (见 [集群](https://npmcn.com/package/%40tsuga/cli/#readme-clusters)）; 任何其他名称都将被拒绝。 `from` 和 `to` 必须是有效的 [时间](https://npmcn.com/package/%40tsuga/cli/#readme-time-formats) 和 `max-results` 一个正整数，因此在设置默认值时报告拼写错误，而不是在以后的每个命令中报告。

当前默认值按 `tsuga config` (自定义覆盖标记为 `*`）。

重置所有自定义默认值：

```bash
tsuga config reset defaults
```

通过将单个默认值设置为空值来清除它。它的内置默认值，如果有，将再次应用：

```bash
tsuga config set default cluster --value ''
```

## 集群

如果您的租户有多个集群，请列出它们：

```bash
tsuga clusters list
```

通过默认机制选择你想默认使用的集群：

```bash
tsuga config set default cluster --value <CLUSTER_ID>
```

覆盖每个命令而不持久化：

```bash
# Environment variable
export TSUGA_CLUSTER_ID=<CLUSTER_ID>

# CLI flag (highest priority)
tsuga --cluster <CLUSTER_ID> logs search
```

优先顺序: `--cluster` 国旗→ `TSUGA_CLUSTER_ID` 环境变量→ `defaults.cluster`。如果不设置，则单集群组织使用其集群；如果有多个集群，遥测和资源命令将失败，并列出要选择的集群。

## 使用

大多数资源遵循相同的CRUD模式：

```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>
```

也可以内联地传递JSON `-d`。命令从 `-f` 或者 `-d`，从不两者兼而有之；

```bash
tsuga teams create -d '{"name": "platform", "visibility": "public"}'
```

### 分页

`list` 默认情况下返回前100项。接受分页资源 `--limit` （最多1000）和 `--offset`：

```bash
tsuga monitors list --limit 500
tsuga monitors list --limit 500 --offset 500

# Follow every page and print one list
tsuga monitors list --all
```

当页面留下了项时，CLI打印一个通知 **stderr** 叶子是 纯JSON，所以 `| jq` 和 `-o csv` 不受影响:

```
Showing 100 of 4212 (offset 0). Use --limit (max 1000) and --offset 100 for the next page.
```

对于具有服务器端过滤器的资源，缩小查询范围胜过对所有内容进行分页。

### 可用的资源

`adaptive-notification-rules`， `cloud-resources`， `custom-roles`， `dashboard-folders`， `dashboards`， `ingestion-api-keys`， `investigations`， `log-routes`， `metric-routes`， `monitor-folders`， `monitors`， `notification-integrations`， `notification-rules`， `notification-silences`， `public-tokens`， `quality-reports`， `retention-policies`， `services`， `slos`， `tag-policies`， `team-memberships`， `teams`， `users`

> 注:
> 
> -   `ingestion-api-keys` 不支持 `get <ID>`.
> -   `services` 和 `users` 是只读的(`list`， `get`）。
> -   `cloud-resources` 只读，仅支持 `list`.
> -   `quality-reports` 是只读的并且支持 `list` 加上 `examples <ID>`.
> -   `team-memberships` 支持 `list`， `create` 和 `delete`. `delete` 需要一个 `{userId, teamId}` body而不是ID。
> -   `investigations` 是测试版：它需要一个操作API密钥与 `investigations` 权限和API可能会更改。
> -   `public-tokens` 管理在浏览器和移动sdk中配置的RUM公共令牌。的操作API密钥 **RUM公共代币** （`rum-public-token`)许可。

```bash
tsuga public-tokens create --generate-skeleton > app.json
# edit app.json
tsuga public-tokens create -f app.json | jq -r .token
tsuga public-tokens list | jq -r '.[0].token'
```

### 生成请求骨架

任何 `create` 或者 `update` 命令接受 `--generate-skeleton` 打印预期请求体的JSON模板：

```bash
tsuga monitors create --generate-skeleton
tsuga notification-rules update abc-123 --generate-skeleton
```

将输出管道输出到一个文件，将其填充，然后将其传递回 `-f`：

```bash
tsuga monitors create --generate-skeleton > monitor.json
# edit monitor.json
tsuga monitors create -f monitor.json
```

## 遥测

### 时间格式

使用等号表示负偏移量，例如 `--from=-1h`.

`--from` 和 `--to` 接受下列任何一项：

| 格式 | 例子 |
| --- | --- |
| 相对 | `-30m`， `-1h`， `-7d`， `-30s` |
| 现在 | `now` |
| Unix秒 | `1704067200` |
| ISO 8601 | `2024-01-01T00:00:00Z` |

从一个狭窄的窗口开始，只有当结果为空时才逐步扩大它。每个查询都在您的集群上运行，而广泛的未过滤扫描会减慢每个人的速度。

### 搜索日志

```bash
tsuga logs search --from=-1h --query 'level:ERROR'
tsuga logs search --from 1704067200 --to 1704153600 --query 'context.service.name:api'
```

```bash
# JSON array projected to selected fields (preserves nested objects)
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

# CSV with custom columns
tsuga logs search --from=-10m -o csv \
  --fields timestamp,level,message,context.k8s.pod.name
```

### 日志属性

```bash
tsuga logs attributes --from=-1h

# Only dot-paths containing "k8s", case-insensitively
tsuga logs attributes --from=-1h --search k8s
```

### 日志模式

```bash
# Group recent logs into patterns
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

# List error patterns whose volume increased for a team
tsuga logs error-pattern-increases --from=-24h --team my-team --env prod
```

### 搜索痕迹

```bash
tsuga traces search --from=-30m --query 'span.name:GET'

# TSV with default columns: start_time, duration, context.service.name, span.name, status_code, trace_id
tsuga traces search --from=-30m --query 'span.name:GET' -o tsv
```

### 搜索RUM事件

为查询字段加上它们所属的流(`measurements.`， `events.`，或者 `exceptions.`)，并在每个查询上过滤一个流。不带前缀字段的查询，包括 默认的 `*`，搜索 `events` 流:

```bash
tsuga rum search --from=-1h --query 'events.view.name:/checkout'
tsuga rum search --from=-1h --query 'exceptions.exception.type:*' --max-results 20
```

### 朗姆酒的属性

列出您可以查询的每个RUM属性：

```bash
tsuga rum attributes
```

两个RUM命令都需要操作API密钥 **朗姆酒的事件** （`rum`)读权限。

### 总结跟踪

将相似跨度的组聚合为合成的汇总跨度(标记为 `span_attributes.aggregation.is_summary`)以获得大轨迹的紧凑视图；

```bash
tsuga traces summarize --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m
```

### 跟踪延迟汇总

在跟踪中总结挂钟时间花费的位置：时间线的每个片段 归因于具有活动叶跨度的服务，每个服务的总数：

```bash
tsuga traces latency-summary --trace-id 78c99c5bb1e4a30297fa134b9dbec64f --from=-30m
```

### 对比组

将目标组的跨度与基线进行比较，并返回属性 在目标中被过度表示的值——这些跨度有什么共同点 而基线则不然。每个组都有自己的过滤器和时间范围。

过滤器是用TQL编写的，TQL与 `--query`。时间范围为Unix秒。 错误跨越健康的范围：

```bash
tsuga traces contrast-sets -d '{
  "targetGroup":   {"filter": "context.service.name:checkout status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}},
  "baselineGroup": {"filter": "context.service.name:checkout NOT status_code:error", "timeRange": {"from": 1704067200, "to": 1704070800}}
}'
```

运行 `tsuga traces contrast-sets --generate-skeleton` 获取完整的请求正文。

### 指标

```bash
# List metrics, sorted by name, one page at a time
tsuga metrics list --from=-1h --limit 500 --offset 1000

# List metrics whose name contains "http" (case-insensitive)
tsuga metrics list --from=-1h --search http

# Get a specific metric
tsuga metrics get my.metric.name --from=-1h

# List dashboards and monitors that use a metric
tsuga metrics assets-usage my.metric.name
```

## 聚合

使用JSON主体运行聚合查询：

```bash
tsuga aggregation scalar -f query.json
tsuga aggregation timeseries -f query.json
```

使用 `--generate-skeleton` 获取模板：

```bash
tsuga aggregation scalar --generate-skeleton > query.json
```

## 服务图

检查服务依赖关系图：

```bash
tsuga service-graph get <SERVICE_ID> --from=-1h --query 'env:prod'
```

## Kubernetes

通过遥测，探索整个组织中观察到的Kubernetes资源：

```bash
tsuga kubernetes pods --search my-service
tsuga kubernetes clusters
tsuga kubernetes nodes --search ip-10-0
tsuga kubernetes events --search my-pod
tsuga kubernetes pod-details --k8s-cluster prod --k8s-namespace default --pod-name my-pod-abc123
```

可用资源: `pods`， `clusters`， `namespaces`， `nodes`， `deployments`， `statefulsets`， `daemonsets`， `events` (列表，带有可选的 `--search`), `pod-details`， `pod-manifest`， `deployment-details` （单资源查找，需要标识标志）。

## 队列

列出从生产者和消费者消息传递范围推断出的消息队列，以及它们的发布、消费和消费者错误率：

```bash
tsuga queues list --env prod --stats-window 24h
tsuga queues get --name orders --messaging-system kafka --env prod
```

## 心意相通

在日志路由中使用示例日志行之前，测试grok解析规则：

```bash
tsuga grok parse --generate-skeleton > grok-test.json
# edit grok-test.json
tsuga grok parse -f grok-test.json
```

## PromQL

对指标后端运行一个PromQL查询。返回时间序列形状匹配 `tsuga aggregation timeseries`.

```bash
tsuga promql query --generate-skeleton > query.json
# edit query.json
tsuga promql query -f query.json
```

或内联:

```bash
tsuga promql query -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` 是以秒为单位的Unix时间戳。

## 连续的分析

```bash
# Rank functions by self (flat) and inclusive (cum) sample value, like `go tool pprof -top`
tsuga profiles top --service api --type cpu --from=-1h
tsuga 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 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
tsuga profiles query -d '{"service":"api","type":"cpu","timeRange":{"from":1704067200,"to":1704070800}}'
```

`--type` pprof示例类型是否为 `cpu`， `samples`， `wall`， `off_cpu`， `alloc_space`， `inuse_space`， `alloc_objects`， `inuse_objects`，或者 `goroutine`. `--filter` 对配置文件标签进行Tsuga查询；只接受标签相等、反和通配符。

## LLM遥测

配置本地Claude代码(`~/.claude/settings.json`)或法典(`~/.codex/config.toml`)将OpenTelemetry数据发送到Tsuga集群。需要OTLP基础URL和 [摄入API密钥](https://app.tsuga.com/settings/api-keys?ingestion=true) （与您的操作API密钥不同）。

```bash
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>
```

这两个选项也从env (`TSUGA_OTLP_ENDPOINT`， `TSUGA_INGESTION_API_KEY`）. 通过 `--no-include-prompts` 从遥测中剥离用户提示（默认：include）；为 `claude-code` 这也剥离了工具内容，但是 `codex` 只删除用户提示。之前的配置备份在文件旁边；重新启动任何运行 `claude` / `codex` 会议之后。

## LLM插件

```bash
tsuga install plugin claude-code
tsuga install plugin codex
```

添加了 `tsuga` 市场(`tsuga-dev/agent-plugins`)，并安装 `tsuga` 插件通过目标CLI (`claude` / `codex` 一定开着 `PATH`）. 对于《Claude Code》，它还开启了市场自动更新功能；通过 `--no-auto-update` 跳过。重新启动任何运行 `claude` / `codex` 会议之后。

## 分享链接

展开从Logs或Traces复制的短链接，或小部件共享链接，并解码其携带的查询、过滤器、时间范围、集群和Analytics设置。一个完整的 `app.tsuga.com` URL在没有API调用的情况下被本地解码：

```bash
tsuga unshorten https://app.tsuga.com/l/<CODE>
tsuga unshorten https://api.tsuga.com/v0/widget-shares/<ORG_ID>/<CODE>
tsuga unshorten 'https://app.tsuga.com/logs?query=level%3AERROR'
```

## 文档

搜索Tsuga文档和完整的API参考，然后通过path获取页面：

```bash
tsuga docs search 'log routes'
tsuga docs get explore/query-syntax
tsuga docs get api/aggregateScalar
```

## 反馈

报告与Tsuga工具或api的摩擦（失败的命令，不可用的输出，混乱的行为）：

```bash
tsuga feedback the traces command keeps timing out on large services
```

## 提示

默认输出是JSON，因此您可以管道到 `jq`：

```bash
tsuga dashboards list | jq '.[].name'
tsuga monitors list | jq '.[] | select(.priority == 1)'
```

从stdin中读取 `-f -`：

```bash
echo '{"name": "my-team", "visibility": "public"}' | tsuga teams create -f -
```

## 命令模式

`tsuga schema` 将命令树打印为JSON：命令路径、描述、位置参数和标志。

## 常见问题

### @tsuga/cli 是什么？

Tsuga CLI -从命令行管理资源

### 如何安装 @tsuga/cli？

在项目目录运行 npm install @tsuga/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tsuga，可以用 npx tsuga 直接运行。

### @tsuga/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/tsuga\_\_cli 是否存在。

### @tsuga/cli 可以商用吗？

@tsuga/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @tsuga/cli 还在维护吗？

最新版本 1\.121\.0 发布于 2026/11/03（今天）；至今共发布 141 个版本，其中过去 12 个月发布了 141 个；首次发布于 2026/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。