Tab completion
The Proxmox VE API has hundreds of paths, and the useful ones contain node names and VM IDs you would otherwise look up in the web interface. cv4pve-cli completes them with TAB, reading the names and IDs from the cluster of the current context.
What it completes
Section titled “What it completes”| You type | TAB offers |
|---|---|
cv4pve-cli |
The commands and the first word of the aliases: api, config, get, do, top… |
cv4pve-cli get |
The next word of the aliases: vms, nodes, vm, guest, cluster… |
cv4pve-cli api get / |
The paths at the top of the API: /access, /cluster, /nodes… |
cv4pve-cli api get /nodes/ |
The nodes of the cluster: /nodes/pve01, /nodes/pve02 |
cv4pve-cli api get /nodes/pve01/qemu/ |
The VM IDs on that node |
cv4pve-cli api get /cluster/resources |
The parameters of the call: --type |
cv4pve-cli api get /cluster/resources --type |
Their allowed values: node, sdn, storage, vm |
cv4pve-cli get vm status |
The nodes, then the VM IDs on the node you chose |
cv4pve-cli do start guest --guest |
The IDs and names of the guests |
cv4pve-cli config use |
The names of your contexts |
Paths complete one segment at a time: TAB after /nodes/pve01/ offers what is under that node.
Nothing to do: the first time cv4pve-cli runs, it writes a completion script in ~/.cv4pve/cli/ and
adds a line that loads it to your shell profile:
| System | Script | Line added to |
|---|---|---|
| Linux, macOS | completion.bash, completion.zsh |
~/.bashrc and ~/.zshrc: both, whichever shell you use; a missing file is created |
| Windows | completion.ps1 |
The profile of PowerShell 7 (pwsh), as $PROFILE reports it |
The line is added once, under a # cv4pve-cli completion comment. Open a new terminal, or reload the
profile (source ~/.bashrc, source ~/.zshrc or . $PROFILE) to start using it.
- The script calls
cv4pve-cliby that name, so the binary must be in yourPATHascv4pve-cli. - zsh: the script uses
compdef, so the zsh completion system must be loaded before it (autoload -Uz compinit && compinit, which frameworks such as Oh My Zsh already do). - Windows: completion works in PowerShell 7. Windows PowerShell 5.1 and
cmdare not set up.
cv4pve-cli completion reset writes the scripts again, and adds the profile line if it is missing, after
an upgrade, or if you removed them. To turn completion off, delete the two lines from the profile but
keep the completion.* files: when they are missing, cv4pve-cli writes them and the profile lines
again at its next run.
Where the names come from
Section titled “Where the names come from”- The structure of the API (paths, parameters and allowed values) comes from a copy of the API
schema that cv4pve-cli downloads from the cluster the first time you run an
apicommand or an alias, and saves in~/.cv4pve/cli/cache/, one file per Proxmox VE version. Until then, only commands and aliases complete. After a Proxmox VE upgrade, the nextapicommand or alias downloads the schema of the new version. - Node names, VM IDs and guest names are read from the cluster at each TAB, with the current context. A TAB therefore takes as long as a login and a call; if the cluster cannot be reached, TAB offers nothing for those parts.