pvectl

A command-line tool for managing Proxmox clusters with kubectl-like syntax.

pvectl wraps the Proxmox API as a Ruby gem, providing familiar commands for managing VMs, containers, nodes, storage, backups, and snapshots from the terminal.

Note: This project is in active development. Some features may not yet be fully stable.

• kubectl-like syntax — familiar commands: get, describe, top, logs
• Multi-resource management — VMs, containers, nodes, storage, snapshots, backups
• Batch operations — act on multiple resources with selectors: -l status=running
• Multiple output formats — table, wide, JSON, YAML
• Watch mode — auto-refreshing resource lists
• Interactive wizards — guided VM/container creation
• Console access — interactive terminal sessions via WebSocket
• Multi-cluster contexts — kubeconfig-style context switching
• Plugin system — extend with gem-based or directory-based plugins
• Template management — convert VMs/containers to templates, linked cloning

All VM and container commands accept a VMID or a name. Numeric arguments are matched against VMIDs first; non-numeric arguments (or numbers with no matching VMID) are matched by name.

pvectl start vm web           # start VM named "web"
pvectl stop ct db             # stop container named "db"
pvectl describe vm web-prod   # describe every VM named "web-prod"
pvectl clone vm web --name web-clone   # clone source by name (unambiguous)

Ambiguity rules:

• Multi-target commands (start, stop, shutdown, restart, reset, suspend, resume, delete) act on every resource whose name matches. If more than one resource matches, a confirmation prompt lists all affected VMIDs before proceeding.
• Single-target commands (clone, console, set, edit) require an unambiguous match. If a name matches several resources, the command errors: 'web' matches multiple resources (VMIDs 100, 105) — specify a VMID.

Name uniqueness: VM and container names must be unique across the entire cluster. create, clone, and renames via set/edit fail if the name (or container hostname) is already in use:

a VM or container named 'web' already exists (VMID 100 on pve1)

gem install pvectl

Or add to your Gemfile:

bundle add pvectl

Requirements: Ruby >= 3.0.0

On first run, pvectl launches an interactive configuration wizard:

$ pvectl get nodes
Proxmox server URL (e.g., https://pve.example.com:8006): https://pve.example.com:8006
Verify SSL certificate? (y/n) y
Authentication method:
  1. API Token (recommended)
  2. Username/Password
Enter number: 1
Token ID (e.g., root@pam!tokenid): root@pam!pvectl
Token Secret: ********
Context name: [default] production

Once configured, explore your cluster:

pvectl get nodes                  # List cluster nodes
pvectl get vms                    # List all VMs
pvectl get vm 100                 # Show one VM by VMID or name
pvectl get vms 100 web-frontend   # Show several VMs by VMID or name
pvectl get vms -o wide            # Extended columns
pvectl get subscription           # Show Proxmox subscription per node (key masked)
pvectl describe vm 100            # Detailed VM info
pvectl top nodes                  # Resource usage

Use pvectl help <command> for detailed usage, examples, and options.

Full documentation is available in the GitHub Wiki:

• Getting Started — installation, configuration, first commands
• Configuration Guide — contexts, auth methods, environment variables
• Command Reference — detailed docs for every command
• Selectors & Filtering — filter resources with -l flag
• Output Formats — table, wide, JSON, YAML
• Workflows — common scenarios and best practices
• Plugin Development — extend pvectl with custom commands
• Troubleshooting — common issues and solutions

Configuration file: ~/.pvectl/config (kubeconfig-style YAML)

pvectl config view                      # Show current config
pvectl config get-contexts              # List contexts
pvectl config use-context production    # Switch context

See the Configuration Guide for details on multi-cluster setup, authentication methods, and environment variables.

pvectl supports plugins via gems (pvectl-plugin-*) and local files (~/.pvectl/plugins/*.rb). See Plugin Development.

git clone https://github.com/pwojcieszonek/pvectl.git
cd pvectl
bin/setup
rake test
bundle exec exe/pvectl

Bug reports and pull requests are welcome on GitHub at https://github.com/pwojcieszonek/pvectl.

Released under the MIT License.