How to use ESXCLI v2 Commands in PowerCLI

PowerCLI, a set of PowerShell extensions for vSphere, is a great tool for automating VMware configuration and management tasks. It allows you to change a lot of ESXi host and vCenter settings. A powerful cmdlet is Get-EsxCli which allows you to run ESXCLI tasks from your PowerCLI console. ESXCLI is the main configuration command on an ESXi host.

This post explains how to use the Get-EsxCli cmdlet with the new V2 interface, which is much more intuitive than the old method.

Getting Started with Get-ESXCli -V2

First of all, grab the latest version of vSphere PowerCLI. You can always find a link to the latest version at my VMware Product Latest Version page. You should at least use PowerCLI 6.5 Release 1 [Download]. PowerCLI cmdlets are backward compatible, so you dont need vSphere 6.5 to use the latest release.

Connect to a vCenter Server or an ESXi Host directly and use the Get-EsxCli cmdlet to create the object that you can run commands against. Make sure to add the -V2 parameter to use new interface.

Connect-VIServer vc.virten.lab -User "admin" -Password "vmware"
$esxcli = Get-EsxCli -VMhost esx1.virten.lab -V2

The $esxcli variable can now be used in the same way as the esxcli command on an ESXi host. You can list all available namespaces by printing the variable:

PS C:\> $esxcli

=======================
EsxCli: esx1.virten.lab

   Elements:
   ---------
   device
   elxnet
   esxcli
   fcoe
   graphics
   hardware
   iscsi
   network
   nvme
   rdma
   sched
   software
   storage
   system
   vm
   vsan

To crawl through namespaces you can append any element to the $esxcli variable like you know it from esxcli. The only difference is that in PowerCLI the namespace is separated by a dot instead of a blank.

PS C:\> $esxcli.network

======================
EsxCliElement: network

   Elements:
   ---------
   diag
   firewall
   ip
   multicast
   nic
   port
   sriovnic
   vm
   vswitch


   Methods:
   --------
   string Help()

At some point "Method Elements" show up:

PS C:\> $esxcli.network.nic

==================
EsxCliElement: nic

   Elements:
   ---------
   coalesce
   cso
   eeprom
   negotiate
   pauseParams
   queue
   register
   ring
   selftest
   sg
   software
   stats
   tso
   vlan


   Method Elements:
   ---------
   down
   get
   list
   set
   up


   Methods:
   --------
   string Help()

The behavior to run a command has been changed with the new Get-EsxCli V2 interface. Instead of using $esxcli.network.nic.list() you have to use $esxcli.network.nic.list.Invoke().

PS C:\> $esxcli.network.nic.list.Invoke()

AdminStatus : Up
Description : Intel Corporation Ethernet Connection (2) I219-V
Driver      : ne1000
Duplex      : Full
Link        : Up
LinkStatus  : Up
MACAddress  : 00:1f:c6:9b:96:59
MTU         : 1500
Name        : vmnic0
PCIDevice   : 0000:00:1f.6
Speed       : 1000

The major change in Get-EsxCli V2 is the behavior when running commands with parameters. Instead of listing all parameters in the required sequence, you can now specify parameters by their name. To list available parameter you can either call CreateArgs() or the Help() function.

PS C:\> $esxcli.vm.process.kill.CreateArgs()

Name        Value 
----        ----- 
type        Unset, ([string]) 
worldid     Unset, ([long])

 C:\> $esxcli.vm.process.kill.Help()

=======================================================================================================================
vim.EsxCLI.vm.process.kill
-----------------------------------------------------------------------------------------------------------------------
Used to forcibly kill Virtual Machines that are stuck and not responding to normal stop operations.

Param
-----------------------------------------------------------------------------------------------------------------------
- type      | The type of kill operation to attempt. There are three types of VM kills that can be attempted: 
            | [soft, hard, force]. Users should always attempt 'soft' kills first, which will give the VMX p
            | rocess a chance to shutdown cleanly (like kill or kill -SIGTERM). If that does not work move to 
            | 'hard' kills which will shutdown the process immediately (like kill -9 or kill -SIGKILL). 'force
            | ' should be used as a last resort attempt to kill the VM. If all three fail then a reboot is req
            | uired. 

- world-id  | The World ID of the Virtual Machine to kill. This can be obtained from the 'vm process list' com
            | mand 

Be aware that the Help() function may display parameters containing hyphens, which does not work when running the command. Just omit hyphens when setting the parameter as correctly shown by CreateArgs().

Use the Invoke() method and pass parameters as a hashtable to run the command:

PS C:\> $esxcli.vm.process.kill.Invoke(@{type = 'hard'; worldid = '2251094'})
true

Alternatively you can use a helper object to pass parameters:

PS C:\> $esxcli = Get-ESXCLI -VMHost (Get-VMhost esx4.virten.lab) -V2
PS C:\> $arguments = $esxcli.network.diag.ping.CreateArgs()
PS C:\> $arguments
Name                           Value 
----                           -----      
host                           Unset, ([string], optional) 
wait                           Unset, ([string], optional) 
df                             Unset, ([boolean], optional)
interval                       Unset, ([string], optional)
ttl                            Unset, ([long], optional) 
debug                          Unset, ([boolean], optional)
nexthop                        Unset, ([string], optional)
count                          Unset, ([long], optional)  
netstack                       Unset, ([string], optional) 
size                           Unset, ([long], optional)  
ipv4                           Unset, ([boolean], optional) 
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional) 
PS C:\> $arguments.count = 2
PS C:\> $arguments.host = “192.168.0.1”
PS C:\> $arguments
Name                           Value
----                           -----   
host                           192.168.222.250   
wait                           Unset, ([string], optional)  
df                             Unset, ([boolean], optional) 
interval                       Unset, ([string], optional)  
ttl                            Unset, ([long], optional)    
debug                          Unset, ([boolean], optional)   
nexthop                        Unset, ([string], optional)  
count                          2   
netstack                       Unset, ([string], optional)    
size                           Unset, ([long], optional)    
ipv4                           Unset, ([boolean], optional)
ipv6                           Unset, ([boolean], optional)
interface                      Unset, ([string], optional)  

PS C:\> $esxcli.network.diag.ping.Invoke($arguments)

With a foreach loop you can quickly run the same esxcli command on many hosts:

$EsxHosts = Get-VMHost
foreach($EsxHost in $EsxHosts){
  $esxcli = Get-VMHost $EsxHost | Get-EsxCli -V2
  $esxcli.vm.process.list.Invoke()
}

The following table displays all commands with their paramters. available in ESXi 6.5.