# Command line reference

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

Source: https://docs.vlayers.ai/developers/sdks/cli

Kind: Reference

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.

```bash
npm install @voicelayer/sdk
```

## Keys 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](https://docs.vlayers.ai/developers/sdks/direct) handler with a handover | `npx tsx agent.ts` |
| `hosted` | An agent [VoiceLayer hosts](https://docs.vlayers.ai/developers/sdks/hosting): one API endpoint and a store collection | `npx voicelayer manifest ./agent.ts --check --offline` |
| `channel` | A [custom channel](https://docs.vlayers.ai/developers/sdks/custom-channels): 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](https://docs.vlayers.ai/developers/sdks/hosting).

## 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>` |

See [Build your own channel](https://docs.vlayers.ai/developers/sdks/custom-channels).

## 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.
