CLS CLI

Command-line tool for managing Tencent Cloud CLS: install, configure, search logs, manage topics, alarms, dashboards, machine groups, and collectors.

Security Scan

The CLI appears to implement the stated Tencent Cloud CLS functionality, but the skill metadata and runtime instructions are inconsistent about installation requirements and required credentials (sensitive keys), and the install/upgrade steps ask you to build and install a binary (potentially with sudo) from an external GitHub repo — so verify the source and keys before use.

Purpose & Capability

The code and SKILL.md implement a Tencent Cloud CLS CLI (API calls, topic/alarm/dashboard/collector functionality) which matches the declared purpose. However the skill metadata claims no required environment variables or credentials while both SKILL.md and the code clearly require Tencent Cloud SecretId/SecretKey (and optionally CLS_DEFAULT_REGION). This mismatch is incoherent and should be fixed or clarified.

Instruction Scope

SKILL.md instructs an installer to run git clone, go build and mv the built binary into /usr/local/bin (with sudo if necessary). It also instructs users/agents to provide Tencent Cloud API keys (or set env vars). The instructions do not direct reading unrelated system files or exfiltrating data, but they do require building and installing a binary from a third-party GitHub repo and advising sudo usage — actions that grant the installed binary local execution privileges.

Install Mechanism

There is no platform package; the runtime instructions clone https://github.com/trumphuang/CLS_CLI and build/install the binary locally. Using GitHub releases (the upgrade command queries api.github.com) is common and acceptable, but building and installing a binary from an external repo (and the code's upgrade routine that can overwrite the executable, possibly via sudo) is higher-risk than an instruction-only skill because arbitrary code will run on the host. The URLs are standard GitHub endpoints (not obscure), which reduces but does not eliminate risk.

Credentials

The tool legitimately needs Tencent Cloud API credentials to call CLS APIs; the code reads/writes config.json under ~/.cls-cli and honors env vars TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY, and CLS_DEFAULT_REGION. However the skill metadata declared no required env vars or primary credential, which is inconsistent and could mislead users into installing without realizing sensitive keys are needed and will be stored on disk.

Persistence & Privilege

The skill is not marked always:true. It installs a binary into /usr/local/bin and includes an upgrade command that can overwrite the executable (using sudo if needed). The binary will run with whatever permissions the invoking user grants; autonomous agent invocation is permitted by default — combine that with stored API keys only if you trust the skill and repository.

What to consider before installing

Before installing: (1) Recognize that this skill requires your Tencent Cloud SecretId/SecretKey (or env vars) and will store them under ~/.cls-cli/config.json unless you use env vars — provide only keys with least privilege. (2) The SKILL.md and code instruct cloning and building a GitHub repo (trumphuang/CLS_CLI) and installing a binary to /usr/local/bin (sudo may be suggested) — this runs arbitrary code on your machine; verify the GitHub repository, review the source, and prefer signed releases. (3) The skill metadata did NOT declare the required env vars or the need for Git/Go; treat that as an omission and be cautious. (4) If you want to test safely, build/run the binary in an isolated environment (container or VM), or inspect and compile the code yourself rather than blindly running the provided install line. (5) If you plan to let an AI agent call this skill autonomously, limit credentials and consider creating a scoped API key for CLS only. If you can get the official homepage/repo verification or a signed release from the author, that would raise confidence.

CLS CLI 安装与使用

一、安装（30秒）

直接执行以下命令，一行搞定：

git clone https://github.com/trumphuang/CLS_CLI.git /tmp/CLS_CLI && cd /tmp/CLS_CLI/cls-cli && go build -o cls-cli . && mv cls-cli /usr/local/bin/ && rm -rf /tmp/CLS_CLI && cls-cli version

前提：系统已安装 Git 和 Go 1.23+。如果 /usr/local/bin 需要权限，把 mv 改成 sudo mv。

验证安装成功：

cls-cli version
# 输出: cls-cli version 0.2.0 (darwin/arm64)

二、配置（10秒）

cls-cli config init --secret-id <SECRET_ID> --secret-key <SECRET_KEY> --region ap-guangzhou

用户需要提供腾讯云 API 密钥，获取地址：https://console.cloud.tencent.com/cam/capi

也支持环境变量（CI/CD 场景推荐）：

export TENCENTCLOUD_SECRET_ID=xxx
export TENCENTCLOUD_SECRET_KEY=xxx
export CLS_DEFAULT_REGION=ap-guangzhou

三、升级

cls-cli upgrade

---

四、使用教程

全局参数

任何命令都可以加：

参数	说明
--region ap-beijing	临时切换地域，不改配置文件
--format table	输出格式：json / pretty / table / csv
--dry-run	预览模式，不实际执行
-y	跳过危险操作确认

日志检索 log

cls-cli log +search --topic-id <id> --query "level:ERROR" --from "1 hour ago"
cls-cli log +context --topic-id <id> --pkg-id <pkg_id> --pkg-log-id <log_id>
cls-cli log +tail --topic-id <id> --query "*"
cls-cli log +histogram --topic-id <id> --query "*" --from "1 hour ago"
cls-cli log +download --topic-id <id> --query "*" --from "1 hour ago" --output logs.json

日志主题 topic

cls-cli topic +list
cls-cli topic +create --logset <logset_id> --name "my-topic" --ttl 30
cls-cli topic +info --topic <topic_id>
cls-cli topic +delete --topic <topic_id>
cls-cli topic +logsets                     # 列出日志集

告警管理 alarm

cls-cli alarm +list
cls-cli alarm +history --from "7 days ago"
cls-cli alarm +create --name "Error Alert" --topic <id> \
  --query "level:ERROR | SELECT COUNT(*) as cnt" \
  --condition '$1.cnt > 100' --period 5
cls-cli alarm +delete --alarm-id <id>
cls-cli alarm +notices                     # 列出通知渠道

仪表盘 dashboard（别名 dash）

cls-cli dash +list
cls-cli dash +info --id <dashboard_id>
cls-cli dash +create --name "运维总览"
cls-cli dash +update --id <id> --name "新名称"
cls-cli dash +delete --id <id>

机器组 machinegroup（别名 mg）

cls-cli mg +list
cls-cli mg +create --name web --type ip --values "10.0.0.1,10.0.0.2"
cls-cli mg +create --name web --type label --values "webserver"
cls-cli mg +status --id <group_id>
cls-cli mg +info --id <group_id>
cls-cli mg +delete --id <group_id>

采集配置 collector（别名 col）

cls-cli col +list
cls-cli col +create --name "app-logs" --topic <id> --type json \
  --path "/var/log/app" --file-pattern "*.log" --group-id <id>
cls-cli col +info --id <config_id>
cls-cli col +delete --id <config_id>
cls-cli col +guide                         # 采集入门指南

LogListener loglistener（别名 ll）

cls-cli ll +install                        # 生成安装脚本
cls-cli ll +init --region ap-guangzhou     # 初始化
cls-cli ll +start                          # 启动
cls-cli ll +stop / +restart / +status / +check / +uninstall

通用 API api

以上快捷命令未覆盖的操作，都可以用通用 API 调用（支持全部 150+ CLS API 3.0）：

cls-cli api <Action> --params '<JSON>'

# 示例
cls-cli api DescribeIndex --params '{"TopicId":"xxx"}'
cls-cli api CreateIndex --params '{"TopicId":"xxx","Rule":{...}}'

---

五、AI Agent 意图映射

当用户用自然语言描述需求时，按此表匹配命令：

用户说	执行
查日志 / 搜错误 / 看看有没有异常	log +search
看这条日志的上下文	log +context
实时看日志	log +tail
有哪些主题 / topic	topic +list
有哪些日志集	topic +logsets
看告警 / 最近有没有报警	alarm +list + alarm +history
创建告警	alarm +create
看仪表盘	dash +list
机器状态 / 哪些机器挂了	mg +status
配置采集	col +guide → 按指南操作
切地域查	加 --region ap-beijing
其他高级操作	api <Action>

六、常见地域

地域	代码
广州	ap-guangzhou
上海	ap-shanghai
北京	ap-beijing
成都	ap-chengdu
南京	ap-nanjing
香港	ap-hongkong
新加坡	ap-singapore
硅谷	na-siliconvalley