@fredlackey/cli-proxmox 0.0.1

package/COMMANDS.md

@@ -0,0 +1,453 @@
+# CLI Commands
+
+## Global Flags
+
+`--json` and `--interactive` can be placed before any subcommand to control output format. `--json` forces JSON output (the default when stdout is not a TTY). `--interactive` forces human-friendly output.
+
+## Credential Flags
+
+The following flags are accepted by every API-calling subcommand. They are optional if credentials have already been saved via `proxmox configure`.
+
+| Flag | Description |
+|---|---|
+| `--base-url <url>` | Proxmox host root URL (e.g. https://pve.example.com:8006) |
+| `--token-id <id>` | Proxmox API token ID (e.g. root@pam!terraform-token) |
+| `--token-secret <secret>` | Proxmox API token secret (UUID) |
+| `--verify-ssl` | Verify the Proxmox TLS certificate (default: false for self-signed) |
+
+## Node Flag
+
+`--node <name>` is accepted by all node-scoped commands. It is optional if `defaultNode` is set in the saved config.
+
+---
+
+## Cluster
+
+Cluster-wide operations.
+
+### resources
+
+List all resources across the cluster (VMs, nodes, storage).
+
+```
+proxmox cluster resources [--type <type>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--type <type>` | optional | Filter by type: vm, storage, node, sdn |
+
+---
+
+## Configure
+
+Write Proxmox credentials to ~/.config/cli-proxmox/config.json. In interactive mode (TTY), missing values are prompted for. In non-interactive mode, flags are required for any value not already saved.
+
+```
+proxmox configure [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--default-node <name>] [--verify-ssl] [--no-verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--base-url <url>` | optional | Proxmox host root URL (e.g. https://pve.example.com:8006) |
+| `--token-id <id>` | optional | Proxmox API token ID (e.g. root@pam!terraform-token) |
+| `--token-secret <secret>` | optional | Proxmox API token secret (UUID) |
+| `--default-node <name>` | optional | Default PVE node name |
+| `--verify-ssl` | optional | Verify TLS cert (default: false for self-signed) |
+| `--no-verify-ssl` | optional | Do not verify TLS cert |
+
+---
+
+## Node
+
+Node operations.
+
+### list
+
+List all nodes in the Proxmox cluster.
+
+```
+proxmox node list [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+No command-specific flags.
+
+### status
+
+Get detailed status of a specific node.
+
+```
+proxmox node status [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+---
+
+## Snapshot
+
+VM snapshot operations.
+
+### list
+
+List snapshots for a VM.
+
+```
+proxmox snapshot list --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### create
+
+Create a snapshot of a VM.
+
+```
+proxmox snapshot create --vmid <id> --snapname <name> [--description <text>] [--vmstate] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--snapname <name>` | **required** | Snapshot name |
+| `--description <text>` | optional | Snapshot description |
+| `--vmstate` | optional | Include RAM state in the snapshot |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### remove
+
+Delete a snapshot from a VM.
+
+```
+proxmox snapshot remove --vmid <id> --snapname <name> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--snapname <name>` | **required** | Snapshot name to delete |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### rollback
+
+Rollback a VM to a previous snapshot.
+
+```
+proxmox snapshot rollback --vmid <id> --snapname <name> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--snapname <name>` | **required** | Snapshot name to rollback to |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+---
+
+## Storage
+
+Storage pool operations.
+
+### list
+
+List storage pools on a node.
+
+```
+proxmox storage list [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### content
+
+List contents of a storage pool (ISOs, disk images, backups, templates).
+
+```
+proxmox storage content --storage <name> [--content <type>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--storage <name>` | **required** | Storage pool name |
+| `--content <type>` | optional | Content type filter (iso, images, backup, vztmpl) |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+---
+
+## Task
+
+Task operations.
+
+### list
+
+List recent tasks on a node.
+
+```
+proxmox task list [--limit <n>] [--source <type>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--limit <n>` | optional | Max tasks to return (default: 50) |
+| `--source <type>` | optional | Filter by source (active, archive, all) |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### get
+
+Get status and log of a specific task by UPID.
+
+```
+proxmox task get --upid <upid> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--upid <upid>` | **required** | Task UPID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### wait
+
+Wait for a task to complete by polling its UPID.
+
+```
+proxmox task wait --upid <upid> [--timeout <seconds>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--upid <upid>` | **required** | Task UPID to wait for |
+| `--timeout <seconds>` | optional | Timeout in seconds (default: 300) |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+---
+
+## VM
+
+Virtual machine operations (QEMU).
+
+### list
+
+List all QEMU VMs on a node.
+
+```
+proxmox vm list [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### get
+
+Get the full configuration of a VM.
+
+```
+proxmox vm get --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### start
+
+Start a VM.
+
+```
+proxmox vm start --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### stop
+
+Force-stop a VM (power off, no graceful ACPI).
+
+```
+proxmox vm stop --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### shutdown
+
+Gracefully shut down a VM via ACPI (needs guest agent).
+
+```
+proxmox vm shutdown --vmid <id> [--timeout <seconds>] [--force] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--timeout <seconds>` | optional | Seconds to wait before giving up |
+| `--force` | optional | Force-stop if graceful shutdown times out |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### reboot
+
+Reboot a VM.
+
+```
+proxmox vm reboot --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### create
+
+Create a new QEMU VM.
+
+```
+proxmox vm create --vmid <id> [--name <name>] [--memory <mb>] [--cores <n>] [--sockets <n>] [--ostype <type>] [--scsi0 <spec>] [--ide2 <spec>] [--net0 <spec>] [--boot <order>] [--agent <0|1>] [--cpu <type>] [--scsihw <type>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID (unique integer) |
+| `--name <name>` | optional | VM name |
+| `--memory <mb>` | optional | Memory in MB (default: 2048) |
+| `--cores <n>` | optional | CPU cores (default: 1) |
+| `--sockets <n>` | optional | CPU sockets (default: 1) |
+| `--ostype <type>` | optional | OS type (default: l26 for Linux) |
+| `--scsi0 <spec>` | optional | SCSI disk (e.g., local-lvm:32) |
+| `--ide2 <spec>` | optional | CD-ROM/ISO (e.g., local:iso/ubuntu.iso,media=cdrom) |
+| `--net0 <spec>` | optional | Network (e.g., virtio,bridge=vmbr0) |
+| `--boot <order>` | optional | Boot order (e.g., order=scsi0;ide2;net0) |
+| `--agent <0\|1>` | optional | QEMU guest agent (0 or 1) |
+| `--cpu <type>` | optional | CPU type (e.g., host, kvm64) |
+| `--scsihw <type>` | optional | SCSI controller (default: virtio-scsi-single) |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### clone
+
+Clone a VM or template to a new VM.
+
+```
+proxmox vm clone --vmid <id> --newid <id> [--name <name>] [--full] [--target <node>] [--storage <name>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | Source VM ID to clone from |
+| `--newid <id>` | **required** | New VM ID for the clone |
+| `--name <name>` | optional | Name for the cloned VM |
+| `--full` | optional | Full clone (not linked) |
+| `--target <node>` | optional | Target node (for cross-node clone) |
+| `--storage <name>` | optional | Target storage for full clone |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### delete
+
+Delete a VM.
+
+```
+proxmox vm delete --vmid <id> [--purge] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID to delete |
+| `--purge` | optional | Remove from backup/replication jobs too |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### config
+
+Update VM hardware configuration (CPU, memory, network, etc.).
+
+```
+proxmox vm config --vmid <id> [--memory <mb>] [--cores <n>] [--sockets <n>] [--cpu <type>] [--name <name>] [--ostype <type>] [--net0 <spec>] [--net1 <spec>] [--scsi0 <spec>] [--scsi1 <spec>] [--ide2 <spec>] [--boot <order>] [--agent <0|1>] [--onboot <0|1>] [--balloon <mb>] [--scsihw <type>] [--delete <keys>] [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--memory <mb>` | optional | Memory in MB |
+| `--cores <n>` | optional | CPU cores |
+| `--sockets <n>` | optional | CPU sockets |
+| `--cpu <type>` | optional | CPU type (e.g., host, kvm64) |
+| `--name <name>` | optional | VM name |
+| `--ostype <type>` | optional | OS type |
+| `--net0 <spec>` | optional | Network interface 0 |
+| `--net1 <spec>` | optional | Network interface 1 |
+| `--scsi0 <spec>` | optional | SCSI disk 0 |
+| `--scsi1 <spec>` | optional | SCSI disk 1 |
+| `--ide2 <spec>` | optional | IDE device 2 (CD-ROM) |
+| `--boot <order>` | optional | Boot order |
+| `--agent <0\|1>` | optional | QEMU guest agent (0 or 1) |
+| `--onboot <0\|1>` | optional | Start on boot (0 or 1) |
+| `--balloon <mb>` | optional | Balloon memory minimum in MB |
+| `--scsihw <type>` | optional | SCSI controller type |
+| `--delete <keys>` | optional | Comma-separated list of settings to delete |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### resize
+
+Resize a VM disk (grow only, works while VM is running).
+
+```
+proxmox vm resize --vmid <id> --disk <name> --size <size> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--disk <name>` | **required** | Disk name (e.g., scsi0, virtio0) |
+| `--size <size>` | **required** | New size or delta (e.g., +10G, 50G) |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### status
+
+Get current runtime status of a VM.
+
+```
+proxmox vm status --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### suspend
+
+Suspend (pause) a VM to memory.
+
+```
+proxmox vm suspend --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |
+
+### resume
+
+Resume a suspended VM.
+
+```
+proxmox vm resume --vmid <id> [--node <name>] [--base-url <url>] [--token-id <id>] [--token-secret <secret>] [--verify-ssl]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--vmid <id>` | **required** | VM ID |
+| `--node <name>` | optional | Proxmox node name (falls back to configured defaultNode) |

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Fred Lackey
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,64 @@
+# @fredlackey/cli-proxmox
+
+Command-line interface for [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview) node, VM, storage, and snapshot management. JSON output by default so AI agents and scripts can consume it directly, with a human-friendly mode when you're working interactively.
+
+## Install
+
+```
+npm install -g @fredlackey/cli-proxmox
+```
+
+## Configure
+
+```
+proxmox configure \
+  --base-url https://pve.example.com:8006 \
+  --token-id 'root@pam!terraform-token' \
+  --token-secret <secret> \
+  --default-node pm-b
+```
+
+Running `proxmox configure` without flags prompts for each value interactively. Credentials are stored in `~/.config/cli-proxmox/config.json` and that file is the only config source. There are no environment variables to set.
+
+TLS certificate verification is disabled by default since Proxmox typically uses self-signed certs. Pass `--verify-ssl` to `configure` if you have a properly signed certificate.
+
+## Usage
+
+```
+proxmox vm list
+proxmox vm clone \
+  --vmid 9000 \
+  --newid 200 \
+  --name web-prod \
+  --full
+proxmox snapshot create \
+  --vmid 200 \
+  --snapname before-upgrade \
+  --vmstate
+proxmox storage content --storage local --content iso
+proxmox task wait --upid <upid> --timeout 120
+```
+
+## Full Command Reference
+
+For the complete list of commands and flags, see [COMMANDS.md](COMMANDS.md).
+
+## Output
+
+All commands write JSON to stdout by default. When run in an interactive terminal, output switches to a human-friendly format with colors. Use the global `--json` and `--interactive` flags to override the auto-detection.
+
+## Contributing
+
+If you find a gap or have a feature request, open an issue or submit a pull request on [GitHub](https://github.com/FredLackeySandbox/cli-proxmox).
+
+## Questions?
+
+If you have questions, comments, or just want to talk shop, feel free to reach out.
+
+Fred Lackey  
+[fred.lackey@gmail.com](mailto:fred.lackey@gmail.com)  
+[https://fredlackey.com](https://fredlackey.com)  
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fredlackey/cli-proxmox",
+  "version": "0.0.1",
+  "description": "AI-first CLI for managing Proxmox VE nodes, VMs, storage, and snapshots",
+  "author": {
+    "name": "Fred Lackey",
+    "email": "fred.lackey@gmail.com",
+    "url": "https://fredlackey.com"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/FredLackeySandbox/cli-proxmox.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FredLackeySandbox/cli-proxmox/issues"
+  },
+  "homepage": "https://github.com/FredLackeySandbox/cli-proxmox#readme",
+  "keywords": [
+    "proxmox",
+    "proxmox-ve",
+    "virtual-machines",
+    "infrastructure",
+    "cli",
+    "ai-first",
+    "json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "proxmox": "./src/bin/proxmox.js"
+  },
+  "scripts": {
+    "start": "node src/bin/proxmox.js"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  }
+}

package/src/bin/proxmox.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { cli } from '../index.js';
+
+cli(process.argv);

package/src/commands/cluster.js

@@ -0,0 +1,54 @@
+/**
+ * `proxmox cluster` subcommands: resources.
+ *
+ * Cluster-level operations that span all nodes. These commands accept
+ * the standard credential flags but do not require --node.
+ */
+
+import { Command } from 'commander';
+import { getRuntime } from '../utils/runtime.js';
+import { createOutput } from '../utils/output.js';
+import { resolveCredentials } from '../utils/config.js';
+import { createProxmoxClient, withCredentialOptions } from '../utils/proxmox-client.js';
+
+export function clusterCommand() {
+  const cmd = new Command('cluster');
+  cmd.description('Cluster-wide operations');
+
+  // ── resources ────────────────────────────────────────────────────
+  withCredentialOptions(
+    cmd.command('resources')
+      .description('List all resources across the cluster (VMs, nodes, storage)')
+      .option('--type <type>', 'Filter by type: vm, storage, node, sdn')
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const client = createProxmoxClient(creds);
+
+    const params = opts.type ? { type: opts.type } : undefined;
+    const data = await client.get('cluster/resources', params);
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Cluster resources');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no resources)');
+      } else {
+        for (const r of list) {
+          const type = (r.type || '').padEnd(10);
+          const id = (r.id || '').padEnd(20);
+          const status = (r.status || '').padEnd(8);
+          const node = r.node || '-';
+          out.info(`${type} ${id} ${status} node=${node}`);
+        }
+        out.dim(`${list.length} resource(s)`);
+      }
+    }
+    out.set('resources', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  return cmd;
+}