Commands

create

Create a new VM or restart a stopped VM:

weave create <name> [--cpus <count>] [--memory <GiB>] [--ttl <duration>] [--template <name-or-path>] [--fresh] [--mount <directory>...]

The default TTL is 10 minutes. A template and --fresh only affect newly created VMs, not restarted VMs. Pass one or more existing directories after --mount to expose them in the guest. Mounts are read-only by default; append :w to a directory to make it writable. With no --mount flag, the VM has no host mounts.

Weave keeps compatible bases for the default, Node.js, and Python environments for three days. Subsequent creates clone the base instead of provisioning the same environment again. Pass --fresh to bypass the base and provision the new VM from scratch. This does not delete or replace an existing cached base. Custom Lima YAML templates are always provisioned from scratch.

During cold provisioning, Weave reports VM image, package-manager, and container-tooling progress. Interactive terminals also show elapsed time; redirected and CI output prints each changed stage as a separate line.

For backward compatibility, create continues to restart stopped VMs and can update their CPU, memory, or mount configuration.

start

Start an existing stopped VM without changing its virtual disk:

weave start <name> [--ttl <duration>] [--mount <directory>...]

Starting assigns a new 10-minute TTL by default. Set --ttl to choose another duration. Pass multiple existing host directories after --mount, optionally with Lima's :w suffix for writable access. Each invocation replaces the VM's previous mounts; with no --mount flag, Weave removes all host mounts. The command reports an error when the VM does not exist, is already running, or is in another non-stopped lifecycle state.

ls

List VMs, their status, and remaining TTL:

weave ls

weave list is an alias.

ssh

Open an interactive shell in a running VM:

weave ssh <name>

port

Publish a guest TCP port on parent localhost:

weave port add <name> <parent-port>:<guest-port>

For example, expose an application listening on guest port 3000 through parent port 8080:

weave port add dev 8080:3000

Mappings bind to 127.0.0.1 on the parent and persist across stops and starts. Multiple mappings can be added to the same VM. List or remove mappings with:

weave port ls dev
weave port remove dev 8080

weave port list and weave port rm are aliases. Changing mappings on a running VM briefly restarts it because Lima cannot reload forwarding rules in place. Weave preserves the VM's existing absolute TTL expiry during that restart.

shell

Run a command in a running VM:

weave shell <name> "<command>"

stop

Stop a VM without deleting it:

weave stop <name>

kill

Permanently delete a VM and its virtual disk:

weave kill <name>

skills

Print version-matched instructions for AI agents:

weave skills list
weave skills get core
weave skills get create
weave skills get copy
weave skills get lifecycle
weave skills get isolation
weave skills get network

The repository includes a small discovery skill that can be installed with:

npx skills add https://github.com/akshat-OwO/weave

The installed SKILL.md points agents to these embedded sections so its guidance stays aligned with the installed CLI release.

upgrade

Upgrade the installed CLI to the newest stable release:

weave upgrade

Weave compares all stable releases and selects the newest version, including newer minor or major versions. The command never downgrades a newer installation and clearly reports when no update is needed.

The update is downloaded before the installed executable is touched. Weave stages the new executable beside the existing one and replaces it atomically, so a download or replacement failure leaves the working binary in place. The default installation under ~/.local/bin does not require administrator access. A custom or legacy installation under a privileged directory such as /usr/local/bin may prompt for it.

On Windows, the running executable cannot replace itself. Weave starts a detached helper that waits for the CLI process to exit and then atomically moves the verified update into place. The command reports the recovery-log path used if that deferred operation fails.

uninstall

Stop every running Weave-managed VM and remove the installed CLI:

weave uninstall

Weave discovers VMs from its dedicated Lima state directory. If any running VM cannot be stopped, uninstall aborts and leaves the CLI installed so you can resolve the failure and retry. The default installation under ~/.local/bin can be removed without administrator access. Removing a custom or legacy installation from a privileged directory may prompt for it.

If no managed state directory exists, uninstall skips Lima discovery without extracting the bundled runtime. On Windows, a detached helper waits for the CLI process to exit before deleting the executable and records any deferred failure at the reported recovery-log path.

Run weave <command> --help for command-specific examples and options.