{"id":13521649,"url":"https://github.com/Corsinvest/cv4pve-api-powershell","last_synced_at":"2025-03-31T20:32:18.690Z","repository":{"id":44573773,"uuid":"206079622","full_name":"Corsinvest/cv4pve-api-powershell","owner":"Corsinvest","description":"ProxmoxVE PowerShell module for accessing API like VMware PowerCLI ","archived":false,"fork":false,"pushed_at":"2025-03-12T14:29:33.000Z","size":2618,"stargazers_count":56,"open_issues_count":3,"forks_count":15,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T14:07:00.883Z","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}},"created_at":"2019-09-03T13:06:28.000Z","updated_at":"2025-03-12T14:29:37.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":19,"template":false,"template_full_name":null,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246536130,"owners_count":20793392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-08-01T06:00:36.749Z","updated_at":"2025-03-31T20:32:18.136Z","avatar_url":"https://github.com/Corsinvest.png","language":"PowerShell","funding_links":[],"categories":["🔧 API \u0026 SDKs"],"sub_categories":["💻 Language-Specific Libraries"],"readme":"# cv4pve-api-powershell\r\n\r\n[![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/Corsinvest.ProxmoxVE.Api)](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/)\r\n![download](https://img.shields.io/powershellgallery/dt/Corsinvest.ProxmoxVE.Api)\r\n\r\n[ProxmoxVE Api](https://pve.proxmox.com/pve-docs/api-viewer/)\r\n\r\n[PowerShell Gallery](https://www.powershellgallery.com/packages/Corsinvest.ProxmoxVE.Api/)\r\n\r\n```text\r\n    ______                _                      __\r\n   / ____/___  __________(_)___ _   _____  _____/ /_\r\n  / /   / __ \\/ ___/ ___/ / __ \\ | / / _ \\/ ___/ __/\r\n / /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_\r\n \\____/\\____/_/  /____/_/_/ /_/|___/\\___/____/\\__/\r\n\r\npowerShell for Proxmox VE         (Made in Italy)\r\n\r\ncv4pve-api-powershell is a part of suite cv4pve.\r\nFor more information visit https://www.corsinvest.it/cv4pve\r\n```\r\n\r\n## 📰 Copyright\r\n\r\nCopyright: Corsinvest Srl\r\nFor licensing details please visit [LICENSE](LICENSE)\r\n\r\n## 🦺 Commercial Support\r\n\r\nThis software is part of a suite of tools called cv4pve. If you want commercial support, visit the [site](https://www.corsinvest.it/cv4pve)\r\n\r\n## Introduction\r\n\r\nPowerShell for Proxmox VE.\r\n\r\n![PowerShell for Proxmox VE](https://raw.githubusercontent.com/Corsinvest/cv4pve-api-powershell/master/images/powershell.png)\r\n\r\nthis is a CmdLet for PowerShell to manage Proxmox VE.\r\n\r\n## 🚀 Main features\r\n\r\n* Easy to learn\r\n* Set ResponseType json, png, extjs, html, text\r\n* Full class and method generated from documentation (about client)\r\n* Comment any method and parameters\r\n* Parameters indexed eg [n] is structured in array index and value\r\n* Return data Proxmox VE\r\n* Return result class more information PveResponse\r\n  * Request\r\n  * Response\r\n  * Status\r\n* Utility\r\n  * ConvertFrom-PveUnixTime\r\n  * Wait-PveTaskIsFinish\r\n  * Get-PveTaskIsRunning\r\n  * Build-PveDocumentation\r\n  * Get-PveVm (from id or name)\r\n  * Unlock-PveVm (from id or name)\r\n  * Start-PveVm (from id or name)\r\n  * Stop-PveVm (from id or name)\r\n  * Suspend-PveVm (from id or name)\r\n  * Resume-PveVm (from id or name)\r\n  * Reset-PveVm (from id or name)\r\n  * And More\r\n* Method direct access using Invoke-PveRestApi return PveResponse\r\n* Connect-PveCluster accept multiple hosts for HA\r\n* Completely written in PowerShell\r\n* Use native api REST Proxmox VE\r\n* Independent os (Windows, Linux, Macosx)\r\n* Installation from PowerShellGallery or download file\r\n* Not require installation in Proxmox VE\r\n* Execute out side Proxmox VE\r\n* Open Source\r\n* Form Proxmox VE 6.2 support Api Token for user\r\n* Invoke-PveSpice enter Spice VM\r\n* Login with One-time password for Two-factor authentication\r\n\r\n## 📙 Documentation\r\n\r\n[Documentation](https://raw.githack.com/Corsinvest/cv4pve-api-powershell/master/doc/index.html)\r\n\r\n## Tutorial\r\n\r\n[Tutorial interactive in VSCode notebook](https://tinyurl.com/cv4pve-api-pwsh-learn)\r\n\r\n## Video\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## Requirement\r\n\r\nMinimum version requirement for Powershell is 6.0\r\n\r\n## Installation\r\n\r\nInstall [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell) in your system.\r\n\r\n### From PowerShell Gallery\r\n\r\nOpen PowerShell and install module form [gallery](https://www.powershellgallery.com/)\r\n\r\n```ps\r\nPS /home/frank\u003e Install-Module -Name Corsinvest.ProxmoxVE.Api\r\n```\r\n\r\n### Manual\r\n\r\nDownload folder Corsinvest.ProxmoxVE.Api and copy in path module\r\n\r\n```ps\r\n# show path module\r\nPS /home/frank\u003e [Environment]::GetEnvironmentVariable(\"PSModulePath\")\r\n```\r\n\r\n## Api token\r\n\r\nFrom version 6.2 of Proxmox VE is possible to use [Api token](https://pve.proxmox.com/pve-docs/pveum-plain.html).\r\nThis feature permit execute Api without using user and password.\r\nIf using **Privilege Separation** when create api token remember specify in permission.\r\nFormat USER@REALM!TOKENID=UUID\r\n\r\n## Connect to cluster\r\n\r\nFor connection use the function Connect-PveCluster. This function generate a Ticket object that refer a PveTicket class.\r\nThe first connection saved ticket data in the variable $Global:PveTicketLast. In the various functions, the -PveTicket parameter is the connection reference ticket. If not specified will be used $Global:PveTicketLast.\r\n\r\n## PveTicket Class\r\n\r\nThis class contain data after connection and login Connect-PveCluster\r\n\r\n```ps\r\nclass PveTicket {\r\n    [string] $HostName = ''\r\n    [int] $Port = 8006\r\n    [bool] $SkipCertificateCheck = $true\r\n    [string] $Ticket = ''\r\n    [string] $CSRFPreventionToken = ''\r\n    [string] $ApiToken = ''\r\n}\r\n```\r\n\r\n## PveResponse Class\r\n\r\nThis class contain data after execution any command\r\n\r\n```ps\r\nclass PveResponse {\r\n    #Contain real response of Proxmox VE\r\n    #Is converted in object Json response\r\n    [PSCustomObject] $Response\r\n    [int] $StatusCode = 200\r\n    [string] $ReasonPhrase\r\n    [bool] $IsSuccessStatusCode = $true\r\n    [string] $RequestResource\r\n    [hashtable] $Parameters\r\n    [string] $Method\r\n    [string] $ResponseType\r\n\r\n    [bool] ResponseInError() { return $null -ne $this.Response.error }\r\n    [PSCustomObject] ToTable() { return $this.Response.data | Format-Table -Property * }\r\n    [PSCustomObject] ToData() { return $this.Response.data }\r\n    [void] ToCsv([string] $filename) { $this.Response.data | Export-Csv $filename }\r\n    [void] ToGridView() { $this.Response.data | Out-GridView -Title \"View Result Data\" }\r\n}\r\n```\r\n\r\n## Usage\r\n\r\nExample Connect and get version\r\n\r\n```ps\r\n#Connection to cluster user and password\r\nPS /home/frank\u003e Connect-PveCluster -HostsAndPorts 192.168.190.191:8006,192.168.190.192 -SkipCertificateCheck\r\nPowerShell credential request\r\nProxmox VE Username and password, username formatted as user@pam, user@pve, user@yourdomain or user (default domain pam).\r\nUser: test\r\nPassword for user test: ****\r\n\r\n#return Ticket, default set $Global:PveTicketLast\r\n#this is useful when connections to multiple clusters are needed use parameter -SkipRefreshPveTicketLast\r\nHostName             : 192.168.190.191\r\nPort                 : 8006\r\nSkipCertificateCheck : True\r\nTicket               : PVE:test@pam:5EFF3CCA::iXhSNb5NTgNUYznf93mBOhj8pqYvAXoecKBHCXa3coYwBWjsWO/x8TO1gIDX0yz9nfHuvY3alJ0+Ew5AouOTZlZl3NODO9Cp4Hl87qnzhsz4wvoYEzvS1NUOTBekt+yAa68jdbhP\r\n                        OzhOd8ozEEQIK7Fw2lOSa0qBFUTZRoMtnCnlsjk/Nn3kNEnZrkHXRGm46fA+asprvr0nslLxJgPGh94Xxd6jpNDj+xJnp9u6W3PxiAojM9g7IRurbp7ZCJvAgHbA9FqxibpgjaVm4NCd8LdkLDgCROxgYCjI3eR\r\n                        gjkDvu1P7lLjK9JxSzqnCWWD739DT3P3bW+Ac3SyVqTf8sw==\r\nCSRFPreventionToken  : 5EFF3CCA:Cu0NuFiL6CkhFdha2V+HHigMQPk\r\n\r\n#Connection to cluster using Api Token\r\nPS /home/frank\u003e Connect-PveCluster -HostsAndPorts 192.168.190.191:8006,192.168.190.192 -SkipCertificateCheck -ApiToken root@pam!qqqqqq=8a8c1cd4-d373-43f1-b366-05ce4cb8061f\r\nHostName             : 192.168.190.191\r\nPort                 : 8006\r\nSkipCertificateCheck : True\r\nTicket               :\r\nCSRFPreventionToken  :\r\nApiToken             : root@pam!qqqqqq=8a8c1cd4-d373-43f1-b366-05ce4cb8061f\r\n\r\n#For disable output call Connect-PveCluster \u003e $null\r\n\r\n#Get version\r\nPS /home/frank\u003e $ret = Get-PveVersion\r\n\r\n#$ret return a class PveResponse\r\n\r\n#Show data\r\nPS /home/frank\u003e $ret.Response.data\r\nrepoid   release keyboard version\r\n------   ------- -------- -------\r\nd0ec33c6 15      it       5.4\r\n\r\n#Show data 2\r\nPS /home/frank\u003e $ret.ToTable()\r\nrepoid   release keyboard version\r\n------   ------- -------- -------\r\nd0ec33c6 15      it       5.4\r\n```\r\n\r\nGet snapshots of vm\r\n\r\n```ps\r\nPS /home/frank\u003e (Get-PveNodesQemuSnapshot -Node pve1 -Vmid 100).ToTable()\r\n\r\nvmstate name                         parent                       description       snaptime\r\n------- ----                         ------                       -----------       --------\r\n      0 autowin10service200221183059 autowin10service200220183012 cv4pve-autosnap 1582306261\r\n      0 autowin10service200220183012 autowin10service200219183012 cv4pve-autosnap 1582219813\r\n      0 autowin10service200224183012 autowin10service200223183014 cv4pve-autosnap 1582565413\r\n      0 autowin10service200223183014 autowin10service200222183019 cv4pve-autosnap 1582479015\r\n      0 autowin10service200215183012 autowin10service200214183012 cv4pve-autosnap 1581787814\r\n      0 autowin10service200216183017 autowin10service200215183012 cv4pve-autosnap 1581874219\r\n      0 autowin10service200218183010 autowin10service200216183017 cv4pve-autosnap 1582047011\r\n      0 autowin10service200219183012 autowin10service200218183010 cv4pve-autosnap 1582133413\r\n      0 autowin10service200214183012                              cv4pve-autosnap 1581701413\r\n      0 autowin10service200222183019 autowin10service200221183059 cv4pve-autosnap 1582392621\r\n        current                      autowin10service200224183012 You are here!\r\n```\r\n\r\nOther method\r\n\r\n```ps\r\n(Get-PveVm -VmIdOrName 100 | Get-PveNodesQemuSnapshot).ToTable()\r\nvmstate name                         parent                       description       snaptime\r\n------- ----                         ------                       -----------       --------\r\n      0 autowin10service200221183059 autowin10service200220183012 cv4pve-autosnap 1582306261\r\n      0 autowin10service200220183012 autowin10service200219183012 cv4pve-autosnap 1582219813\r\n      0 autowin10service200224183012 autowin10service200223183014 cv4pve-autosnap 1582565413\r\n      0 autowin10service200223183014 autowin10service200222183019 cv4pve-autosnap 1582479015\r\n      0 autowin10service200215183012 autowin10service200214183012 cv4pve-autosnap 1581787814\r\n      0 autowin10service200216183017 autowin10service200215183012 cv4pve-autosnap 1581874219\r\n      0 autowin10service200218183010 autowin10service200216183017 cv4pve-autosnap 1582047011\r\n      0 autowin10service200219183012 autowin10service200218183010 cv4pve-autosnap 1582133413\r\n      0 autowin10service200214183012                              cv4pve-autosnap 1581701413\r\n      0 autowin10service200222183019 autowin10service200221183059 cv4pve-autosnap 1582392621\r\n        current                      autowin10service200224183012 You are here!\r\n```\r\n\r\n## Indexed data parameter\r\n\r\nif you need to pass indexed parameters e.g. (-ScsiN, -IdeN, -NetN) you must use the following way:\r\n\r\n```powershell\r\n#create variabile\r\n$networkConfig = @{ 1 = [uri]::EscapeDataString(\"model=virtio,bridge=vmbr0\") }\r\n$storageConfig = @{ 1 = 'ssdpool:32' }\r\n$bootableIso = @{ 1 = 'local:iso/ubuntu.iso' }\r\n\r\n#use variable\r\nNew-PveNodesQemu -Node $node -Vmid 105 -Memory 2048 -ScsiN $storageConfig -IdeN $bootableIso -NetN $networkConfig\r\n```\r\n\r\nThe **[uri]::EscapeDataString** escape value to pass.\r\n\r\n## Build documentation\r\n\r\nFor build documentation use command **Build-PveDocumentation**\r\n\r\nThis command accept **TemplateFile** parameter is a template for generate documentation.\r\nThe default [file](https://raw.githubusercontent.com/corsinvest/cv4pve-api-powershell/master/help-out-html.ps1).\r\n","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"}