@fredlackey/cli-proxmox 0.0.1

package/src/commands/configure.js

@@ -0,0 +1,105 @@
+/**
+ * `proxmox configure`
+ *
+ * Writes Proxmox credentials to ~/.config/cli-proxmox/config.json. Supports
+ * two modes:
+ *
+ *   - Non-interactive: pass --base-url, --token-id, --token-secret (and
+ *     optionally --default-node / --verify-ssl) as flags. Any value not
+ *     provided falls back to the existing saved config, so partial rotations
+ *     work (e.g. only --token-secret to rotate).
+ *
+ *   - Interactive: if stdin/stdout are a TTY, any value still missing
+ *     after flag + existing-config fallback is prompted for.
+ *
+ * In neither mode do we read environment variables.
+ */
+
+import { Command } from 'commander';
+import { getRuntime } from '../utils/runtime.js';
+import { createOutput } from '../utils/output.js';
+import { loadConfig, saveConfig, getConfigPath } from '../utils/config.js';
+import { ask, confirm, closeRl } from '../utils/readline.js';
+
+export function configureCommand() {
+  const cmd = new Command('configure');
+  cmd
+    .description('Write Proxmox credentials to ~/.config/cli-proxmox/config.json')
+    .option('--base-url <url>', 'Proxmox host root URL (e.g. https://pve.example.com:8006)')
+    .option('--token-id <id>', 'Proxmox API token ID (e.g. root@pam!terraform-token)')
+    .option('--token-secret <secret>', 'Proxmox API token secret (UUID)')
+    .option('--default-node <name>', 'Default PVE node name (optional)')
+    .option('--verify-ssl', 'Verify TLS cert (default: false for self-signed)')
+    .option('--no-verify-ssl', 'Do not verify TLS cert')
+    .action(async (opts) => {
+      const runtime = getRuntime();
+      const out = createOutput(runtime);
+
+      const existing = loadConfig() || {};
+
+      let baseUrl = opts.baseUrl ?? existing.baseUrl;
+      let tokenId = opts.tokenId ?? existing.tokenId;
+      let tokenSecret = opts.tokenSecret ?? existing.tokenSecret;
+      let defaultNode = opts.defaultNode ?? existing.defaultNode;
+      // commander sets opts.verifySsl to true/false if --verify-ssl or
+      // --no-verify-ssl was passed, and undefined if neither.
+      let verifySsl = opts.verifySsl;
+      if (verifySsl === undefined) verifySsl = existing.verifySsl;
+
+      // In interactive mode, prompt for anything still missing.
+      if (runtime.interactive) {
+        if (!baseUrl) {
+          baseUrl = await ask('Proxmox base URL', 'https://pve.example.com:8006');
+        }
+        if (!tokenId) {
+          tokenId = await ask('Token ID (e.g. root@pam!mytoken)');
+        }
+        if (!tokenSecret) {
+          process.stderr.write(
+            '(heads up: token secret input will be visible in the terminal — if that is a concern, Ctrl-C and pass --token-secret)\n'
+          );
+          tokenSecret = await ask('Token secret (UUID)');
+        }
+        if (defaultNode === undefined || defaultNode === null || defaultNode === '') {
+          defaultNode = await ask('Default node name (optional, blank to skip)', '');
+        }
+        if (verifySsl === undefined) {
+          verifySsl = await confirm('Verify TLS certificate?', false);
+        }
+        closeRl();
+      }
+
+      const missing = [];
+      if (!baseUrl) missing.push('--base-url');
+      if (!tokenId) missing.push('--token-id');
+      if (!tokenSecret) missing.push('--token-secret');
+
+      if (missing.length) {
+        const err = new Error(`Missing required values: ${missing.join(', ')}`);
+        err.code = 'missing_required_value';
+        err.detail = { missing };
+        throw err;
+      }
+
+      const config = {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        tokenId,
+        tokenSecret,
+        verifySsl: Boolean(verifySsl),
+      };
+      if (defaultNode) config.defaultNode = defaultNode;
+      saveConfig(config);
+
+      out.heading('Configured');
+      out.success('Config written', { path: getConfigPath() });
+      out.set('path', getConfigPath());
+      out.set('baseUrl', config.baseUrl);
+      out.set('tokenId', config.tokenId);
+      if (config.defaultNode) out.set('defaultNode', config.defaultNode);
+      out.set('verifySsl', config.verifySsl);
+      // Deliberately omit tokenSecret from the result payload.
+      out.flush();
+    });
+
+  return cmd;
+}

package/src/commands/node.js

@@ -0,0 +1,81 @@
+/**
+ * `proxmox node` subcommands: list, status.
+ *
+ * Each subcommand accepts the standard credential flags and falls back to
+ * ~/.config/cli-proxmox/config.json for any that are omitted.
+ */
+
+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 nodeCommand() {
+  const cmd = new Command('node');
+  cmd.description('Node operations');
+
+  // ── list ──────────────────────────────────────────────────────────
+  withCredentialOptions(
+    cmd.command('list').description('List all nodes in the Proxmox cluster')
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const client = createProxmoxClient(resolveCredentials(opts));
+
+    const data = await client.get('nodes');
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Nodes');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no nodes)');
+      } else {
+        for (const n of list) {
+          const name = (n.node || '').padEnd(16);
+          const status = (n.status || '').padEnd(8);
+          out.info(`${name} ${status} cpu=${n.cpu ?? '-'} mem=${n.mem ?? '-'}/${n.maxmem ?? '-'}`);
+        }
+        out.dim(`${list.length} total`);
+      }
+    }
+    out.set('nodes', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  // ── status ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('status').description('Get detailed status of a specific 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}/status`);
+
+    out.heading('Node status');
+    if (runtime.interactive) {
+      out.info(`Node: ${node}`);
+      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(16)} ${display}`);
+        }
+      }
+    }
+    out.set('node', node);
+    out.set('status', data);
+    out.flush();
+  });
+
+  return cmd;
+}

package/src/commands/snapshot.js

@@ -0,0 +1,157 @@
+/**
+ * `proxmox snapshot` subcommands: list, create, remove, rollback.
+ *
+ * Each subcommand accepts the standard credential flags, --node (with
+ * fallback to configured defaultNode), and --vmid.
+ */
+
+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 snapshotCommand() {
+  const cmd = new Command('snapshot');
+  cmd.description('VM snapshot operations');
+
+  // ── list ──────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('list')
+        .description('List snapshots for 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}/snapshot`);
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Snapshots');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no snapshots)');
+      } else {
+        for (const s of list) {
+          const name = (s.name || '').padEnd(20);
+          const parent = s.parent ? `parent=${s.parent}` : '';
+          out.info(`${name} ${parent}`);
+        }
+        out.dim(`${list.length} total for VM ${opts.vmid}`);
+      }
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('snapshots', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  // ── create ────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('create')
+        .description('Create a snapshot of a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .requiredOption('--snapname <name>', 'Snapshot name')
+        .option('--description <text>', 'Snapshot description')
+        .option('--vmstate', 'Include RAM state in the snapshot')
+    )
+  ).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 = { snapname: opts.snapname };
+    if (opts.description) body.description = opts.description;
+    if (opts.vmstate) body.vmstate = 1;
+
+    const upid = await client.post(`nodes/${node}/qemu/${opts.vmid}/snapshot`, body);
+
+    out.heading('Snapshot create');
+    if (runtime.interactive) {
+      out.success(`Snapshot '${opts.snapname}' requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('snapname', opts.snapname);
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── remove ────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('remove')
+        .description('Delete a snapshot from a VM')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .requiredOption('--snapname <name>', 'Snapshot name 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 upid = await client.delete(
+      `nodes/${node}/qemu/${opts.vmid}/snapshot/${encodeURIComponent(opts.snapname)}`
+    );
+
+    out.heading('Snapshot remove');
+    if (runtime.interactive) {
+      out.success(`Delete requested for snapshot '${opts.snapname}' on VM ${opts.vmid}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('snapname', opts.snapname);
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  // ── rollback ──────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('rollback')
+        .description('Rollback a VM to a previous snapshot')
+        .requiredOption('--vmid <id>', 'VM ID')
+        .requiredOption('--snapname <name>', 'Snapshot name to rollback to')
+    )
+  ).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}/snapshot/${encodeURIComponent(opts.snapname)}/rollback`
+    );
+
+    out.heading('Snapshot rollback');
+    if (runtime.interactive) {
+      out.success(`Rollback to '${opts.snapname}' requested for VM ${opts.vmid} on ${node}`);
+      if (upid) out.info(`UPID: ${upid}`);
+    }
+    out.set('node', node);
+    out.set('vmid', opts.vmid);
+    out.set('snapname', opts.snapname);
+    out.set('upid', upid);
+    out.flush();
+  });
+
+  return cmd;
+}

package/src/commands/storage.js

@@ -0,0 +1,95 @@
+/**
+ * `proxmox storage` subcommands: list, content.
+ *
+ * Lists storage pools on a node with usage stats, and browse pool contents.
+ */
+
+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 storageCommand() {
+  const cmd = new Command('storage');
+  cmd.description('Storage pool operations');
+
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('list').description('List storage pools 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}/storage`);
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Storage');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no storage)');
+      } else {
+        for (const s of list) {
+          const name = (s.storage || '').padEnd(16);
+          const type = (s.type || '').padEnd(8);
+          out.info(`${name} ${type} used=${s.used ?? '-'}/${s.total ?? '-'}`);
+        }
+        out.dim(`${list.length} total on ${node}`);
+      }
+    }
+    out.set('node', node);
+    out.set('storage', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  // ── content ───────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('content')
+        .description('List contents of a storage pool (ISOs, disk images, backups, templates)')
+        .requiredOption('--storage <name>', 'Storage pool name')
+        .option('--content <type>', 'Content type filter (iso, images, backup, vztmpl)')
+    )
+  ).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.content ? { content: opts.content } : undefined;
+    const data = await client.get(`nodes/${node}/storage/${opts.storage}/content`, params);
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Storage content');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no content)');
+      } else {
+        for (const item of list) {
+          const volid = (item.volid || '').padEnd(40);
+          const format = (item.format || '').padEnd(8);
+          const size = item.size ?? '-';
+          out.info(`${volid} ${format} size=${size}`);
+        }
+        out.dim(`${list.length} item(s) in ${opts.storage} on ${node}`);
+      }
+    }
+    out.set('node', node);
+    out.set('storage', opts.storage);
+    out.set('content', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  return cmd;
+}

package/src/commands/task.js

@@ -0,0 +1,155 @@
+/**
+ * `proxmox task` subcommands: list, get, wait.
+ *
+ * Each subcommand accepts the standard credential flags and --node, which
+ * falls back to the configured defaultNode.
+ */
+
+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 taskCommand() {
+  const cmd = new Command('task');
+  cmd.description('Task operations');
+
+  // ── list ──────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('list')
+        .description('List recent tasks on a node')
+        .option('--limit <n>', 'Max tasks to return (default: 50)')
+        .option('--source <type>', 'Filter by source (active, archive, all)')
+    )
+  ).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 = {
+      limit: opts.limit || '50',
+      source: opts.source || 'active',
+    };
+    const data = await client.get(`nodes/${node}/tasks`, params);
+    const list = Array.isArray(data) ? data : [];
+
+    out.heading('Tasks');
+    if (runtime.interactive) {
+      if (!list.length) {
+        out.dim('(no tasks)');
+      } else {
+        for (const t of list) {
+          const type = (t.type || '').padEnd(12);
+          const status = (t.status || '').padEnd(10);
+          const id = t.id || '-';
+          out.info(`${type} ${status} id=${id} user=${t.user || '-'}`);
+        }
+        out.dim(`${list.length} task(s) on ${node}`);
+      }
+    }
+    out.set('node', node);
+    out.set('tasks', list);
+    out.set('total', list.length);
+    out.flush();
+  });
+
+  // ── get ───────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('get')
+        .description('Get status and log of a specific task by UPID')
+        .requiredOption('--upid <upid>', 'Task UPID')
+    )
+  ).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 = encodeURIComponent(opts.upid);
+    const [status, log] = await Promise.all([
+      client.get(`nodes/${node}/tasks/${upid}/status`),
+      client.get(`nodes/${node}/tasks/${upid}/log`),
+    ]);
+
+    const logLines = Array.isArray(log)
+      ? log.map((l) => l.t).filter(Boolean)
+      : [];
+
+    out.heading('Task detail');
+    if (runtime.interactive) {
+      out.info(`Node: ${node}`);
+      if (status && typeof status === 'object') {
+        for (const [k, v] of Object.entries(status)) {
+          out.info(`${k.padEnd(14)} ${v}`);
+        }
+      }
+      if (logLines.length) {
+        out.info('');
+        out.info('Log:');
+        for (const line of logLines) {
+          out.info(`  ${line}`);
+        }
+      }
+    }
+    out.set('node', node);
+    out.set('upid', opts.upid);
+    out.set('status', status);
+    out.set('log', logLines);
+    out.flush();
+  });
+
+  // ── wait ──────────────────────────────────────────────────────────
+  withNodeOption(
+    withCredentialOptions(
+      cmd.command('wait')
+        .description('Wait for a task to complete by polling its UPID')
+        .requiredOption('--upid <upid>', 'Task UPID to wait for')
+        .option('--timeout <seconds>', 'Timeout in seconds (default: 300)')
+    )
+  ).action(async (opts) => {
+    const runtime = getRuntime();
+    const out = createOutput(runtime);
+    const creds = resolveCredentials(opts);
+    const node = resolveNode(opts, creds);
+    const client = createProxmoxClient(creds);
+
+    const timeoutMs = opts.timeout ? parseInt(opts.timeout, 10) * 1000 : 300000;
+    const upid = encodeURIComponent(opts.upid);
+    const start = Date.now();
+
+    let status;
+    while (Date.now() - start < timeoutMs) {
+      status = await client.get(`nodes/${node}/tasks/${upid}/status`);
+      if (status && status.status === 'stopped') break;
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+
+    const finished = status && status.status === 'stopped';
+
+    out.heading('Task wait');
+    if (runtime.interactive) {
+      if (finished) {
+        out.success(`Task completed: ${status.exitstatus || 'OK'}`);
+      } else {
+        out.info('Task did not complete within timeout');
+      }
+    }
+    out.set('node', node);
+    out.set('upid', opts.upid);
+    out.set('status', status);
+    out.set('finished', finished);
+    out.flush();
+  });
+
+  return cmd;
+}