TiRTC DevTools CLI Guide

TiRTC DevTools CLI is intended for development, integration, acceptance, and field troubleshooting.

This guide covers only two things:

how to start a local upstream endpoint for client-side integration and begin sending media
how to keep operating on the returned sessionId, including commands, stream messages, logs, and reports

If you only need to generate a connection token, read Get a Connection Token first. If you want AI to execute the post-token workflow for you, read Agent Skills.

TiRTC DevTools CLI is for development and debugging only. It should not be treated as a production service.

Before You Start

You already have a usable client-side connection token; if not, read Get a Connection Token
Your machine already has a valid license, a local MP4 file, and the absolute path of that MP4 file
You know which audio and video streamId values this integration uses
You are working in a development environment, not a production deployment environment

Who This Page Is For

You already have a license, a local MP4 file, and the token needed by the client side
You want to start a TiRTC server-side endpoint locally for integration or acceptance testing
You need to keep operating on an existing session, including commands, stream messages, log export, and troubleshooting

What a Minimal Integration Round Looks Like

A minimal round usually has only these steps:

Install the CLI
Clear old host sessions on the current machine
Generate and fill server.toml
Run service start and get a sessionId
Use that sessionId for follow-up actions such as command request, stream message send, and stream list
Export logs and reports when you need evidence
Run host stop --all when the round is over

The rest of this page follows that order.

Step 1: Install the CLI

Install or update:

bash

npm install -g tirtc-devtools-cli@latest

Then confirm that the CLI works on the current machine:

bash

tirtc-devtools-cli --help

If this prints the help menu, the CLI is installed correctly.

Step 2: Clear Old Sessions

Before starting a new integration round, clear the machine first:

bash

tirtc-devtools-cli host stop --all

This stops any leftover host sessions on the current machine so they do not interfere with the next service start.

Step 3: Generate a Config Template

Generate a minimal template:

bash

tirtc-devtools-cli init ./server.toml

This creates server.toml in the current directory.

Step 4: Prepare the Required Inputs

The current server-only service start path uses a local MP4 file as the media input. Prepare these before startup:

one valid license
one local .mp4 file
the absolute path of that MP4 file
one audio streamId
one video streamId

For example:

text

/Users/yourname/media/source.mp4

If you are integrating with the Android experience client, you can usually use these defaults directly:

audio_stream_id = 10
video_stream_id = 11

If the two sides do not match, the client cannot pull the expected audio or video stream.

Step 5: Fill `server.toml`

At minimum, fill [server] and [logging] like this:

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"

Field meanings:

license: required; the license used to run this server-side endpoint
mp4_path: required; the absolute path of the local MP4 file
audio_stream_id: required; the audio stream ID
video_stream_id: required; the video stream ID
service_entry: optional; leave it empty to use the underlying default
logging.root_dir: log root directory
logging.console_mirror: whether to mirror host console logs into the current terminal; true is recommended

Important checks:

mp4_path must point to a real readable .mp4 file
use an absolute path instead of relying on a relative path
audio_stream_id and video_stream_id must be different
if you do not know what service_entry should be, leave it empty

Step 6: Start the Upstream Endpoint

After the config is ready, run:

bash

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

service start automatically does the following:

reads and validates [server]
prepares local media assets from mp4_path
starts a service session
binds the audio and video streams to that session

You do not need to run media assets prepare manually, and you do not need to call stream send start yourself.

When startup succeeds, the CLI returns a sessionId. The rest of the workflow uses that sessionId.

Step 7: Confirm the Service Is Running

The most direct way is to inspect the current stream state:

bash

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

At this stage, the usual success signals are:

service start returned a sessionId
stream list shows the audio and video streams you configured
the current terminal is not continuously printing new errors

If service start fails, read the error in the current terminal first. If service start succeeds but the client still cannot integrate correctly, continue with the log and report checks below.

Continue Operating on the Upstream Session

After you get a sessionId, these are the most common commands.

1. Send a Command

bash

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

Parameter meanings:

7953: command ID
utf8: payload encoding
time?: payload text
--timeout-ms 15000: response timeout in milliseconds

If you need to send JSON, pass the JSON text directly as payload.

2. Inspect and Reply to Remote Commands

First inspect current pending requests:

bash

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

The result includes at least:

remoteRequestId
commandId
payloadEncoding
payload
receivedAt

Then reply by remoteRequestId:

bash

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

There are two important constraints:

the same remoteRequestId can only be replied to successfully once
the commandId must match the original request, or the CLI fails

3. Send a Stream Message

bash

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

12: the streamId used for the message stream
heartbeat 2026-04-10T12:00:00Z: the string payload

That streamId should be the agreed message stream ID. Do not reuse audio or video stream IDs unless your peer contract explicitly does that.

4. Inspect the Current Stream State Again

bash

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

This is useful before and after sending commands, after the client connects, and during acceptance checks.

Inspect Logs and Reports

Watch the Current Terminal

If your config keeps:

toml

[logging]
console_mirror = true

then host logs are mirrored directly into the terminal where you started the CLI.

Export Logs

bash

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

Show or Export the Current Report

bash

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

bash

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

Common Failures and Troubleshooting

`service start` fails immediately

Check these first:

whether license is empty or obviously wrong
whether mp4_path is a real readable absolute path on the current machine
whether audio_stream_id and video_stream_id conflict
whether old host sessions are still running; if needed, run host stop --all again

`service start` succeeds, but the client cannot receive audio or video

Check these first:

whether the client and server are using the same streamId values
whether the client token, peer_id, and connection parameters are correct
whether the mirrored terminal logs show a successful connection but no media request, or a request for the wrong stream ID

Follow-up commands fail

Check these first:

whether the command explicitly includes --session <SESSION_ID>
whether the current sessionId is the exact one returned by this service start
if the failure is on command reply, whether remoteRequestId and commandId match the original request

You need evidence for someone else to debug

At minimum, export both of these:

the log archive from logs export
the JSON report from report export

Stop the Current Round

When the round is over, run:

bash

tirtc-devtools-cli host stop --all

If you want to begin a fresh round, it is also a good idea to run this first and then start the service again.

Common Misunderstandings

after service start succeeds, follow-up commands usually need an explicit --session <SESSION_ID>
the current public workflow does not require you to run media assets prepare manually first
host stop --all clears all host sessions on the current machine, not just one session
this CLI is suitable for development and integration work, not as a production service entrypoint

Common Help Entrypoints

tirtc-devtools-cli --help
tirtc-devtools-cli host --help
tirtc-devtools-cli token issue --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

TiRTC DevTools CLI Guide ​

Before You Start ​

Who This Page Is For ​

What a Minimal Integration Round Looks Like ​

Step 1: Install the CLI ​

Step 2: Clear Old Sessions ​

Step 3: Generate a Config Template ​

Step 4: Prepare the Required Inputs ​

Step 5: Fill server.toml ​

Step 6: Start the Upstream Endpoint ​

Step 7: Confirm the Service Is Running ​

Continue Operating on the Upstream Session ​

1. Send a Command ​

2. Inspect and Reply to Remote Commands ​

3. Send a Stream Message ​

4. Inspect the Current Stream State Again ​

Inspect Logs and Reports ​

Watch the Current Terminal ​

Export Logs ​

Show or Export the Current Report ​

Common Failures and Troubleshooting ​

service start fails immediately ​

service start succeeds, but the client cannot receive audio or video ​

Follow-up commands fail ​

You need evidence for someone else to debug ​

Stop the Current Round ​

Common Misunderstandings ​

Common Help Entrypoints ​

TiRTC DevTools CLI Guide

Before You Start

Who This Page Is For

What a Minimal Integration Round Looks Like

Step 1: Install the CLI

Step 2: Clear Old Sessions

Step 3: Generate a Config Template

Step 4: Prepare the Required Inputs

Step 5: Fill `server.toml`

Step 6: Start the Upstream Endpoint

Step 7: Confirm the Service Is Running

Continue Operating on the Upstream Session

1. Send a Command

2. Inspect and Reply to Remote Commands

3. Send a Stream Message

4. Inspect the Current Stream State Again

Inspect Logs and Reports

Watch the Current Terminal

Export Logs

Show or Export the Current Report

Common Failures and Troubleshooting

`service start` fails immediately

`service start` succeeds, but the client cannot receive audio or video

Follow-up commands fail

You need evidence for someone else to debug

Stop the Current Round

Common Misunderstandings

Common Help Entrypoints