@voicethere/cli

@voicethere/cli talks to the VoiceThere control plane. Current npm cut: 0.14.5. Requires Node.js 22+. Source: voicethere/cli.

Default API: https://app.voicethere.io/api/v1. Override with --api-base or VOICETHERE_API_BASE. The OpenAPI contract is the same as the control plane API docs.

Install

npm install -g @voicethere/cli
voicethere --help
# or without a global install:
npx @voicethere/cli --help

Progress and resolved paths go to stderr as [voicethere] …. Stdout stays tables/JSON so scripts can capture --print-id. Add -v / VOICETHERE_VERBOSE=1 for API method, path, and timing (no secrets).

Release loop

Upload stores an immutable build. Promote marks it active in the control plane. Deploy rolls that build onto cloud runners. Skipping deploy leaves live pods on the previous bundle.

npx @voicethere/agent build
BUILD_ID=$(voicethere build upload -m "shorter silence timeout" --print-id)
voicethere deploy --wait --build-id "$BUILD_ID"

deploy --wait promotes if needed, then blocks until the rollout is active or failed. Use build promote alone when you only need the control-plane pointer (smoke tests).

Login

Interactive machines should run voicethere login (browser device approval). CI should pass --api-key. Credentials live in ~/.config/voicethere/credentials.json (mode 0600), never in the agent repo. Full flow, flags, and env precedence: CLI login.

Init and project config

voicethere init my-agent --template echo
cd my-agent
npm install
npm run verify

--template follows the product registry in @voicethere/agent (plus CLI-only blank). --local-only writes files without creating a cloud project. Template list.

The CLI remembers the active project in .voicethere/config.json (safe to commit — no API keys):

projects create writes this file. projects use switches it. projects show prints it. Without a config file, interactive terminals get a picker; CI must call projects use <id>.

Source and builds

voicethere source push          # upload local .ts / .json to the Code tab
voicethere source pull          # download cloud workspace (does not delete extras)
voicethere source download -o ./workspace.zip
voicethere build validate
voicethere build upload -m "fix barge-in" --print-id
voicethere build list
voicethere build promote
voicethere build download -o ./agent.js          # active or newest passed
voicethere build download --build-id <uuid> -o ./agent.js

source download writes a zip of the saved Code-tab workspace. build download writes the compiled agent.js. Both accept --project when you are not in a linked repo. Dashboard Code tab and Overview history expose the same downloads. Code editor.

Deploy

voicethere deploy --wait
voicethere deploy --wait --build-id "$BUILD_ID"
voicethere undeploy

Settings that freeze into the runner env (idle timeout, voice vendors, warm pool, secrets) take effect on the next successful deploy. The overview Cloud rollout panel warns when saved config drifted from the last deploy.

Command catalog

projects session-settings --help prints keys, defaults, and ranges. Changes apply on the next deploy --wait. See idle timeout, billing, embed widget.

CI

voicethere login --api-key "$VOICETHERE_API_KEY"
npx @voicethere/agent build
BUILD_ID=$(voicethere build upload -m "$GITHUB_SHA" --skip-validate --print-id)
voicethere deploy --wait --build-id "$BUILD_ID"

Commit .voicethere/config.json so CI does not need projects use. --print-id writes only the UUID to stdout. Split upload and promote across jobs if a human should approve the bundle before rollout.

Related

• npm packages overview
• Quickstart
• CLI login