@vitex/tcm-cli

TCM 控制台命令行工具，面向 agent 使用。所有业务输入/输出都是 JSON，可直接被脚本或 agent 解析。

• 零运行时依赖，基于 Node.js 内置模块（Node ≥ 18.17）
• 常规 CLI 体验：help、子命令、--help、退出码
• login / logout / status 三个命令管理授权
• 授权信息保存在 ~/.tmc/auth.json，所有业务子命令从这里读取用户 Key

安装

# 发布后
npm install -g @vitex/tcm-cli

# 或本地开发
node bin/tcm.js --help

快速开始

# 登录：用户 Key 在控制台「系统 - 用户」里获取（uk_ 开头）
tcm login --key uk_xxxxxxxx --server https://tcm.example.com

# 也可以从 stdin 读取，避免 Key 进入 shell 历史
cat key.txt | tcm login --key - --server https://tcm.example.com

# 也可以用位置参数或环境变量
tcm login uk_xxxxxxxx
TCM_SERVER_URL=https://tcm.example.com tcm login --key uk_xxxxxxxx

# 查看当前登录状态
tcm status

# 调用后端接口
tcm machine list --statuses NORMAL --pageSize 20
tcm account get --id 12
tcm machine-job create --type EXEC --machineIds 1,2 --input '{"command":"ipconfig /all"}'

# 退出登录
tcm logout

授权

授权文件默认位于 ~/.tmc/auth.json（目录 0700、文件 0600），内容形如：

{
  "serverUrl": "https://tcm.example.com",
  "apiKey": "uk_xxxxxxxx",
  "user": { "id": 1, "teamId": 9, "name": "alice", "roles": ["ADMIN"] },
  "createdAt": "2025-01-01T00:00:00.000Z"
}

所有请求使用 Authorization: ApiKey <key>。服务端地址、Key、授权文件路径都可以临时覆盖：

| 环境变量 | 说明 | | --- | --- | | TCM_SERVER_URL | 服务端地址（默认 https://tcm.58corp.com/） | | TCM_API_KEY | 用户 Key | | TCM_AUTH_FILE | 授权文件路径（默认 ~/.tmc/auth.json） |

优先级：命令行参数 > 环境变量 > 授权文件 > 默认值。

全局选项

| 选项 | 说明 | | --- | --- | | --server <url> | 覆盖服务端地址 | | --key <key> | 覆盖用户 Key | | --auth-file <path> | 授权文件路径 | | --timeout <ms> | 请求超时毫秒数（默认 30000） | | --compact | 紧凑 JSON 输出（单行） | | --version, -V | 显示版本号 | | --help, -h | 显示帮助 |

输出与退出码

• 成功：将后端 ApiResponse.data 以 JSON 写到 stdout
• 失败：将错误以 JSON 写到 stderr，例如：

{
  "error": {
    "type": "ApiError",
    "message": "未登录或用户 Key 已失效",
    "code": 401,
    "status": 401,
    "data": null
  }
}

| 退出码 | 含义 | | --- | --- | | 0 | 成功 | | 1 | 业务/网络/授权错误（ApiError），或本地工具执行失败（ToolError，见下） | | 2 | 参数或用法错误（UsageError） |

业务失败（HTTP 200 但 code !== 1）与 HTTP 非 2xx 都会被视为失败。触发限流时后端返回 HTTP 429，错误的 data.retryAfterMs 给出建议重试等待毫秒数。

tool 分组下的命令在本地直接抓第三方页面（不经过 TCM 后端），失败时 type 为具体原因：

{ "error": { "type": "FetchError", "message": "抓取抖音页面失败（…）：HTTP 404", "status": 404 } }

| type | 含义 | | --- | --- | | FetchError | 网络失败 / 超时 / HTTP 非 2xx，带 status | | ParseError | 页面结构不符（视频不存在、被风控、抖音改版） |

参数约定

• 标量：--pageNum 1、--status NORMAL
• 数组：可重复或逗号分隔，也支持 JSON 数组
  • --statuses NORMAL,HIDDEN
  • --statuses NORMAL --statuses HIDDEN
  • --statuses '["NORMAL","HIDDEN"]'
• JSON 字段：传 JSON 字符串、@文件 或 -（stdin）
  • --input '{"command":"ls"}'
  • --input @input.json
• 文件上传（multipart）：传本地路径，如 --file ./a.png
• 布尔筛选：出现即为 true，例如 --verified
• 必填布尔值：显式写 true / false，例如 tcm comment update --folded false（--folded 这种开关写法表达不了 false）

命令一览

通用命令：

• tcm login — 使用用户 Key 登录并保存到 ~/.tmc/auth.json
• tcm logout — 退出登录并删除本地授权文件
• tcm status — 查看当前登录状态（--local 只读本地）

user — 用户

• tcm user list — 分页查询用户（管理员）
• tcm user me — 当前登录用户
• tcm user create — 新建用户
• tcm user update — 编辑用户
• tcm user api-key — 获取当前用户 API Key（旧 Key 立即失效）

workbench — 工作台统计

• account-cards、machine-cards
• accounts、comments、awemes、comment-records、comment-candidates、comment-likes、top-comments
• tasks、task-success-rate、task-type-trend、task-status-trend、task-type-share、task-status-share、task-error-top
• comment-overview-trend

统计接口一般需要 --startDate / --endDate；任务类接口还支持 --types、--status。

machine — 机器

list、get、create、update、status、names、summary、logs、statistics

机器对象带两个 IP 字段：ip 是内网 IP，publicIp 是 Agent 心跳时探测的公网出口 IP（探测失败为 null，不携带该字段的旧 Agent 也是 null）。machine list / machine get 与工作台 workbench machine-cards 都返回 publicIp；--keyword 只匹配 ip（内网）等文本字段，不能按 publicIp 搜索。

account — 账号

list、get、update、status、toggle-verify、brief、summary、logs、cookies

machine-job — 机器作业

list、create（EXEC / REBOOT / UPDATE / UPDATE_EXTENSION）

machine-task — 机器任务

list、cancel、abort、reset

extension-task — 插件任务

list、get、create、cancel、abort、reset

agent-artifact / extension-artifact — 制品

list、create、update、activate、statistics

author / aweme / comment / comment-candidate / hot-comment — 神评

• author：list、get、create、update、status、profile
• aweme：list、get、analysis
• comment：list、get、refresh、update
• comment-candidate：list、discard
• comment-strategy（仅管理员）：list、get、create、update、delete
• hot-comment：list

material / draft / item — 素材 / 草稿 / 作品

• material：list、get、create、update、upload
• draft：list、create、create-urls、discard
• item：list

tool — 本地取数工具

本地执行、直接抓第三方公开页面，不经过 TCM 后端、不需要登录、不写库。

• tcm tool seo_video_detail --id <awemeId> — 按视频 ID 取抖音 SEO 版视频页：视频（文案 / 封面 / 发布时间 / 时长 / 点赞 / 评论 / 收藏 / 分享）、达人（昵称 / secUid / 获赞 / 粉丝）、首屏 10 条评论
  • 也支持 --url <链接或分享文案>（短链会自动跟随跳转）与 --html <本地文件>（离线解析已保存的页面）
  • 点赞 / 收藏 / 分享来自页面展示文本（5.4万 → 54000），是近似值；评论数取 ld+json 的精确值
  • 只有首屏 10 条一级评论，没有视频直链 / 音乐 / 弹幕

# 按 ID
tcm tool seo_video_detail --id 7701278853448142120 --compact

# 按链接（分享文案也行）
tcm tool seo_video_detail --url https://www.douyin.com/video/7701278853448142120

# 离线重放（排查页面改版用）
tcm tool seo_video_detail --html ./page.html --compact

每个命令都支持 --help 查看完整参数，例如：

tcm machine list --help
tcm machine-job create --help

Agent 用法示例

# 获取第一页在线机器，单行 JSON
tcm machine list --health ONLINE --compact

# 批量创建执行作业
tcm machine-job create --type EXEC --machineIds 1,2,3 \
  --input '{"command":"systeminfo","timeoutSec":120}' --compact

# 组合筛选条件
tcm account list --statuses NORMAL --machineId 3 --compact

# 把作业输入写到文件再引用
tcm machine-job create --type EXEC --machineIds 1 --input @job.json