Skip to content

README.en.md

Latest commit

 

History

History
126 lines (87 loc) · 6.36 KB

README.en.md

File metadata and controls

126 lines (87 loc) · 6.36 KB
Raw

vertc

CI Release npm Go Version License: MIT

简体中文 | English

vertc is a CLI for Volcengine RTC projects. Developers and coding agents can use it to create, configure, run, and diagnose AI audio/video applications.

Current scope: voice-agent × web. More scenes and platforms will be added when their end-to-end flows are ready.

Install · Quick start · Core capabilities · Agent and CI · Security · Documentation

Install

Prebuilt binaries

Available for macOS, Linux, and Windows on amd64 and arm64. Installation requires Node.js 16 or later:

npm install -g @volcengine/rtc-cli
vertc version

The installer downloads the binary matching the npm package version and current platform from GitHub Releases, then verifies it against checksums.txt.

Build locally

Requires Go 1.25.12 or later:

git clone https://github.com/volcengine/VolcEngineRTC_CLI.git
cd VolcEngineRTC_CLI
make build
./bin/vertc version

Quick start

Before you start, make sure your Volcengine account has an RTC application. A conversational-AI agent is optional; if the account has none, dev uses the built-in default scene.

# 1. Create a project
vertc init ./my-agent --scene voice-agent --platform web
cd my-agent

# 2. Sign in to Volcengine
vertc auth login

# 3. Configure RTC resources and start the web app and local server
vertc dev

Open the URL printed in the terminal and click Start to join the room and talk. On the first run, vertc finds the RTC applications and conversational-AI agents in the account. It prompts only when there is more than one choice. If setup or runtime fails, run vertc doctor; it inspects the problem without changing the project.

See Voice-agent projects for the generated layout, runtime options, and identity management.

Core capabilities

  • Create and run projects — init creates a project from a pinned official template. dev configures Console resources and starts the web app and local server.
  • Diagnose problems — doctor reports PASS/WARN/SKIP/UNKNOWN/FAIL checks; explain-error looks up SDK and conversational-AI errors offline.
  • Read RTC documentation — docs search/fetch/list queries the live, read-only documentation endpoint without project configuration or signin.
  • Use it from agents and scripts — pipes and redirected output default to JSON, stdout contains data only, and failures return a stable error.code. Side-effecting commands support --dry-run.
  • Keep configuration and credentials separate — project metadata, runtime secrets, scene data, and Signin credentials use separate storage.

Common commands

Command Purpose
init [dir] --scene <scene> --platform <platform> List or scaffold supported project templates
auth login / auth status / auth logout Manage the Volcengine Signin session
dev [--web-port N] [--server-port N] [--auto-port] Configure RTC resources, check ports, and run the project
doctor [cli|project] Check CLI and project readiness without changing the project
explain-error <code> Look up SDK and conversational-AI errors offline
docs search/fetch/list Search, fetch, or browse RTC documentation
skills list/read/sync Inspect or synchronize the official Skill embedded in the current release
update [--check|--force] Check or update an npm-managed installation

Run vertc <command> --help for prerequisites, complete options, and examples.

Agent and CI

Install the official Skill:

npx skills add volcengine/VolcEngineRTC_CLI -g -y

To match the Skill to the current vertc version or repair an existing installation:

vertc skills sync

Agents and automation scripts should pass --format json explicitly so output does not depend on the terminal environment. stdout contains data only, while progress and warnings go to stderr. Failures return a non-zero exit code and a stable error.code. See Automation and structured output for headless authorization, non-interactive resource selection, error handling, and notification settings.

Configuration and security

  • vertc.config.yaml contains only non-secret project metadata and ${ENV} references.
  • .env.local contains local runtime values, is Gitignored, and is written with restricted permissions; never commit it.
  • Signin credentials are stored in the protected $VERTC_HOME/auth.json file by default. You can choose the operating-system keyring instead.
  • RTC_APP_KEY is never written to project configuration, VITE_* frontend variables, logs, command arguments, or structured output; never provide AppKey in chat.

See Automation and structured output for authentication modes, credential storage, and automation safety boundaries. See SECURITY.md for vulnerability reporting.

Documentation

Development and contributing

make build
make test
make ci

Read CONTRIBUTING.md before opening a pull request. This project is licensed under the MIT License.