{"id":20399260,"url":"https://github.com/corsinvest/cv4pve-cli","last_synced_at":"2026-03-13T11:02:41.137Z","repository":{"id":54748077,"uuid":"195868531","full_name":"Corsinvest/cv4pve-cli","owner":"Corsinvest","description":"Cli for Proxmox VE (Command Line Interfaces)","archived":false,"fork":false,"pushed_at":"2025-03-21T17:26:45.000Z","size":99,"stargazers_count":44,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T18:28:31.184Z","etag":null,"topics":["api-client","cli","cluster","command-line-interface","dotnet","kvm","lxc","migration","proxmox","proxmox-apis","proxmox-cluster","proxmox-exporter","proxmox-ve","proxmoxve","remote-admin-tool","vm","web-api"],"latest_commit_sha":null,"homepage":"https://www.cv4pve-tools.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Corsinvest.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-08T18:46:20.000Z","updated_at":"2025-03-21T17:22:02.000Z","dependencies_parsed_at":"2024-10-31T04:31:16.638Z","dependency_job_id":"8ec41491-7a88-485d-88e9-68ffadb6c9d1","html_url":"https://github.com/Corsinvest/cv4pve-cli","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Corsinvest%2Fcv4pve-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Corsinvest","download_url":"https://codeload.github.com/Corsinvest/cv4pve-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571972,"owners_count":21126555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","cli","cluster","command-line-interface","dotnet","kvm","lxc","migration","proxmox","proxmox-apis","proxmox-cluster","proxmox-exporter","proxmox-ve","proxmoxve","remote-admin-tool","vm","web-api"],"created_at":"2024-11-15T04:28:00.583Z","updated_at":"2026-03-13T11:02:41.103Z","avatar_url":"https://github.com/Corsinvest.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cv4pve-cli\n\n```\n   ______                _                      __\n  / ____/___  __________(_)___ _   _____  _____/ /_\n / /   / __ \\/ ___/ ___/ / __ \\ | / / _ \\/ ___/ __/\n/ /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_\n\\____/\\____/_/  /____/_/_/ /_/|___/\\___/____/\\__/\n\nCommand Line Interface for Proxmox VE (Made in Italy)\n```\n\n[![License](https://img.shields.io/github/license/Corsinvest/cv4pve-cli.svg?style=flat-square)](LICENSE.md)\n[![Release](https://img.shields.io/github/release/Corsinvest/cv4pve-cli.svg?style=flat-square)](https://github.com/Corsinvest/cv4pve-cli/releases/latest)\n[![Downloads](https://img.shields.io/github/downloads/Corsinvest/cv4pve-cli/total.svg?style=flat-square\u0026logo=download)](https://github.com/Corsinvest/cv4pve-cli/releases)\n\ncv4pve-cli is to Proxmox VE what `kubectl` is to Kubernetes — a remote-first CLI with context switching, direct API access, and aliases for common operations. Think of it as [`pvesh`](https://pve.proxmox.com/pve-docs/pvesh.1.html), but running from your workstation, supporting multiple clusters, and with tab completion that queries the live API.\n\n| | [pvesh](https://pve.proxmox.com/pve-docs/pvesh.1.html) | kubectl | cv4pve-cli |\n|---|---|---|---|\n| Direct API access | yes | yes | yes |\n| Runs remotely (off-node) | no | yes | yes |\n| Multiple clusters / contexts | no | yes | yes |\n| Tab completion (live) | yes (local only) | yes | yes |\n| Aliases / shortcuts | no | yes | yes |\n\n---\n\n## Quick Start\n\n```bash\n# 1. Add a context (connection profile)\ncv4pve-cli config add homelab --host 192.168.1.100 --username root@pam --password secret\n\n# 2. Use it\ncv4pve-cli config use homelab\n\n# 3. Run commands\ncv4pve-cli api get /nodes\ncv4pve-cli top\n```\n\n---\n\n## Installation\n\n### Linux\n\n```bash\nLATEST_URL=$(curl -s https://api.github.com/repos/Corsinvest/cv4pve-cli/releases/latest | grep browser_download_url | grep linux-x64 | cut -d '\"' -f 4)\nwget \"$LATEST_URL\" \u0026\u0026 unzip cv4pve-cli-linux-x64.zip\nchmod +x cv4pve-cli\nsudo mv cv4pve-cli /usr/local/bin/\n```\n\n### Windows\n\n```powershell\nwinget install Corsinvest.cv4pve.cli\n```\n\n### macOS\n\n```bash\nwget https://github.com/Corsinvest/cv4pve-cli/releases/latest/download/cv4pve-cli-osx-x64.zip\nunzip cv4pve-cli-osx-x64.zip \u0026\u0026 chmod +x cv4pve-cli\nsudo mv cv4pve-cli /usr/local/bin/\n```\n\n---\n\n## Configuration\n\nAll configuration is managed through the `config` subcommand. Contexts are connection profiles — each one stores a host, credentials, and port.\n\n### File locations\n\n| Platform | Base path |\n|----------|-----------|\n| Linux / macOS | `~/.cv4pve/cli/` |\n| Windows | `%USERPROFILE%\\.cv4pve\\cli\\` |\n\nAll files are in YAML format and can be edited directly with any text editor.\n\n| File | Content |\n|------|---------|\n| `config` | Contexts (connection profiles) |\n| `alias` | User-defined aliases |\n| `cache/\u003cversion\u003e.json` | API schema cache (auto-generated) |\n\n### Add a context\n\n```bash\n# Username/password\ncv4pve-cli config add homelab --host 192.168.1.100 --username root@pam --password secret\n\n# API token (recommended for production)\ncv4pve-cli config add prod --host pve.company.com --api-token root@pam!mytoken=uuid-here\n\n# Custom port, skip certificate validation\ncv4pve-cli config add dev --host 10.0.0.1 --port 8007 --username root@pam --password secret --validate-certificate false\n\n# Custom timeout (default: 30s)\ncv4pve-cli config add slow --host 10.0.0.1 --username root@pam --password secret --timeout 60\n```\n\n### Switch context\n\n```bash\ncv4pve-cli config use prod\ncv4pve-cli config current               # Show which context is active\n```\n\n### List and inspect contexts\n\n```bash\ncv4pve-cli config list                  # List all contexts (* = active)\ncv4pve-cli config view                  # Full config dump (passwords hidden)\n```\n\n### Update a context\n\nOnly the fields you specify are changed:\n\n```bash\ncv4pve-cli config set homelab --password newpass\ncv4pve-cli config set homelab --host 192.168.1.200 --port 8006\ncv4pve-cli config set homelab --timeout 60\n```\n\n### Rename and delete\n\n```bash\ncv4pve-cli config rename homelab lab\ncv4pve-cli config delete lab\n```\n\n### Verify connection\n\n```bash\ncv4pve-cli config verify                # Test the current context\ncv4pve-cli config verify homelab        # Test a specific context\n```\n\n---\n\n## API Commands\n\nAll Proxmox VE REST API calls go through the `api` subcommand.\n\n```\ncv4pve-cli api get    \u003cresource\u003e [--key value ...]\ncv4pve-cli api set    \u003cresource\u003e [--key value ...]\ncv4pve-cli api create \u003cresource\u003e [--key value ...]\ncv4pve-cli api delete \u003cresource\u003e\ncv4pve-cli api ls     \u003cresource\u003e\ncv4pve-cli api usage  \u003cresource\u003e [method] [--returns] [--output \u003cformat\u003e]\n```\n\nParameters use `--key value` format and can be repeated:\n\n```bash\ncv4pve-cli api get /cluster/resources --type vm\ncv4pve-cli api set /nodes/pve1/qemu/100/config --memory 4096 --cores 2\ncv4pve-cli api create /nodes/pve1/qemu/100/snapshot --snapname before-update\ncv4pve-cli api delete /nodes/pve1/qemu/100/snapshot/before-update\n```\n\n### Output formats\n\nUse `--output` (or `-o`) to control the output format:\n\n```bash\ncv4pve-cli api get /nodes --output text        # default, table\ncv4pve-cli api get /nodes --output json\ncv4pve-cli api get /nodes --output jsonpretty\ncv4pve-cli api get /nodes --output html\ncv4pve-cli api get /nodes --output markdown\n```\n\n### Browse and explore the API\n\n```bash\n# List children of a path\ncv4pve-cli api ls /\ncv4pve-cli api ls /nodes\ncv4pve-cli api ls /nodes/pve1/qemu\n\n# Show parameters and schema for a resource\ncv4pve-cli api usage /cluster/resources\ncv4pve-cli api usage /nodes/{node}/qemu/{vmid}/config get\ncv4pve-cli api usage /nodes/{node}/qemu/{vmid}/config get --returns --output json\n```\n\n---\n\n## Aliases\n\nAliases are shortcuts for frequently used API commands. A command can contain named placeholders in curly braces (e.g. `{node}`, `{vmid}`). When you run the alias, you supply values for each placeholder positionally — the first argument fills the first placeholder, the second fills the second, and so on.\n\n### Built-in aliases\n\nA set of read-only aliases is available out of the box, organized by verb and resource. They cannot be modified or removed. A few examples:\n\n| Alias | Arguments | Description |\n|-------|-----------|-------------|\n| `top` | — | Cluster resource overview |\n| `get vms` | — | List all VMs (cluster-wide) |\n| `show vm` | `\u003cnode\u003e \u003cvmid\u003e` | Show VM config |\n| `do start vm` | `\u003cnode\u003e \u003cvmid\u003e` | Start a VM |\n| `do snapshot vm` | `\u003cnode\u003e \u003cvmid\u003e \u003csnapname\u003e` | Create a VM snapshot |\n| `get cluster not-backed-up` | — | List guests with no backup job |\n\nSee all built-in and user aliases:\n\n```bash\ncv4pve-cli alias list\ncv4pve-cli alias list --verbose        # includes command and placeholder args\ncv4pve-cli alias list --search snap    # filter by keyword\n```\n\n### Run an alias\n\n```bash\n# No arguments\ncv4pve-cli top\ncv4pve-cli get vms\n\n# With arguments — placeholders filled positionally\n#   \"show vm\" command: \"get /nodes/{node}/qemu/{vmid}/config\"\n#                                          ↑          ↑\ncv4pve-cli show vm pve1 100            #  node=pve1  vmid=100\ncv4pve-cli do start vm pve1 100\ncv4pve-cli get vm snapshots pve1 100\n\n# Options: --output, --verbose, --wait (passed through to the underlying api call)\ncv4pve-cli get nodes --output json\ncv4pve-cli show vm pve1 100 --output jsonpretty\ncv4pve-cli do start vm pve1 100 --wait\n```\n\nIf you omit a required placeholder, the CLI prints an error with the expected usage:\n\n```\nError: missing arguments: {vmid}\nUsage: show vm \u003cnode\u003e \u003cvmid\u003e\n```\n\n### User aliases\n\nYou can create your own aliases using any API call as the command. Use `{name}` placeholders in the path wherever you want the caller to supply a value at runtime.\n\n```bash\n# Add an alias without placeholders\ncv4pve-cli alias add cluster-res \\\n    --command \"get /cluster/resources\" \\\n    --description \"All cluster resources\"\n\n# Add an alias with placeholders\ncv4pve-cli alias add vm-net \\\n    --command \"get /nodes/{node}/qemu/{vmid}/config\" \\\n    --description \"Show VM network config\"\n\n# Use them\ncv4pve-cli cluster-res\ncv4pve-cli vm-net pve1 100\n\n# Remove a user alias (built-in aliases cannot be removed)\ncv4pve-cli alias remove vm-net\n```\n\n\u003e Built-in aliases cannot be added, modified, or removed. Attempting to create an alias with the same name as a built-in will return an error.\n\n---\n\n## Tab Completion\n\nTab completion is registered automatically on first run. It works across all commands, API paths, parameters, contexts, and alias arguments. Open a new terminal session after the first run to activate it.\n\n### What completes\n\n| Typing | TAB suggests |\n|--------|-------------|\n| `cv4pve-cli \u003cTAB\u003e` | `api`, `config`, `alias`, `top`, `get`, `show`, `do`, ... |\n| `cv4pve-cli get \u003cTAB\u003e` | `vms`, `nodes`, `storages`, `cluster`, `vm`, `ct`, ... |\n| `cv4pve-cli do \u003cTAB\u003e` | `start`, `stop`, `shutdown`, `migrate`, `clone`, ... |\n| `cv4pve-cli config \u003cTAB\u003e` | `add`, `use`, `list`, `set`, `delete`, `rename`, `verify`, `view` |\n| `cv4pve-cli config use \u003cTAB\u003e` | context names (e.g. `homelab`, `prod`) |\n| `cv4pve-cli alias remove \u003cTAB\u003e` | user alias names only |\n| `cv4pve-cli api get /nodes/\u003cTAB\u003e` | node names live from API (e.g. `pve1`, `pve2`) |\n| `cv4pve-cli api get /nodes/pve1/qemu/\u003cTAB\u003e` | VM IDs live from API (e.g. `100`, `101`) |\n| `cv4pve-cli api get /nodes/pve1/qemu/100/config \u003cTAB\u003e` | parameter names (e.g. `--cores`, `--memory`) |\n| `cv4pve-cli show vm \u003cTAB\u003e` | node names live from API |\n| `cv4pve-cli show vm pve1 \u003cTAB\u003e` | VM IDs live from API |\n\nCompletion for API paths and alias arguments queries the live Proxmox VE API, so results reflect the actual state of your cluster.\n\n### Setup\n\nTab completion shims are written to `~/.cv4pve/cli/` (`completion.ps1` on Windows, `completion.bash` / `completion.zsh` on Linux/macOS) and sourced automatically into your shell profile on first run.\n\n**After the first run, open a new terminal session** to activate completion. Alternatively, reload your profile in the current session:\n\n**PowerShell**\n```powershell\n. $PROFILE\n```\n\n**Bash**\n```bash\nsource ~/.bashrc\n```\n\n**Zsh**\n```bash\nsource ~/.zshrc\n```\n\nTo force re-registration (e.g. after reinstalling or upgrading), run the following and then open a new terminal:\n\n```bash\ncv4pve-cli completion reset\n```\n\n---\n\n## API Metadata Cache\n\nThe Proxmox VE API schema is downloaded once from the connected host and cached locally under `~/.cv4pve/cli/cache/`. The cache is keyed by PVE version, so it is refreshed automatically when the host is upgraded.\n\n---\n\n## Links\n\n- [Proxmox VE API reference](https://pve.proxmox.com/pve-docs/api-viewer/index.html)\n- [Proxmox VE API token documentation](https://pve.proxmox.com/pve-docs/pveum-plain.html)\n\n---\n\n## Support\n\nProfessional support available through [Corsinvest](https://www.corsinvest.it/cv4pve).\n\nPart of [cv4pve](https://www.corsinvest.it/cv4pve) suite | Made with ❤️ in Italy by [Corsinvest](https://www.corsinvest.it)\n\nCopyright © Corsinvest Srl\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorsinvest%2Fcv4pve-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorsinvest%2Fcv4pve-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorsinvest%2Fcv4pve-cli/lists"}