CLI command reference

This page lists every voicethere command by subject, with its usage line, options, an example, and what the example prints. For install, the release loop, and CI, see @voicethere/cli. For sign-in, see CLI login.

Stdout carries tables and JSON. Progress goes to stderr as [voicethere] …. Where a command accepts --project <id>, it overrides the project from .voicethere/config.json. voicethere <command> --help prints the same options. Checked against @voicethere/cli 0.16.7.

Subjects

• login
• init
• orgs
• org
• account deletion
• projects
• projects environment
• projects secrets
• projects settings
• projects session-settings
• projects billing-settings
• projects subscription
• projects usage
• projects voice
• projects voice-advanced
• projects widget
• projects metrics
• projects logs
• projects conversation
• build
• source
• deploy
• undeploy
• deployments
• sessions
• api-keys

login

Signs the CLI in and stores credentials in ~/.config/voicethere/credentials.json. The default is browser device approval, which saves a personal API key. Pass a key to skip the browser.

Guide: CLI login

Sign in with browser device approval, or store API keys for CI and automation.

voicethere login [--api-key <key>] [--api-base <url>] [--user-api-key <key>] [--dashboard-cookie <cookie>] [--force] [--no-open]

Example

voicethere login --no-open

Example output

[voicethere] Starting browser device login
[voicethere] api base: https://app.voicethere.io/api/v1
voicethere-login:status=pending_approval
voicethere-login:verification_uri_complete=https://app.voicethere.io/device?user_code=ABCD-EFGH
voicethere-login:user_code=ABCD-EFGH

Confirm this login in your browser:
  https://app.voicethere.io/device?user_code=ABCD-EFGH

User code: ABCD-EFGH

[voicethere] Browser open suppressed (--no-open)
[voicethere] Waiting for approval
[voicethere] Saved personal API key
[voicethere] credentials: /home/you/.config/voicethere/credentials.json
[voicethere] active org: 9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94
voicethere-login:status=completed
voicethere-login:active_org_id=9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94
Logged in. Personal API key saved to /home/you/.config/voicethere/credentials.json (expires in ~90 days).

Lines starting with [voicethere] go to stderr, the rest to stdout. If valid credentials already exist the command prints "Already logged in" and exits, unless you pass --force. Browser login stops with an error while VOICETHERE_API_KEY or VOICETHERE_USER_API_KEY is set, so use --api-key in CI.

init

Scaffolds a local agent workspace from a template and, unless --local-only is set, creates a linked cloud project. It needs credentials unless --local-only is set.

Guide: Agent templates

Scaffold an agent workspace and optionally create a linked cloud project.

voicethere init [dir] [--name <name>] [--slug <slug>] [--template <id>] [--local-only] [--no-install] [--force]

Example

voicethere init support-agent --template echo --no-install

Example output

[voicethere] Scaffolding echo workspace in /home/you/support-agent
[voicethere] Creating cloud project "support-agent" (slug=support-agent, template=echo)
[voicethere] Writing .voicethere/config.json
[voicethere] project config: /home/you/support-agent/.voicethere/config.json
[voicethere] Seeding dashboard Code workspace
Next: edit sources, npm run verify, voicethere source push

init prints nothing on stdout. Every line above goes to stderr. With --local-only the cloud steps are skipped and the last line is "Next: npm run verify". It refuses to run when package.json already exists unless you pass --force.

orgs

Lists and switches organizations. These commands need a personal user API key (vthu_) or a legacy dashboard cookie, which browser login provides.

orgs list

List organizations for the signed-in dashboard user.

voicethere orgs list

Example

voicethere orgs list

Example output

*	9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94	acme	Acme Inc.	owner
 	5d0a7c32-91be-4e48-8f16-a2c4b9e07d53	acme-labs	Acme Labs	member

Columns are tab-separated: active marker (* for the active org), org id, slug, name, and owner or member. Prints "No organizations found." when the list is empty.

orgs use

Set the active organization.

voicethere orgs use <orgId>

Example

voicethere orgs use 9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94

Example output

Active organization set to 9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94

Run this when your account belongs to several orgs and project commands hit the wrong one. With a personal user API key the choice is also saved in the credentials file.

org

Organization actions that change membership or ownership. These need a personal user API key.

org transfer-ownership

Transfer organization ownership to another member.

voicethere org transfer-ownership <newOwnerUserId>

Example

voicethere org transfer-ownership c4a8e2f6-5d17-4b39-8e60-2f9a1d7b3c05

Example output

Ownership transfer complete.

Applies to the active organization. The new owner must already be a member, and you can no longer manage ownership afterwards.

account deletion

Previews and confirms deletion of your own account. Confirmation needs a 6-digit code sent by email. These commands need a personal user API key.

account deletion preview

Show owned orgs and any in-flight deletion job.

voicethere account deletion preview

Example

voicethere account deletion preview

Example output

{
  "owned_orgs": [
    {
      "id": "9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94",
      "name": "Acme Inc.",
      "slug": "acme",
      "project_count": 3
    }
  ],
  "job": null
}

Read-only. Check owned_orgs first, because deleting the account affects the orgs you own. job is null when no deletion has been started.

account deletion request-code

Email a 6-digit verification code.

voicethere account deletion request-code

Example

voicethere account deletion request-code

Example output

Verification code sent to your account email.

Run this before account deletion confirm. The code goes to the email address on your account.

account deletion confirm

Confirm deletion with the emailed code.

voicethere account deletion confirm <code> [--wait]

Example

voicethere account deletion confirm 123456

Example output

Account deletion queued: 0c9f3b7e-4a62-4d15-b8e1-6f2d7a90c354
Poll with: voicethere account deletion confirm 123456 --wait
{
  "ok": true,
  "job_id": "0c9f3b7e-4a62-4d15-b8e1-6f2d7a90c354",
  "message": "Account deletion queued. Cleanup runs in the background; use --wait to block until finished."
}

The code must be exactly 6 digits. With --wait the command prints the queued line, then blocks and ends with "Account deletion completed: <job id>" followed by the status and step lines, or exits with an error if the job fails.

projects

Creates, lists, selects, and deletes agent projects. The active project for a repo is stored in .voicethere/config.json. These commands work with an org API key or a personal user API key.

projects list

List projects in your organization.

voicethere projects list

Example

voicethere projects list

Example output

3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42	support-agent	Support Agent	active_build=b81d5c20-7e94-4a3f-92c6-0d4e1f7a8b35
6a2e8d10-c3f5-4b97-a1d4-9e07b25c3f68	demo-agent	Demo Agent	active_build=none

Columns are tab-separated: project id, slug, name, and the active build id or none. Prints "No projects found." when the org has no projects.

projects create

Create a new project.

voicethere projects create <name> [--slug <slug>] [--no-link] [--bundle <path>]

Example

voicethere projects create "Support Agent"

Example output

{
  "id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42",
  "org_id": "9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94",
  "name": "Support Agent",
  "slug": "support-agent",
  "active_build_id": null,
  "deployed_build_id": null,
  "deployed_at": null,
  "is_deployed": false,
  "created_at": "2026-01-15T10:24:31.000Z"
}

The JSON goes to stdout. Unless you pass --no-link, the command also writes .voicethere/config.json and prints a "Using project …" line to stderr. Commit that file so CI does not need projects use.

projects use

Link this repo to a project by writing .voicethere/config.json.

voicethere projects use [projectId] [--slug <slug>] [--name <name>] [--bundle <path>]

Example

voicethere projects use 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42

Example output

Using project Support Agent (3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42)
Saved /home/you/support-agent/.voicethere/config.json

Without a project id the command re-reads the existing config, or opens a picker in an interactive terminal. In CI, always pass the id. When it refreshes an existing config it prints one "Using project … from <path>" line instead of two.

projects show

Show the active project from .voicethere/config.json.

voicethere projects show

Example

voicethere projects show

Example output

{
  "path": "/home/you/support-agent/.voicethere/config.json",
  "project_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42",
  "project_slug": "support-agent",
  "name": "Support Agent",
  "bundle": "dist/agent.js"
}

Reads the local file only and makes no API call. When no config is found in this directory or a parent, it prints a two-line hint to run voicethere projects use <projectId>.

projects delete

Delete a project and all its builds.

voicethere projects delete [projectId] [--force] [--wait]

Example

voicethere projects delete 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42 --force --wait

Example output

Project deletion queued: 5e1c7a93-0b48-4d26-9f3a-c8d2e6b41f07
  project: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
  status: queued
Project deletion completed: 5e1c7a93-0b48-4d26-9f3a-c8d2e6b41f07
  status: completed
  step: done

Without --force the command asks you to type the project name, and refuses to run outside a terminal. Without --wait it prints a "Poll with:" line and returns while deletion continues. If the deleted project is the one in .voicethere/config.json, that file is removed. The step value shown is illustrative.

projects environment

Manages the non-secret AGENT_* variables of a project. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Agent environment and secrets

projects environment list

List the environment variables of a project.

voicethere projects environment list [--project <id>]

Example

voicethere projects environment list

Example output

[voicethere] Listing environment variables for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
AGENT_GREETING=Hello from Support Agent
AGENT_LANGUAGE=en

The [voicethere] line goes to stderr, the variables go to stdout as KEY=value. Prints "No environment variables." when the project has none.

projects environment view

View one environment variable.

voicethere projects environment view <key> [--project <id>]

Example

voicethere projects environment view AGENT_GREETING

Example output

[voicethere] Reading AGENT_GREETING for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "key": "AGENT_GREETING",
  "value": "Hello from Support Agent"
}

The [voicethere] line goes to stderr and the JSON to stdout. Use it to read a single value in a script instead of parsing the full list.

projects environment create

Create an environment variable.

voicethere projects environment create <key> <value> [--project <id>]

Example

voicethere projects environment create AGENT_GREETING "Hello from Support Agent"

Example output

[voicethere] Saving AGENT_GREETING for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "key": "AGENT_GREETING",
  "value": "Hello from Support Agent"
}

This sends the same request as environment update, so an existing key is overwritten. The key and the value must not be empty. The [voicethere] line goes to stderr.

projects environment update

Create or update an environment variable.

voicethere projects environment update <key> <value> [--project <id>]

Example

voicethere projects environment update AGENT_GREETING "Welcome back"

Example output

[voicethere] Saving AGENT_GREETING for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "key": "AGENT_GREETING",
  "value": "Welcome back"
}

Use it to change a value or to create a missing key in one step. The key and the value must not be empty. The [voicethere] line goes to stderr.

projects environment delete

Delete an environment variable.

voicethere projects environment delete <key> [--project <id>]

Example

voicethere projects environment delete AGENT_GREETING

Example output

[voicethere] Deleting AGENT_GREETING from project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Deleted AGENT_GREETING

The [voicethere] line goes to stderr and the confirmation to stdout. Code that reads the variable gets no value after the change is applied.

projects secrets

Manages the encrypted AGENT_* secrets of a project. Values are never printed back, only masked. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Agent environment and secrets

projects secrets list

List secrets with masked values only.

voicethere projects secrets list [--project <id>]

Example

voicethere projects secrets list

Example output

[voicethere] Listing secrets for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
AGENT_API_KEY	********

The [voicethere] line goes to stderr. Columns are tab-separated: secret name and masked value. The mask shown here is illustrative, the server decides its format. Prints "No secrets." when the project has none.

projects secrets create

Create a secret.

voicethere projects secrets create <name> <value> [--project <id>]

Example

voicethere projects secrets create AGENT_API_KEY "your-api-key-value"

Example output

[voicethere] Creating secret AGENT_API_KEY for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "name": "AGENT_API_KEY",
  "masked_value": "********",
  "created_at": "2026-01-15T10:24:31.000Z",
  "updated_at": "2026-01-15T10:24:31.000Z"
}

The CLI help says to delete and recreate a secret to change its value. The name and the value must not be empty. The [voicethere] line goes to stderr, and the mask shown here is illustrative.

projects secrets delete

Delete a secret.

voicethere projects secrets delete <name> [--project <id>]

Example

voicethere projects secrets delete AGENT_API_KEY

Example output

[voicethere] Deleting secret AGENT_API_KEY from project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Deleted secret AGENT_API_KEY

The [voicethere] line goes to stderr and the confirmation to stdout. Delete first and then create again when you need to rotate a value.

projects settings

Reads and changes the runner pool settings of a project, such as warm pool and idle scale-down. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Runner settings

projects settings list

List runner settings for the active project.

voicethere projects settings list [--project <id>]

Example

voicethere projects settings list

Example output

[voicethere] Listing runner settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
mode=voice
warm_pool_enabled=false
redis_enabled=false
webhooks_enabled=false
idle_scale_down_seconds=300
data_only=false
shared_child_per_session=false
agent_crash_policy=disconnect_all

The [voicethere] line goes to stderr. The command always prints these eight keys in this order, and a key the API does not return prints as undefined. The values above are illustrative.

projects settings set

Set a runner setting.

voicethere projects settings set <name> <value> [--project <id>]

Example

voicethere projects settings set idle_scale_down_seconds 600

Example output

[voicethere] Setting idle_scale_down_seconds=600 on project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
idle_scale_down_seconds=600

Allowed names are mode, warm_pool_enabled, redis_enabled, webhooks_enabled, idle_scale_down_seconds, data_only, shared_child_per_session, and agent_crash_policy. mode takes voice, data, or voice+data. agent_crash_policy takes disconnect_all or restart_child. idle_scale_down_seconds takes 60 to 86400. The rest take true or false (also 1, 0, yes, no). The [voicethere] line goes to stderr.

projects session-settings

Reads and changes WebRTC idle timeout, crash message, speech-to-text, and conversation storage settings. Changes apply on the next deploy. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Session idle timeout

projects session-settings list

List session settings for the active project.

voicethere projects session-settings list [--project <id>]

Example

voicethere projects session-settings list

Example output

[voicethere] Listing session settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
idle_timeout_enabled=true
idle_timeout_seconds=30
stt_enabled=true
conversation_history_enabled=true

The [voicethere] line goes to stderr. The command prints one key=value line for each setting the project has, so a project without overrides shows fewer lines than this example.

projects session-settings set

Set one session setting.

voicethere projects session-settings set <name> <value> [--project <id>]

Example

voicethere projects session-settings set idle_timeout_seconds 90

Example output

[voicethere] Setting idle_timeout_seconds for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
idle_timeout_seconds=90

Settings apply on the next deploy, so run voicethere deploy --wait afterwards. Booleans take true, false, 1, 0, yes, or no. idle_timeout_seconds and data_only_idle_timeout_seconds have a default range of 30 to 120, the CLI accepts up to 86400, and the API may reject values above what your organization allows. Setting idle_timeout_enabled to false prints a billing warning to stderr. The [voicethere] line also goes to stderr.

projects billing-settings

Reads and changes project billing toggles and the spend cap. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Billing

projects billing-settings list

List billing settings for the active project.

voicethere projects billing-settings list [--project <id>]

Example

voicethere projects billing-settings list

Example output

[voicethere] Listing billing settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
metered_overage_enabled=false
conversation_overage_enabled=false
agent_log_overage_enabled=false
budget_cap_amount=null
budget_cap_currency=null
effective_metered_overage_enabled=false
org_metered_overage_enabled=false
org_payment_ready=false
org_budget_cap_amount=null
org_budget_cap_currency=null
validation_warning=null

The [voicethere] line goes to stderr. The first five lines are settings you can change. The last six describe the organization and the effective result, and they are read-only. An unset value prints as null. The values above are illustrative.

projects billing-settings set

Set one billing setting.

voicethere projects billing-settings set <name> <value> [--project <id>]

Example

voicethere projects billing-settings set budget_cap_amount 50

Example output

[voicethere] Setting budget_cap_amount for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
budget_cap_amount=50

The toggles take true, false, 1, 0, yes, or no. budget_cap_amount takes a positive number rounded to two decimals, and budget_cap_currency takes eur or usd. Use null or none to clear either one. The [voicethere] line goes to stderr, and the command prints the new value as key=value on stdout.

projects subscription

Lists the subscriptions of your organization and assigns one to a project. The show and set commands target the project in .voicethere/config.json unless you pass --project.

Guide: Billing

projects subscription list

List organization subscriptions.

voicethere projects subscription list

Example

voicethere projects subscription list

Example output

[voicethere] Listing organization subscriptions
b6e0f3a8-2d74-4c19-a853-9e1c7d4f2a06	tier=ultimate	status=active	project_id=3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42	price_id=none
1c8a5d2f-7e93-4b60-8d4a-e2f9b0c3a751	tier=free	status=active	project_id=none	price_id=none

The [voicethere] line goes to stderr. Columns are tab-separated: subscription id, tier (free or ultimate), status (active or canceled), the assigned project id or none, and the price id or none. Prints "No subscriptions found." when the list is empty.

projects subscription show

Show the assigned subscription for a project.

voicethere projects subscription show [--project <id>]

Example

voicethere projects subscription show

Example output

[voicethere] Reading assigned subscription for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "project_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42",
  "subscription": {
    "id": "b6e0f3a8-2d74-4c19-a853-9e1c7d4f2a06",
    "tier": "ultimate",
    "status": "active"
  }
}

The [voicethere] line goes to stderr. "subscription" is null when nothing is assigned. When the API returns them, the object also carries billing_source and a capacity block.

projects subscription set

Assign or clear the subscription for a project.

voicethere projects subscription set <subscriptionId> [--project <id>]

Example

voicethere projects subscription set b6e0f3a8-2d74-4c19-a853-9e1c7d4f2a06

Example output

[voicethere] Assigning subscription for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "project_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42",
  "subscription": {
    "id": "b6e0f3a8-2d74-4c19-a853-9e1c7d4f2a06",
    "tier": "ultimate",
    "status": "active"
  }
}

Get the id from projects subscription list. Pass none (or null) to clear the assignment, and the first line then reads "Clearing subscription for project …". The [voicethere] line goes to stderr.

projects usage

Reads usage credits for one project or as an organization rollup. The top-level voicethere usage command is the same command as projects usage show.

Guide: Billing

projects usage show

Show usage credits for a project, or an organization rollup with --org.

voicethere projects usage show [--project <id>] [--org] [--period <period>] [--from <iso>] [--to <iso>] [--bucket <bucket>]

Example

voicethere projects usage show --period 7d

Example output

[voicethere] Reading usage for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "org_id": "9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94",
  "project_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42",
  "period": "7d",
  "range_start": "2026-01-08T10:24:31.000Z",
  "range_end": "2026-01-15T10:24:31.000Z",
  "bucket": "day",
  "total_credits": 0,
  "totals": [],
  "series": [],
  "balance": null
}

The [voicethere] line goes to stderr and the JSON to stdout. totals holds one entry per usage kind with raw_quantity, millicredits, and credits, and it is empty here. The timestamps are illustrative. Use --from and --to for a custom range.

usage

Show usage credits for the current project or organization.

voicethere usage [--project <id>] [--org] [--period <period>] [--from <iso>] [--to <iso>] [--bucket <bucket>]

Example

voicethere usage --org --period 30d

Example output

[voicethere] Reading organization usage rollup
{
  "org_id": "9b1d4e7a-2c35-4f08-a6d3-71e0c58b2a94",
  "project_ids": [
    "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42"
  ],
  "period": "30d",
  "range_start": "2025-12-16T10:24:31.000Z",
  "range_end": "2026-01-15T10:24:31.000Z",
  "bucket": "day",
  "total_credits": 0,
  "totals": [],
  "series": [],
  "balance": null
}

This is the same command as projects usage show, with the same options. With --org the JSON lists project_ids instead of a single project_id. The timestamps are illustrative, and the [voicethere] line goes to stderr.

projects voice

Shows and changes the speech-to-text and text-to-speech vendors and models of a project, and lists the available VoiceThere models. Every project command targets the project in .voicethere/config.json unless you pass --project.

Guide: Voice vendors

projects voice catalog

List VoiceThere speech-to-text and text-to-speech models from the control plane.

voicethere projects voice catalog [--json]

Example

voicethere projects voice catalog

Example output

[voicethere] Fetching voice catalog

Sherpa STT models (default: en)
────────────────────────────────────────────────────────────────────────
* en                 en   English
                     bundle=sherpa-onnx-whisper-tiny

Sherpa TTS models (default: en-amy-low)
────────────────────────────────────────────────────────────────────────
* en-amy-low         en   Amy (low)
                     bundle=vits-piper-en_US-amy-low

Select with: voicethere projects voice set --interactive
Or:          voicethere projects voice set --tts-model-id <id> --stt-model-id <id>
Full JSON:   voicethere projects voice catalog --json

The model ids, labels, bundles, and defaults come from the control plane, so the rows here are illustrative and your output lists every model. A * marks the default. The [voicethere] line goes to stderr.

projects voice show

Show voice settings for the active project.

voicethere projects voice show [--project <id>]

Example

voicethere projects voice show

Example output

[voicethere] Reading voice settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
{
  "stt_provider": "openai",
  "tts_provider": "openai",
  "stt_model_id": "en",
  "tts_model_id": "en-amy-low",
  "stt_model": "whisper-1",
  "tts_model": "tts-1"
}

The [voicethere] line goes to stderr. The JSON may also include stt_language and tts_voice when they are set. The values above are illustrative.

projects voice set

Update voice settings.

voicethere projects voice set [--project <id>] [--stt-provider <id>] [--tts-provider <id>] [--stt-model-id <id>] [--tts-model-id <id>] [--stt-model <name>] [--stt-language <code>] [--tts-model <name>] [--tts-voice <id>] [--interactive]

Example

voicethere projects voice set --stt-provider openai --stt-model whisper-1

Example output

[voicethere] Updating voice settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
stt_provider=openai
stt_model=whisper-1

The change requires a redeploy, so run voicethere deploy --wait afterwards. Options you leave out keep their current value, and stdout echoes only the fields you passed. With --interactive the command asks for providers and VoiceThere models in a terminal and prints the chosen values. The [voicethere] line goes to stderr.

projects voice-advanced

Reads and changes advanced voice pipeline settings: voice activity detection, barge-in, speech-to-text lifecycle, and language identification. Changes apply on the next deploy. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Advanced voice settings

projects voice-advanced list

List resolved advanced voice settings for the active project.

voicethere projects voice-advanced list [--project <id>]

Example

voicethere projects voice-advanced list

Example output

[voicethere] Listing advanced voice settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
vad.enabled=true
vad.provider=energy
vad.threshold=0.15
vad.minSpeechDurationMs=250
vad.minSilenceDurationMs=1100
vad.bargeIn.enabled=true
tts.speed=0.9
noiseSuppression.enabled=true
events.mode=both

The [voicethere] line goes to stderr. The command prints one key=value line for every setting the API returns, and this example is shortened. The values above are illustrative.

projects voice-advanced set

Set one advanced voice setting.

voicethere projects voice-advanced set <name> <value> [--project <id>]

Example

voicethere projects voice-advanced set vad.bargeIn.requireSttPartial false

Example output

[voicethere] Setting vad.bargeIn.requireSttPartial for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
vad.bargeIn.requireSttPartial=false

The change requires a redeploy, so run voicethere deploy --wait afterwards. Booleans take true, false, 1, 0, yes, or no. Numbers must fall inside the key's range, and keys with a fixed list such as vad.provider or events.mode reject other values. The [voicethere] line goes to stderr.

projects voice-advanced reset

Clear all advanced voice overrides and return to the library defaults.

voicethere projects voice-advanced reset [--project <id>]

Example

voicethere projects voice-advanced reset

Example output

[voicethere] Resetting advanced voice settings for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
reset=defaults

This clears every override at once, not a single key. Like set, it takes effect on the next deploy. The [voicethere] line goes to stderr.

projects widget

Configures and publishes the embeddable voice and chat widget. You edit a draft with set and publish it to the CDN with deploy. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Embed widget

projects widget show

Show the widget draft, publish status, and CDN URLs.

voicethere projects widget show [--project <id>] [--cdn-base <url>] [--json]

Example

voicethere projects widget show

Example output

[voicethere] Loading embed widget config for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
public_id: d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68
publish_status: published
published_revision: 3
  cdn_url: https://cdn.voicethere.io/widgets/d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68/config.json
  cdn_url_immutable: https://cdn.voicethere.io/widgets/d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68/r3.json
  draft: preset=pill-dark position=bottom-right mode=voice
  launcher_label: Talk to us
  greeting: Hi, how can I help?

The [voicethere] line goes to stderr. publish_status is one of idle, queued, publishing, published, or failed, and a publish_error line appears after a failed publish. The CDN host is derived from your API base, and --cdn-base or VOICETHERE_WIDGET_CDN_BASE overrides it.

projects widget set

Merge flags into the widget draft and save.

voicethere projects widget set [--project <id>] [--preset <id>] [--position <corner>] [--mode <mode>] [--launcher-label <text>] [--greeting <text>] [--theme-primary <hex>] [--theme-background <hex>] [--theme-text <hex>] [--json]

Example

voicethere projects widget set --preset pill-light --position bottom-left --launcher-label "Talk to us"

Example output

[voicethere] Updating embed widget draft for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
public_id: d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68
publish_status: idle
  draft: preset=pill-light position=bottom-left mode=voice
  launcher_label: Talk to us

This only changes the draft, so run projects widget deploy to publish it. Pass at least one field flag or the command fails, and the colors must be hex values such as #1a73e8. Fields you leave out keep their current value. The publish_status shown is illustrative, and the [voicethere] line goes to stderr.

projects widget deploy

Publish the widget draft to the CDN.

voicethere projects widget deploy [--project <id>] [--wait] [--timeout-ms <ms>] [--cdn-base <url>] [--json]

Example

voicethere projects widget deploy --wait

Example output

[voicethere] Publishing embed widget for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
[voicethere] Waiting for widget publish to complete
public_id: d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68
publish_status: published
published_revision: 4
  cdn_url: https://cdn.voicethere.io/widgets/d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68/config.json
  cdn_url_immutable: https://cdn.voicethere.io/widgets/d2f7a6b1-4c93-4e08-b5a1-7c3e9f0a2d68/r4.json

Lines starting with [voicethere] go to stderr. Without --wait the command prints public_id, publish_status, the CDN URL, and a "Poll with:" line, then returns. With --wait it exits with an error when the publish fails or the timeout passes.

projects metrics

Reads the same numbers as the Metrics area of the dashboard, one command per tab. The command targets the project in .voicethere/config.json unless you pass --project.

Guide: Project metrics

projects metrics overview

Show session totals, error rate and billable seconds for a window.

voicethere projects metrics overview [--project <id>] [--period <period>] [--start <ISO> --end <ISO>] [--json]

Example

voicethere projects metrics overview --period 7d

Example output

[voicethere] Reading metrics for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Project metrics (7d)
  active sessions:     2
  sessions started:    148
  sessions ended:      146
  sessions failed:     6
  error rate:          4.1%
  billable seconds:    18240
  sessions in queue:   0
  avg queue wait (s):  -

The [voicethere] line goes to stderr and the summary to stdout. Use either --period or --start with --end, not both. The numbers are illustrative.

projects metrics sessions

Show session totals, durations and failures by reason.

voicethere projects metrics sessions [--project <id>] [--period <period>] [--start <ISO> --end <ISO>] [--json]

Example

voicethere projects metrics sessions --period 24h

Example output

[voicethere] Reading session metrics for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Session metrics (24h)
  started:             148
  completed:           139
  failed:              6
  never connected:     3
  peak concurrent:     9 (plan limit 20)
  duration p50/p95 (s): 74 / 312
  connect p50/p95 (s):  1.2 / 3.4

Failures by reason
  agent_crashed  4
  idle_timeout   2

End reasons
  caller_hangup  120
  agent_crashed  4

The [voicethere] line goes to stderr and the summary to stdout. Use either --period or --start with --end, not both. The numbers are illustrative. Failures by reason lists the reason keys you can pass to sessions list --reason.

projects metrics agent

Show agent log counts, crashes and top errors.

voicethere projects metrics agent [--project <id>] [--period <period>] [--start <ISO> --end <ISO>] [--json]

Example

voicethere projects metrics agent --period 24h

Example output

[voicethere] Reading agent metrics for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Agent metrics (24h)
  errors:              12
  warnings:            31
  info:                0
  crashes:             4
  turns/conversation p50/p95: 6 / 19

Top errors
  message                  count
  model request timed out  7
  tool call failed         5

The [voicethere] line goes to stderr and the summary to stdout. Use either --period or --start with --end, not both. The numbers are illustrative.

projects metrics voice

Show speech latency percentiles for a window.

voicethere projects metrics voice [--project <id>] [--period <period>] [--start <ISO> --end <ISO>] [--json]

Example

voicethere projects metrics voice --period 24h

Example output

[voicethere] Reading voice metrics for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Voice metrics (24h)
  STT: p50 180 ms, p95 420 ms, p99 610 ms
  TTS: p50 210 ms, p95 480 ms, p99 700 ms
  Turn response (speech end to first audio): p50 1100 ms, p95 1900 ms, p99 2600 ms
  Final to audio (STT final to first audio): p50 620 ms, p95 1200 ms, p99 1700 ms
  Finalize delay (speech end to STT final): p50 480 ms, p95 700 ms, p99 900 ms
  TTS first audio: p50 190 ms, p95 430 ms, p99 650 ms

The [voicethere] line goes to stderr and the summary to stdout. Use either --period or --start with --end, not both. The numbers are illustrative. Voice metrics are kept for 14 days; a longer range prints a notice instead of numbers.

projects logs

Lists structured agent logs for a project, or for one conversation. The command targets the project in .voicethere/config.json unless you pass --project.

Guide: Agent logs

projects logs list

List recent agent logs, 20 by default.

voicethere projects logs list [--project <id>] [--limit <n>] [--session <id>] [--q <text>] [--level <level>] [--severity <level>] [--from <ISO>] [--to <ISO>] [--json]

Example

voicethere projects logs list --level error --limit 2

Example output

[voicethere] Listing last 2 project agent logs
2026-01-15T10:24:31.000Z	e7b3c9a2-1d4…	error	tool call failed
2026-01-15T10:21:07.000Z	4a9d1c7e-b03…	error	model request timed out

The [voicethere] line goes to stderr. Columns are tab-separated: timestamp, the first 12 characters of the session id (— when there is none), level, and message. With --session the session column is dropped and the first line reads "Listing logs for session <id>". The messages above are illustrative.

projects conversation

Searches, reads, and exports stored voice conversation transcripts. Every command targets the project in .voicethere/config.json unless you pass --project.

Guide: Conversation history

projects conversation list

List recent project conversations, 50 by default.

voicethere projects conversation list [--project <id>] [--limit <n>] [--q <text>] [--period <period>] [--from <iso>] [--to <iso>] [--cursor <token>] [--json]

Example

voicethere projects conversation list --limit 2 --period 7d

Example output

[voicethere] Listing last 2 project conversations
2026-01-15T10:20:02.000Z	e7b3c9a2-1d4…	6 turn(s)	e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
2026-01-14T16:41:55.000Z	4a9d1c7e-b03…	12 turn(s)	4a9d1c7e-b035-4e82-9c16-f7d2a8e3b590

The [voicethere] line goes to stderr. Columns are tab-separated: start time (— when unknown), shortened session id, turn count, and full session id. When more results exist the output ends with "More results available (cursor: …)", and you pass that cursor to --cursor.

projects conversation get

Load the full turn timeline for one session.

voicethere projects conversation get <sessionId> [--project <id>] [--json]

Example

voicethere projects conversation get e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146

Example output

[voicethere] Loading conversation for session e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
Session e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146 (2 turn(s))
2026-01-15T10:20:02.000Z	#0	user	user_speech_final	I need help with my order
2026-01-15T10:20:05.000Z	#1	agent	agent_speak	Sure, what is your order number?

The [voicethere] line goes to stderr. Columns are tab-separated: time, turn number, role (user or agent), event type, and text. The turn numbers and text above are illustrative.

projects conversation search

Search conversation history. This is an alias for list --q.

voicethere projects conversation search <query> [--project <id>] [--limit <n>] [--period <period>] [--from <iso>] [--to <iso>] [--json]

Example

voicethere projects conversation search "order number"

Example output

[voicethere] Searching conversation history for "order number"
2026-01-15T10:20:02.000Z	e7b3c9a2-1d4…	6 turn(s)	e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146

Matching turns:
2026-01-15T10:20:05.000Z	e7b3c9a2-1d4…	#1	agent	Sure, what is your order number?

It runs the same code as conversation list with --q set, so the output has the same columns. The Matching turns block appears only when the API returns matching turns, with columns time, shortened session id, turn number, role, and text. The [voicethere] line goes to stderr.

projects conversation export

Export conversation transcripts to a downloadable JSON file.

voicethere projects conversation export [--project <id>] [--session <id>] [--q <text>] [--all] [--period <period>] [--from <iso>] [--to <iso>] [--wait] [-o, --output <path>] [--json]

Example

voicethere projects conversation export --all --period 30d --wait -o export.json

Example output

[voicethere] Creating conversation export job
Conversation export queued: 8d3f6b1a-5c20-4e97-b4a8-0a7e2c9d1f53
  project: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
  mode: filter
[voicethere] Waiting for conversation export to complete
Conversation export completed: 8d3f6b1a-5c20-4e97-b4a8-0a7e2c9d1f53
  conversations: 12/12
  download expires: 2026-01-16T10:24:31.000Z
[voicethere] Writing export to export.json
Wrote export JSON to export.json

Pass exactly one of --session, --q, or --all. Lines starting with [voicethere] go to stderr. --output needs --wait, and without --wait the command prints a "Poll with:" line and returns while the export runs. Without --output, --wait prints the download_url (or the job as JSON with --json). The counts and expiry time are illustrative.

build

Validates, uploads, lists, promotes, and downloads agent bundles. Every command except validate needs a login, and the ones that act on a project use the project in .voicethere/config.json.

Guide: @voicethere/cli

build validate

Run the @voicethere/agent sandbox verify on a bundle.

voicethere build validate [file]

Example

voicethere build validate

Example output

[voicethere] Validating agent bundle
[voicethere] bundle: /home/dev/my-agent/dist/agent.js (default (dist/agent.js))
[voicethere] Running @voicethere/agent verify on bundle
[voicethere] Bundle validated: /home/dev/my-agent/dist/agent.js

Use it to check a bundle before you upload it. Every line shown goes to stderr. Between the second and last lines the @voicethere/agent verify tool prints its own output, which is not shown here. The command exits with an error when verify fails.

build list

List uploaded builds for the active project, newest first.

voicethere build list

Example

voicethere build list

Example output

[voicethere] Listing builds for active project
[voicethere] project: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42 (project config (/home/dev/my-agent/.voicethere/config.json))
build_id	uploaded_at	status	active	message
a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68	2026-01-15 10:24:31 UTC	passed	yes	shorter silence timeout
f0c7b2d9-3e51-4a8c-9d64-18a5e7c2b03f	2026-01-14 16:02:09 UTC	passed		first production build

The [voicethere] lines go to stderr. Columns are tab-separated: build id, upload time, validation status, "yes" for the active build (empty otherwise), and the build message. Prints "No builds uploaded yet." when there are none. The ids, times, and messages above are illustrative.

build upload

Validate a bundle locally, then upload it as a new build.

voicethere build upload [file] [-m, --message <text>] [--skip-validate] [--print-id]

Example

voicethere build upload -m "shorter silence timeout" --print-id

Example output

a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68

With --print-id, stdout holds only the new build id, so scripts can capture it. Progress lines such as "[voicethere] Uploading agent bundle" and the validation steps go to stderr. Without --print-id, stdout reads "Uploaded build <id>", then "Message: <text>" when you passed -m, "Uploaded at: <time>", and a hint to run voicethere build promote <id>. An upload only stores the build. Promote it, then deploy, to run it.

build promote

Make a build the active build in the control plane.

voicethere build promote [buildId]

Example

voicethere build promote a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68

Example output

[voicethere] Promoting build to active
[voicethere] build: a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68
[voicethere] project: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42 (project config (/home/dev/my-agent/.voicethere/config.json))
[voicethere] Calling control plane promote API
Promoted build a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68 for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
Active artifact: builds/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42/a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68/agent.js
Control plane updated. Run voicethere deploy --wait to roll out to cloud runners.

Promote only moves the control-plane pointer to that build. Run voicethere deploy --wait afterwards to roll it out to cloud runners. In a script you must pass the build id, because the picker needs a terminal. The [voicethere] lines go to stderr, and the artifact path is illustrative.

build download

Download a compiled agent bundle as JavaScript.

voicethere build download -o, --output <path> [--project <id>] [--build-id <id>]

Example

voicethere build download -o ./agent.js

Example output

[voicethere] Downloading compiled bundle a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68
[voicethere] wrote 48213 byte(s) to /home/dev/my-agent/agent.js
/home/dev/my-agent/agent.js

Use it to inspect or archive what is deployed. Without --build-id it picks the active build, or the newest build that passed validation. The first two lines go to stderr, and stdout is the absolute path of the written file. The byte count is illustrative, and the second line adds the server's file name in parentheses when the server sends one.

source

Syncs your agent source with the Code workspace in the dashboard. Push and pull use the project in .voicethere/config.json.

Guide: Dashboard code editor

source push

Upload local workspace sources to the cloud project.

voicethere source push

Example

voicethere source push

Example output

[voicethere] Collecting workspace files from /home/dev/my-agent
[voicethere] Uploading 14 file(s) (revision 6)
[voicethere] source revision: 7
7

Use it to move local edits into the dashboard Code workspace. The first three lines go to stderr, and stdout is the new revision number. The upload sends the revision it just read from the cloud workspace. The file count and revisions are illustrative.

source pull

Download cloud workspace sources into the local repo.

voicethere source pull

Example

voicethere source pull

Example output

[voicethere] Downloading Code workspace from VoiceThere
[voicethere] pulled 14 file(s) at revision 7

Use it to bring dashboard edits into your local checkout. Both lines go to stderr and nothing is printed to stdout. Files with the same path are overwritten in place, so commit or stash local edits first. The file count and revision are illustrative.

source download

Download the saved Code workspace as a zip file.

voicethere source download -o, --output <path> [--project <id>]

Example

voicethere source download -o ./workspace.zip

Example output

[voicethere] Downloading Code workspace zip from VoiceThere
[voicethere] wrote 20480 byte(s) to /home/dev/my-agent/workspace.zip
/home/dev/my-agent/workspace.zip

Use it for a backup or to read the workspace without linking a repo. The first two lines go to stderr, and stdout is the absolute path of the zip. The byte count is illustrative, and the second line adds the server's file name in parentheses when the server sends one.

deploy

Promotes the build if needed and rolls it out to cloud runners for the project.

Guide: Rollout modes

Roll the active build out to cloud runners.

voicethere deploy [--project <id>] [--build-id <id>] [--mode <mode>] [--wait]

Example

voicethere deploy --wait

Example output

[voicethere] Starting cloud deployment
[voicethere] Calling POST /deployments
Deployment queued: 2e9a6c4d-8f13-4b75-a0d2-6c1f8e3b9a47
  build: a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68
  mode: drain
  status: queued
[voicethere] Waiting for rollout to complete
Deployment completed: 2e9a6c4d-8f13-4b75-a0d2-6c1f8e3b9a47
  build: a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68
  status: completed

Use --wait in scripts and CI so the command only returns once the rollout has finished. The [voicethere] lines go to stderr. If the rollout fails, the command exits with an error that carries the failure message. Without --wait it prints the queued job and a "Poll with:" line, but running that line starts a new deployment instead of checking the old one. --mode accepts drain or force, and any other value is rejected.

undeploy

Removes the project's runner deployments from the cloud.

Remove the project's cloud runner deployments.

voicethere undeploy [--project <id>] [--wait]

Example

voicethere undeploy --wait

Example output

[voicethere] Starting project undeploy
[voicethere] Calling POST /projects/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42/undeploy
Undeploy queued: 6b3f1d8a-9c42-4e07-b5a9-d0e4c7a2f815
  build: a5d1e8c3-7b24-4f96-8e0a-c3b97d2f1e68
  status: queued
[voicethere] Waiting for undeploy to complete
Undeploy completed: 6b3f1d8a-9c42-4e07-b5a9-d0e4c7a2f815
  status: completed

Use it to take the project agent off cloud runners. The [voicethere] lines go to stderr. With --wait the command exits with an error if the undeploy fails. Without --wait it prints a "Poll with:" line, but running that line starts another undeploy instead of checking the first one.

deployments

Lists a project's deploys and shows the timeline of one deploy, with server timestamps in UTC. Timelines are kept for 90 days. Commands use the project in .voicethere/config.json unless you pass one.

Guide: Deployment history

deployments list

List the project's deploys, newest first.

voicethere deployments list [--project <id>] [--limit <n>] [--before <ISO>] [--json]

Example

voicethere deployments list --limit 2

Example output

[voicethere] Listing last 2 deployments
Started (UTC)        Build     Mode   Status     By                 Duration  Last event (UTC)
2026-10-17 12:00:00  a1b2c3d4  drain  completed  alice@example.com  2:05      2026-10-17 12:09:30
2026-10-17 10:30:00  e5f6a7b8  force  completed  ci-deploy          0:42      2026-10-17 10:30:42
next: --before 2026-10-17T10:30:00.000Z

By is who started the deploy: a user's email or an API key's name (- when unknown; needs CLI 0.16.7). Duration runs from the request to the finish, and Last event is the last recorded step, which for a drain deploy can come minutes after the deploy finished. When more deploys exist the output ends with a next: line; pass that time to --before for the next page. The [voicethere] line goes to stderr, and --json prints the API response unchanged.

deployments show

Show the timeline of one deploy.

voicethere deployments show <deploymentId> [--project <id>] [--json]

Example

voicethere deployments show 2e9a6c4d-8f13-4b75-a0d2-6c1f8e3b9a47

Example output

[voicethere] Showing deployment 2e9a6c4d-8f13-4b75-a0d2-6c1f8e3b9a47
2e9a6c4d-8f13-4b75-a0d2-6c1f8e3b9a47  build a1b2c3d4  drain  completed  started 2026-10-17 12:00:00 UTC
Requested by: alice@example.com
12:00:00 UTC  +0:00  Deploy requested                      mode=drain
12:00:02 UTC  +0:02  Rollout started                       mode=drain
12:01:40 UTC  +1:40  New version ready                     runners=2
12:01:41 UTC  +1:41  New calls go to the new version       versions=1
12:01:42 UTC  +1:42  Previous version finishing its calls  runners=2
12:02:05 UTC  +2:05  Deploy finished
12:09:30 UTC  +9:30  Previous version stopped              drained in 7:48

The second line names who started the deploy. Each line after it shows the time in UTC, the time since the request, and what happened. A deploy that was refused shows the reason in plain words. Deploys from before history was recorded list only the request and the result and end with "(start and end only)". The [voicethere] line goes to stderr, and --json prints the API response unchanged.

sessions

Lists voice sessions, shows what one session was billed, and reads or deletes its audio recording. Commands use the project in .voicethere/config.json unless you pass one.

Guide: Conversation recording

sessions list

List sessions for a project, newest first.

voicethere sessions list [projectId] [--project <id>] [--start <n>] [--end <n>] [--failed] [--reason <key>] [--from <ISO>] [--to <ISO>] [--json]

Example

voicethere sessions list --start 0 --end 2

Example output

[voicethere] Listing sessions for project 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42
e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146	ended	billable=84	created=2026-01-15T10:20:02.000Z
4a9d1c7e-b035-4e82-9c16-f7d2a8e3b590	active	billable=-	created=2026-01-15T10:31:40.000Z

Showing 1-2 of 9 sessions

The [voicethere] line goes to stderr. Columns are tab-separated: session id, status (active, ended, or failed), billable seconds (- when not set), an optional reason=<end reason> column, and the creation time. Use the session id with sessions billing and sessions recording. Prints "No sessions found (<total> total)." when the page is empty. The rows and counts are illustrative.

sessions billing

Show billing details for one session.

voicethere sessions billing <sessionId> [--project <id>] [--json]

Example

voicethere sessions billing e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146

Example output

[voicethere] Fetching billing for session e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
orchestrator_session_id=e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
status=ended
billable_seconds=84
end_reason=-
billing_started_at=2026-01-15T10:20:04.000Z
ended_at=2026-01-15T10:21:31.000Z
created_at=2026-01-15T10:20:02.000Z

The [voicethere] line goes to stderr. Stdout is key=value lines, and a field that is not set prints as -. The first key, orchestrator_session_id, is the session id you passed. --json prints the same fields as an object, plus project_id. The values above are illustrative.

sessions recording get

Show a session recording's status, or download its audio.

voicethere sessions recording get <sessionId> [options…]

Example

voicethere sessions recording get e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146 --wait -o call.wav

Example output

[voicethere] Fetching session recording for e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
[voicethere] Waiting for session recording to become ready
[voicethere] Writing recording to call.wav
[voicethere] Converted recording to wav
Wrote 1843244 byte(s) to call.wav

get is the default subcommand, so you can omit it (voicethere sessions recording <sessionId>). Without -o and --json it prints status, format, duration_ms, byte_size, and the play_url when one exists. --output needs --wait, because the recording must be ready first. Lines starting with [voicethere] go to stderr, and the Converted line appears only when the output format is not opus. The byte count is illustrative.

sessions recording delete

Delete a session recording.

voicethere sessions recording delete <sessionId> [--project <id>]

Example

voicethere sessions recording delete e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146

Example output

[voicethere] Deleting session recording for e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146
Deleted session recording for e7b3c9a2-1d46-4f80-a5c7-3b2e8d9f0146

Use it to remove a stored recording. The first line goes to stderr.

api-keys

Manages organization API keys. Listing shows only the prefix, and the full key is printed once at creation.

api-keys list

List API keys (prefix and permissions only).

voicethere api-keys list

Example

voicethere api-keys list

Example output

7e2b9d41-6a03-4c58-b1f7-d85c0a3e9246	CI deploy	admin	vth_a1b2c3…	—	active
2d8f4a60-b7e3-4915-8c2a-f01d6e93b7a4	Widget	client	vthc_d4e5f6…	Support Agent	expired

Columns are tab-separated: key id, name, kind, key prefix, project name (or — for org-wide keys), and status (active, expired, or revoked). Prints "No API keys." when there are none.

api-keys create

Create an API key. The plaintext key is shown once.

voicethere api-keys create --name <name> [--kind <kind>] [--project-id <id>] [--expires-in-days <days>]

Example

voicethere api-keys create --name "Widget" --kind client --project-id 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42

Example output

=== API key (shown once — store securely) ===
vthc_…

id: 7e2b9d41-6a03-4c58-b1f7-d85c0a3e9246
kind: client
project_id: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c1f42

The key line is shortened to vthc_… here and prints in full on your terminal. Client keys need a project, either from --project-id or the linked .voicethere/config.json. Admin keys are org-wide and reject --project-id.

api-keys revoke

Revoke an API key by id.

voicethere api-keys revoke <id>

Example

voicethere api-keys revoke 7e2b9d41-6a03-4c58-b1f7-d85c0a3e9246

Example output

Revoked CI deploy (vth_a1b2c3…)

Get the id from api-keys list. Anything still using the key stops working, so rotate in CI first.