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/sdkKeys and settings
| Setting | What it is |
|---|---|
VOICELAYER_API_KEY | A project API key (vl_…). Commands that upload, publish, list or send use it. A worker key (vlw_…) is refused here. |
VOICELAYER_API_URL | The API address. Default https://api.vlayers.ai. It must be https://; only localhost may use http://. |
VOICELAYER_WORKER_KEY | A worker key (vlw_…) for one environment. Only a worker uses it, not the CLI. |
VOICELAYER_EDGE_URL | Where workers connect. Default wss://edge.vlayers.ai/worker. |
VOICELAYER_LOCK_FILE | Where the lock file is. Default ./voicelayer.lock.json. |
VOICELAYER_LOG | Worker log level: debug, info (default), warn, error or silent. Logs go to stderr. |
VOICELAYER_WORKER_CAPACITY | How many calls one worker takes at once. Default 20. |
VOICELAYER_DASHBOARD_URL, VOICELAYER_OAUTH_ISSUER, VOICELAYER_OAUTH_CLIENT_ID | For 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
| Flag | Meaning |
|---|---|
--api-key <key> | A project API key |
--api-url <url> | The API address |
--agent-id <uuid> | The agent, when there is no lock file |
--json | Machine-readable output, where a command supports it |
--help, -h | Print the usage |
--version, -v | Print the version |
Start a project
| Command | What 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.
| Template | What you get | Run it with |
|---|---|---|
voice | A phone agent: greeting, prompt, one tool, a transfer to a person | npx voicelayer dev ./agent.ts |
text | A messaging bot: one direct mode handler with a handover | npx tsx agent.ts |
hosted | An agent VoiceLayer hosts: one API endpoint and a store collection | npx voicelayer manifest ./agent.ts --check --offline |
channel | A custom channel: a webhook in, a reply template out | npx 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
| Command | What 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
| Command | What it does |
|---|---|
deploy <entry...> --env <env> --hosted | Build 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> |
rooms | List 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
| Command | What 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> |
Messages and events
| Command | What it does |
|---|---|
login --api-key <key> | Check the key against the API and store it. --api-url <url> |
logout | Remove 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 |
listen | Print 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 tail | Your 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
| Command | What 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 |
status | The line, the connector service and the assistant |
tools | The VoiceLayer tools the assistant can use on its line, and why any cannot |
disconnect | Stop the connector, undo what connect changed and revoke this device |
mcp | Started 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.