Contexts

The other cv4pve tools take the host and the token on every command line. cv4pve-cli is used interactively, many times a day, often against more than one cluster, so, as kubectl does, it saves each connection once as a context and every command uses the current one.

Add a context

# API token (recommended)
cv4pve-cli config add prod --host=pve01.example.com --api-token='cli@pve!cli=UUID'

# User and password
cv4pve-cli config add lab --host=10.0.0.11 --username=admin@pve --password='…'

Option	What it does
<name>	Name of the context, used by config use and the other config commands. Adding a name that exists replaces that context.
--host	Required. A node of the cluster: host name, IPv4 or IPv6 address, with its own port if it differs (pve01:8007, [fd00::11]:8007). Several nodes, comma-separated (pve01,pve02), are tried in order at each command, and the first that answers is used, so the context keeps working while a node is down. A node that does not answer delays the command until the connection attempt fails (the operating system decides how long, not --timeout); if the login fails on the node that answered, the others are not tried.
--port	API port of the nodes written without one. Default 8006.
--api-token	USER@REALM!TOKENID=UUID. When a token is set, it is used and the username and password are ignored.
--username / --password	Alternative to the token. Without a realm (root), pam is used. Accounts with two-factor authentication cannot log in this way: use a token.
--validate-certificate	true or false. Default true, see Certificate.
--timeout	Seconds to wait for each API call. Default 30.

After saving, cv4pve-cli connects once and prints the Proxmox VE version, or a Warning: with the reason it could not connect. The context is saved either way, so you can fix it with config set. The first context you add becomes the current one.

Several clusters

cv4pve-cli config list                 # * marks the current context
cv4pve-cli config use lab              # every command from now on goes to lab
cv4pve-cli config current              # prints: lab

  prod                 pve01.example.com:8006   (api-token)
* lab                  10.0.0.11:8006  admin@pve

The current context is saved in the configuration file, so it stays the same in every terminal until you change it. There is no option to pick a context for a single command: switch with config use.

Change, check and remove

Command	What it does
config set <name> [options]	Changes only the options given (the same options as config add), then tries to connect.
config verify [<name>]	Connects to the context (the current one when no name is given) and prints the Proxmox VE version. Exit code 4 if it cannot connect, 3 if the context does not exist.
config view	Prints every context. The password and the secret of the token are shown as ****.
config rename <name> <new-name>	Renames a context.
config delete <name>	Removes a context. If it was the current one, the first remaining context becomes current.

Certificate

Unlike the other cv4pve tools, cv4pve-cli validates the certificate of the nodes by default. A new Proxmox VE node has a self-signed certificate, so the connection fails until you either give the nodes a trusted certificate (the ACME support of Proxmox VE can get one from Let’s Encrypt), or turn the check off for that context:

cv4pve-cli config set lab --validate-certificate false

Without the check, anyone who can intercept the traffic between you and the node can read the token or the password. Turn it off only on a network you trust.

Options in a file

The options of a context (several nodes, token, timeout) can also go in a file, passed with @. Useful to create the same context on several workstations, or to keep it next to the scripts that use it. The options belong to config add, so the file goes after the command.

Put the options you repeat (the connection above all) in a file and pass it with @. The file is read as if its content were typed on the command line, so no shell quoting is needed: an API token with ! goes in as it is.

prod.rsp

# Nodes of the production cluster
--host=pve01,pve02,pve03

# API token (recommended)
--api-token=cli@pve!cli=<uuid>

# The certificate is checked by default in cv4pve-cli: turn it off for self-signed certificates
# --validate-certificate=false

--timeout=60

cv4pve-cli config add prod @prod.rsp

• @prod.rsp is replaced by its content where it stands, so put it where those options are valid: with the other options of the command, before or after them.
• Options are separated by spaces, one or more per line: --option=value or--option value. A value with spaces goes in quotes: --settings-file="C:\My Files\settings.json".
• A line that starts with # is a comment: handy to keep alternatives ready, as above. A# after an option is not: it is read as an argument and the command fails.
• @other.rsp inside a file includes another file, for example one with the connection, shared by files with different options.

A file with a password or an API token is as sensitive as the password itself: keep it readable only by the account that runs the tool (chmod 600 on Linux). TheSystem.CommandLine library the tools are built on calls such a file a response file.

Where the credentials are stored

Contexts are saved in a YAML file in your home folder:

System	File
Linux, macOS	~/.cv4pve/cli/config
Windows	%USERPROFILE%\.cv4pve\cli\config

The token and the password are stored in clear text

The file holds the API token and the password as you typed them, neither encrypted nor obfuscated. On Linux and macOS cv4pve-cli sets its permissions to 600 (readable only by you) every time it writes it. On Windows it leaves the permissions the file inherits from your profile folder.

Anyone who can read the file can use the cluster with the privileges of that account. So:

• prefer an API token to a password: it can be revoked on its own and limited to the privileges cv4pve-cli needs (see Permissions);
• never use root@pam for a saved context;
• keep the file out of backups, dotfile repositories and shared folders.

You can edit the file by hand; the other files cv4pve-cli keeps in the same folder are listed in Files.