TGLab-CLI

TGLab-CLI is a headless RAPID runtime client. It runs one device playback session, uploads runtime logs, and writes a machine-readable result with the uploaded log_id.

The npm package name is tglab-cli because npm package names cannot contain uppercase characters. The command name is TGLab-CLI.

Prepare Native Runtime

Run from the repository root:

./headless/script/prepare_native.sh

The script builds the runtime SDK, stages headers and libraries into headless/native/<platform>/, and builds the C++ runner into headless/native/<platform>/bin/tglab-headless-runner.

headless/native/ is generated and ignored by git.

Run

node headless/cli/bin/TGLab-CLI.js run \
  --app-id "<APP_ID>" \
  --package-name "<PACKAGE_NAME>" \
  --device-id "<DEVICE_ID>" \
  --token "<ACCESS_TOKEN>" \
  --duration-ms 300000 \
  --json

Or use debugging auth:

node headless/cli/bin/TGLab-CLI.js run \
  --device-id "<DEVICE_ID>" \
  --debugging-code "<CODE>" \
  --duration-ms 300000 \
  --json

Default output paths are relative to the current working directory:

• Artifacts: ./tglab-cli/artifact
• Runtime logging: ./.tglab-cli/logging

--device-id is always required. --app-id and --package-name are required only when --token is used. Debugging auth gets app metadata from the debugging code.

Runtime console logging is disabled by default. Pass --console-logging to enable it.

On macOS, audio output uses the runtime's real AudioQueue aout, matching Studio's playback path. If AudioQueue creation fails, the runner falls back to silence aout. Video output remains mocked by the silence vout.

The CLI also exposes the Flutter sample playback switches that map to runtime C APIs:

• --tgrtc-debugging: RAPID_Core_Pipe_TGRTC_EnableDebugging(1)
• --tgrtc-tcp-mode: RAPID_Core_PipeProxy_SetTransportMode(pipe, 1)
• --stream-debugging: RAPID_Core_Stream_EnableDebugging(1)
• --audio-only: RAPID_MediaPlayer_EnableVout(player, 0)
• --clock-mode audio|video: RAPID_MediaPlayer_SetClockMode(...)

Result

The command prints JSON to stdout and writes the same payload to <artifact-root>/result.json.

{
  "code": 0,
  "message": "OK",
  "data": {
    "reason_code": "ok",
    "log_id": "353/0602-1530",
    "raw_log_id": "/app-log/353/0602-1530.zip",
    "artifact_root": "/path/to/tglab-cli/artifact",
    "result_path": "/path/to/tglab-cli/artifact/result.json"
  }
}

Scope

The first version does not diagnose playback quality locally. Automation should consume log_id and run existing log analysis tools as the next step.

Release

The first npm version is 0.0.1. The npm package name is tglab-cli; the installed command is TGLab-CLI.

Run a dry-run release first:

./headless/script/release_tglab_cli.sh --version 0.0.1 --dry-run

The release script stages native runtime assets, runs the CLI smoke check, creates an npm tarball under headless/.build/release/, and verifies that the tarball contains the runner and unified runtime libraries.

Publish uses the same authentication shape as the Matrix CLI release wrapper: set NPM_TOKEN, then let the script create a temporary npmrc for the npmjs registry.

export NPM_TOKEN="<npm_token>"
./headless/script/release_tglab_cli.sh --version 0.0.1 --publish --yes

The default release platform is the host platform. macOS arm64 is the initial supported package target. Linux x64 can be added once the native bundle is built and verified in the same release flow:

TGLAB_RELEASE_PLATFORMS="macos-arm64 linux-x64" \
  ./headless/script/release_tglab_cli.sh --bump minor --dry-run