pvesh

List available nodes

$ pvesh [[g|get]] /nodes

$ pvesh [[g|get]] /nodes/[node_name]/[lxc|qemu]

$ pvesh [[l|ls]] [/]

pvesh help [<path>]
pvesh [<METHOD>] [<path>] [<options>]

<METHOD>: One of get, put, post, delete. These map directly to HTTP API methods.
<path>: The API resource path (e.g., /nodes/{node}/qemu, /cluster/status).
<options>: Parameters specific to the API method and path, often key-value pairs (e.g., -vmid 100, -name myvm). Global options like --output-format can also be used.

--nobanner
    Suppresses the Proxmox VE Shell header and footer, useful for scripting.

-o, --output-format <format>
    Specifies the output format (e.g., json, json-pretty, text, yaml, proxmox-ve-shell).

-v, --verbose
    Enables verbose output, showing more details about the operation.

-q, --quiet
    Suppresses non-error output.

--dry-run
    Performs a dry run, showing what would happen without making actual changes.

--rpc-error-continuation
    Allows scripts to continue execution even if an RPC error occurs.

--pretty-json
    An alias for --output-format json-pretty.

pvesh is the Proxmox VE Shell, a powerful command-line interface (CLI) for managing Proxmox Virtual Environment (PVE) installations. It acts as a direct client to the Proxmox VE API, allowing administrators to interact with all aspects of a PVE cluster, including virtual machines (VMs), containers (LXC), storage, networking, and cluster resources. Unlike specific tools like qm or pct that focus on a single resource type, pvesh provides a unified interface to the entire API, enabling comprehensive management tasks, automation, and scripting. It supports various HTTP methods (GET, PUT, POST, DELETE) for interacting with API paths and can be used both interactively and non-interactively for scripting purposes. It also offers the unique ability to execute arbitrary Perl code within the Proxmox environment.

Requires a running Proxmox VE installation for full functionality.
API calls require appropriate user permissions and authentication, which pvesh inherits from the current user's session or relies on configured API tokens.
Direct interaction with the API is powerful and can lead to unintended consequences if not used carefully, especially with put, post, or delete methods.

When executed without arguments (e.g., just pvesh), it launches an interactive shell environment, similar to a regular Linux shell, but tailored for Proxmox VE commands. This mode provides tab-completion for API paths and parameters, making exploration and management easier.

pvesh translates its command syntax (e.g., pvesh get /cluster/status) directly into HTTP requests to the Proxmox VE REST API. get maps to HTTP GET, post to HTTP POST, put to HTTP PUT, and delete to HTTP DELETE. This direct mapping makes it an ideal tool for understanding and interacting with the underlying API structure.

Beyond API calls, pvesh allows users to execute arbitrary Perl code. This feature provides advanced scripting capabilities, enabling complex logic and data manipulation directly within the Proxmox environment, leveraging Perl's rich ecosystem and Proxmox's internal libraries.

pvesh has been a fundamental component of Proxmox VE since its inception, evolving alongside the Proxmox VE API. It was designed to provide a consistent and programmatic interface to the underlying API, enabling both interactive system administration and advanced scripting for automation. Its development has focused on reflecting the growing capabilities of the PVE platform, making it the primary command-line tool for managing the entire Proxmox ecosystem.

qm(1), pct(1), pvecm(1), pveceph(1), man pvesh