{"id":14980325,"url":"https://github.com/corsinvest/cv4pve-api-powershell","last_synced_at":"2026-02-24T19:04:04.375Z","repository":{"id":44573773,"uuid":"206079622","full_name":"Corsinvest/cv4pve-api-powershell","owner":"Corsinvest","description":"Proxmox VE PowerShell module for accessing API like VMware PowerCLI","archived":false,"fork":false,"pushed_at":"2026-02-09T13:08:11.000Z","size":4723,"stargazers_count":71,"open_issues_count":0,"forks_count":15,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-02-09T18:18:32.316Z","etag":null,"topics":["api","cluster","powershell","powershell-modules","powershell-script","proxmox","proxmox-cluster","proxmox-ve","script","web-api"],"latest_commit_sha":null,"homepage":"https://www.corsinvest.it/cv4pve","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Corsinvest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-09-03T13:06:28.000Z","updated_at":"2026-02-09T13:07:20.000Z","dependencies_parsed_at":"2023-01-29T20:50:13.366Z","dependency_job_id":"d2477969-85c6-4542-b51c-cc18d7fa99d2","html_url":"https://github.com/Corsinvest/cv4pve-api-powershell","commit_stats":{"total_commits":71,"total_committers":4,"mean_commits":17.75,"dds":0.07042253521126762,"last_synced_commit":"55a680973d4d92287cfcf2fe0eb7bfc77ce07d3a"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/Corsinvest/cv4pve-api-powershell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-api-powershell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-api-powershell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-api-powershell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-api-powershell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Corsinvest","download_url":"https://codeload.github.com/Corsinvest/cv4pve-api-powershell/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-api-powershell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29796840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T16:37:37.581Z","status":"ssl_error","status_checked_at":"2026-02-24T16:37:37.074Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cluster","powershell","powershell-modules","powershell-script","proxmox","proxmox-cluster","proxmox-ve","script","web-api"],"created_at":"2024-09-24T14:01:36.690Z","updated_at":"2026-02-24T19:04:04.369Z","avatar_url":"https://github.com/Corsinvest.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cv4pve-api-powershell\r\n\r\n[![PowerShell for Proxmox VE](https://img.shields.io/badge/PowerShell-Proxmox%20VE-blue?style=for-the-badge)](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/)\r\n[![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/Corsinvest.ProxmoxVE.Api?style=for-the-badge)](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/)\r\n[![Downloads](https://img.shields.io/powershellgallery/dt/Corsinvest.ProxmoxVE.Api?style=for-the-badge)](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/)\r\n[![License](https://img.shields.io/github/license/Corsinvest/cv4pve-api-powershell?style=for-the-badge)](LICENSE)\r\n[![GitHub Stars](https://img.shields.io/github/stars/Corsinvest/cv4pve-api-powershell?style=for-the-badge)](https://github.com/Corsinvest/cv4pve-api-powershell/stargazers)\r\n\r\n```text\r\n    ______                _                      __\r\n   / ____/___  __________(_)___ _   _____  _____/ /_\r\n  / /   / __ \\/ ___/ ___/ / __ \\ | / / _ \\/ ___/ __/\r\n / /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_\r\n \\____/\\____/_/  /____/_/_/ /_/|___/\\___/____/\\__/\r\n\r\n         Corsinvest - Proxmox VE API PowerShell\r\n```\r\n\r\nA comprehensive PowerShell module that provides everything you need to build powerful automation scripts that manage [Proxmox VE](https://www.proxmox.com/en/proxmox-ve) infrastructure programmatically.\r\n\r\nPart of the [cv4pve](https://www.corsinvest.it/cv4pve) suite of tools.\r\n\r\n**Quick Links:** [PowerShell Gallery](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/) | [Documentation](https://corsinvest.github.io/cv4pve-api-powershell/) | [Proxmox VE API](https://pve.proxmox.com/pve-docs/api-viewer/)\r\n\r\n## Overview\r\n\r\nThe **cv4pve-api-powershell** module enables system administrators and developers to manage and automate Proxmox VE environments using PowerShell.\r\n\r\nIt provides a comprehensive set of cmdlets that wrap the Proxmox REST API, allowing operations such as VM and container management, node monitoring, backup handling, and storage inspection—all from PowerShell.\r\n\r\nThis module serves as the **PowerCLI equivalent for Proxmox VE**:\r\n- While PowerCLI facilitates VMware vSphere automation via PowerShell\r\n- **cv4pve-api-powershell** offers similar capabilities for Proxmox VE environments\r\n\r\n![PowerShell for Proxmox VE](https://raw.githubusercontent.com/Corsinvest/cv4pve-api-powershell/master/images/powershell.png)\r\n\r\n## Key Features\r\n\r\n### Core Capabilities\r\n* **Easy to Learn** - Intuitive PowerShell cmdlet interface\r\n* **Complete API Coverage** - Automatically generated from official Proxmox VE API documentation\r\n* **Multiple Response Types** - Support for JSON, PNG, ExtJS, HTML, and text formats\r\n* **Rich Response Objects** - PveResponse class with detailed request/response information\r\n* **Cross-Platform** - Works on Windows, Linux, and macOS (PowerShell 6.0+)\r\n* **No Remote Installation Required** - Execute from any machine outside Proxmox VE\r\n\r\n### Authentication \u0026 Security\r\n* **API Token Support** - Proxmox VE 6.2+ API token authentication\r\n* **Two-Factor Authentication** - One-time password (OTP) support\r\n* **Secure Connections** - TLS/SSL support with certificate validation options\r\n* **High Availability** - Multi-host cluster connection for HA environments\r\n\r\n### Virtual Machine \u0026 Container Management\r\n* **VM Operations** - Start, stop, suspend, resume, reset, unlock\r\n* **Container Support** - Full LXC container lifecycle management\r\n* **Snapshot Management** - Create, list, rollback, and delete snapshots\r\n* **Clone Operations** - Clone VMs and containers\r\n* **Resource Monitoring** - RRD data collection from nodes, QEMU VMs, and LXC containers\r\n\r\n### Advanced Features\r\n* **Direct API Access** - Use `Invoke-PveRestApi` for custom API calls\r\n* **Indexed Parameters** - Support for indexed parameters (e.g., -NetN, -ScsiN, -IdeN)\r\n* **Task Management** - Wait for task completion, check task status\r\n* **Utility Functions** - Unix time conversion, VM lookup by ID or name, and more\r\n* **SPICE Integration** - Connect to VM consoles via `Invoke-PveSpice`\r\n* **Documentation Generation** - Built-in help documentation builder\r\n\r\n### Developer-Friendly\r\n* **PowerShell Gallery** - Simple installation via `Install-Module`\r\n* **Comprehensive Documentation** - HTML and Markdown documentation included\r\n* **Interactive Tutorials** - VSCode notebook tutorials available\r\n* **Open Source** - Full source code available on GitHub\r\n\r\n## Utility Functions\r\n\r\nThe module includes a rich set of utility cmdlets to simplify common operations:\r\n\r\n### Time Conversion\r\n* `ConvertFrom-PveUnixTime` - Convert Unix timestamp to DateTime\r\n* `ConvertTo-PveUnixTime` - Convert DateTime to Unix timestamp\r\n\r\n### Task Management\r\n* `Wait-PveTaskIsFinish` - Wait for a task to complete\r\n* `Get-PveTaskIsRunning` - Check if a task is still running\r\n\r\n### VM Operations (by ID or Name)\r\n* `Get-PveVm` - Find VM by ID or name\r\n* `Start-PveVm` - Start a VM\r\n* `Stop-PveVm` - Stop a VM\r\n* `Suspend-PveVm` - Suspend a VM\r\n* `Resume-PveVm` - Resume a VM\r\n* `Reset-PveVm` - Reset a VM\r\n* `Unlock-PveVm` - Unlock a VM\r\n\r\n### Monitoring \u0026 Statistics\r\n* `Get-PveNodeMonitoring` - Get RRD monitoring data from nodes\r\n* `Get-PveQemuMonitoring` - Get RRD monitoring data from QEMU VMs\r\n* `Get-PveLxcMonitoring` - Get RRD monitoring data from LXC containers\r\n\r\n### Snapshot Management\r\n* `Get-PveVmSnapshot` - Get snapshots for a VM\r\n* `New-PveVmSnapshot` - Create a new snapshot\r\n* `Undo-PveVmSnapshot` - Rollback to a snapshot\r\n* `Remove-PveVmSnapshot` - Delete a snapshot\r\n\r\nAnd many more! Explore the full cmdlet list with `Get-Command -Module Corsinvest.ProxmoxVE.Api`\r\n\r\n## Documentation\r\n\r\nComprehensive documentation is available in multiple formats:\r\n\r\n* **[HTML Documentation](https://corsinvest.github.io/cv4pve-api-powershell/)** - Full API reference in HTML format\r\n* **[Markdown Documentation](https://github.com/Corsinvest/cv4pve-api-powershell/blob/master/doc/markdown/about_cv4pve-api-powershell.md)** - Documentation in Markdown format\r\n\r\n## Tutorial \u0026 Learning Resources\r\n\r\n* **[Interactive VSCode Notebook Tutorial](https://tinyurl.com/cv4pve-api-pwsh-learn)** - Learn by doing with interactive examples\r\n* **[Common Issues \u0026 Examples](https://corsinvest.github.io/cv4pve-api-powershell/common-issues.html)** - Practical solutions to common problems and advanced examples\r\n* **[Video Demo](https://asciinema.org/a/656606)** - Watch a quick demonstration of the module in action\r\n\r\n\u003ca href=\"https://asciinema.org/a/656606\" target=\"_blank\"\u003e\u003cimg src=\"https://asciinema.org/a/656606.svg\" /\u003e\u003c/a\u003e\r\n\r\n## Requirements\r\n\r\n* **PowerShell 6.0 or higher** (PowerShell Core)\r\n* **Network access** to your Proxmox VE cluster\r\n* **Valid credentials** or API token for Proxmox VE\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n\r\nFirst, ensure you have [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell) installed on your system (version 6.0 or later).\r\n\r\n### From PowerShell Gallery (Recommended)\r\n\r\nThe easiest way to install is directly from the [PowerShell Gallery](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/):\r\n\r\n```powershell\r\nInstall-Module -Name Corsinvest.ProxmoxVE.Api\r\n```\r\n\r\n### Manual Installation\r\n\r\n1. Download the `Corsinvest.ProxmoxVE.Api` folder from the repository\r\n2. Copy it to one of your PowerShell module paths\r\n\r\nTo view your module paths:\r\n```powershell\r\n# Display module paths\r\n$env:PSModulePath -split [IO.Path]::PathSeparator\r\n```\r\n\r\n## Documentation\r\n\r\n**Need help getting started or troubleshooting issues?**\r\n\r\n- **[Common Issues \u0026 Examples](https://corsinvest.github.io/cv4pve-api-powershell/common-issues.html)** - Practical examples and solutions to common problems:\r\n  - Hashtable parameters (NetN, SataN, ScsiN)\r\n  - Boolean vs Switch parameters\r\n  - Working with result objects\r\n  - Creating VMs with disks and network\r\n  - Guest agent commands\r\n  - And more!\r\n\r\n- **[Full Documentation](https://corsinvest.github.io/cv4pve-api-powershell/)** - Complete reference with all cmdlets\r\n- **[Proxmox VE API Viewer](https://pve.proxmox.com/pve-docs/api-viewer/)** - Official Proxmox VE API documentation\r\n\r\n## Quick Start\r\n\r\n### Connecting to Your Cluster\r\n\r\nUse `Connect-PveCluster` to establish a connection. This cmdlet supports both username/password and API token authentication.\r\n\r\n#### Using Username and Password\r\n\r\n```powershell\r\n# Connect with username and password\r\nConnect-PveCluster -HostsAndPorts 192.168.1.100:8006 -SkipCertificateCheck\r\n\r\n# PowerShell will prompt for credentials\r\n# Username format: user@pam, user@pve, or user@yourdomain\r\n```\r\n\r\n#### Using API Token (Proxmox VE 6.2+)\r\n\r\nFrom Proxmox VE 6.2+, you can use [API tokens](https://pve.proxmox.com/pve-docs/pveum-plain.html) for authentication without username/password.\r\n\r\n```powershell\r\n# Connect using API token\r\nConnect-PveCluster -HostsAndPorts 192.168.1.100:8006 `\r\n                   -SkipCertificateCheck `\r\n                   -ApiToken \"root@pam!mytoken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\r\n```\r\n\r\n**Note:** API token format is `USER@REALM!TOKENID=UUID`. If using **Privilege Separation**, ensure proper permissions are configured.\r\n\r\n### Connection Management\r\n\r\nThe `Connect-PveCluster` function creates a `PveTicket` object and stores it in `$Global:PveTicketLast`. All cmdlets use this ticket by default, or you can specify a different ticket with the `-PveTicket` parameter.\r\n\r\n## 💡 Usage Examples\r\n\r\n### Basic Operations\r\n\r\n```powershell\r\n# Connect to cluster\r\nConnect-PveCluster -HostsAndPorts 192.168.1.100:8006 -SkipCertificateCheck\r\n\r\n# Get Proxmox VE version\r\nGet-PveVersion | Select-Object -ExpandProperty Response | Select-Object -ExpandProperty data\r\n# Output: version : 8.2.0, release : 1, repoid : abc123...\r\n\r\n# List all VMs in the cluster\r\nGet-PveClusterResources -Type vm | Select-Object -ExpandProperty Response | Select-Object -ExpandProperty data\r\n# Output: vmid, name, status, node, uptime, etc.\r\n```\r\n\r\n### VM Management\r\n\r\n```powershell\r\n# Start a VM (by ID or name)\r\nStart-PveVm -VmIdOrName 100\r\n# Output: UPID:pve1:00001234:...\r\n\r\n# Stop a VM gracefully\r\nStop-PveVm -VmIdOrName \"my-vm\"\r\n\r\n# Suspend/Resume a VM\r\nSuspend-PveVm -VmIdOrName 100\r\nResume-PveVm -VmIdOrName 100\r\n\r\n# Reset a VM\r\nReset-PveVm -VmIdOrName 100\r\n\r\n# Unlock a VM\r\nUnlock-PveVm -VmIdOrName 100\r\n```\r\n\r\n### Snapshot Management\r\n\r\n```powershell\r\n# List snapshots for a VM\r\nGet-PveNodesQemuSnapshot -Node pve1 -Vmid 100 | Select -Expand Response | Select -Expand data\r\n# Output: name, snaptime, description, vmstate...\r\n\r\n# Using Get-PveVm helper\r\nGet-PveVm -VmIdOrName 100 | Get-PveNodesQemuSnapshot\r\n\r\n# Create a snapshot\r\nNew-PveNodesQemuSnapshot -Node pve1 -Vmid 100 -Snapname \"backup-2024-01-15\"\r\n# Output: snapshot created successfully\r\n\r\n# Rollback to a snapshot\r\nNew-PveNodesQemuSnapshotRollback -Node pve1 -Vmid 100 -Snapname \"backup-2024-01-15\"\r\n\r\n# Delete a snapshot\r\nRemove-PveNodesQemuSnapshot -Node pve1 -Vmid 100 -Snapname \"backup-2024-01-15\"\r\n```\r\n\r\n### Working with Indexed Parameters\r\n\r\nWhen working with indexed parameters (e.g., `-ScsiN`, `-IdeN`, `-NetN`), use hashtables:\r\n\r\n```powershell\r\n# Define configurations using hashtables\r\n$networkConfig = @{\r\n    1 = [uri]::EscapeDataString(\"model=virtio,bridge=vmbr0\")\r\n}\r\n$storageConfig = @{\r\n    1 = 'ssdpool:32'\r\n}\r\n$bootableIso = @{\r\n    1 = 'local:iso/ubuntu-22.04.iso'\r\n}\r\n\r\n# Create a new VM with indexed parameters\r\nNew-PveNodesQemu -Node pve1 `\r\n                 -Vmid 105 `\r\n                 -Memory 2048 `\r\n                 -ScsiN $storageConfig `\r\n                 -IdeN $bootableIso `\r\n                 -NetN $networkConfig\r\n```\r\n\r\n**Note:** Use `[uri]::EscapeDataString` to properly escape parameter values containing special characters.\r\n\r\nFor more detailed examples and common issues, see the [Common Issues \u0026 Examples](https://corsinvest.github.io/cv4pve-api-powershell/common-issues.html) documentation.\r\n\r\n### Monitoring Resources\r\n\r\n```powershell\r\n# Get node monitoring data (RRD data)\r\nGet-PveNodeMonitoring -Node pve1 -Timeframe hour\r\n# Output: cpu, memory, network, disk usage statistics\r\n\r\n# Get QEMU VM monitoring data\r\nGet-PveQemuMonitoring -Node pve1 -Vmid 100 -Timeframe day\r\n# Output: CPU usage, disk I/O, network traffic over time\r\n\r\n# Get LXC container monitoring data\r\nGet-PveLxcMonitoring -Node pve1 -Vmid 200 -Timeframe week\r\n```\r\n\r\n### Task Management\r\n\r\n```powershell\r\n# Execute a long-running task\r\n$result = New-PveNodesQemu -Node pve1 -Vmid 110 -Memory 4096 -Name \"new-vm\"\r\n$taskId = $result.Response.data\r\n# Output: UPID:pve1:00001F40:...\r\n\r\n# Wait for task completion\r\nWait-PveTaskIsFinish -Node pve1 -Upid $taskId\r\n\r\n# Check if a task is still running\r\n$isRunning = Get-PveTaskIsRunning -Node pve1 -Upid $taskId\r\n# Output: True/False\r\n```\r\n\r\n## Advanced Features\r\n\r\n### PveResponse Class\r\n\r\nAll cmdlets return a `PveResponse` object with rich information:\r\n\r\n```powershell\r\nclass PveResponse {\r\n    [PSCustomObject] $Response           # The actual API response\r\n    [int] $StatusCode                    # HTTP status code\r\n    [string] $ReasonPhrase              # HTTP reason phrase\r\n    [bool] $IsSuccessStatusCode         # Success indicator\r\n    [string] $RequestResource           # API endpoint called\r\n    [hashtable] $Parameters             # Request parameters\r\n    [string] $Method                    # HTTP method used\r\n    [string] $ResponseType              # Response format\r\n\r\n    # Helper methods\r\n    [bool] ResponseInError()            # Check for errors\r\n    [PSCustomObject] ToTable()          # Format as table\r\n    [PSCustomObject] ToData()           # Extract data only\r\n    [void] ToCsv([string] $filename)    # Export to CSV\r\n    [void] ToGridView()                 # Display in grid view\r\n}\r\n```\r\n\r\n### PveTicket Class\r\n\r\nConnection information is stored in a `PveTicket` object:\r\n\r\n```powershell\r\nclass PveTicket {\r\n    [string] $HostName\r\n    [int] $Port\r\n    [bool] $SkipCertificateCheck\r\n    [string] $Ticket\r\n    [string] $CSRFPreventionToken\r\n    [string] $ApiToken\r\n}\r\n```\r\n\r\n### Direct API Access\r\n\r\nFor operations not covered by cmdlets, use `Invoke-PveRestApi`:\r\n\r\n```powershell\r\n# Make a custom API call\r\n$result = Invoke-PveRestApi -Method Get `\r\n                            -Resource \"/api2/json/nodes/pve1/status\" `\r\n                            -PveTicket $Global:PveTicketLast\r\n\r\n# Display results\r\n$result.Response.data\r\n```\r\n\r\n### High Availability Connections\r\n\r\nConnect to multiple hosts for HA failover:\r\n\r\n```powershell\r\n# Connect to multiple nodes\r\nConnect-PveCluster -HostsAndPorts \"192.168.1.100:8006,192.168.1.101:8006,192.168.1.102:8006\" `\r\n                   -SkipCertificateCheck\r\n```\r\n\r\n---\r\n\r\n## Support\r\n\r\nFor professional consulting and enterprise support, visit [www.corsinvest.it](https://www.corsinvest.it)\r\n\r\n---\r\n\r\nPart of [cv4pve](https://www.corsinvest.it/cv4pve) suite | Made with ❤️ in Italy by [Corsinvest](https://www.corsinvest.it)\r\n\r\nCopyright © Corsinvest Srl","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorsinvest%2Fcv4pve-api-powershell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorsinvest%2Fcv4pve-api-powershell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorsinvest%2Fcv4pve-api-powershell/lists"}