DevTools CLI 使用指南

TiRTC DevTools CLI 面向开发联调、测试验收和现场排查。

在当前对外公开的能力里，CLI 主要分成两大类功能：

围绕连接 Token 的功能
围绕创建一个推流方、用于辅助客户端联调的功能

这两类都服务于开发联调阶段，不是正式业务服务端接入文档。

如果你要对接正式业务服务端里的 Token 签发逻辑，再看获取连接 Token。那篇文档讲的是业务服务端该如何实现签发，不是 CLI 在开发联调期怎么用。

TiRTC DevTools CLI 适合开发、联调和验收阶段，不适合作为正式生产服务。

这篇文档适合谁

你想用 CLI 在开发联调阶段直接生成连接 Token
你想用 CLI 在本机启动一个 Server 或推流 Session
你想在已有 Session 上继续发送命令、回复命令、发送流消息、导出日志和报告
你想先了解当前 CLI 已经公开了哪些能力，后面再按需深入某一条链路

当前功能列表

当前 CLI 已公开的能力，建议先按下面两组理解。

一、连接 Token 相关

这组能力用于在开发联调期间，快速给客户端或体验端生成连接 Token。

功能	使用命令	说明
生成连接 Token	`token issue`	从环境变量或显式参数读取 access/secret，为指定 `peer_id` 生成 Token
生成二维码	`token issue`	成功后同时输出控制台 ASCII 二维码和本地 PNG 路径
组合连接信息	`token issue --service-entry ...`	可把 `service_entry` 组合进 payload 和二维码

二、创建推流方并辅助客户端联调

这组能力用于在本机启动一个推流方，让客户端接入它、拉取它的音视频流，并继续围绕这条联调链路做命令、流消息、日志和报告操作。

功能	使用命令	说明
清理旧 host session	`host stop --all`	开始新一轮联调前先清场
生成配置模板	`init`	生成 `server.toml` 模板
启动推流方	`service start`	基于配置启动一个本地推流方
查看流状态	`stream list`	确认当前流是否已经挂到 session
发送命令	`command request`	主动向远端发送命令请求
查看待回复命令	`command pending list`	查看当前 session 内待处理的远端命令
回复远端命令	`command reply`	按 `remoteRequestId` 显式回复
发送流消息	`stream message send`	发送轻量字符串型 stream message
导出日志	`logs export`	导出当前 session 的运行日志
查看或导出报告	`report show`、`report export`	查看或导出当前 session 的验收与排查信息

后续如果 CLI 补充了上传日志拿 log_id、诊断等能力，也应继续按这两大类或其近邻能力组往下扩，不要打散成没有骨架的命令堆。

第一步：安装 CLI

安装或更新最新版：

bash

npm install -g tirtc-devtools-cli@latest

安装完成后，先确认当前机器上的 CLI 可以正常工作：

bash

tirtc-devtools-cli --help

如果能正常打印帮助菜单，说明 CLI 已经安装成功。

第一类功能：生成连接 Token

这一类能力服务的是“开发联调期间，快速拿到一个可用的连接 Token 和二维码”。

它不等于正式业务服务端签发方案，但在本地联调、Android 双端体验、临时给某个设备生成连接信息时非常有用。

开始前准备

至少准备：

access_id
secret_key
peer_id

推荐先把 access_id 和 secret_key 放进环境变量：

bash

export TIRTC_CONN_ACCESS_ID="<ACCESS_ID>"
export TIRTC_CONN_SECRET_KEY="<SECRET_KEY>"

生成 Token

执行：

bash

tirtc-devtools-cli token issue "<PEER_ID>"

如果你想先看帮助：

bash

tirtc-devtools-cli token issue --help

执行成功后，CLI 会输出：

peer_id
token
控制台里的 ASCII 二维码
本地二维码 PNG 路径

可选参数

按当前公开帮助，token issue 还支持这些常用选项：

--local-id <localId>：不传时默认使用同一个 peer_id
--service-entry <entry>：用于组合连接 payload 和二维码 PNG
--user-ttl-seconds <seconds>
--channel-ttl-seconds <seconds>
--qr-error-correction-level <L|M|Q|H>
--ascii-max-columns <columns>

如果你只是做最小联调，默认只传 <PEER_ID> 通常就够了。

适合用在什么场景

本地联调时，临时给某个 peer_id 生成连接 Token
Android 双端体验时，快速拿一个可扫码的连接信息
排查客户端连接问题时，先排除“是不是连最小 Token 都拿不到”

什么时候不要把它当成最终方案

当你要建设正式业务服务端签发逻辑时，不要直接把 CLI 调用当成产品接入方案
正式方案仍应回到获取连接 Token 那条业务服务端文档

第二类功能：创建一个推流方，用于辅助客户端联调

这一类能力服务的是“在本机启动一个推流方，让客户端来连它、拉它的流，然后继续围绕这条联调链路做操作”。

先清理旧 session

开始一轮新的联调前，建议先清场：

bash

tirtc-devtools-cli host stop --all

这样可以清掉当前机器上残留的 host session，避免旧服务影响新的 service start。

如果你想先看帮助：

bash

tirtc-devtools-cli host --help
tirtc-devtools-cli host stop --help

生成配置模板

启动服务前，先生成一份配置模板：

bash

tirtc-devtools-cli init ./server.toml

执行完成后，当前目录会生成一个 server.toml 文件。

如果你想先看 init 的用法：

bash

tirtc-devtools-cli init --help

准备并填写配置

当前 service start 的 server-only 正式路径使用本地 MP4 作为媒体来源，所以启动前至少要准备：

一个可用的 license
一个本地 .mp4 文件
这个 MP4 文件的绝对路径
一个音频 streamId
一个视频 streamId

例如：

text

/Users/yourname/media/source.mp4

如果你正和 Android 体验端联调，默认通常可直接使用：

audio_stream_id = 10
video_stream_id = 11

至少把 [server] 和 [logging] 填成下面这样：

toml

[server]
service_entry = ""
license = "runtime-license"
mp4_path = "/absolute/path/to/source.mp4"
audio_stream_id = 10
video_stream_id = 11

[logging]
root_dir = "./.tmp/tirtc-devtools-cli/logging"
console_mirror = true
level = "info"

这些字段的含义如下：

license：必填，运行这个推流端所需的 license
mp4_path：必填，本地 MP4 文件的绝对路径
audio_stream_id：必填，音频流 ID
video_stream_id：必填，视频流 ID
service_entry：可留空，留空时走底层默认值
logging.root_dir：日志根目录
logging.console_mirror：是否把 Host 控制台日志同时打印到当前终端，建议设为 true

填写时注意：

mp4_path 必须指向真实存在、当前机器可读的 .mp4 文件
建议直接填写绝对路径，不要依赖相对路径
audio_stream_id 和 video_stream_id 不能相同
如果你不确定 service_entry，先留空

启动服务

配置完成后，执行：

bash

tirtc-devtools-cli --config ./server.toml service start

如果你想先看帮助：

bash

tirtc-devtools-cli service --help
tirtc-devtools-cli service start --help

service start 固定会做这些事：

读取并校验 [server]
基于 mp4_path 自动准备本地媒体资产
启动一个 service session
自动把音频流和视频流挂到当前 session

所以使用者不需要额外手工执行 media assets prepare，也不需要自己再补 stream send start。

确认是否启动成功

启动成功后，CLI 会返回一个 sessionId。这个 sessionId 很重要，因为后续大多数操作都要显式带上它。

如果想确认当前流状态，执行：

bash

tirtc-devtools-cli --session <SESSION_ID> stream list

如果你想先看帮助：

bash

tirtc-devtools-cli stream --help
tirtc-devtools-cli stream list --help

这一阶段最常见的成功信号有三个：

service start 返回了 sessionId
stream list 能看到你刚配置的音频流和视频流
当前终端没有持续滚动新的错误日志

在已有 Session 上继续操作

拿到 sessionId 之后，可以继续做命令通道、流消息、状态查看、日志导出和报告查看。

发送命令

bash

tirtc-devtools-cli --session <SESSION_ID> command request 7953 utf8 "time?" --timeout-ms 15000

参数含义：

7953：命令 ID
utf8：payload 编码方式
time?：要发送的字符串 payload
--timeout-ms 15000：等待响应的超时时间，单位毫秒

说明：

command request 是当前 command 面的 canonical 主语
command send 仍可用，但只是兼容别名
如果你要发送 JSON，可以把 JSON 文本直接作为 payload 传入

如果你想先看帮助：

bash

tirtc-devtools-cli command --help
tirtc-devtools-cli command request --help

查看并回复远端命令

先查看当前待处理命令：

bash

tirtc-devtools-cli --session <SESSION_ID> command pending list

返回结果里至少会包含：

remoteRequestId
commandId
payloadEncoding
payload
receivedAt

再按 remoteRequestId 回复：

bash

tirtc-devtools-cli --session <SESSION_ID> command reply 42 7953 utf8 "cli reply payload"

说明：

同一个 remoteRequestId 只能成功回复一次
commandId 必须与原始请求中的值一致，否则 CLI 会失败

如果你想先看帮助：

bash

tirtc-devtools-cli command pending list --help
tirtc-devtools-cli command reply --help

发送流消息

bash

tirtc-devtools-cli --session <SESSION_ID> stream message send 12 "heartbeat 2026-04-10T12:00:00Z"

参数含义：

12：消息流使用的 streamId
heartbeat 2026-04-10T12:00:00Z：要发送的字符串内容

说明：

streamId 应使用双方约定好的消息流 ID
不要直接复用音频流或视频流 ID，除非对端就是这样定义的

如果你想先看帮助：

bash

tirtc-devtools-cli stream --help
tirtc-devtools-cli stream message --help
tirtc-devtools-cli stream message send --help

查看日志和报告

1. 直接看终端输出

如果配置里保留：

toml

[logging]
console_mirror = true

那么 Host 的运行日志会直接镜像到你当前启动 CLI 的终端里。

2. 导出日志文件

bash

tirtc-devtools-cli --session <SESSION_ID> logs export ./host-logs.zip

如果你想先看帮助：

bash

tirtc-devtools-cli logs --help
tirtc-devtools-cli logs export --help

3. 查看或导出报告

bash

tirtc-devtools-cli --session <SESSION_ID> report show

bash

tirtc-devtools-cli --session <SESSION_ID> report export ./report.json

如果你想先看帮助：

bash

tirtc-devtools-cli report --help
tirtc-devtools-cli report show --help

常见失败与排查

Token 生成失败

优先检查：

TIRTC_CONN_ACCESS_ID 和 TIRTC_CONN_SECRET_KEY 是否已经配置
peer_id 是否填写正确
如果你传了显式 TTL、service_entry 或其他参数，是否有明显拼写错误

`service start` 直接失败

优先检查：

license 是否为空或明显错误
mp4_path 是否是本机真实可读的绝对路径
audio_stream_id 和 video_stream_id 是否冲突
本机是否残留旧 host session；必要时先重新执行一次 host stop --all

`service start` 成功，但客户端拉不到音视频

优先检查：

客户端和服务端使用的 streamId 是否一致
客户端使用的 Token、peer_id、连接参数是否正确
终端镜像日志里是否出现连接成功但媒体未请求、或请求了错误 stream id 的线索

后续命令执行失败

优先检查：

命令是否显式带了 --session <SESSION_ID>
当前 sessionId 是否就是这次 service start 刚返回的那个值
如果是 command reply，remoteRequestId 和 commandId 是否与原始请求一致

停止当前联调

联调结束后，执行：

bash

tirtc-devtools-cli host stop --all

如果你准备重新开始一轮新的联调，也建议先执行这条命令，再重新 service start。

常用帮助入口

tirtc-devtools-cli --help
tirtc-devtools-cli token issue --help
tirtc-devtools-cli host --help
tirtc-devtools-cli init --help
tirtc-devtools-cli service --help
tirtc-devtools-cli stream --help
tirtc-devtools-cli command --help
tirtc-devtools-cli logs --help
tirtc-devtools-cli report --help

DevTools CLI 使用指南 ​

这篇文档适合谁 ​

当前功能列表 ​

一、连接 Token 相关 ​

二、创建推流方并辅助客户端联调 ​

第一步：安装 CLI ​

第一类功能：生成连接 Token ​

开始前准备 ​

生成 Token ​

可选参数 ​

适合用在什么场景 ​

什么时候不要把它当成最终方案 ​

第二类功能：创建一个推流方，用于辅助客户端联调 ​

先清理旧 session ​

生成配置模板 ​

准备并填写配置 ​

启动服务 ​

确认是否启动成功 ​

在已有 Session 上继续操作 ​

发送命令 ​

查看并回复远端命令 ​

发送流消息 ​

查看日志和报告 ​

1. 直接看终端输出 ​

2. 导出日志文件 ​

3. 查看或导出报告 ​

常见失败与排查 ​

Token 生成失败 ​

service start 直接失败 ​

service start 成功，但客户端拉不到音视频 ​

后续命令执行失败 ​

停止当前联调 ​

常用帮助入口 ​

DevTools CLI 使用指南

这篇文档适合谁

当前功能列表

一、连接 Token 相关

二、创建推流方并辅助客户端联调

第一步：安装 CLI

第一类功能：生成连接 Token

开始前准备

生成 Token

可选参数

适合用在什么场景

什么时候不要把它当成最终方案

第二类功能：创建一个推流方，用于辅助客户端联调

先清理旧 session

生成配置模板

准备并填写配置

启动服务

确认是否启动成功

在已有 Session 上继续操作

发送命令

查看并回复远端命令

发送流消息

查看日志和报告

1. 直接看终端输出

2. 导出日志文件

3. 查看或导出报告

常见失败与排查

Token 生成失败

`service start` 直接失败

`service start` 成功，但客户端拉不到音视频

后续命令执行失败

停止当前联调

常用帮助入口