@fredlackey/cli-proxmox 0.0.1

package/src/commands/vm.js

@@ -0,0 +1,521 @@
+/**
+ * `proxmox vm` subcommands: list, get, start, stop, shutdown, reboot,
+ * create, clone, delete, config, resize, status, suspend, resume.
+ *
+ * Every subcommand accepts the standard credential flags and --node, which
+ * falls back to the configured defaultNode. `list` targets a single node.
+ */
+
+import { Command } from 'commander';
+import { getRuntime } from '../utils/runtime.js';
+import { createOutput } from '../utils/output.js';
+import { resolveCredentials, resolveNode } from '../utils/config.js';
+import {
+  createProxmoxClient,
+  withCredentialOptions,
+  withNodeOption,
+} from '../utils/proxmox-client.js';
+
+export function vmCommand() {
+  const cmd = new Command('vm');
+  cmd.description('Virtual machine operations (QEMU)');
+
+  // ── list ──────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('list').description('List all QEMU VMs on a node')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const data = await client.get(`nodes/${node}/qemu`);
+    const list = Array.isArray(data) ? data : [];
+    list.sort((a, b) => (a.vmid ?? 0) - (b.vmid ?? 0));
+
+    out.heading('Virtual machines');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no VMs)');
+      } else {
+        for (const v of list) {
+          const vmid = String(v.vmid ?? '-').padEnd(6);
+          const status = (v.status || '').padEnd(8);
+          const name = v.name || '';
+          out.info(`${vmid} ${status} ${name}`);
+        }
+        out.dim(`${list.length} total on ${node}`);
+      }
+    }
+    out.set('node', node);
+    out.set('vms', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  // ── get ───────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('get')
+        .description('Get the full configuration of a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const data = await client.get(`nodes/${node}/qemu/${opts.vmid}/config`);
+
+    out.heading('VM config');
+    if (runtime.interactive) {
+      out.info(`Node:   ${node}`);
+      out.info(`VMID:   ${opts.vmid}`);
+      if (data && typeof data === 'object') {
+        for (const [k, v] of Object.entries(data)) {
+          const display = typeof v === 'object' ? JSON.stringify(v) : v;
+          out.info(`${k.padEnd(12)} ${display}`);
+        }
+      }
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('config', data);
+    out.flush();
+  });
+
+  // ── start ─────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('start')
+        .description('Start a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/status/start`);
+
+    out.heading('VM start');
+    if (runtime.interactive) {
+      out.success(`Start requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('action', 'start');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── stop ──────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('stop')
+        .description('Force-stop a VM (power off, no graceful ACPI)')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/status/stop`);
+
+    out.heading('VM stop');
+    if (runtime.interactive) {
+      out.success(`Stop (force) requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('action', 'stop');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── shutdown ──────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('shutdown')
+        .description('Gracefully shut down a VM via ACPI (needs guest agent)')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .option('--timeout <seconds>', 'Seconds to wait before giving up')
+        .option('--force', 'Force-stop if graceful shutdown times out')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const body = {};
+    if (opts.timeout) body.timeout = parseInt(opts.timeout, 10);
+    if (opts.force) body.forceStop = 1;
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/status/shutdown`, body);
+
+    out.heading('VM shutdown');
+    if (runtime.interactive) {
+      out.success(`Shutdown requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('action', 'shutdown');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── reboot ────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('reboot')
+        .description('Reboot a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/status/reboot`);
+
+    out.heading('VM reboot');
+    if (runtime.interactive) {
+      out.success(`Reboot requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('action', 'reboot');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── create ────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('create')
+        .description('Create a new QEMU VM')
+        .requiredOption('--vmid <id>', 'VM ID (unique integer)')
+        .option('--name <name>', 'VM name')
+        .option('--memory <mb>', 'Memory in MB (default: 2048)')
+        .option('--cores <n>', 'CPU cores (default: 1)')
+        .option('--sockets <n>', 'CPU sockets (default: 1)')
+        .option('--ostype <type>', 'OS type (default: l26 for Linux)')
+        .option('--scsi0 <spec>', 'SCSI disk (e.g., local-lvm:32)')
+        .option('--ide2 <spec>', 'CD-ROM/ISO (e.g., local:iso/ubuntu.iso,media=cdrom)')
+        .option('--net0 <spec>', 'Network (e.g., virtio,bridge=vmbr0)')
+        .option('--boot <order>', 'Boot order (e.g., order=scsi0;ide2;net0)')
+        .option('--agent <0|1>', 'QEMU guest agent (0 or 1)')
+        .option('--cpu <type>', 'CPU type (e.g., host, kvm64)')
+        .option('--scsihw <type>', 'SCSI controller (default: virtio-scsi-single)')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const body = { vmid: parseInt(opts.vmid, 10) };
+    if (opts.name)    body.name    = opts.name;
+    if (opts.memory)  body.memory  = parseInt(opts.memory, 10);
+    if (opts.cores)   body.cores   = parseInt(opts.cores, 10);
+    if (opts.sockets) body.sockets = parseInt(opts.sockets, 10);
+    if (opts.ostype)  body.ostype  = opts.ostype;
+    if (opts.scsi0)   body.scsi0   = opts.scsi0;
+    if (opts.ide2)    body.ide2    = opts.ide2;
+    if (opts.net0)    body.net0    = opts.net0;
+    if (opts.boot)    body.boot    = opts.boot;
+    if (opts.agent)   body.agent   = opts.agent;
+    if (opts.cpu)     body.cpu     = opts.cpu;
+    if (opts.scsihw)  body.scsihw  = opts.scsihw;
+
+    const upid = await client.post(`nodes/${node}/qemu`, body);
+
+    out.heading('VM create');
+    if (runtime.interactive) {
+      out.success(`Create requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', parseInt(opts.vmid, 10));
+    out.set('action', 'create');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── clone ────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('clone')
+        .description('Clone a VM or template to a new VM')
+        .requiredOption('--vmid <id>', 'Source VM ID to clone from')
+        .requiredOption('--newid <id>', 'New VM ID for the clone')
+        .option('--name <name>', 'Name for the cloned VM')
+        .option('--full', 'Full clone (not linked)')
+        .option('--target <node>', 'Target node (for cross-node clone)')
+        .option('--storage <name>', 'Target storage for full clone')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const body = { newid: parseInt(opts.newid, 10) };
+    if (opts.name)    body.name    = opts.name;
+    if (opts.full)    body.full    = 1;
+    if (opts.target)  body.target  = opts.target;
+    if (opts.storage) body.storage = opts.storage;
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/clone`, body);
+
+    out.heading('VM clone');
+    if (runtime.interactive) {
+      out.success(`Clone of VM ${opts.vmid} to ${opts.newid} requested on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('sourceVmid', parseInt(opts.vmid, 10));
+    out.set('newid', parseInt(opts.newid, 10));
+    out.set('action', 'clone');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── delete ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('delete')
+        .description('Delete a VM')
+        .requiredOption('--vmid <id>', 'VM ID to delete')
+        .option('--purge', 'Remove from backup/replication jobs too')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const params = opts.purge ? { purge: 1 } : undefined;
+    const upid = await client.delete(
+      `nodes/${node}/qemu/${opts.vmid}${params ? '?purge=1' : ''}`
+    );
+
+    out.heading('VM delete');
+    if (runtime.interactive) {
+      out.success(`Delete requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', parseInt(opts.vmid, 10));
+    out.set('action', 'delete');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── config (update) ──────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('config')
+        .description('Update VM hardware configuration (CPU, memory, network, etc.)')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .option('--memory <mb>', 'Memory in MB')
+        .option('--cores <n>', 'CPU cores')
+        .option('--sockets <n>', 'CPU sockets')
+        .option('--cpu <type>', 'CPU type (e.g., host, kvm64)')
+        .option('--name <name>', 'VM name')
+        .option('--ostype <type>', 'OS type')
+        .option('--net0 <spec>', 'Network interface 0')
+        .option('--net1 <spec>', 'Network interface 1')
+        .option('--scsi0 <spec>', 'SCSI disk 0')
+        .option('--scsi1 <spec>', 'SCSI disk 1')
+        .option('--ide2 <spec>', 'IDE device 2 (CD-ROM)')
+        .option('--boot <order>', 'Boot order')
+        .option('--agent <0|1>', 'QEMU guest agent (0 or 1)')
+        .option('--onboot <0|1>', 'Start on boot (0 or 1)')
+        .option('--balloon <mb>', 'Balloon memory minimum in MB')
+        .option('--scsihw <type>', 'SCSI controller type')
+        .option('--delete <keys>', 'Comma-separated list of settings to delete')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const body = {};
+    const skip = new Set([
+      'baseUrl', 'tokenId', 'tokenSecret', 'verifySsl',
+      'node', 'vmid', 'json', 'interactive',
+    ]);
+    for (const [key, val] of Object.entries(opts)) {
+      if (skip.has(key)) continue;
+      if (val === undefined || val === true && key !== 'delete') continue;
+      if (['memory', 'cores', 'sockets', 'balloon'].includes(key)) {
+        body[key] = parseInt(val, 10);
+      } else {
+        body[key] = val;
+      }
+    }
+
+    if (Object.keys(body).length === 0) {
+      const err = new Error(
+        'No configuration changes specified. Use flags like --memory, --cores, --name, etc.'
+      );
+      err.code = 'missing_required_value';
+      throw err;
+    }
+
+    await client.put(`nodes/${node}/qemu/${opts.vmid}/config`, body);
+
+    out.heading('VM config');
+    if (runtime.interactive) {
+      out.success(`Config updated for VM ${opts.vmid} on ${node}`);
+      out.info(`Updated: ${Object.keys(body).join(', ')}`);
+    }
+    out.set('node', node);
+    out.set('vmid', parseInt(opts.vmid, 10));
+    out.set('updated', Object.keys(body));
+    out.flush();
+  });
+
+  // ── resize ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('resize')
+        .description('Resize a VM disk (grow only, works while VM is running)')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .requiredOption('--disk <name>', 'Disk name (e.g., scsi0, virtio0)')
+        .requiredOption('--size <size>', 'New size or delta (e.g., +10G, 50G)')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const body = { disk: opts.disk, size: opts.size };
+    await client.put(`nodes/${node}/qemu/${opts.vmid}/resize`, body);
+
+    out.heading('VM resize');
+    if (runtime.interactive) {
+      out.success(`Resized disk ${opts.disk} on VM ${opts.vmid} (${opts.size})`);
+    }
+    out.set('node', node);
+    out.set('vmid', parseInt(opts.vmid, 10));
+    out.set('disk', opts.disk);
+    out.set('size', opts.size);
+    out.flush();
+  });
+
+  // ── status ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('status')
+        .description('Get current runtime status of a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const data = await client.get(`nodes/${node}/qemu/${opts.vmid}/status/current`);
+
+    out.heading('VM status');
+    if (runtime.interactive) {
+      out.info(`Node: ${node}`);
+      out.info(`VMID: ${opts.vmid}`);
+      if (data && typeof data === 'object') {
+        for (const [k, v] of Object.entries(data)) {
+          const display = typeof v === 'object' ? JSON.stringify(v) : v;
+          out.info(`${k.padEnd(12)} ${display}`);
+        }
+      }
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('status', data);
+    out.flush();
+  });
+
+  // ── suspend ──────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('suspend')
+        .description('Suspend (pause) a VM to memory')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/status/suspend`);
+
+    out.heading('VM suspend');
+    if (runtime.interactive) {
+      out.success(`Suspend requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('action', 'suspend');
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── resume ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('resume')
+        .description('Resume a suspended VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    await client.post(`nodes/${node}/qemu/${opts.vmid}/status/resume`);
+
+    out.heading('VM resume');
+    if (runtime.interactive) {
+      out.success(`Resume requested for VM ${opts.vmid} on ${node}`);
+    }
+    out.set('node', node);
+    out.set('vmid', parseInt(opts.vmid, 10));
+    out.set('action', 'resume');
+    out.flush();
+  });
+
+  return cmd;
+}

package/src/index.js

@@ -0,0 +1,89 @@
+/**
+ * Program entry point. Builds the commander tree, installs the --json /
+ * --interactive global flag hook, and catches any thrown error from an
+ * async action and routes it through the structured fatalError emitter.
+ */
+
+import { Command } from 'commander';
+import { setForceJson, setForceInteractive } from './utils/runtime.js';
+import { fatalError } from './utils/errors.js';
+import { configureCommand } from './commands/configure.js';
+import { nodeCommand } from './commands/node.js';
+import { vmCommand } from './commands/vm.js';
+import { snapshotCommand } from './commands/snapshot.js';
+import { storageCommand } from './commands/storage.js';
+import { taskCommand } from './commands/task.js';
+import { clusterCommand } from './commands/cluster.js';
+
+export async function cli(argv) {
+  // Peek at argv before commander parses so that even pre-parse errors
+  // respect the caller's preferred output mode.
+  if (argv.includes('--json')) setForceJson(true);
+  if (argv.includes('--interactive')) setForceInteractive(true);
+
+  const program = new Command();
+
+  program
+    .name('proxmox')
+    .description('AI-first CLI for managing Proxmox VE nodes, VMs, storage, and snapshots')
+    .version('0.0.1')
+    .option('--json', 'force JSON output (default when stdout is not a TTY)')
+    .option('--interactive', 'force interactive/human-friendly output')
+    .hook('preAction', (thisCommand, actionCommand) => {
+      const opts = actionCommand.optsWithGlobals();
+      if (opts.json) setForceJson(true);
+      if (opts.interactive) setForceInteractive(true);
+    });
+
+  program.addCommand(configureCommand());
+  program.addCommand(nodeCommand());
+  program.addCommand(vmCommand());
+  program.addCommand(snapshotCommand());
+  program.addCommand(storageCommand());
+  program.addCommand(taskCommand());
+  program.addCommand(clusterCommand());
+
+  applyHelpOnError(program);
+
+  try {
+    await program.parseAsync(argv);
+  } catch (err) {
+    fatalError(err);
+  }
+}
+
+/**
+ * Recursively install an exitOverride that prints help on commander parse
+ * errors (missing arg, unknown option, etc.) instead of a one-line message.
+ */
+function applyHelpOnError(cmd) {
+  const HELP_CODES = new Set([
+    'commander.missingArgument',
+    'commander.missingMandatoryOptionValue',
+    'commander.invalidArgument',
+    'commander.invalidOptionArgument',
+    'commander.unknownOption',
+    'commander.unknownCommand',
+    'commander.excessArguments',
+  ]);
+
+  cmd.exitOverride((err) => {
+    if (err.code === 'commander.help' ||
+        err.code === 'commander.version' ||
+        err.code === 'commander.helpDisplayed') {
+      process.exit(err.exitCode ?? 0);
+    }
+
+    if (HELP_CODES.has(err.code)) {
+      process.stderr.write('\n');
+      cmd.outputHelp({ error: true });
+      process.exit(err.exitCode ?? 1);
+    }
+
+    throw err;
+  });
+
+  for (const sub of cmd.commands ?? []) {
+    applyHelpOnError(sub);
+  }
+}