Michal Jankowski
Michal Jankowski Allowing the use of STS for exchanging tokens
In the simplest STS is responsible for issuing tokens required for
authentication. In the most common case it issues SAML Bearer token when
client authenticates using credentials and SAML Holder-of-key (HOK) token
when certificate/private key pair is used for authentication.

STS however supports also more sophisticated use-cases for exchanging
one type of token for another. Allowing to exchange an HOK token for
bearer token or use of JWT tokens.

This change adds an option to allow requesting a specific KeyType when
calling Issue to obtain a new token and use a previously obtained Signer
to authenticate the new call to STS to issue another token.
Latest commit 862da06 Sep 6, 2018
Failed to load latest commit information.
about Switch to kr/pretty package for the -dump flag Oct 26, 2017
cli Add support for SOAP request operation ID header Sep 26, 2017
cluster govc: add new command cluster.rule.info Jul 27, 2018
datacenter Switch to kr/pretty package for the -dump flag Oct 26, 2017
datastore Add VirtualDiskManager wrapper to set UUID May 19, 2018
device Add 'Type' field to device.info -json output Feb 16, 2018
dvs Print action for dvs security groups Aug 28, 2018
emacs Bump versions May 24, 2018
env Documentation updates Oct 20, 2016
events vcsim: add support for PropertyCollector incremental updates Jul 19, 2018
examples/lib Use vcsim in bats tests Jul 13, 2017
export Add support for VM export Oct 3, 2017
extension Refactor LoginExtensionByCertificate tunnel usage Apr 6, 2018
fields Bump to 1.7 and start using new context pkg Aug 22, 2016
flags Avoid use of Finder all param in govc Aug 24, 2018
folder Switch to kr/pretty package for the -dump flag Oct 26, 2017
host Fixed govc host.info logical CPU count Jun 13, 2018
importx Handle empty file name in import.spec Sep 6, 2018
license govc: add -cluster flag to license.assign command Jan 17, 2018
logs Several context changes: Jan 25, 2018
ls Avoid use of Finder all param in govc Aug 24, 2018
metric Switch to kr/pretty package for the -dump flag Oct 26, 2017
object vcsim: add support for PropertyCollector incremental updates Jul 19, 2018
option vcsim: add UpdateOptions support Jan 12, 2018
permissions vcsim: AuthorizationManager additions Oct 19, 2017
pool Add support for cpu + mem allocation to vm.change command (#916) Nov 10, 2017
role Doc updates Jun 6, 2017
session Allowing the use of STS for exchanging tokens Sep 6, 2018
sso Merge pull request #1129 from dougm/govc-sso-login May 19, 2018
tags Finalize tags API Aug 22, 2018
task Fixup recent tasks output Sep 18, 2017
test Finalize tags API Aug 22, 2018
vapp Remove _Task suffix from vapp methods Jan 24, 2017
version Add goreleaser to automate release process Mar 16, 2018
vm Add -sharing option to vm.disk.create and vm.disk.attach May 20, 2018
.gitignore Print DVS rules for dvportgroup Aug 23, 2018
CHANGELOG.md Update docs for 0.18 release May 24, 2018
README.md Update docs for 0.18 release May 24, 2018
USAGE.md Update docs for 0.18 release May 24, 2018
build.sh Print DVS rules for dvportgroup Aug 23, 2018
main.go Complete tags management APIs (#1162) Jun 25, 2018
main_test.go Bump to 1.7 and start using new context pkg Aug 22, 2016
release.sh govc release 0.17 Feb 28, 2018
usage.sh Print Table of Contents in usage.md Feb 28, 2018



govc is a vSphere CLI built on top of govmomi.

The CLI is designed to be a user friendly CLI alternative to the GUI and well suited for automation tasks. It also acts as a test harness for the govmomi APIs and provides working examples of how to use the APIs.


You can find prebuilt govc binaries on the releases page.

Download and install a binary locally like this:

% curl -L $URL_TO_BINARY | gunzip > /usr/local/bin/govc
% chmod +x /usr/local/bin/govc


To build govc from source, first install the Go toolchain.

Make sure to set the environment variable GOPATH.

You can then install the latest govc from github using:

% go get -u github.com/vmware/govmomi/govc

Make sure $GOPATH/bin is in your PATH to use the version installed from source.

If you've made local modifications to the repository at $GOPATH/src/github.com/vmware/govmomi, you can install using:

% go install github.com/vmware/govmomi/govc


For the complete list of commands and flags, refer to the USAGE document.

Common flags include:

  • -u: ESXi or vCenter URL (ex: user:pass@host)
  • -debug: Trace requests and responses (to ~/.govmomi/debug)

Managed entities can be referred to by their absolute path or by their relative path. For example, when specifying a datastore to use for a subcommand, you can either specify it as /mydatacenter/datastore/mydatastore, or as mydatastore. If you're not sure about the name of the datastore, or even the full path to the datastore, you can specify a pattern to match. Both /*center/*/my* (absolute) and my*store (relative) will resolve to the same datastore, given there are no other datastores that match those globs.

The relative path in this example can only be used if the command can umambigously resolve a datacenter to use as origin for the query. If no datacenter is specified, govc defaults to the only datacenter, if there is only one. The datacenter itself can be specified as a pattern as well, enabling the following arguments: -dc='my*' -ds='*store'. The datastore pattern is looked up and matched relative to the datacenter which itself is specified as a pattern.

Besides specifying managed entities as arguments, they can also be specified using environment variables. The following environment variables are used by govc to set defaults:

  • GOVC_URL: URL of ESXi or vCenter instance to connect to.

    The URL scheme defaults to https and the URL path defaults to /sdk. This means that specifying user:pass@host is equivalent to https://user:pass@host/sdk.

    If username or password includes special characters like \, # or : you can use GOVC_USERNAME and GOVC_PASSWORD to have a simple GOVC_URL

    When using govc against VMware Workstation, GOVC_URL can be set to "localhost" without a user or pass, in which case local ticket based authentication is used.

  • GOVC_USERNAME: USERNAME to use if not specified in GOVC_URL.

  • GOVC_PASSWORD: PASSWORD to use if not specified in GOVC_URL.

  • GOVC_TLS_CA_CERTS: Override system root certificate authorities.

    $ export GOVC_TLS_CA_CERTS=~/.govc_ca.crt
    # Use path separator to specify multiple files:
    $ export GOVC_TLS_CA_CERTS=~/ca-certificates/bar.crt:~/ca-certificates/foo.crt
  • GOVC_TLS_KNOWN_HOSTS: File(s) for thumbprint based certificate verification.

    Thumbprint based verification can be used in addition to or as an alternative to GOVC_TLS_CA_CERTS for self-signed certificates. Example:

    $ export GOVC_TLS_KNOWN_HOSTS=~/.govc_known_hosts
    $ govc about.cert -u host -k -thumbprint | tee -a $GOVC_TLS_KNOWN_HOSTS
    $ govc about -u user:pass@host
  • GOVC_TLS_HANDSHAKE_TIMEOUT: Limits the time spent performing the TLS handshake.

  • GOVC_INSECURE: Disable certificate verification.

    This option sets Go's tls.Config.InsecureSkipVerify flag and is false by default. Quoting https://golang.org/pkg/crypto/tls/#Config:

    InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name.

    If InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate.

    In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.






  • GOVC_GUEST_LOGIN: Guest credentials for guest operations

  • GOVC_VIM_NAMESPACE: Vim namespace defaults to urn:vim25

  • GOVC_VIM_VERSION: Vim version defaults to 6.0


Environment variables

If you're using environment variables to set GOVC_URL, verify the values are set as expected:

% govc env

Connection issues

Check your proxy settings:

% env | grep -i https_proxy

Test connection using curl:

% curl --verbose -k -X POST https://x.x.x.x/sdk

MSYS2 (Windows)

Inventory path arguments with a leading '/' are subject to Posix path conversion.


Several examples are embedded in the govc command help


Changes to the cli are subject to semantic versioning.

Refer to the CHANGELOG for version to version changes.

When new govc commands or flags are added, the PATCH version will be incremented. This enables you to require a minimum version from within a script, for example:

% govc version -require 0.14

Projects using govc

Related projects


govc is available under the Apache 2 license.