# VOLT(1) — Unified Linux Platform Management

## NAME

**volt** — unified CLI for managing containers, VMs, services, networking, storage, and more

## SYNOPSIS

**volt** [*command*] [*subcommand*] [*flags*]

**volt** **ps** [*filter*] [*flags*]

**volt** **container** *command* [*name*] [*flags*]

**volt** **vm** *command* [*name*] [*flags*]

**volt** **service** *command* [*name*] [*flags*]

**volt** **net** *command* [*flags*]

**volt** **compose** *command* [*flags*]

## DESCRIPTION

**volt** is a unified Linux platform management CLI that replaces the fragmented toolchain of `systemctl`, `journalctl`, `machinectl`, `ip`, `nft`, `virsh`, and other utilities with a single binary.

It manages three engines:

**Voltainer**
: Container engine built on `systemd-nspawn`(1). Provides OS-level containerization using Linux namespaces, cgroups v2, and systemd service management.

**Voltvisor**
: Virtual machine engine built on KVM/QEMU. Full hypervisor capabilities with support for live migration, snapshots, and hardware passthrough.

**Stellarium**
: Content-addressed storage backend shared by both engines. Provides deduplication, integrity verification, and efficient image storage using BLAKE3 hashing.

## COMMANDS

### Workloads

**container**
: Manage Voltainer containers. Subcommands: create, start, stop, restart, kill, exec, attach, shell, list, inspect, logs, cp, rename, update, export, delete.

**vm**
: Manage Voltvisor virtual machines. Subcommands: create, start, stop, destroy, ssh, exec, attach, list.

**desktop**
: Manage desktop VMs (VDI). Subcommands: create, connect, list.

**service**
: Manage systemd services. Subcommands: create, start, stop, restart, reload, enable, disable, status, list, inspect, show, edit, deps, logs, mask, unmask, template, delete.

**task**
: Manage scheduled tasks (systemd timers). Subcommands: create, list, run, status, logs, enable, disable, edit, delete.

### Infrastructure

**net**
: Manage networking. Subcommands: create, list, inspect, delete, connect, disconnect, status. Subsystems: bridge, firewall, dns, port, policy, vlan.

**volume**
: Manage persistent volumes. Subcommands: create, list, inspect, attach, detach, resize, snapshot, backup, delete.

**image**
: Manage images. Subcommands: list, pull, build, inspect, import, export, tag, push, delete.

**cas**
: Stellarium CAS operations. Subcommands: status, info, build, verify, gc, dedup, pull, push, sync.

### Observability

**ps**
: List all running workloads — containers, VMs, and services — in one unified view.

**logs**
: View logs for any workload. Auto-detects type via the systemd journal.

**top**
: Show real-time CPU, memory, and process counts for all workloads.

**events**
: Stream real-time platform events.

### Composition & Orchestration

**compose**
: Manage declarative multi-service stacks. Subcommands: up, down, start, stop, restart, ps, logs, build, pull, exec, config, top, events.

**cluster**
: Manage cluster nodes. Subcommands: status, node (list, add, drain, remove).

### System

**daemon**
: Manage the volt daemon. Subcommands: start, stop, restart, status, reload, config.

**system**
: Platform information and maintenance. Subcommands: info, health, update, backup, restore, reset.

**config**
: Configuration management. Subcommands: show, get, set, edit, validate, reset.

**tune**
: Performance tuning. Subcommands: show, profile, cpu, memory, io, net, sysctl.

### Shortcuts

**get** *resource*
: List resources by type. Routes to canonical list commands.

**describe** *resource* *name*
: Show detailed resource info. Routes to canonical inspect commands.

**delete** *resource* *name*
: Delete a resource. Routes to canonical delete commands.

**run** *image*
: Quick-start a container from an image.

**ssh** *vm-name*
: SSH into a VM.

**exec** *container* **--** *command*
: Execute a command in a container.

**connect** *desktop*
: Connect to a desktop VM.

**status**
: Platform status overview (alias for **system info**).

## GLOBAL FLAGS

**-h**, **--help**
: Show help for the command.

**-o**, **--output** *format*
: Output format: **table** (default), **json**, **yaml**, **wide**.

**-q**, **--quiet**
: Suppress non-essential output.

**--debug**
: Enable debug logging to stderr.

**--no-color**
: Disable colored output.

**--config** *path*
: Config file path (default: /etc/volt/config.yaml).

**--timeout** *seconds*
: Command timeout in seconds (default: 30).

## FILES

*/usr/local/bin/volt*
: The volt binary.

*/etc/volt/config.yaml*
: Main configuration file.

*/etc/volt/profiles/*
: Custom tuning profiles.

*/var/lib/volt/*
: Persistent data (containers, VMs, images, volumes, CAS store).

*/var/run/volt/volt.sock*
: Daemon Unix socket.

*/var/run/volt/volt.pid*
: Daemon PID file.

*/var/log/volt/daemon.log*
: Daemon log.

*/var/log/volt/audit.log*
: Audit trail of state-changing operations.

*/var/cache/volt/*
: Cache directory (safe to delete).

## ENVIRONMENT

**VOLT_CONFIG**
: Config file path override.

**VOLT_COLOR**
: Color mode: **auto**, **always**, **never**.

**VOLT_OUTPUT**
: Default output format.

**VOLT_DEBUG**
: Enable debug output.

**VOLT_HOST**
: Daemon socket path or remote host.

**VOLT_CONTEXT**
: Named context for multi-cluster operation.

**VOLT_COMPOSE_FILE**
: Default compose file path.

**EDITOR**
: Editor for **volt service edit** and **volt config edit**.

## EXIT CODES

| Code | Description |
|------|-------------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid usage / bad arguments |
| 3 | Resource not found |
| 4 | Resource already exists |
| 5 | Permission denied |
| 6 | Daemon not running |
| 7 | Timeout |
| 8 | Network error |
| 9 | Conflicting state |
| 10 | Dependency error |
| 11 | Insufficient resources |
| 12 | Invalid configuration |
| 13 | Interrupted by signal |

## EXAMPLES

List all running workloads:

    volt ps

Create and start a container:

    volt container create --name web --image ubuntu:24.04 --start

SSH into a VM:

    volt ssh db-primary

Check service status:

    volt service status nginx

View logs:

    volt logs -f web-frontend

Create a scheduled task:

    volt task create --name backup --exec /usr/local/bin/backup.sh --calendar daily --enable

Deploy a compose stack:

    volt compose up -d

Show platform health:

    volt system health

Apply a tuning profile:

    volt tune profile apply web-server

## SEE ALSO

**systemd-nspawn**(1), **systemctl**(1), **journalctl**(1), **qemu-system-x86_64**(1), **nft**(8), **ip**(8)

## VERSION

Volt version 0.2.0

## AUTHORS

Volt Platform — https://armoredgate.com