@vox-ai/cli-darwin-arm64

@vox-ai/cli

vox.ai CLI for agent-as-code workflows.

vox lets you build, validate, diff, and ship vox.ai voice agents as code. It is designed to be driven both by people in a terminal and by coding agents (Claude Code, Codex, and similar): edit JSON sources in your repo, read structured --json output, review diffs, and push when you are ready.

The CLI is the durable authoring surface — what belongs in your repo, gets reviewed, and can be reproduced or rolled back. The dashboard stays the viewer and admin surface.

Install

# npm (macOS, Linux, and Windows x64; requires Node >= 20.17)
npm install -g @vox-ai/cli

# npm pre-release channel
npm install -g @vox-ai/cli@beta

# Homebrew (macOS)
brew install vox-public/tap/vox

On Windows, npm is the official install path: npm install -g @vox-ai/cli@beta, then run vox (or vox.cmd) from any terminal. There is no separate .exe or zip download to install.

Verify the install:

vox --version
vox --help

Quick Start

# 1. Sign in (OAuth in your browser)
vox auth login
vox auth whoami --json

# 2. Read the operating contract (especially useful for coding agents)
vox guide coding-agent

# 3. Start a project — scaffold a new one, or import what already exists
vox init
# or, in an existing workspace:
vox sync import --all --dry-run --json

Agent-as-Code Workflow

The core loop is a code workflow, not a sequence of dashboard clicks:

pull / init  ->  edit JSON files  ->  doctor / validate  ->  diff / status  ->  push  ->  version save / promote

• vox agent pull / vox init — bring remote agents into local JSON source.
• Edit the JSON files in your editor or with a coding agent.
• vox agent doctor / vox agent validate — catch authoring risks before you push.
• vox agent diff / vox agent status — review exactly what will change.
• vox agent push — apply your local source to the remote draft.
• vox agent version save / vox agent promote — snapshot an immutable version and promote it to production.

Commands

A high-level map of the public surface. Run any command with --help for details, or add --json for structured output.

Area	Commands
Auth & config	auth login, auth whoami, auth switch, auth logout, config get/set
Get started	init, doctor, guide coding-agent, guide flow
Discover offline	docs search/show, skills list/show (deprecated: vox.ai plugin 사용), schema list/get
Authoring	agent …, tool …, knowledge … (plan, create, edit, validate, diff, push, version, promote)
Sync	sync status, sync import, sync bootstrap
Organization	org get/usage/members, org invoice list/get, org verification status, org create/delete, org api-key create/list/revoke
Multi-org	org list, org switch, workspace init
Runtime & telephony	chat, call …, number …, widget …, version, upgrade

For sub-organization API keys, --org selects the authenticated caller while --sub-org selects the organization in the API path:

vox org api-key list --sub-org <sub-organization-id> --json
vox org api-key create --sub-org <sub-organization-id> --key-name production --allowed-ip 203.0.113.10 --allowed-ip 10.0.0.0/24 --json
vox org api-key revoke --sub-org <sub-organization-id> --key-name production --secret-key-suffix <last4> --yes --json

The plaintext data.api_key from create is shown exactly once and cannot be retrieved later; store it immediately in a secure secret store. It is never written to CLI config, project state, telemetry, or error details. Each list item contains only the key name, last-four suffix, creation time, last-used time, and allowed_ips.

--allowed-ip <ip|cidr> (repeatable, up to 20; '*' allows every IP) restricts a key to those addresses at create. The server validates and normalizes entries, and an empty allowed_ips means no restriction.

Using vox from Coding Agents

vox is built to be a first-class tool for coding agents. Point your agent at these bootstrap commands:

vox guide coding-agent --json     # the operating contract to follow
vox docs search "<query>" --json  # offline official docs
vox skills list --json            # deprecated: frozen snapshot, prefer the vox.ai plugin
vox schema get <namespace> <schema-type> --json

vox skills list/show is deprecated and frozen at a pinned snapshot; install the vox.ai plugin for current skills (https://github.com/vox-public/plugin).

Every command accepts --json and emits a stable envelope ({ ok, data } on success, { ok: false, error: { code, message, … } } on failure), so agents and automation can branch on results, read error.details.hint, and follow related_commands. On the shared read-command error path (llm, number, widget, and other list/get-style commands) API failures promote the server error.code and error.message into that envelope (for example VALIDATION_ERROR); commands with their own error normalizers keep API_REQUEST_FAILED; 401/403/404 keep AUTH_REQUIRED / API_FORBIDDEN / the command's not-found mapping, and the original API body stays in error.details. Text mode prints a single line: <action> failed with <status>: <code> — <message>.

Authentication

• vox uses OAuth only. vox auth login opens your browser and completes a loopback flow.
• Refresh tokens are stored in your OS keychain / secret store — never in project files.
• Project and workspace JSON never contain tokens or secrets.

Telemetry and Privacy

Official builds always send CLI usage and signed-in account metadata. Signed-in events identify the vox user and update the PostHog Person profile with the user's email, name, local profile, install ID, last login time, and current/default organization metadata. Usage properties include the command, exit status, CLI version, OS, and sanitized runtime signals.

The CLI does not send prompts, paths, argument values, file contents, tokens, secrets, message content, customer data, hostnames, or free-text errors. Official builds do not provide a telemetry opt-out.

Development and local builds never emit telemetry.

Upgrade

vox upgrade is a package-manager aware upgrade assistant: it detects how vox was installed (npm, Homebrew, standalone, or unknown) and prints the exact upgrade command for that install. It never modifies your installation itself — run the printed command to update.

vox upgrade                              # detect the install and print the exact upgrade command
vox upgrade --channel beta               # check the beta channel
vox upgrade --json                       # structured output for scripts / coding agents
npm install -g @vox-ai/cli@latest        # update an npm install
brew upgrade vox-public/tap/vox          # update a Homebrew install

For Homebrew, vox upgrade distinguishes the newest upstream release from what the formula currently offers, so it won't tell you to brew upgrade before the formula has caught up. vox upgrade --json (schema vox.ai.cli.upgrade.v2) returns status, confidence, actions, and verify_commands so a coding agent can pick the next command without parsing human text.

Update notices

vox occasionally checks — at most once a day, when you run a command — whether a newer version is published, and caches the result locally (no daemon, no background process). When an update exists, it prints a single line to stderr on your next interactive run:

A newer vox.ai CLI is available: 0.1.0-beta.9
Run `vox upgrade` for the exact upgrade command.

The check only queries the public npm registry — it is not telemetry and sends no account, organization, or auth information. It stays silent for --json, non-interactive shells, and CI, and never changes a command's exit code. Homebrew installs are not nudged by this periodic notice (npm alone cannot tell whether the formula has published the new version yet) — run vox upgrade or brew outdated for accurate Homebrew guidance. Turn it off with:

VOX_NO_UPDATE_NOTIFIER=1 vox …

macOS code signing

Official macOS binaries are signed with the company Developer ID Application identity, with a stable signing identity across builds:

Identifier=ai.vox.cli
TeamIdentifier=Z47Q5G9FA2
Authority=Developer ID Application: Fleek Corp. (Z47Q5G9FA2)

Because the identity is stable, the macOS Keychain "Always Allow" choice keeps applying across brew upgrades instead of re-prompting on every update. The first release that moves to the company Developer ID may prompt once (the identity changed from the previous one); after that it stays quiet while the identity is unchanged. This phase ships a Developer ID signature, not Apple notarization. Inspect it with codesign -dvvv "$(which vox)".

Support

• Homepage: https://www.tryvox.co
• Documentation: https://docs.tryvox.co
• npm package: https://www.npmjs.com/package/@vox-ai/cli

Licensed under the MIT License.