CLI Commands

The vole CLI is the primary interface for managing your OpenVole agent.

TIP

Install with npm install -g openvole (the package is openvole; the command is vole). To run without installing: npx openvole <command> — not npx vole, which is an unrelated package.

Removed commands

The single-engine commands vole init, vole start, and vole run have been removed. OpenVole now runs as a server — use vole serve and manage agents as spaces (each its own config, paws, identity, and data).

Dashboard & Spaces

vole serve

Start the control-plane dashboard — one web server that manages all your agents ("spaces") from the browser. This is the primary way to run and operate OpenVole.

vole serve

By default it listens on http://localhost:3000; set VOLE_DASHBOARD_PORT to change the port.

On first run it generates a session token (persisted at <root>/.openvole/dashboard-token, or supply VOLE_DASHBOARD_TOKEN) and prints a tokenized URL — open that URL; the token is required to reach the dashboard, its WebSocket, and panel routes. It binds all interfaces (0.0.0.0) by default; set VOLE_DASHBOARD_HOST=127.0.0.1 to restrict it to localhost. See Security › Dashboard / Control Plane.

Root resolution — vole serve operates on an OpenVole root directory (which holds a spaces.json registry). The root is resolved in this order:

1. VOLE_HOME if set — an explicit override that always wins.
2. Otherwise the current directory, if it is already a root (contains spaces.json).
3. Otherwise the current directory, if it is empty (ignoring .DS_Store, .git, .gitignore) — it becomes a new root.
4. Otherwise it refuses to start with a clear error. If a legacy ~/.openvole with spaces exists, it prints how to reach it.

# Use a dedicated directory as your root
mkdir ~/agents && cd ~/agents && vole serve

# Or pin a fixed root from anywhere
VOLE_HOME=~/agents vole serve

NOTE

The implicit global ~/.openvole root (used regardless of the current directory) is gone. If your spaces live there, run cd ~/.openvole && vole serve or VOLE_HOME=~/.openvole vole serve.

See the Dashboard guide for the full walkthrough.

vole space

Manage spaces from the CLI. (The dashboard's space switcher does the same things visually.)

Command	Description
vole space create <name>	Scaffold a new space (clones your template if set).
vole space template	Create or locate the template that new spaces clone.
vole space list	List spaces and their running status.
vole space status [name]	Show live status (pid, port).
vole space start <name>	Start a space's engine (its own process).
vole space stop <name> | --all	Stop a space (or all spaces).
vole space switch <name>	Set the active space.
vole space remove <name> [--purge]	Remove a space. Add --purge to delete its files on disk.

vole space create research
vole space start research
vole space list

WARNING

vole space remove <name> removes the space from the registry but keeps its files. Add --purge to permanently delete the space's directory (config, identity, installed paws, data). Deleting a space from the dashboard is equivalent to --purge.

Paw Management

vole paw add

Install a Paw from npm and add it to your config.

vole paw add @openvole/paw-telegram
vole paw add @openvole/paw-browser

vole paw remove

Remove an installed Paw.

vole paw remove @openvole/paw-telegram

vole paw list

List all loaded Paws.

vole paw list

vole paw create

Scaffold a new Paw project.

vole paw create my-custom-paw

Skill Management

vole skill add

Add a local skill.

vole skill add my-skill

vole skill remove

Remove a skill.

vole skill remove my-skill

vole skill list

List all loaded skills.

vole skill list

vole skill create

Create a new local skill with a template SKILL.md.

vole skill create email-triage

VoleHub

VoleHub is OpenVole's skill registry. Installs pull every bundled file (SKILL.md + scripts/references) and verify each against a per-file SHA-256 in the registry's INDEX.json.

vole skill install

Install a skill (and all its files) from VoleHub.

vole skill install resolve-autocut

vole skill hub / vole skill uninstall

List installed VoleHub skills, or remove one.

vole skill hub
vole skill uninstall resolve-autocut

vole skill publish

Print a skill's files manifest (paths + SHA-256 hashes) to add to INDEX.json when contributing to VoleHub.

vole skill publish ./skills/my-skill

ClawHub

vole clawhub install

Install a skill from ClawHub.

vole clawhub install summarize

vole clawhub remove

Remove an installed ClawHub skill.

vole clawhub remove summarize

vole clawhub search

Search for skills on ClawHub.

vole clawhub search email

Tool Commands

vole tool list

List all registered tools (from manifests, no paw spawning).

vole tool list

Use --live to boot the full engine and discover MCP tools:

vole tool list --live

vole tool call

Call a tool directly without going through the Brain. Useful for debugging.

vole tool call list_schedules

VoleNet

Distributed agent networking. See Configuration → net for the config fields.

vole net init

Generate an Ed25519 keypair for this instance. Pass an optional name.

vole net init my-instance

vole net show-key

Display this instance's public key — share it with peers so they can trust you.

vole net show-key

vole net trust

Trust a peer's public key (paste the string from their vole net show-key).

vole net trust "vole-ed25519 ..."

vole net join

Join a public mesh hub: registers with the hub over HTTP, trusts its key, and adds it as a peer in vole.config.json. Use --name to set the name advertised to the hub.

vole net join https://hub.example.com:9700 --name my-laptop

vole net revoke

Remove trust for a peer by instance ID or key.

vole net revoke <instance-id-or-key>

vole net peers

List trusted peers.

vole net peers

vole net status

Show a network status overview.

vole net status

Utility Commands

vole upgrade

Upgrade OpenVole and all installed paws to their latest versions.

vole upgrade

vole --version

Show the installed OpenVole version.

vole --version