云听 CEM CLI 使用指南 - 安装、认证与命令参考

Overview

为什么使用 YTCEM CLI？

人机友好

同一套命令同时支持终端用户、脚本、CI 和 AI Agent。

结构化输出

默认输出 JSON，可使用稳定字段、Schema 和进程退出码进行自动化判断。

异步任务闭环

支持创建查询、等待结果、恢复轮询，以及下载并校验 CSV 文件。

凭证安全

OAuth Token 和持久化 API Key 保存在操作系统安全凭证存储中。

功能目录

ytcem-cli
├── auth
│   ├── login                 登录
│   ├── status                查看登录状态
│   └── logout                退出登录
├── config
│   ├── show                  查看当前配置
│   └── reset                 重置配置
├── project
│   ├── list                  查看可访问的项目
│   ├── data-types            查看项目数据类型
│   ├── topics                查看项目 Topic
│   ├── topic-values          查看 Topic 可选值
│   ├── tag-trees             查看项目标签树
│   └── tag-tree-details      查看标签树详情
├── message
│   └── query                 创建消息查询任务
├── task
│   ├── status                查看任务状态
│   ├── result                查看任务结果元数据
│   └── download              下载 CSV 结果
├── doctor                    检查配置、凭证、网络和版本兼容性
└── version                   查看 CLI 版本

Install

安装与快速开始

环境要求

Node.js 18 或更高版本，仅安装时需要。
当前支持平台：macOS arm64。
安装后的 ytcem-cli 是独立可执行文件，日常使用不依赖 Node.js。

安装 CLI

# 安装最新版本的 CEM CLI
npx --registry=https://nexus.ops.skieer.com/repository/npm-hosted-public/ \
  @cem/ytcem-cli@latest install

按需安装 CLI Skill

# 安装到全局 Agent 环境
npx --registry=https://nexus.ops.skieer.com/repository/npm-hosted-public/ \
  @cem/ytcem-cli-skill@latest install

# 安装到指定目录
npx --registry=https://nexus.ops.skieer.com/repository/npm-hosted-public/ \
  @cem/ytcem-cli-skill@latest install \
  --install-dir /指定目录/ytcem-cli

登录并确认状态

# 使用企业域名发起浏览器 OAuth 登录
ytcem-cli auth login --tenant-domain cem.example.com

# 查看当前登录状态
ytcem-cli auth status --output json

CI、脚本和无法打开浏览器的 Agent 应使用 API Key，参见下方“认证”。

Command discovery

命令结构与发现

命令统一采用 ytcem-cli <业务域> <动作> [参数]。业务域和动作使用小写英文，多个单词使用连字符，例如 data-types、topic-values、tag-tree-details。

# 查看当前账号可访问的项目
ytcem-cli project list

# 使用 JSON 文件创建消息查询任务
ytcem-cli message query --input ./query.json --idempotency-key RUN_KEY_001

# 查询指定异步任务的状态
ytcem-cli task status --task-id TASK_ID

# 查看全部业务域
ytcem-cli --help

# 查看 project 业务域下的动作
ytcem-cli project --help

# 查看 message query 的参数说明
ytcem-cli message query --help

# 离线查看全部命令目录
ytcem-cli --schema

# 离线查看 message 业务域的命令目录
ytcem-cli message --schema

# 离线查看 message query 的输入输出 Schema
ytcem-cli message query --schema

业务域	命令	用途
认证	`auth login / status / logout`	登录、查看状态和退出登录
配置	`config show / reset`	查看或重置当前配置
项目	`project list / data-types / topics`	发现项目及查询项目结构
项目	`project topic-values / tag-trees / tag-tree-details`	查询 Topic 取值和标签树
消息查询	`message query`	创建消息查询任务
任务	`task status / result / download`	查询任务并下载 CSV
诊断	`doctor / version`	检查配置、网络和版本

Authentication

认证

浏览器登录

# 交互式输入企业域名并发起浏览器 OAuth 登录
ytcem-cli auth login

# 通过命令参数指定企业域名并登录
ytcem-cli auth login --tenant-domain cem.example.com

# 为当前 Shell 设置默认企业域名
export CEM_TENANT_DOMAIN=cem.example.com

# 使用环境变量中的企业域名登录
ytcem-cli auth login

企业域名只用于构造租户授权页面地址，不会改变 Gateway 或业务 API 地址。

非交互环境不能使用浏览器 OAuth，请使用 API Key 登录方式。

API Key 登录

通过 stdin 提供 API Key，避免凭证进入命令历史。

ytcem-cli auth login --api-key-stdin --output json

查看或清除凭证

# 查看当前凭证状态
ytcem-cli auth status

# 删除当前保存的凭证
ytcem-cli auth logout

Global options

公共参数

参数	用途
`--output json`	输出结构化 JSON，默认格式。
`--output table`	输出适合终端阅读的表格。
`--schema`	离线查看命令目录或输入输出 Schema。
`--non-interactive`	禁止交互输入和动态输出。
`--debug`	将脱敏诊断信息输出到 stderr。
`--ca-file <path>`	为当前命令指定 CA 证书。
`--help`	查看帮助。

脚本、CI 和 AI Agent 建议显式使用 --output json，并同时检查 outcome 和进程退出码。

Projects

项目查询

# 查看当前账号可访问的项目
ytcem-cli project list

# 查看指定项目支持的数据类型
ytcem-cli project data-types --project-id PROJECT_ID

# 查看指定项目的 Topic 列表
ytcem-cli project topics --project-id PROJECT_ID

# 查看指定 Topic 的可选值
ytcem-cli project topic-values \
  --project-id PROJECT_ID \
  --topic-name TOPIC_NAME

# 查看指定项目的标签树列表
ytcem-cli project tag-trees --project-id PROJECT_ID

# 按名称查看指定标签树的详情
ytcem-cli project tag-tree-details \
  --project-id PROJECT_ID \
  --tree-name CUSTOMER_TAGS

Message query

消息查询

消息查询至少需要项目 ID、数据类型、开始时间、结束时间和幂等键。

ytcem-cli message query \
  --project-id PROJECT_ID \
  --data-type COMMENT \
  --start-time 2026-01-01T00:00:00+08:00 \
  --end-time 2026-01-31T23:59:59+08:00 \
  --idempotency-key comment-202601 \
  --output json

查询参数

参数	用途
`--source <name>`	按消息来源筛选。
`--topic name=value1,value2`	按 Topic 筛选，可以重复。
`--emotion <value>`	按情感筛选，支持 POSITIVE、NEGATIVE、NEUTRAL、MIXED。
`--limit <n>`	最大返回行数，默认 5000。
`--wait`	等待任务完成。
`--timeout <duration>`	等待时间，默认 30 分钟，必须和 `--wait` 一起使用。
`--dry-run`	只校验参数，不创建任务，不能和 `--wait` 一起使用。
`--input <file>` 或 `--input -`	从 JSON 文件或 stdin 读取条件。

筛选示例

ytcem-cli message query \
  --project-id PROJECT_ID \
  --data-type COMMENT \
  --start-time 2026-01-01T00:00:00Z \
  --end-time 2026-01-31T23:59:59Z \
  --topic brand=BrandA,BrandB \
  --emotion NEGATIVE \
  --idempotency-key negative-202601 \
  --wait

JSON 输入

{
  "project_id": "PROJECT_ID",
  "data_type": "COMMENT",
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-01-31T23:59:59Z",
  "filters": {
    "source": "taobao",
    "emotion": "NEGATIVE",
    "topics": [{"name": "brand", "values": ["BrandA", "BrandB"]}]
  },
  "limit": 5000,
  "output_format": "CSV"
}

ytcem-cli message query \
  --input ./query.json \
  --idempotency-key negative-202601

幂等键必须通过 --idempotency-key 提供，长度为 8–128 个字符。
同一个字段不能同时出现在 JSON 和命令参数中。
结果格式目前只支持 CSV，服务端会应用任务行数上限。

Tasks & download

任务与下载

# 查看指定任务的当前状态
ytcem-cli task status --task-id TASK_ID

# 查看指定任务的结果元数据
ytcem-cli task result --task-id TASK_ID

# 下载并校验指定任务的 CSV 结果
ytcem-cli task download \
  --task-id TASK_ID \
  --destination ./result.csv

下载前请确认任务已成功。目标文件不能已存在，CLI 会校验文件大小和 SHA-256。

Diagnostics

配置与诊断

# 查看解析后的非敏感配置
ytcem-cli config show

# 重置配置
ytcem-cli config reset --yes

# 检查本地配置、凭证和 Gateway 连通性
ytcem-cli doctor

# 查看当前 CLI 版本
ytcem-cli version

# 查看 CLI 版本并检查 API 兼容信息
ytcem-cli version --online

Output contract

输出与退出码

JSON 结果包含 schema_version、command、outcome、data、error、checkpoint、warnings、request_id 和 trace_id。

{
  "schema_version": "1",
  "command": "message.query",
  "outcome": "success",
  "data": {},
  "error": null,
  "checkpoint": null,
  "warnings": [],
  "request_id": null,
  "trace_id": null
}

0: 成功。
2: 参数或本地输入无效。
3: Context、CA 或配置无效。
4: 凭证缺失、无效、过期或安全存储不可用。
5: 已认证但无权限。
6: 业务或任务失败。
7: 网络、Gateway 或认证服务暂时不可用。
8: 等待超时，任务仍在运行。
9: 下载文件完整性校验失败。
10: CLI 与 API 版本不兼容。
130: 用户中断。

退出码 8 或 130 且已返回任务 ID 时，保存 checkpoint.task_id，之后继续查询：

ytcem-cli task status --task-id TASK_ID

Security

安全提醒

CLI 会尽量保护凭证，但命令、日志和下载文件仍需要由使用者按企业安全规范管理。

不要把 API Key 写入命令参数、查询文件、日志或聊天消息。
不要将查询结果下载到不可信目录，也不要随意分享下载文件。
--debug 会输出租户和请求诊断信息，分享日志前应先检查内容。
自动化调用应只解析 stdout 的 JSON、Schema 和退出码，不应依赖 stderr 文案。

数阔云听CEM

YTCEM CLI 使用指南