Skip to content

CLI surface

The weft binary is HashiCorp-style : weft agent boots the daemon, every other subcommand is a client. Every subcommand uses cobra (no flag stdlib anywhere — convention, see Contributing).

Source for every subcommand lives under cmd/weft/ in the openweft/weft repo.

Top-level commands

weft agent                         # long-lived control daemon

# Tenancy
weft project                       # tenant projects
weft user                          # user lifecycle (usually via OIDC IdP)

# Workloads — microvm is the default execution path ; instance is the escape hatch
weft microvm                       # tenant microVMs (OCI image -> fast-boot micro-VM, shared kernel)
weft instance                      # classic full VM ; for Windows / BSD guests, VM-image network appliances, custom kernels

# Storage
weft volume                        # block volumes (RWO)
weft share                         # POSIX shares (RWX)

# Networking
weft network                       # overlay networks
weft securitygroup                 # L3/L4 rules
weft overlaycmd                    # overlay debug commands

# Compute envelope
weft flavor                        # compute flavours (cpu/mem/disk)

# Platform
weft image                         # OCI image cache
weft script                        # provisioning scripts
weft host                          # hypervisor inventory
weft infra                         # platform services
weft events                        # live event stream

# Cluster lifecycle
weft up                            # bring up from cluster.hcl
weft down                          # tear down

# Auth + admin
weft login                         # OIDC auth
weft admin                         # platform admin
weft clean                         # garbage-collect orphaned state
weft wait                          # block until a resource reaches a state

Detailed docs for the two most-used subcommands :

weft microvm quick reference

weft microvm run IMAGE[:TAG] [-- CMD...]   # boot a VM from OCI image
weft microvm ls                            # list VMs
weft microvm logs NAME                     # tail guest serial
weft microvm rm NAME...                    # stop + remove
weft microvm pull IMAGE[:TAG]              # warm the image cache
weft microvm pull-kernel REF               # pull the microVM kernel OCI artifact
weft microvm init-build INIT_BINARY        # build the single-binary initrd
weft microvm pod-init-build                # build the pod-mode initrd

See weft microvm for the full flag matrix.

weft volume

weft volume create  NAME --size <bytes> [--type block|file] [--source /dev/...] [--flavor <name>]
weft volume ls
weft volume rm      NAME
weft volume attach  NAME --vm <name>
weft volume detach  NAME --vm <name>

The default backend for --type block (or no --type) is Longhorn — replicated block storage with snapshots and backups. Escape hatches : --source /dev/nvmeXn1 passes a host device straight through (raw bandwidth, no replication), --type file is a host-side image. All three surface inside the guest as virtio-blk.

A weft volume snapshot subcommand is on the roadmap to wrap Longhorn's snapshot path ; the reflink CoW described in Backup & restore covers the file/passthrough escape hatches. Today the operator runs cp --reflink=always (Linux) or cp -c (APFS) against the volume image directly for the non-Longhorn paths.

weft flavor

weft flavor set NAME --vcpu N --ram <bytes> [--ephemeral <bytes>] [--gpu N --gpu-type MODEL]
weft flavor ls
weft flavor rm NAME

Flavors are the compute envelope — vCPU, RAM, optional GPU(s), optional ephemeral scratch cap. GPUs are scheduled like vCPU / RAM : declare a count and a model, the scheduler picks a host with that many free matching cards, the hypervisor driver binds them via VFIO PCI passthrough on QEMU/KVM.

$ weft flavor set ai-h200 --vcpu 32 --ram 256Gi --gpu 1 --gpu-type nvidia-h200          --ephemeral 400Gi
$ weft flavor set ws-rtx6 --vcpu 16 --ram 96Gi  --gpu 1 --gpu-type nvidia-rtx-6000-ada  --ephemeral 200Gi

Supported --gpu-type values today : nvidia-h200 (datacenter, MIG-capable — slices surface as just another GPU type to the scheduler) and nvidia-rtx-6000-ada (workstation, whole-card bind). The Apple-VZ driver doesn't expose discrete GPUs to guests, so GPU flavors are host-feature-gated.

weft up / weft down

weft up   -f cluster.hcl --apply       # bring up from HCL
weft up   -f cluster.hcl --dry-run     # preview the plan
weft down -f cluster.hcl --apply       # tear down

Convergent — re-running weft up reconciles against declared state instead of duplicating resources. See 3-DC bring-up.

weft infra

weft infra bootstrap                       # deploy all infra services
weft infra bootstrap --services etcd,dex   # subset
weft infra status                          # health + placement
weft infra validate                        # check plans
weft infra deploy <service>                # force-redeploy one

See Infra services.

weft events

weft events --vm  <name>           # subscribe to a single VM
weft events --project <name>       # subscribe to a project
weft events                        # all events the caller can see (RBAC-scoped)

Wraps a gRPC streaming RPC ; the same subjects the dashboard's activity feed subscribes to. See Observability.

weft login

weft login                                  # opens browser, completes OIDC dance
weft login --provider https://dex.weft.lan  # explicit issuer

Token cache at $XDG_CONFIG_HOME/weft/credentials.json (mode 0600).

Global flags

Flag Default Notes
--socket unix:///run/weft/agent.sock Local agent socket ; override for cross-host CLI use.
--server discovered via SRV Explicit gRPC endpoint. Format host:port.
--project empty (= caller's default) Project namespace for the call.
--insecure false Skip TLS verification. Lab clusters only.
--debug false Verbose logging on the client side.

Source

Every subcommand's source lives under cmd/weft/<subcommand>/. The cobra command tree is wired in cmd/weft/main.go. For a complete flag matrix run :

$ weft <subcommand> --help
$ weft help <subcommand>

Cross-references