DevTools CLI 使用指南

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

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

围绕连接 Token 的功能
围绕本地推流方的功能
围绕本地收流方和浏览器预览的功能

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

如果你要对接正式业务服务端里的连接主线，再看连接。那篇文档讲的是设备端启动、服务端签发 Token 和客户端建连的完整闭环，不是 CLI 在开发联调期怎么用。

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

这篇文档适合谁

你想用 CLI 在开发联调阶段直接生成连接 Token
你想用 CLI 在本机启动一个推流方，让远端客户端来连你、拉你的流
你想用 CLI 在本机启动一个收流方，并在浏览器里直接预览远端音视频
你想在已有 Session 上继续发送命令、回复命令、发送流消息、导出日志和报告
你想先了解当前 CLI 已经公开了哪些能力，后面再按需深入某一条链路

当前功能列表

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

一、连接 Token 相关

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

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

二、推流方相关

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

功能	使用命令	说明
清理旧 host session	`host stop --all`	开始新一轮联调前先清场
生成配置模板	`init`	生成 TOML 模板
启动推流方	`service start`	基于 `[server]` 启动一个本地推流方
查看流状态	`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 的验收与排查信息

三、收流方和本地 Web 预览相关

这组能力用于在本机启动一个收流方，连接远端 remote_id，自动接收指定音视频流，并在浏览器里直接做本地预览。

功能	使用命令	说明
生成配置模板	`init`	生成 TOML 模板
启动收流方	`client start --token <token>`	基于 `[client]` 建立连接并自动挂载本地 Web 预览
查看流状态	`stream list`	确认当前 session 已声明接收哪些流
导出日志	`logs export`	导出当前 session 的运行日志
查看或导出报告	`report show`、`report export`	查看或导出当前 session 的验收与排查信息

第一步：安装 CLI

安装或更新最新版：

bash

npm install -g tirtc-devtools-cli@latest

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

bash

tirtc-devtools-cli --help

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

第一类功能：生成连接 Token

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

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

开始前准备

至少准备：

access_id
secret_key
remote_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 "<REMOTE_ID>"

如果你想先看帮助：

bash

tirtc-devtools-cli token issue --help

执行成功后，CLI 会输出：

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

可选参数

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

--local-id <localId>：不传时默认使用同一个目标 remote_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>

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

适合用在什么场景

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

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

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

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

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

先清理旧 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

执行完成后，当前目录会生成一个 TOML 文件。模板里会同时带上 [server] 和 [client] 两段；如果你当前只做推流方联调，只需要先把 [server] 填完整。

如果你想先看 init 的用法：

bash

tirtc-devtools-cli init --help

准备并填写配置

当前 service start 的正式路径只读取 [server]。启动前至少要准备：

一组可用的设备启动参数，也就是 device_id + device_secret_key 的组合；在这个 CLI 的配置字段里写作 license
一个本地 .mp4 文件
这个 MP4 文件的路径
一个音频 stream_id
一个视频 stream_id

例如：

text

/Users/yourname/media/source.mp4

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

audio_stream_id = 10
video_stream_id = 11

最小配置可以写成：

toml

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

这些字段的含义如下：

license：必填，运行这个推流端所需的设备启动组合字符串，对应 device_id + device_secret_key
mp4_path：必填，本地 MP4 文件路径
audio_stream_id：必填，音频流 ID
video_stream_id：必填，视频流 ID
service_entry：可留空，留空时走默认服务入口

填写时注意：

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 能看到你刚配置的音频流和视频流
当前终端没有持续滚动新的错误日志

日志默认位置

正式命令会把运行日志固定落到：

text

~/.tirtc-devtools-cli/logging/

这条路径由 CLI 自动管理，当前不需要在配置文件里单独填写 [logging]。

第三类功能：启动一个收流方，在本机浏览器预览远端音视频

这一类能力服务的是“在本机启动一个收流方，连接远端 remote_id，自动接收指定音视频流，并在浏览器里直接预览”。

适合场景包括：

在桌面环境快速验证远端推流是否能被拉到
在没有专门 App 的情况下，直接在浏览器里查看本地预览
做验收或排查时，把“连接是否成功”和“媒体是否真的到达”放到同一条本地链路里看

准备配置模板

先生成一份配置模板：

bash

tirtc-devtools-cli init ./client.toml

你也可以继续沿用已有 TOML，只要里面包含完整的 [client] 即可。

填写 `[client]`

client start 的正式路径只读取 [client]。最小配置如下：

toml

[client]
service_entry = ""
remote_id = "remote-123"
audio_stream_id = 10
video_stream_id = 11
consumer = "web_preview"

这些字段的含义如下：

remote_id：必填，要连接的目标端
audio_stream_id：必填，要接收的音频流 ID
video_stream_id：必填，要接收的视频流 ID
consumer：必填，当前固定写成 web_preview
service_entry：可留空，留空时走默认服务入口

填写时注意：

audio_stream_id 和 video_stream_id 不能相同
consumer 当前只能使用 web_preview
token 不写进配置文件，而是通过命令行 --token 显式传入

准备 Token

client start 需要一个显式传入的 token。这个 token 可以来自：

你的业务服务端
你用 tirtc-devtools-cli token issue 临时生成的一次性调试 token

如果你当前只是本地联调，常见做法是先执行：

bash

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

把输出里的 token 复制出来，给下一步使用。

启动收流方

配置和 token 都准备好后，执行：

bash

tirtc-devtools-cli --config ./client.toml client start --token "<TOKEN>"

如果你想先看帮助：

bash

tirtc-devtools-cli client --help
tirtc-devtools-cli client start --help

client start 固定会做这些事：

读取并校验 [client]
使用 --token 建立连接
自动声明音频和视频接收
自动挂载本地 Web 预览输出

所以使用者不需要再手工执行 connection connect、stream receive start 或 output attach。

打开浏览器预览

启动成功后，CLI 会返回本地预览入口。

如果你是脚本调用，建议加上 --json；这时预览地址位于：

text

data.result.autoApplied.preview.url

拿到这个地址后，直接在浏览器中打开即可。预览页会向本地预览服务发起启动请求，并开始拉取已经声明好的音视频流。

确认是否启动成功

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

bash

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

常见的成功信号有这些：

client start 返回了新的 sessionId
CLI 返回了可访问的本地预览地址
浏览器页面已经打开，并开始出现音视频预览

在已有 Session 上继续操作

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

除了 service start 和 client start 之外，其余命令都建议显式带上：

bash

--session <SESSION_ID>

发送命令

bash

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

参数含义：

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

说明：

command request 是当前 command 面的正式主语
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
cmdw
payloadEncoding
payload
receivedAt

再按 remoteRequestId 回复：

bash

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

说明：

同一个 remoteRequestId 只能成功回复一次
cmdw 必须与原始请求中的值一致，否则 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：消息流使用的 stream_id
heartbeat 2026-04-10T12:00:00Z：要发送的字符串内容

说明：

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

如果你想先看帮助：

bash

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

导出日志和报告

导出日志：

bash

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

查看报告：

bash

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

导出报告：

bash

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

如果你想先看帮助：

bash

tirtc-devtools-cli logs --help
tirtc-devtools-cli logs export --help
tirtc-devtools-cli report --help
tirtc-devtools-cli report show --help

常见失败与排查

Token 生成失败

优先检查：

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

`service start` 直接失败

优先检查：

license 字段是否为空或格式明显错误（它对应的是 device_id + device_secret_key 的组合字符串）
mp4_path 是否是本机真实可读的文件路径
audio_stream_id 和 video_stream_id 是否冲突
本机是否残留旧 host session；必要时先重新执行一次 host stop --all

`client start` 直接失败

优先检查：

是否显式传了 --token
[client] 是否已经填写目标 remote_id、audio_stream_id、video_stream_id
consumer 是否仍然是 web_preview
audio_stream_id 和 video_stream_id 是否误填成同一个值
remote_id、token 和 service_entry 是否属于同一条联调链路

`client start` 成功，但浏览器没有看到音视频

优先检查：

浏览器打开的是否就是 CLI 返回的那条预览地址
远端推流方是否真的已经开始发送对应的音视频流
收流方填写的 audio_stream_id、video_stream_id 是否与远端一致
浏览器是否因为自动播放策略而需要你手工点击播放或允许声音

后续命令执行失败

优先检查：

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

停止当前联调

联调结束后，执行：

bash

tirtc-devtools-cli host stop --all

如果你准备重新开始一轮新的联调，也建议先执行这条命令，再重新启动推流方或收流方。

常用帮助入口

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 client --help
tirtc-devtools-cli stream --help
tirtc-devtools-cli command --help
tirtc-devtools-cli logs --help
tirtc-devtools-cli report --help

DevTools CLI 使用指南 ​

这篇文档适合谁 ​

当前功能列表 ​

一、连接 Token 相关 ​

二、推流方相关 ​

三、收流方和本地 Web 预览相关 ​

第一步：安装 CLI ​

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

开始前准备 ​

生成 Token ​

可选参数 ​

适合用在什么场景 ​

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

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

先清理旧 session ​

生成配置模板 ​

准备并填写配置 ​

启动服务 ​

确认是否启动成功 ​

日志默认位置 ​

第三类功能：启动一个收流方，在本机浏览器预览远端音视频 ​

准备配置模板 ​

填写 [client] ​

准备 Token ​

启动收流方 ​

打开浏览器预览 ​

确认是否启动成功 ​

在已有 Session 上继续操作 ​

发送命令 ​

查看并回复远端命令 ​

发送流消息 ​

导出日志和报告 ​

常见失败与排查 ​

Token 生成失败 ​

service start 直接失败 ​

client start 直接失败 ​

client start 成功，但浏览器没有看到音视频 ​

后续命令执行失败 ​

停止当前联调 ​

常用帮助入口 ​

DevTools CLI 使用指南

这篇文档适合谁

当前功能列表

一、连接 Token 相关

二、推流方相关

三、收流方和本地 Web 预览相关

第一步：安装 CLI

第一类功能：生成连接 Token

开始前准备

生成 Token

可选参数

适合用在什么场景

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

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

先清理旧 session

生成配置模板

准备并填写配置

启动服务

确认是否启动成功

日志默认位置

第三类功能：启动一个收流方，在本机浏览器预览远端音视频

准备配置模板

填写 `[client]`

准备 Token

启动收流方

打开浏览器预览

确认是否启动成功

在已有 Session 上继续操作

发送命令

查看并回复远端命令

发送流消息

导出日志和报告

常见失败与排查

Token 生成失败

`service start` 直接失败

`client start` 直接失败

`client start` 成功，但浏览器没有看到音视频

后续命令执行失败

停止当前联调

常用帮助入口