Reference

Command line reference

Every voicelayer command and flag, with the environment variables and the file where login keeps your key.

The voicelayer command ships with @voicelayer/sdk. Run it with npx voicelayer <command>, or install the package and use ./node_modules/.bin/voicelayer. voicelayer --help prints the same list as this page, and voicelayer --version prints the version.

npm install @voicelayer/sdk

Keys and settings

SettingWhat it is
VOICELAYER_API_KEYA project API key (vl_…). Commands that upload, publish, list or send use it. A worker key (vlw_…) is refused here.
VOICELAYER_API_URLThe API address. Default https://api.vlayers.ai. It must be https://; only localhost may use http://.
VOICELAYER_WORKER_KEYA worker key (vlw_…) for one environment. Only a worker uses it, not the CLI.
VOICELAYER_EDGE_URLWhere workers connect. Default wss://edge.vlayers.ai/worker.
VOICELAYER_LOCK_FILEWhere the lock file is. Default ./voicelayer.lock.json.
VOICELAYER_LOGWorker log level: debug, info (default), warn, error or silent. Logs go to stderr.
VOICELAYER_WORKER_CAPACITYHow many calls one worker takes at once. Default 20.
VOICELAYER_DASHBOARD_URL, VOICELAYER_OAUTH_ISSUER, VOICELAYER_OAUTH_CLIENT_IDFor connect against a local or staging setup. Leave them unset.

The key is taken from, in order: --api-key, VOICELAYER_API_KEY, the key login stored. --api-url and VOICELAYER_API_URL work the same way.

login stores the key and URL in $XDG_CONFIG_HOME/voicelayer/config.json, or ~/.config/voicelayer/config.json when XDG_CONFIG_HOME is not set. The file has mode 0600.

Flags every command takes

FlagMeaning
--api-key <key>A project API key
--api-url <url>The API address
--agent-id <uuid>The agent, when there is no lock file
--jsonMachine-readable output, where a command supports it
--help, -hPrint the usage
--version, -vPrint the version

Start a project

CommandWhat it does
init [dir]Write a project that runs in two commands: package.json (pinned to this SDK version, with dev, test, typecheck and deploy scripts), tsconfig.json, agent.ts, a passing agent.test.ts, .env.example and .gitignore. No network, no install. Flags: --template voice|text|hosted|channel (default voice), --force, --json

init with no directory writes into the current one. It refuses a directory that is not empty (a .git folder does not count). --force writes the files that are missing and still never replaces a file that differs. It prints the commands to run next.

TemplateWhat you getRun it with
voiceA phone agent: greeting, prompt, one tool, a transfer to a personnpx voicelayer dev ./agent.ts
textA messaging bot: one direct mode handler with a handovernpx tsx agent.ts
hostedAn agent VoiceLayer hosts: one API endpoint and a store collectionnpx voicelayer manifest ./agent.ts --check --offline
channelA custom channel: a webhook in, a reply template outnpx voicelayer channel manifest ./agent.ts

To run init before anything is installed, use npx @voicelayer/sdk init my-agent: the package has a single command, so npx runs it.

Build and run agents

CommandWhat it does
dev <entry...>Serve your handlers against the dev environment and publish. Watches the files and restarts. Flags: --no-watch, --edge-url <wss://…>, --capacity <n>
manifest <entry...>Print the manifest. Flags: --json, --check (run the upload's checks; online it also checks the model catalog), --offline (skip the online half), --build <id>
deploy <entry...> --env <env>Upload the manifest, write voicelayer.lock.json, wait for workers, publish. Flags: --no-publish, --min-workers <n> (default 1), --build <id>, --lock <file>, --note <text>, --timeout <seconds> (default 600)
publish --env <env>Publish an uploaded build once its workers are connected. Flags: --manifest <hash> (a specific build; publishing an older one is a rollback), --agent <name>, --min-workers <n>, --lock <file>, --timeout <seconds>
versions --env <env>Published versions and uploaded builds, with connected workers
versions discard --env <env> --manifest <hash>Discard an uploaded build. --agent <name> picks the agent.

--env is dev, stg or prd. A deploy's build id is --build, else the git commit when the tree is clean, else a content hash.

--poll-ms <ms> (default 2000) sets how often the waiting commands check. --timeout <seconds> applies to every waiting command.

Hosted agents

CommandWhat it does
deploy <entry...> --env <env> --hostedBuild your project into an image, push it, submit the version by digest and wait for its room. --image <digest> submits an image you built elsewhere, in any language. A tag is refused. --image alone implies --hosted.
serve <entry>Run your agent as a room does: the SDK's room server on $PORT. --port <n>
image test <image> <entry>Run the image locally against the platform's conformance calls for your agent's manifest. --port <n> (8080), --conformance-image <ref>
roomsList your hosted rooms. --agent <agentId>, --env dev|stg|prd, --all (include ended ones from the last week)
rooms drain <roomId>Stop sending a room new work. It ends when its current work is done.
logs <roomId>A room's container logs: --container process|shim, --stdout or --stderr, --since <iso>, --grep <text>, --tail <n> (200), --follow or -f. Needs the room_logs:read scope; each read is audited.

See Run your agent on VoiceLayer.

Channels

CommandWhat it does
channel manifest <entry>Print the manifest of the channel you defined with defineChannel, checked as the API checks it. --json
channel serve <entry>Run your channel as a connector room does. --port <n>
channel deploy <entry>Create the connector, build and push its image, submit the version and wait for its room. --image <digest>, --note <text>, --timeout <seconds>

See Build your own channel.

Messages and events

CommandWhat it does
login --api-key <key>Check the key against the API and store it. --api-url <url>
logoutRemove the stored key
messages send --channel <c> --to <address> --text <text>Send a message. --from-number <id> or --from-binding <id> picks the sender, --idempotency-key <k> makes a retry safe
listenPrint events as they happen. --types message.*, --channel <c>, --forward http://localhost:<port>/<path> re-POSTs each event to your local app, signed like a webhook with a secret printed at start. --forward accepts localhost only.
logs tailYour API requests as they happen: method, route, status, error, latency. --errors, --key <api key id>, --poll-ms <ms>
test inbound --channel <c> --from <address> --text <text>Simulate a person writing. Needs a test key. --from is a reserved address (+15550100 to +15550199, test-<n>, <name>@test.vlayers.ai). --to <address> picks your sender. Prints the conversation id.

Give an assistant its own line

CommandWhat it does
connect <hermes|openclaw>Sign in, edit the assistant's configuration and run the connector, so the assistant has its own phone number. --docker, --setup-key <key>, --name <device name>, --yes or -y
statusThe line, the connector service and the assistant
toolsThe VoiceLayer tools the assistant can use on its line, and why any cannot
disconnectStop the connector, undo what connect changed and revoke this device
mcpStarted by the assistant, not by you: a stdio MCP proxy to your line's tools

Exit codes

0 means the command did what you asked. 1 means it failed or the arguments were wrong, and the message says why. deploy --hosted and channel deploy return 2 when they stopped waiting before the version published; the version stays submitted.

On this page