# Volt CLI Reference

Complete command reference for Volt. Generated from actual `--help` output.

## Global Flags

Available on every command:

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--help` | `-h` | | | Show help for the command |
| `--output` | `-o` | string | `table` | Output format: `table`, `json`, `yaml`, `wide` |
| `--quiet` | `-q` | | | Suppress non-essential output |
| `--debug` | | | | Enable debug logging to stderr |
| `--no-color` | | | | Disable colored output |
| `--config` | | string | `/etc/volt/config.yaml` | Path to config file |
| `--timeout` | | int | `30` | Command timeout in seconds |
| `--backend` | | string | auto-detect | Container backend: `systemd` |

---

## Workload Commands

### `volt container` — Voltainer (systemd-nspawn)

Manage containers built on systemd-nspawn. Alias: `con`.

#### `volt container create`

Create a new container from an image.

```
volt container create [flags]
```

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--name` | | string | Container name (required) |
| `--image` | | string | Image name or path (required) |
| `--start` | | | Start container after creation |
| `--memory` | | string | Memory limit (e.g., `512M`, `2G`) |
| `--cpu` | | string | CPU shares/quota |
| `--network` | | string | Network bridge (default: `volt0`) |
| `--env` | `-e` | strings | Environment variables |
| `--volume` | `-v` | strings | Volume mounts (`host:container`) |

```bash
volt container create --name web --image ubuntu:24.04 --start
volt container create --name db --image debian:bookworm --memory 2G --start
volt container create --name api --image ubuntu:24.04 --cpu 200 --memory 1G -e "NODE_ENV=production" --start
```

#### `volt container list`

List containers. Alias: `ls`.

```bash
volt container list
volt container list -o json
volt container ls
```

#### `volt container start`

Start a stopped container.

```bash
volt container start web
```

#### `volt container stop`

Stop a running container (graceful SIGTERM, then SIGKILL).

```bash
volt container stop web
```

#### `volt container restart`

Restart a container.

```bash
volt container restart web
```

#### `volt container kill`

Send a signal to a container (default: SIGKILL).

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--signal` | string | `SIGKILL` | Signal to send |

```bash
volt container kill web
volt container kill --signal SIGTERM web
```

#### `volt container exec`

Execute a command inside a running container.

```bash
volt container exec web -- nginx -t
volt container exec web -- ls -la /var/log
volt container exec db -- psql -U postgres
```

#### `volt container shell`

Open an interactive shell in a container (shortcut for `exec /bin/sh`).

```bash
volt container shell web
```

#### `volt container attach`

Attach to a container's main process (stdin/stdout/stderr).

```bash
volt container attach web
```

#### `volt container inspect`

Show detailed container configuration and state.

```bash
volt container inspect web
volt container inspect web -o json
```

#### `volt container logs`

View container logs from the systemd journal.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--follow` | `-f` | | Follow log output |
| `--tail` | | int | Number of lines from end |

```bash
volt container logs web
volt container logs -f web
volt container logs --tail 50 web
```

#### `volt container cp`

Copy files between host and container. Use `container_name:/path` for container paths.

```bash
volt container cp ./config.yaml web:/etc/app/config.yaml
volt container cp web:/var/log/app.log ./app.log
```

#### `volt container rename`

Rename a container.

```bash
volt container rename old-name new-name
```

#### `volt container update`

Update resource limits on a running container.

| Flag | Type | Description |
|------|------|-------------|
| `--memory` | string | New memory limit |
| `--cpu` | string | New CPU quota |

```bash
volt container update web --memory 1G
volt container update web --cpu 200
```

#### `volt container export`

Export container filesystem as a tarball.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--output` | `-O` | string | Output file path |

```bash
volt container export web
volt container export web --output web-backup.tar.gz
```

#### `volt container delete`

Delete a container. Alias: `rm`.

| Flag | Short | Description |
|------|-------|-------------|
| `--force` | `-f` | Force delete (stop if running) |

```bash
volt container delete web
volt container rm web
volt container delete -f web
```

---

### `volt vm` — Voltvisor (KVM)

Create, manage, and destroy virtual machines.

#### `volt vm create`

Create a new VM.

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--image` | `-i` | string | `volt/server` | VM image |
| `--cpu` | `-c` | int | `1` | CPU cores |
| `--memory` | `-m` | string | `256M` | Memory |
| `--kernel` | `-k` | string | `server` | Kernel profile (`server\|desktop\|rt\|minimal\|dev`) |
| `--network` | `-n` | string | `default` | Network name |
| `--attach` | | strings | | Attach storage (repeatable) |
| `--env` | `-e` | strings | | Environment variables |
| `--ode-profile` | | string | | ODE profile for desktop VMs |

```bash
volt vm create myvm
volt vm create db-primary -c 4 -m 8G -i armoredgate/ubuntu-24.04
volt vm create rt-worker -c 2 -m 4G -k rt
```

#### `volt vm list`

List all VMs.

```bash
volt vm list
volt vm list -o json
```

#### `volt vm start`

Start a VM.

```bash
volt vm start myvm
```

#### `volt vm stop`

Stop a VM (ACPI shutdown).

```bash
volt vm stop myvm
```

#### `volt vm destroy`

Destroy a VM and its resources.

```bash
volt vm destroy myvm
```

#### `volt vm ssh`

SSH into a VM by name.

```bash
volt vm ssh myvm
```

#### `volt vm exec`

Execute a command inside a VM.

```bash
volt vm exec myvm -- uname -a
```

#### `volt vm attach`

Attach storage to a VM.

```bash
volt vm attach myvm /path/to/disk.qcow2
```

---

### `volt desktop` — VDI Management

Create and manage desktop VMs with remote display.

#### `volt desktop create`

Create a desktop VM.

```bash
volt desktop create --name dev-workstation
```

#### `volt desktop list`

List desktop VMs.

```bash
volt desktop list
```

#### `volt desktop connect`

Connect to a desktop VM via remote display.

```bash
volt desktop connect dev-workstation
```

---

### `volt workload` — Unified Workload Management

Manage workloads across Voltainer containers, hybrid-native processes, and Voltvisor VMs. Alias: `wl`.

The workload abstraction layer provides a single interface for lifecycle operations regardless of backend type and execution mode. Each command auto-detects whether a workload is a container, hybrid-native, or VM and delegates to the appropriate backend.

**Execution Modes:**

| Mode | Description |
|------|-------------|
| `container` | Voltainer (systemd-nspawn) — full OS container isolation |
| `hybrid-native` | Landlock LSM + seccomp-bpf + cgroups v2 — no namespace overhead |
| `hybrid-kvm` | Voltvisor (KVM) micro-VM — hardware-level isolation |
| `hybrid-emulated` | QEMU user-mode emulation — cross-arch workloads |

Used by the Volt Edge wake proxy and Sleep Controller for scale-to-zero operations. Supports freeze/thaw for sub-second wake times and full start/stop for maximum resource savings.

#### `volt workload create`

Create a new workload.

```bash
volt workload create --name my-app --mode hybrid-native --manifest app.toml
```

#### `volt workload list`

List all workloads with state and mode.

```bash
volt workload list
```

#### `volt workload status`

Show workload status (state, mode, uptime, resources).

```bash
volt workload status my-app
```

#### `volt workload start`

Start a stopped workload.

```bash
volt workload start my-app
```

#### `volt workload stop`

Stop a running or frozen workload.

```bash
volt workload stop my-app
```

#### `volt workload restart`

Restart a workload.

```bash
volt workload restart my-app
```

#### `volt workload freeze`

Freeze a running workload (preserve memory state for sub-second wake).

```bash
volt workload freeze my-app
```

#### `volt workload thaw`

Thaw a frozen workload (resume from preserved memory state).

```bash
volt workload thaw my-app
```

#### `volt workload toggle`

Toggle workload between execution modes.

```bash
volt workload toggle my-app --target-mode hybrid-native
```

#### `volt workload inspect`

Show detailed workload info.

```bash
volt workload inspect my-app
```

#### `volt workload manifest`

Validate a workload manifest.

```bash
volt workload manifest app.toml
```

---

### `volt service` — systemd Services

Manage systemd services. Alias: `svc`.

#### `volt service create`

Create a new systemd service unit file.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string | | Service name (required) |
| `--exec` | string | | Command to execute (required) |
| `--user` | string | | Run as user |
| `--group` | string | | Run as group |
| `--workdir` | string | | Working directory |
| `--restart` | string | `on-failure` | Restart policy: `no\|on-failure\|always\|on-success` |
| `--after` | string | | Start after this unit |
| `--description` | string | | Service description |
| `--env` | strings | | Environment variables (`KEY=VALUE`) |
| `--enable` | | | Enable service after creation |
| `--start` | | | Start service after creation |

```bash
volt service create --name myapp --exec /usr/bin/myapp
volt service create --name myapi --exec "/usr/bin/myapi --port 8080" \
  --user www-data --restart always --enable --start
volt service create --name worker --exec /usr/bin/worker \
  --after postgresql.service --restart on-failure
```

#### `volt service list`

List services. Alias: `ls`.

| Flag | Description |
|------|-------------|
| `--all` | Show all services (including inactive) |

```bash
volt service list
volt service list --all
volt service list -o json
```

#### `volt service status`

Show service status.

```bash
volt service status nginx
```

#### `volt service start`

Start a service.

```bash
volt service start nginx
```

#### `volt service stop`

Stop a service.

```bash
volt service stop nginx
```

#### `volt service restart`

Restart a service.

```bash
volt service restart nginx
```

#### `volt service reload`

Reload service configuration (sends SIGHUP).

```bash
volt service reload nginx
```

#### `volt service enable`

Enable a service to start at boot.

| Flag | Description |
|------|-------------|
| `--now` | Also start the service now |

```bash
volt service enable nginx
volt service enable nginx --now
```

#### `volt service disable`

Disable a service from starting at boot.

| Flag | Description |
|------|-------------|
| `--now` | Also stop the service now |

```bash
volt service disable nginx
volt service disable nginx --now
```

#### `volt service inspect`

Show detailed service properties.

```bash
volt service inspect nginx
volt service inspect nginx -o json
```

#### `volt service show`

Show service unit file contents. Alias: `cat`.

```bash
volt service show nginx
volt service cat nginx
```

#### `volt service edit`

Open a service unit file in `$EDITOR`, then daemon-reload.

| Flag | Type | Description |
|------|------|-------------|
| `--inline` | string | Apply inline override without opening editor |

```bash
volt service edit nginx
volt service edit myapp --inline "Restart=always"
```

#### `volt service deps`

Show service dependency tree.

```bash
volt service deps nginx
volt service deps sshd
```

#### `volt service logs`

View service logs from the systemd journal.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--follow` | `-f` | | Follow log output |
| `--tail` | | int | Number of lines from end |
| `--since` | | string | Show entries since (e.g., `"1 hour ago"`) |

```bash
volt service logs nginx
volt service logs -f nginx
volt service logs --tail 100 nginx
```

#### `volt service mask`

Mask a service (prevent starting entirely).

```bash
volt service mask bluetooth
```

#### `volt service unmask`

Unmask a service.

```bash
volt service unmask bluetooth
```

#### `volt service template`

Generate a systemd unit file from a template type.

Templates: `simple`, `oneshot`, `forking`, `notify`, `socket`.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Service name (required) |
| `--exec` | string | Command to execute (required) |
| `--description` | string | Service description |
| `--user` | string | Run as user |

```bash
volt service template simple --name myapp --exec /usr/bin/myapp
volt service template oneshot --name backup --exec /usr/local/bin/backup.sh
volt service template notify --name myapi --exec /usr/bin/myapi
```

#### `volt service delete`

Delete a service (stop, disable, remove unit file). Alias: `rm`.

```bash
volt service delete myapp
```

---

### `volt task` — Scheduled Tasks

Manage scheduled tasks using systemd timers. Alias: `timer`.

#### `volt task create`

Create a timer + service pair.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Task name (required) |
| `--exec` | string | Command to execute (required) |
| `--calendar` | string | systemd calendar syntax |
| `--interval` | string | Interval (e.g., `15min`, `1h`, `30s`) |
| `--description` | string | Task description |
| `--user` | string | Run as user |
| `--persistent` | | Run missed tasks on boot |
| `--enable` | | Enable timer after creation |

Calendar syntax examples:
- `daily`, `weekly`, `monthly`, `hourly`, `minutely`
- `*-*-* 03:00:00` — every day at 3 AM
- `Mon *-*-* 09:00` — every Monday at 9 AM
- `*:0/15` — every 15 minutes

```bash
volt task create --name backup --exec /usr/local/bin/backup.sh --calendar "daily"
volt task create --name cleanup --exec "/usr/bin/find /tmp -mtime +7 -delete" --calendar "*:0/30"
volt task create --name report --exec /opt/report.sh --calendar "Mon *-*-* 09:00" --enable
volt task create --name healthcheck --exec "curl -sf http://localhost/health" --interval 5min --enable
```

#### `volt task list`

List scheduled tasks. Alias: `ls`.

| Flag | Description |
|------|-------------|
| `--all` | Show all timers (including inactive) |

```bash
volt task list
volt task list --all
```

#### `volt task run`

Run a task immediately (one-shot, regardless of schedule).

```bash
volt task run backup
```

#### `volt task status`

Show task timer status (next run, last run, etc.).

```bash
volt task status backup
```

#### `volt task logs`

View task execution logs.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--follow` | `-f` | | Follow log output |
| `--tail` | | int | Number of lines from end |

```bash
volt task logs backup
volt task logs -f backup
```

#### `volt task enable`

Enable a scheduled task.

```bash
volt task enable backup
```

#### `volt task disable`

Disable a scheduled task.

```bash
volt task disable backup
```

#### `volt task edit`

Edit a task's timer or service file in `$EDITOR`.

```bash
volt task edit backup
```

#### `volt task delete`

Delete a scheduled task. Alias: `rm`.

```bash
volt task delete backup
```

---

## Infrastructure Commands

### `volt net` — Networking

Manage networks, bridges, firewall rules, DNS, port forwarding, and policies. Alias: `network`.

#### `volt net create`

Create a network.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string | | Network name |
| `--subnet` | string | `10.0.0.0/24` | Subnet CIDR |
| `--no-nat` | | | Disable NAT |

```bash
volt net create --name mynet --subnet 10.0.1.0/24
volt net create --name isolated --subnet 172.20.0.0/16 --no-nat
```

#### `volt net list`

List networks. Alias: `ls`.

```bash
volt net list
volt net list -o json
```

#### `volt net inspect`

Show detailed network information.

```bash
volt net inspect mynet
```

#### `volt net delete`

Delete a network. Alias: `rm`.

```bash
volt net delete mynet
```

#### `volt net connect`

Connect an interface to a network.

```bash
volt net connect backend web-frontend
```

#### `volt net disconnect`

Disconnect an interface from its network.

```bash
volt net disconnect web-frontend
```

#### `volt net status`

Show network overview (bridges, interfaces, IPs).

```bash
volt net status
```

#### `volt net bridge list`

List bridge interfaces. Alias: `ls`.

```bash
volt net bridge list
```

#### `volt net bridge create`

Create a bridge.

| Flag | Type | Description |
|------|------|-------------|
| `--subnet` | string | IP/CIDR for bridge |

```bash
volt net bridge create mybridge --subnet 10.50.0.0/24
```

#### `volt net bridge delete`

Delete a bridge.

```bash
volt net bridge delete mybridge
```

#### `volt net firewall list`

List firewall rules. Alias: `ls`.

```bash
volt net firewall list
```

#### `volt net firewall add`

Add a firewall rule.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string | | Rule name |
| `--source` | string | `any` | Source IP/CIDR |
| `--dest` | string | `any` | Destination IP/CIDR |
| `--port` | string | | Destination port |
| `--proto` | string | `tcp` | Protocol (`tcp`/`udp`) |
| `--action` | string | | Action (`accept`/`drop`) |

```bash
volt net firewall add --name allow-web \
  --source 10.0.0.0/24 --dest 10.0.1.0/24 --port 80 --proto tcp --action accept
volt net firewall add --name block-ssh \
  --source any --dest 10.0.0.5 --port 22 --proto tcp --action drop
```

#### `volt net firewall delete`

Delete a firewall rule by name.

```bash
volt net firewall delete --name allow-web
```

#### `volt net firewall flush`

Flush all firewall rules.

```bash
volt net firewall flush
```

#### `volt net dns list`

List DNS servers.

```bash
volt net dns list
```

#### `volt net port list`

List port forwards.

```bash
volt net port list
```

#### `volt net policy create`

Create a network policy.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Policy name |
| `--from` | string | Source workload |
| `--to` | string | Destination workload |
| `--port` | string | Destination port |
| `--action` | string | Action (`allow`/`deny`) |

```bash
volt net policy create --name web-to-db \
  --from web --to database --port 5432 --action allow
```

#### `volt net policy list`

List network policies. Alias: `ls`.

```bash
volt net policy list
```

#### `volt net policy delete`

Delete a network policy.

```bash
volt net policy delete --name web-to-db
```

#### `volt net policy test`

Test if traffic would be allowed by current policies.

| Flag | Type | Description |
|------|------|-------------|
| `--from` | string | Source workload |
| `--to` | string | Destination workload |
| `--port` | string | Destination port |

```bash
volt net policy test --from web --to database --port 5432
```

#### `volt net vlan list`

List VLANs.

```bash
volt net vlan list
```

---

### `volt ingress` — Reverse Proxy

Manage the built-in reverse proxy for routing external traffic to workloads. Aliases: `gateway`, `gw`.

Routes are matched by hostname and optional path prefix. Supports automatic TLS via ACME (Let's Encrypt) or manual certificates.

See also: [Ingress Proxy](networking.md#ingress-proxy) in the networking docs.

#### `volt ingress create`

Create a new ingress route.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Route name |
| `--hostname` | string | Hostname to match |
| `--path` | string | Path prefix to match |
| `--backend` | string | Backend address (`container:port` or `IP:port`) |
| `--tls` | string | TLS mode: `auto`, `manual`, `passthrough` |
| `--cert` | string | TLS certificate file (for `manual` mode) |
| `--key` | string | TLS key file (for `manual` mode) |
| `--timeout` | int | Backend timeout in seconds (default: 30) |

```bash
volt ingress create --name web --hostname app.example.com --backend web:8080
volt ingress create --name api --hostname api.example.com --path /v1 --backend api:3000 --tls auto
volt ingress create --name static --hostname cdn.example.com --backend static:80 \
  --tls manual --cert /etc/certs/cdn.pem --key /etc/certs/cdn.key
```

#### `volt ingress list`

List ingress routes. Alias: `ls`.

```bash
volt ingress list
volt ingress list -o json
```

#### `volt ingress status`

Show ingress proxy status.

```bash
volt ingress status
```

#### `volt ingress delete`

Delete an ingress route. Alias: `rm`.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Route name to delete |

```bash
volt ingress delete --name web
```

#### `volt ingress serve`

Start the ingress reverse proxy in the foreground.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--http-port` | int | `80` | HTTP listen port |
| `--https-port` | int | `443` | HTTPS listen port |

For production use, run as a systemd service:
```bash
systemctl enable --now volt-ingress.service
```

```bash
volt ingress serve
volt ingress serve --http-port 8080 --https-port 8443
```

#### `volt ingress reload`

Reload route configuration without downtime. Routes are re-read from the store and applied to the running proxy.

```bash
volt ingress reload
```

---

### `volt volume` — Persistent Storage

Manage persistent storage volumes. Alias: `vol`.

#### `volt volume create`

Create a volume.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Volume name (required) |
| `--size` | string | Size for file-backed ext4 (e.g., `1G`, `500M`) |

```bash
volt volume create --name mydata
volt volume create --name mydata --size 10G
```

#### `volt volume list`

List volumes. Alias: `ls`.

```bash
volt volume list
```

#### `volt volume inspect`

Show detailed volume information.

```bash
volt volume inspect mydata
```

#### `volt volume attach`

Attach a volume to a workload.

| Flag | Type | Description |
|------|------|-------------|
| `--target` | string | Target workload name |
| `--mount` | string | Mount path inside workload |

```bash
volt volume attach mydata --target web --mount /data
```

#### `volt volume detach`

Detach a volume from a workload.

```bash
volt volume detach mydata
```

#### `volt volume resize`

Resize a volume.

| Flag | Type | Description |
|------|------|-------------|
| `--size` | string | New size (required) |

```bash
volt volume resize mydata --size 20G
```

#### `volt volume snapshot`

Create a volume snapshot.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Snapshot name |

```bash
volt volume snapshot mydata --name pre-migration
```

#### `volt volume backup`

Backup a volume.

```bash
volt volume backup mydata
```

#### `volt volume delete`

Delete a volume. Alias: `rm`.

```bash
volt volume delete mydata
```

---

### `volt image` — Image Management

Manage container and VM images. Alias: `img`.

#### `volt image list`

List local images. Alias: `ls`.

```bash
volt image list
volt image list -o json
```

#### `volt image pull`

Pull a distribution image using debootstrap.

```bash
volt image pull ubuntu:24.04
volt image pull debian:bookworm
```

#### `volt image build`

Build an image from a spec file.

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--file` | `-f` | string | `Voltfile` | Build spec file path |
| `--tag` | `-t` | string | | Image tag name (required) |
| `--no-cache` | | | | Build without cache |

```bash
volt image build -f spec.yaml -t myimage
volt image build -f Voltfile -t webserver
```

#### `volt image inspect`

Show detailed image information.

```bash
volt image inspect ubuntu_24.04
```

#### `volt image import`

Import an image from a tarball.

| Flag | Type | Description |
|------|------|-------------|
| `--tag` | string | Image tag name (required) |

```bash
volt image import rootfs.tar.gz --tag myimage
```

#### `volt image export`

Export an image as a tarball.

```bash
volt image export ubuntu_24.04
```

#### `volt image tag`

Tag an image.

```bash
volt image tag ubuntu_24.04 my-base
```

#### `volt image push`

Push an image to a registry.

```bash
volt image push myimage
```

#### `volt image delete`

Delete an image. Alias: `rm`.

```bash
volt image delete myimage
```

---

### `volt cas` — Stellarium CAS

Content-addressed storage operations.

#### `volt cas status`

Show CAS store statistics (object count, total size, dedup ratio).

```bash
volt cas status
```

#### `volt cas info`

Show information about a specific CAS object by hash.

```bash
volt cas info abc123def456
```

#### `volt cas build`

Hash a directory tree, store each file as a CAS object, and create a manifest.

```bash
volt cas build /path/to/rootfs
```

#### `volt cas verify`

Verify integrity of all CAS objects (hash matches filename).

```bash
volt cas verify
```

#### `volt cas gc`

Garbage collect unreferenced objects.

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be deleted without deleting |

```bash
volt cas gc --dry-run
volt cas gc
```

#### `volt cas dedup`

Run deduplication analysis.

```bash
volt cas dedup
```

#### `volt cas pull`

Pull an object from remote CAS.

```bash
volt cas pull abc123def456
```

#### `volt cas push`

Push an object to remote CAS.

```bash
volt cas push /path/to/object
```

#### `volt cas sync`

Sync local CAS store with remote.

```bash
volt cas sync
```

---

### `volt registry` — OCI Container Registry

Manage the built-in OCI Distribution Spec compliant container registry. Alias: `reg`.

The registry stores all blobs in Stellarium CAS — the SHA-256 digest IS the CAS address. Manifests and tags are indexed alongside the CAS store.

**Licensing**: Pull is free for all tiers. Push requires a Pro license.

See also: [Registry](registry.md) for full documentation.

#### `volt registry serve`

Start the OCI registry server in the foreground.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--port` | int | `5000` | Listen port |
| `--tls` | | | Enable TLS |
| `--cert` | string | | TLS certificate file |
| `--key` | string | | TLS key file |
| `--public` | | `true` | Allow anonymous pull |
| `--read-only` | | | Read-only mode (pull only) |

For production use, run as a systemd service:
```bash
systemctl enable --now volt-registry.service
```

```bash
volt registry serve
volt registry serve --port 5000
volt registry serve --port 5000 --tls --cert /etc/volt/certs/reg.pem --key /etc/volt/certs/reg.key
```

#### `volt registry status`

Show registry status and statistics.

```bash
volt registry status
volt registry status -o json
```

#### `volt registry list`

List all repositories and their tags. Alias: `ls`.

```bash
volt registry list
volt registry list -o json
```

#### `volt registry gc`

Garbage collect unreferenced registry blobs.

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would be deleted without deleting |

```bash
volt registry gc --dry-run
volt registry gc
```

#### `volt registry token`

Generate a bearer token for authenticating with the registry.

Tokens are HMAC-SHA256 signed and include an expiration time. Use `--push` to generate a token with push (write) access.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--push` | | | Generate token with push (write) access |
| `--expiry` | string | `24h` | Token expiry duration (e.g., `24h`, `7d`) |

```bash
volt registry token
volt registry token --push
volt registry token --push --expiry 7d
```

---

### `volt snapshot` — Workload Snapshots

Capture and restore point-in-time snapshots of workload filesystems.

Snapshots are lightweight CAS-based captures that can be restored instantly via hard-link assembly. Ideal for pre-deploy snapshots, experimentation, and quick rollback.

#### `volt snapshot create`

Create a snapshot of a workload's filesystem.

Only changed files since the last snapshot produce new CAS blobs, making snapshots extremely fast and space-efficient.

| Flag | Type | Description |
|------|------|-------------|
| `--notes` | string | Notes for the snapshot |
| `--tags` | strings | Tags (comma-separated) |

```bash
volt snapshot create my-app
volt snapshot create my-app --notes "before v2.1 deploy"
volt snapshot create my-app --tags "pre-release,v2.1"
```

#### `volt snapshot list`

List snapshots for a workload.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit` | int | `20` | Maximum results to show |

```bash
volt snapshot list my-app
volt snapshot list my-app -o json
```

#### `volt snapshot restore`

Restore a workload's rootfs from a point-in-time snapshot.

By default, restores to the original rootfs location (overwriting current state). Use `--target` to restore to a different location.

| Flag | Type | Description |
|------|------|-------------|
| `--target` | string | Target directory (default: original path) |
| `--force` | | Overwrite existing target |

```bash
volt snapshot restore my-app-20260619-143052-snapshot
volt snapshot restore my-app-20260619-143052-snapshot --target /tmp/restore-test
volt snapshot restore my-app-20260619-143052-snapshot --force
```

#### `volt snapshot delete`

Delete a snapshot.

```bash
volt snapshot delete my-app-20260619-143052-snapshot
```

---

### `volt qemu` — QEMU Profile Management

Manage purpose-built QEMU compilations stored in Stellarium CAS.

Each profile contains only the QEMU binary, shared libraries, and firmware needed for a specific use case, maximizing CAS deduplication.

**Profiles:**

| Profile | Description |
|---------|-------------|
| `kvm-linux` | Headless Linux KVM guests (virtio-only, no TCG) |
| `kvm-uefi` | Windows/UEFI KVM guests (VNC, USB, TPM, OVMF) |
| `emulate-x86` | x86 TCG emulation (legacy OS, SCADA, nested) |
| `emulate-foreign` | Foreign arch TCG (ARM, RISC-V, MIPS, PPC) |

#### `volt qemu list`

List available QEMU profiles. Alias: `ls`.

```bash
volt qemu list
volt qemu list -o json
```

#### `volt qemu status`

Show detailed QEMU profile status including CAS references.

```bash
volt qemu status
```

#### `volt qemu resolve`

Assemble a QEMU profile from CAS. Downloads and links all required binaries, libraries, and firmware for the specified profile.

```bash
volt qemu resolve kvm-linux
volt qemu resolve emulate-x86
```

#### `volt qemu test`

Run a smoke test on a QEMU profile. Verifies the profile works by running `--version` and optionally booting a minimal test payload.

```bash
volt qemu test kvm-linux
volt qemu test emulate-x86
```

---

## Observability Commands

### `volt ps` — Unified Process Listing

Show all running workloads in one view. Alias: `processes`.

```
volt ps [filter] [flags]
```

**Filters** (positional): `containers` (`con`, `container`), `vms` (`vm`), `services` (`svc`, `service`)

| Flag | Description |
|------|-------------|
| `--all` | Show all workloads (including stopped) |

```bash
volt ps                    # All running workloads
volt ps --all              # Include stopped
volt ps containers         # Only containers
volt ps vms                # Only VMs
volt ps services           # Only services
volt ps -o json            # JSON output
volt ps -o wide            # All columns
```

#### `volt ps` Subcommands

`volt ps` also provides quick lifecycle operations:

```bash
volt ps start <name>       # Start a workload
volt ps stop <name>        # Stop a workload
volt ps restart <name>     # Restart a workload
volt ps kill <name>        # Kill a workload
volt ps inspect <name>     # Inspect a workload
```

---

### `volt logs` — Unified Logging

View logs for any workload. Auto-detects type from the systemd journal.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--follow` | `-f` | | Follow log output |
| `--tail` | | int | Number of lines from end |
| `--since` | | string | Show entries since (e.g., `"1 hour ago"`) |
| `--until` | | string | Show entries until |
| `--type` | | string | Filter by type: `container`, `vm`, `service` |
| `--priority` | | string | Filter by priority: `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, `debug` |
| `--all` | | | Show all workload logs |
| `--json` | | | Output in JSON format |

```bash
volt logs nginx                            # Auto-detect type
volt logs -f nginx                         # Follow
volt logs --tail 100 nginx                 # Last 100 lines
volt logs --since "1 hour ago" nginx       # Time filter
volt logs --type container web             # Explicit type
volt logs --priority err --all             # All errors
```

---

### `volt top` — Resource Usage

Show CPU, memory, and process counts for all workloads.

**Filters** (positional): `containers`, `vms`, `services`

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--sort` | string | `name` | Sort by: `cpu`, `mem`, `name`, `pids` |

```bash
volt top                   # All workloads
volt top containers        # Only containers
volt top --sort cpu        # Sort by CPU
volt top --sort mem        # Sort by memory
```

---

### `volt events` — Event Stream

Stream real-time events from the platform via the systemd journal.

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--follow` | `-f` | | `true` | Follow event stream |
| `--type` | | string | | Filter: `container`, `vm`, `service`, `task` |
| `--since` | | string | | Show events since |

```bash
volt events                        # Follow all events
volt events --type container       # Container events only
volt events --since "1 hour ago"   # Recent events
volt events --no-follow            # Show and exit
```

---

## Composition & Orchestration

### `volt compose` — Declarative Stacks

Manage multi-service stacks from `volt-compose.yaml` files.

| Flag | Short | Type | Description |
|------|-------|------|-------------|
| `--file` | `-f` | string | Compose file path |
| `--project` | | string | Project name override |

#### `volt compose up`

Create and start all services.

| Flag | Short | Description |
|------|-------|-------------|
| `--detach` | `-d` | Run in background |
| `--build` | | Build images before starting |
| `--force-recreate` | | Force recreate services |

```bash
volt compose up
volt compose up -d
volt compose -f production.yaml up -d
volt compose up --build
```

#### `volt compose down`

Stop and remove all services.

| Flag | Description |
|------|-------------|
| `--volumes` | Also remove created volumes |

```bash
volt compose down
volt compose down --volumes
```

#### `volt compose ps`

List services in the compose stack.

```bash
volt compose ps
```

#### `volt compose logs`

View logs for compose services.

| Flag | Type | Description |
|------|------|-------------|
| `--follow` | | Follow log output |
| `--tail` | int | Number of lines from end |

```bash
volt compose logs
volt compose logs --follow
volt compose logs api
```

#### `volt compose start`

Start existing services (without recreating).

```bash
volt compose start
```

#### `volt compose stop`

Stop running services (without removing).

```bash
volt compose stop
```

#### `volt compose restart`

Restart services.

```bash
volt compose restart
```

#### `volt compose exec`

Execute a command in a compose service.

```bash
volt compose exec myservice -- ls -la
volt compose exec web -- /bin/sh
```

#### `volt compose build`

Build images defined in the compose file.

```bash
volt compose build
volt compose build web
```

#### `volt compose pull`

Pull images defined in the compose file.

```bash
volt compose pull
```

#### `volt compose config`

Validate and display the resolved compose file.

```bash
volt compose config
```

#### `volt compose top`

Show resource usage for compose services.

```bash
volt compose top
```

#### `volt compose events`

Stream events from compose services.

| Flag | Default | Description |
|------|---------|-------------|
| `--follow` | `true` | Follow event stream |

```bash
volt compose events
```

---

### `volt deploy` — Deployment Strategies

Deploy workloads using zero-downtime strategies. Alias: `dp`.

Volt deploy coordinates updates across container instances using CAS (content-addressed storage) for image management. Each instance is updated to a new CAS ref, with health verification and automatic rollback on failure.

**Strategies:**
- **rolling** — Update instances one-by-one with health checks
- **canary** — Route a percentage of traffic to a new instance first

#### `volt deploy rolling`

Perform a rolling update.

```bash
volt deploy rolling web-app --image sha256:def456
```

#### `volt deploy canary`

Perform a canary deployment.

```bash
volt deploy canary api-svc --image sha256:new --weight 10
```

#### `volt deploy status`

Show active deployments.

```bash
volt deploy status
```

#### `volt deploy rollback`

Rollback to previous version.

```bash
volt deploy rollback web-app
```

#### `volt deploy history`

Show deployment history.

```bash
volt deploy history web-app
```

---

### `volt cluster` — Multi-Node

Manage cluster nodes.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--cluster` | string | `default` | Cluster name |
| `--kubeconfig` | string | | Path to kubeconfig |

#### `volt cluster status`

Show cluster overview.

```bash
volt cluster status
```

#### `volt cluster node list`

List cluster nodes. Alias: `ls`.

```bash
volt cluster node list
```

#### `volt cluster node add`

Add nodes to the cluster.

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--count` | `-c` | int | `1` | Number of nodes |
| `--cpu` | | int | `1` | CPUs per node |
| `--memory` | `-m` | string | `512M` | Memory per node |
| `--image` | `-i` | string | `volt/k8s-node` | Node image |
| `--parallel` | | int | `10` | Parallel creation |

```bash
volt cluster node add --count 10 --memory 512M
volt cluster node add -c 3 --cpu 2 -m 2G
```

#### `volt cluster node drain`

Drain a node for maintenance.

```bash
volt cluster node drain volt-node-default-0001
```

#### `volt cluster node remove`

Remove a node from the cluster.

```bash
volt cluster node remove volt-node-default-0001
```

---

### `volt gitops` — GitOps Pipelines

Manage GitOps pipelines that automatically deploy workloads when code is pushed to a Git repository. Alias: `go`.

Supports GitHub, GitLab, Bitbucket (webhooks) and SVN (polling). Each pipeline links a repository branch to a Volt workload — pushes to the tracked branch trigger automatic clone-and-deploy.

See also: [GitOps](gitops.md) for full documentation.

#### `volt gitops create`

Create a new GitOps pipeline linking a Git repository to a Volt workload.

When a push is detected on the tracked branch (via webhook or SVN polling), the pipeline will:
1. Clone or pull the repository
2. Look for `volt-manifest.yaml` or `Voltfile` in the repo root
3. Deploy/update the workload accordingly
4. Log the result

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string | | Pipeline name (required) |
| `--repo` | string | | Repository URL (required) |
| `--provider` | string | | Git provider: `github`, `gitlab`, `bitbucket`, `svn` (required) |
| `--branch` | string | `main` | Branch to track |
| `--workload` | string | | Target workload name (required) |
| `--secret` | string | | Webhook HMAC secret for signature validation |
| `--poll-interval` | int | `60` | SVN poll interval in seconds |

```bash
volt gitops create --name web-app --repo https://github.com/org/repo \
  --provider github --branch main --workload web --secret my-webhook-secret
volt gitops create --name api --repo https://gitlab.com/org/api \
  --provider gitlab --branch develop --workload api-svc
volt gitops create --name legacy --repo svn://svn.example.com/trunk \
  --provider svn --branch trunk --workload legacy-app
```

#### `volt gitops list`

List all configured GitOps pipelines. Alias: `ls`.

```bash
volt gitops list
volt gitops list -o json
```

#### `volt gitops status`

Show all pipelines with last deploy status.

```bash
volt gitops status
```

#### `volt gitops serve`

Start the webhook receiver HTTP server in the foreground.

The server listens for push events from GitHub, GitLab, and Bitbucket, and polls SVN repositories for revision changes.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--port` | int | `9090` | HTTP listen port |

**Endpoints:**
- `POST /hooks/github` — GitHub push webhooks
- `POST /hooks/gitlab` — GitLab push webhooks
- `POST /hooks/bitbucket` — Bitbucket push webhooks
- `GET /healthz` — Health check

For production use, install and run as a systemd service:
```bash
volt gitops install-service
systemctl enable --now volt-gitops.service
```

```bash
volt gitops serve
volt gitops serve --port 9090
```

#### `volt gitops sync`

Manually trigger a sync/deploy for a pipeline.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Pipeline name to sync |

```bash
volt gitops sync --name web-app
```

#### `volt gitops logs`

Show deploy history for a pipeline.

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string | | Pipeline name |
| `--limit` | int | `20` | Number of entries to show |

```bash
volt gitops logs --name web-app
volt gitops logs --name web-app --limit 50
```

#### `volt gitops delete`

Delete a GitOps pipeline. Alias: `rm`.

| Flag | Type | Description |
|------|------|-------------|
| `--name` | string | Pipeline name to delete |

```bash
volt gitops delete --name web-app
```

#### `volt gitops install-service`

Install the `volt-gitops` systemd service for production use.

```bash
sudo volt gitops install-service
systemctl enable --now volt-gitops.service
```

---

## Security & Governance

### `volt rbac` — Role-Based Access Control

Manage roles, permissions, and user assignments.

RBAC controls who can perform which operations on the Volt platform. Roles define sets of permissions, and users/groups are assigned to roles.

**Built-in roles:** `admin`, `operator`, `deployer`, `viewer`

#### `volt rbac init`

Initialize RBAC configuration.

```bash
volt rbac init
```

#### `volt rbac role list`

List available roles.

```bash
volt rbac role list
```

#### `volt rbac user assign`

Assign a user to a role.

```bash
volt rbac user assign karl admin
```

#### `volt rbac check`

Check if a user has a specific permission.

```bash
volt rbac check karl containers.create
```

---

### `volt audit` — Operational Audit Log

Query, verify, and manage the Volt operational audit log.

The audit log records every CLI and API action with structured JSON entries including who, what, when, where, and result. Entries are optionally signed (HMAC-SHA256) for tamper evidence.

Log location: `/var/log/volt/audit.log`

#### `volt audit search`

Search audit log entries.

```bash
volt audit search --user karl --action deploy --since 24h
```

#### `volt audit tail`

Show recent audit entries (or follow).

```bash
volt audit tail
volt audit tail -f
```

#### `volt audit verify`

Verify audit log integrity.

```bash
volt audit verify
```

#### `volt audit stats`

Show audit log statistics.

```bash
volt audit stats
```

#### `volt audit export`

Export audit data for compliance.

```bash
volt audit export
```

---

### `volt security` — Security Profiles & Auditing

Security commands for managing Landlock/seccomp profiles and auditing the system security posture.

#### `volt security profile list`

List available security profiles.

```bash
volt security profile list
```

#### `volt security profile show`

Show details of a security profile.

```bash
volt security profile show webserver
```

#### `volt security audit`

Audit system security posture.

```bash
volt security audit
```

#### `volt security scan`

Scan for vulnerabilities.

```bash
volt security scan
```

#### `volt security keys`

Manage encryption keys.

```bash
volt security keys
```

#### `volt security luks-status`

Show LUKS full-disk encryption status.

```bash
volt security luks-status
```

#### `volt security luks-check`

Check if LUKS encryption is active (exit code).

```bash
volt security luks-check
```

---

## Monitoring

### `volt health` — Continuous Health Monitoring

Configure and manage continuous health checks for Volt workloads.

The health daemon monitors workloads with HTTP, TCP, or exec health checks and can automatically restart workloads that become unhealthy. Unlike deploy-time health checks, the health daemon runs continuously.

#### `volt health configure`

Configure health check for a workload.

```bash
volt health configure web-app --http /healthz --port 8080 --interval 30s
volt health configure db --tcp --port 5432 --interval 15s --auto-restart
```

#### `volt health list`

List configured health checks.

```bash
volt health list
```

#### `volt health status`

Show health status of monitored workloads.

```bash
volt health status web-app
```

#### `volt health check`

Run an immediate health check.

```bash
volt health check web-app
```

#### `volt health remove`

Remove health check for a workload.

```bash
volt health remove web-app
```

---

### `volt webhook` — Event Notifications

Configure webhook endpoints that receive notifications when events occur.

**Supported events:** `deploy`, `deploy.fail`, `crash`, `health.fail`, `health.ok`, `scale`, `restart`, `create`, `delete`

**Supported formats:** `json` (default), `slack`

#### `volt webhook add`

Add a webhook endpoint.

```bash
volt webhook add https://hooks.slack.com/xxx --events deploy,crash --name prod-slack --format slack
volt webhook add https://api.pagerduty.com/... --events crash,health.fail --name pagerduty
```

#### `volt webhook list`

List configured webhooks.

```bash
volt webhook list
```

#### `volt webhook test`

Send a test notification to a webhook.

```bash
volt webhook test prod-slack
```

#### `volt webhook remove`

Remove a webhook.

```bash
volt webhook remove prod-slack
```

---

## System Commands

### `volt daemon` — Daemon Management

Manage the volt platform daemon (`voltd`).

```bash
volt daemon status         # Show daemon status
volt daemon start          # Start daemon
volt daemon stop           # Stop daemon
volt daemon restart        # Restart daemon
volt daemon reload         # Reload configuration
volt daemon config         # Show daemon configuration
```

---

### `volt system` — Platform Information

```bash
volt system info           # Platform info (OS, kernel, CPU, memory, disk)
volt system health         # Health check all subsystems
volt system update         # Check for updates
volt system backup         # Backup config and state
volt system restore <file> # Restore from backup
volt system reset --confirm  # Factory reset (destructive!)
```

---

### `volt config` — Configuration

```bash
volt config show                              # Show current config
volt config get runtime.default_memory        # Get a value
volt config set runtime.default_memory 512M   # Set a value
volt config edit                              # Open in $EDITOR
volt config validate                          # Validate config file
volt config reset                             # Reset to defaults
```

---

### `volt tune` — Performance Tuning

#### `volt tune show`

Show current tuning overview.

```bash
volt tune show
```

#### `volt tune profile`

Manage tuning profiles.

```bash
volt tune profile list              # List available profiles
volt tune profile show web-server   # Show profile settings
volt tune profile apply web-server  # Apply a profile
```

#### `volt tune sysctl`

Manage sysctl parameters.

| Subcommand | Description |
|------------|-------------|
| `list` | List all sysctl parameters |
| `get <key>` | Get a value |
| `set <key> <value>` | Set a value |

| Flag (set) | Description |
|------------|-------------|
| `--persist` | Persist across reboots |

| Flag (list) | Type | Description |
|-------------|------|-------------|
| `--filter` | string | Filter by keyword |

```bash
volt tune sysctl list
volt tune sysctl list --filter net
volt tune sysctl get net.ipv4.ip_forward
volt tune sysctl set net.ipv4.ip_forward 1
volt tune sysctl set vm.swappiness 10 --persist
```

#### `volt tune cpu`

CPU tuning.

```bash
volt tune cpu governor                 # Show current governor
volt tune cpu governor performance     # Set governor
```

#### `volt tune memory`

Memory tuning.

```bash
volt tune memory show                  # Show memory settings
volt tune memory limit <workload> --max 4G
volt tune memory hugepages --enable --size 2M --count 4096
```

#### `volt tune io`

I/O tuning.

```bash
volt tune io show                      # Show I/O schedulers
volt tune io scheduler /dev/sda --scheduler mq-deadline
volt tune io limit <workload> --read-bps 500M --write-bps 200M
```

#### `volt tune net`

Network tuning.

```bash
volt tune net show                     # Show network tuning
volt tune net buffers --rmem-max 16M --wmem-max 16M
```

---

## Shortcuts

These resolve to their canonical commands. They exist where intent is unambiguous.

| Shortcut | Equivalent | Notes |
|----------|-----------|-------|
| `volt ps` | Unified listing | Shows all workloads |
| `volt run <image>` | `volt container create --image <image> --start` | Quick-start container |
| `volt exec <name> -- <cmd>` | `volt container exec <name> -- <cmd>` | Container exec |
| `volt ssh <name>` | `volt vm ssh <name>` | Only VMs have SSH |
| `volt connect <name>` | `volt desktop connect <name>` | Desktop connect |
| `volt status` | `volt system info` | Platform overview |

### `volt get` — List Resources

```bash
volt get vms             # volt vm list
volt get containers      # volt container list
volt get services        # volt service list
volt get networks        # volt net list
volt get volumes         # volt volume list
volt get images          # volt image list
volt get nodes           # volt cluster node list
volt get tasks           # volt task list
volt get desktops        # volt desktop list
```

### `volt describe` — Inspect Resources

```bash
volt describe vm myvm              # volt vm inspect myvm
volt describe container web        # volt container inspect web
volt describe service nginx        # volt service inspect nginx
volt describe network backend      # volt net inspect backend
volt describe volume pgdata        # volt volume inspect pgdata
```

### `volt delete` — Delete Resources

```bash
volt delete vm myvm                # volt vm destroy myvm
volt delete container web          # volt container delete web
volt delete service myapp          # volt service delete myapp
volt delete network backend        # volt net delete backend
```