First CLI session

What you build

You install the kyvernon command-line client on a machine of your own, sign in to the controller, list objects of the inventory and start a task that you wait for.

Before you start

• A running controller whose address you know, for example https://controller.example.com:8443. Install from an offline depot sets one up.
• A user name and password for it. After First sign-in the admin user needs its six-digit code as well.
• A Debian or Ubuntu machine, the depot directory and the release public key, as in the install lesson.

1. Install the client

On the machine that should run the client:

sudo ./kyvernon-install --role cli --pubkey /path/to/release-signing.minisign.pub

The installer verifies the depot as in the install lesson, then installs only the kyvernon-cli package.

2. Tell the client where the controller is

The client reads the address of the controller from --server or from the variable KYVERNON_SERVER:

export KYVERNON_SERVER=https://controller.example.com:8443

A controller that still has its bootstrap certificate is not trusted by the machine. Add --insecure to every command until the controller has a certificate that the machine trusts, and only on a network you control. The examples below leave it out.

3. Sign in

The client reads the password from the variable KYVERNON_PASSWORD or from standard input, never from the command line:

read -rs KYVERNON_PASSWORD
export KYVERNON_PASSWORD
kyvernon login admin --save --code <code>

Replace <code> with the current six-digit code of your authenticator app, or leave out --code for a user without two-step verification. The command prints the token. --save also writes it to the credentials file, so later commands need no --token. The file is $XDG_CONFIG_HOME/kyvernon/credentials.json, written with mode 0600 in a directory with mode 0700. The saved token belongs to the controller you signed in to: with another --server the client refuses to send it and exits with code 3.

4. Check the connection

kyvernon whoami
kyvernon about

whoami shows the identity of the current session. about prints the service information of the controller.

5. List the inventory

kyvernon inventory roots
kyvernon inventory vms
kyvernon inventory hosts
kyvernon inventory datastores
kyvernon inventory search <name>

Lists appear as a table. Add --json for the raw response, which scripts can read:

kyvernon inventory vms --json

Every object has an identifier such as vm-42. The commands that act on an object take it as an argument.

6. Start a task and wait for it

Pick a powered-off virtual machine, for example the one from First virtual machine, and power it on:

kyvernon vm power-on <id>

The command returns at once with the task that Kyvernon created. Wait for the task to end with the identifier it printed:

kyvernon tasks wait <task-id>

The wait command stops after 60 seconds by default; --timeout changes that. Most commands that start a task accept --wait, which does both steps:

kyvernon vm shutdown <id> --wait

The exit code tells a script what happened: 0 for success, 1 for failure, 2 for a usage or connection error, 3 when the session is not authenticated or not permitted, and 4 when the object is not found.

7. Keep a token for scripts

A script should not hold your password. Create an API token and give it to the script as a file:

kyvernon auth api-tokens create ci-build --ttl <seconds>
kyvernon --token-file /etc/ci/kyvernon.token inventory vms

The secret is printed once; store it on the first line of the file. The client also reads --token and the variables KYVERNON_TOKEN and KYVERNON_TOKEN_FILE.

8. End the session

kyvernon logout

This revokes the session on the controller. For tab completion in your shell, kyvernon completion bash prints a script for Bash. Zsh, Fish, PowerShell and Elvish are available under the same command, for example source <(kyvernon completion bash).

Result

You have a client that signs in to the controller, lists the inventory, runs a task and waits for it. The complete list of commands is in the CLI reference.

Next steps

• Overview explains the objects that the commands name.
• Power operations lists the power commands of a virtual machine.
• Connect vSphere tools points tools written for the vSphere API at the controller.