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; every agent is fully isolated (its own config, paws, identity, and data).

Dashboard & Agents

`vole serve`

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

bash

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 an agents.json registry; a legacy spaces.json root is recognized too). The root is resolved in this order:

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

bash

# 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 agents live there, run cd ~/.openvole && vole serve or VOLE_HOME=~/.openvole vole serve.

See the Dashboard guide for the full walkthrough.

`vole agent`

Manage agents from the CLI. (The dashboard's agent switcher does the same things visually.) These commands operate on the same root vole serve resolves — VOLE_HOME if set, else the current directory when it is a root or empty — so run them from your server directory.

NOTE

Agents were called spaces before v4.6. vole space … still works as a deprecated alias, a legacy spaces.json registry is read transparently (the next write migrates it to agents.json), and an existing space-template is still honored.

Command	Description
`vole agent create <name>`	Scaffold a new agent (clones your template if set). Add `--orchestrator` to let it manage its siblings.
`vole agent orchestrate <name> [on\|off]`	Grant or revoke an agent's authority to manage its siblings (see below).
`vole agent template`	Create or locate the template that new agents clone.
`vole agent list`	List agents and their running status.
`vole agent status [name]`	Show live status (pid, port).
`vole agent start <name>`	Start an agent's engine (its own process).
`vole agent stop <name> \| --all`	Stop an agent (or all agents).
`vole agent switch <name>`	Set the active agent.
`vole agent rename <name> <new name>`	Rename an agent's display name. Its id, directory, and MCP endpoint stay put, so a running agent is unaffected.
`vole agent remove <name> [--purge]`	Remove an agent. Add `--purge` to delete its files on disk.

bash

vole agent create research
vole agent start research
vole agent list

WARNING

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

Orchestrator agents

An agent flagged as orchestrator gets a set of agent_* tools when it runs under vole serve: list siblings, submit tasks to them, read/write their config and identity files, restart/start/stop them, and create new agents. This lets one agent supervise the others — pair it with the vole-orchestrate skill from VoleHub for the playbook.

The flag lives in the server's agents.json registry — outside every agent's sandbox — and the control plane re-checks it on every request, so off takes effect immediately. Granting (on) requires restarting the agent under vole serve.
Guardrails: an orchestrator cannot stop/start/restart itself, cannot remove agents at all, and config writes go through the same sandbox-weakening refusal as the dashboard.
Detached agents (vole agent start) have no control channel — orchestrator tools require vole serve.
Creating (or granting) an orchestrator seeds an orchestrator AGENT.md brief — unless you've already customized the identity, which is never overwritten. The system prompt also states the authority whenever the agent_* tools are registered, so the agent always knows what it is.

Upgrading

bash

vole upgrade

Run at a vole server root — the directory holding agents.json — it upgrades the openvole packages in every registered agent and prints a per-agent summary. Run inside a single agent directory, it upgrades just that agent.

This matters because paws are installed per agent: a fix published to npm reaches an agent only when someone upgrades that directory, so on a multi-agent server it was easy to end up with agents quietly running old paws — which looks like a live bug rather than a missed upgrade.

Paws load when an engine starts, so restart the server for running agents to pick up an upgrade.

A customized BRAIN.md is never overwritten. If the package ships a newer default, it is written alongside as BRAIN.md.dist and your prompt is left as-is.

Projects & Tasks

What the agent is working on. See Projects & Tasks for the full model.

bash

vole project list [--all]              # projects in this agent's workspace
vole project scan <path>               # inspect a directory before adopting it (read-only)
vole project create <id> [--name <n>] [--kind <k>] [--root <path>]
vole project open <id>                 # manifest, CONTEXT.md and open tasks
vole project archive <id>              # retire a project, keeping all files and history

vole task list [projectId] [--state <s>]         # default: open tasks
vole task add <projectId> <goal...> [--criteria "..."] [--priority <n>]
vole task next [projectId]             # the next queued task
vole task update <projectId> <taskId> --state <s> [--note "..."]
vole task cancel <projectId> <taskId>

--kind is one of code, writing, media, research, general.

--root attaches the project to files outside the workspace. It must already resolve inside security.allowedPaths; if it does not, the command fails and names the path to grant.

Give every task criteria you can check — a task moves running → verifying → done and cannot be marked done without passing verification against them.

These commands read project files directly, so they work while the agent is stopped.

Paw Management

`vole paw add`

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

bash

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

`vole paw remove`

Remove an installed Paw.

bash

vole paw remove @openvole/paw-telegram

`vole paw list`

List all loaded Paws.

bash

vole paw list

`vole paw create`

Scaffold a new Paw project.

bash

vole paw create my-custom-paw

Skill Management

`vole skill add`

Add a local skill.

bash

vole skill add my-skill

`vole skill remove`

Remove a skill.

bash

vole skill remove my-skill

`vole skill list`

List all loaded skills.

bash

vole skill list

`vole skill create`

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

bash

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.

bash

vole skill install resolve-autocut

`vole skill hub` / `vole skill uninstall`

List installed VoleHub skills, or remove one.

bash

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.

bash

vole skill publish ./skills/my-skill

ClawHub

`vole clawhub install`

Install a skill from ClawHub.

bash

vole clawhub install summarize

`vole clawhub remove`

Remove an installed ClawHub skill.

bash

vole clawhub remove summarize

`vole clawhub search`

Search for skills on ClawHub.

bash

vole clawhub search email

Tool Commands

`vole tool list`

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

bash

vole tool list

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

bash

vole tool list --live

`vole tool call`

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

bash

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.

bash

vole net init my-instance

`vole net show-key`

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

bash

vole net show-key

`vole net trust`

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

bash

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.

bash

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

`vole net pair`

Connect two nodes you (or two cooperating operators) run — the easy alternative to the manual show-key/trust exchange, with consent on both ends:

bash

# On node A (the initiator):
vole net pair http://192.168.1.20:9700 --name gaming-pc [--note "same fleet"] [--yes]

The initiator fetches the peer's public key from /volenet/info, shows its fingerprint for confirmation, trusts it, adds a net.peers entry — then files a pair request that the other side's operator must accept (dashboard VoleNet tab → Pair requests, or vole net pair accept <name>; vole net pair list / deny also exist). Nothing is trusted on the remote side until they accept; acceptance takes effect live (no restart on the acceptor). Restart the initiating agent if it was running so it picks up the new peer entry.

`vole net send`

Send a file to a peer, end-to-end encrypted (VoleDrop). Requires a running vole serve on this machine — the transfer executes inside the named agent's engine, so it keeps running after the CLI exits.

bash

vole net send recording.mkv --to video-editor --agent gaming-pc [--note "ep 12"] [--wait]

--wait polls until the transfer reaches a terminal state. The receiver must consent (its net.files.acceptFrom, or an explicit accept in its dashboard/tools).

`vole net revoke`

Remove trust for a peer by instance ID or key.

bash

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

`vole net peers`

List trusted peers.

bash

vole net peers

`vole net status`

Show a network status overview.

bash

vole net status

Utility Commands

`vole upgrade`

Upgrade OpenVole and all installed paws to their latest versions.

bash

vole upgrade

`vole --version`

Show the installed OpenVole version.

bash

vole --version

CLI Commands ​

Dashboard & Agents ​

vole serve ​

vole agent ​

Orchestrator agents ​

Upgrading ​

Projects & Tasks ​

Paw Management ​

vole paw add ​

vole paw remove ​

vole paw list ​

vole paw create ​

Skill Management ​

vole skill add ​

vole skill remove ​

vole skill list ​

vole skill create ​

VoleHub ​

vole skill install ​

vole skill hub / vole skill uninstall ​

vole skill publish ​

ClawHub ​

vole clawhub install ​

vole clawhub remove ​

vole clawhub search ​

Tool Commands ​

vole tool list ​

vole tool call ​

VoleNet ​

vole net init ​

vole net show-key ​

vole net trust ​

vole net join ​

vole net pair ​

vole net send ​

vole net revoke ​

vole net peers ​

vole net status ​

Utility Commands ​

vole upgrade ​

vole --version ​

CLI Commands

Dashboard & Agents

`vole serve`

`vole agent`

Orchestrator agents

Upgrading

Projects & Tasks

Paw Management

`vole paw add`

`vole paw remove`

`vole paw list`

`vole paw create`

Skill Management

`vole skill add`

`vole skill remove`

`vole skill list`

`vole skill create`

VoleHub

`vole skill install`

`vole skill hub` / `vole skill uninstall`

`vole skill publish`

ClawHub

`vole clawhub install`

`vole clawhub remove`

`vole clawhub search`

Tool Commands

`vole tool list`

`vole tool call`

VoleNet

`vole net init`

`vole net show-key`

`vole net trust`

`vole net join`

`vole net pair`

`vole net send`

`vole net revoke`

`vole net peers`

`vole net status`

Utility Commands

`vole upgrade`

`vole --version`