influx-local-cli 0.1.0

package/src/cli.js

@@ -0,0 +1,1092 @@
+'use strict';
+
+const { Command } = require('commander');
+const fs = require('fs/promises');
+const path = require('path');
+const pkg = require('../package.json');
+const manager = require('./manager');
+const configMod = require('./config');
+const { FLAVORS, FLAVOR_ORDER, flavorOf, artifactsFor, resolveVersionInput, versionCatalog } = require('./versions');
+const {
+  loadConfig,
+  saveConfig,
+  configExists,
+  listInstances,
+  assertValidInstanceName,
+  readCreds,
+  getConfigPath,
+  SETTABLE_KEYS,
+  miseBin,
+} = configMod;
+
+// ANSI color codes as constants (empty when stdout is not a tty or NO_COLOR is
+// set). wrap(text, code) colors a single piece of text.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const code = (c) => (useColor ? `\u001b[${c}m` : '');
+const reset = code('0');
+const colors = { cyan: code('36'), bright: code('1'), dim: code('2'), red: code('31'), green: code('32'), yellow: code('33'), magenta: code('35') };
+function wrap(s, c) {
+  const col = code(c);
+  return useColor ? `${col}${s}${reset}` : String(s);
+}
+
+// DSNs carry either "user:password@" (1.x) or a bare "token@" (2.x/3.x) in the
+// userinfo position — mask both shapes.
+function maskSecrets(uri) {
+  let out = String(uri).replace(/\/\/([^:@/]+):([^@/]+)@/, '//$1:•••••••@');
+  out = out.replace(/\/\/([^:@/]+)@/, '//•••••••@');
+  return out;
+}
+
+function formatState(state) {
+  if (state === 'running') return wrap('running', '32');
+  if (state === 'port-conflict') return wrap('port-conflict', '31');
+  if (state === 'stale-pid') return wrap('stale-pid', '31');
+  return wrap('stopped', '33');
+}
+
+function flavorTag(flavorId) {
+  const f = FLAVORS[flavorId];
+  return f ? f.label : flavorId;
+}
+
+// --- First-run wizard -------------------------------------------------------
+
+// Scan upward from startPort until a free port is found.
+async function findFreePort(startPort, host, maxAttempts = 50) {
+  for (let port = startPort; port < startPort + maxAttempts; port++) {
+    if (!(await manager.checkPort(port, host))) return port;
+  }
+  return startPort;
+}
+
+// Minimal arrow-key list selector (↑/↓ to move, Enter to pick, Esc/q/Ctrl+C to
+// abort). Returns the chosen option value, or null when aborted.
+function selectOption(question, options) {
+  const readline = require('readline');
+  const { stdin, stdout } = process;
+  return new Promise((resolve) => {
+    readline.emitKeypressEvents(stdin);
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+
+    let index = 0;
+    const totalLines = Math.min(options.length, 20) + 1;
+    const cleanup = () => {
+      if (stdin.isTTY) stdin.setRawMode(false);
+      stdout.write('\n');
+    };
+    const onKeypress = (str, key) => {
+      if (key.name === 'up' || key.name === 'k') {
+        index = (index - 1 + options.length) % options.length;
+        render(false);
+      } else if (key.name === 'down' || key.name === 'j') {
+        index = (index + 1) % options.length;
+        render(false);
+      } else if (key.name === 'return') {
+        stdin.removeListener('keypress', onKeypress);
+        cleanup();
+        resolve(options[index].value);
+      } else if (str && /^[1-9]$/.test(str)) {
+        const num = parseInt(str, 10);
+        if (num <= options.length) {
+          index = num - 1;
+          render(false);
+        }
+      } else if ((key.ctrl && key.name === 'c') || key.name === 'escape' || key.name === 'q') {
+        stdin.removeListener('keypress', onKeypress);
+        cleanup();
+        resolve(null);
+      }
+    };
+    function render(initial) {
+      if (!initial) stdout.write(`\x1b[${totalLines}A\x1b[0J`);
+      stdout.write(`${question}\n`);
+      for (let i = 0; i < options.length; i++) {
+        stdout.write(
+          i === index
+            ? `  ${colors.cyan}${colors.bright}> ${options[i].label}${reset}\n`
+            : `    ${options[i].label}\n`,
+        );
+      }
+    }
+    stdin.on('keypress', onKeypress);
+    render(true);
+  });
+}
+
+// Interactive InfluxDB version picker (the whole point of the --version flag):
+// the catalog grouped by product line, plus an escape hatch for any other
+// published version.
+async function selectVersion(defaultVersion, store) {
+  const options = [];
+  for (const id of FLAVOR_ORDER) {
+    const f = FLAVORS[id];
+    for (const version of f.versions) {
+      const marks = [];
+      if (version === f.defaultVersion) marks.push('default for ' + f.label);
+      if (version === defaultVersion) marks.push('current');
+      options.push({
+        value: version,
+        label: `${version}  ${colors.dim}${f.label}${marks.length ? ` — ${marks.join(', ')}` : ''}${reset}`,
+      });
+    }
+  }
+  options.push({ value: '__custom__', label: `${colors.dim}enter another published version…${reset}` });
+
+  const picked = await selectOption('Which InfluxDB version should this instance pin?', options);
+  if (picked === null) return null;
+  if (picked !== '__custom__') return picked;
+
+  const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const raw = (await new Promise((r) => readline.question(`  ${colors.bright}Version${reset} (e.g. 2.7.11): `, r))).trim();
+    return resolveVersionInput(raw);
+  } finally {
+    readline.close();
+  }
+}
+
+// First run of any command targeting an instance: ask the user to configure it
+// interactively. Pressing Enter keeps the default. Returns true when a config
+// was saved, false when there is nothing to configure.
+async function ensureInstanceConfigured(name) {
+  if (await configExists(name)) return false;
+  if (!process.stdin.isTTY) return false;
+
+  const config = await loadConfig(name);
+  console.log(
+    `${colors.cyan}Instance "${name}" has not been configured yet.\nPlease answer the following questions (press ${colors.bright}Enter${reset}${colors.cyan} to use the default value):${reset}`,
+  );
+
+  const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question) => new Promise((resolve) => readline.question(question, resolve));
+
+  try {
+    console.log(`  ${colors.dim}available lines: 1.x = InfluxQL, 2.x = Flux, 3.x = Core/SQL${reset}`);
+    const versionRaw = (await ask(`  ${colors.bright}InfluxDB version${reset} (default: ${config.version}): `)).trim();
+    if (versionRaw !== '') config.version = resolveVersionInput(versionRaw);
+    config.port = await findFreePort(config.port, config.host);
+    const portRaw = (await ask(`  ${colors.bright}Port${reset} (default: ${config.port}): `)).trim();
+    if (portRaw !== '') {
+      const port = parseInt(portRaw, 10);
+      if (Number.isNaN(port) || port <= 0 || port > 65535) throw new Error('port must be 1-65535');
+      config.port = port;
+    }
+    const hostRaw = (await ask(`  ${colors.bright}Host / bind IP${reset} (default: ${config.host}): `)).trim();
+    if (hostRaw !== '') config.host = hostRaw;
+    const dbRaw = (await ask(`  ${colors.bright}Database${reset} (default: ${config.database}): `)).trim();
+    if (dbRaw !== '') config.database = dbRaw;
+  } finally {
+    readline.close();
+  }
+
+  await saveConfig(name, config);
+  console.log(`${colors.green}✓ Configuration for "${name}" saved.${reset}`);
+  return true;
+}
+
+// Decide which instance a command targets. Explicit name wins; otherwise, when
+// several instances exist on an interactive terminal, ask the user to pick one.
+async function resolveInstanceName(providedName) {
+  if (providedName) return providedName;
+  if (!process.stdin.isTTY) return 'default';
+
+  const names = await listInstances();
+  if (names.length === 0) return 'default';
+  if (names.length === 1) return names[0];
+
+  const labels = [];
+  for (const name of names) {
+    const cfg = await loadConfig(name);
+    labels.push({
+      value: name,
+      label: `${name}  ${colors.dim}${cfg.version} (${cfg.host}:${cfg.port})${reset}`,
+    });
+  }
+  return selectOption('Select the InfluxDB instance:', labels);
+}
+
+async function prepareInstance(providedName) {
+  if (providedName !== undefined && providedName !== null) assertValidInstanceName(providedName);
+  const name = await resolveInstanceName(providedName);
+  if (name === null) return null;
+  await ensureInstanceConfigured(name);
+  return name;
+}
+
+function mergeInstanceArg(name, options) {
+  const fromFlag = options && options.instance;
+  if (fromFlag !== undefined && name !== undefined && fromFlag !== name) {
+    throw new Error('Specify the instance either as an argument or with --instance, not both.');
+  }
+  return fromFlag !== undefined ? fromFlag : name;
+}
+
+function handle(action) {
+  return (...args) => {
+    action(...args).catch((err) => {
+      console.error(`${colors.red}Error: ${err && err.message ? err.message : err}${reset}`);
+      process.exitCode = 1;
+    });
+  };
+}
+
+function printConnection(cfg, { showSecrets = false } = {}) {
+  console.log(`\n${colors.bright}Connection details${reset}:`);
+  console.log(`  ${colors.bright}Flavor:${reset}     ${flavorTag(cfg.flavor)} — version ${cfg.version} (auth: ${cfg.auth})`);
+  console.log(`  ${colors.bright}Host:${reset}       ${cfg.host}`);
+  console.log(`  ${colors.bright}Port:${reset}       ${cfg.port}`);
+  console.log(`  ${colors.bright}Endpoint:${reset}   http://${cfg.host === '0.0.0.0' ? '127.0.0.1' : cfg.host}:${cfg.port}`);
+  if (cfg.flavor === 'v1') {
+    console.log(`  ${colors.bright}Database:${reset}   ${cfg.database} (measurement: ${cfg.measurement})`);
+    console.log(`  ${colors.bright}Admin user:${reset} ${cfg.adminUser} (ALL PRIVILEGES)`);
+    console.log(`  ${colors.bright}App user:${reset}   ${cfg.appUser} (ALL on ${cfg.database})`);
+  } else if (cfg.flavor === 'v2') {
+    console.log(`  ${colors.bright}Org:${reset}        ${cfg.org}`);
+    console.log(`  ${colors.bright}Bucket:${reset}     ${cfg.database}`);
+    console.log(`  ${colors.bright}Admin user:${reset} ${cfg.adminUser} (operator password + all-access token)`);
+    console.log(`  ${colors.bright}App token:${reset}  read/write on bucket "${cfg.database}"`);
+  } else {
+    console.log(`  ${colors.bright}Database:${reset}   ${cfg.database}`);
+    console.log(`  ${colors.bright}Auth:${reset}       single admin token ("_admin")`);
+  }
+  console.log(`  ${colors.bright}Data dir:${reset}   ${cfg.dataDir}`);
+  if (showSecrets) {
+    console.log(`  ${colors.bright}creds:${reset}      ${cfg.credsPath} (mode 0600)`);
+  }
+}
+
+function printUris(uris, { showSecrets = false } = {}) {
+  if (!uris) return;
+  const rows = [
+    ['App DSN', uris.appUri],
+    ['Admin DSN', uris.adminUri],
+    ['Public DSN', uris.publicAppUri],
+  ];
+  for (const [label, value] of rows) {
+    if (!value) continue;
+    console.log(`  ${colors.bright}${label.padEnd(10)}${reset} ${showSecrets ? value : maskSecrets(value)}`);
+  }
+  if (!showSecrets && (uris.appUri || uris.adminUri)) {
+    console.log(`  ${colors.dim}(re-run with --show-secrets to print real secrets)${reset}`);
+  }
+}
+
+async function printInstanceResult(name, result, options, { verb }) {
+  console.log(`${colors.green}✓ Instance "${name}" ${verb}.${reset}`);
+  printConnection(result.config, { showSecrets: options.showSecrets });
+  const creds = await readCreds(name, result.config.flavor);
+  if (creds) {
+    const status = await manager.getStatus(name, { detail: false });
+    printUris(status.uris, { showSecrets: options.showSecrets });
+  }
+}
+
+// --- Program ----------------------------------------------------------------
+
+function buildProgram() {
+  const program = new Command();
+  program
+    .name('influx-local')
+    .description('Create, start and manage local InfluxDB instances (1.x / 2.x / 3.x) without Docker/Podman (powered by mise)')
+    .version(pkg.version)
+    .showSuggestionAfterError();
+
+  program
+    .command('versions')
+    .description('List the InfluxDB versions this tool can install (pin one with "create -v/--influxdb")')
+    .option('-f, --flavor <line>', 'Only this line: 1, 2 or 3')
+    .option('-j, --json', 'Print machine-readable JSON')
+    .action(
+      handle(async (options) => {
+        const catalog = versionCatalog();
+        const filtered = options.flavor
+          ? catalog.filter((entry) => entry.flavor === `v${String(options.flavor).replace(/^v/, '')}`)
+          : catalog;
+        if (filtered.length === 0) throw new Error(`unknown flavor "${options.flavor}" — use 1, 2 or 3`);
+        if (options.json) {
+          console.log(JSON.stringify(filtered, null, 2));
+          return;
+        }
+        console.log(`${colors.bright}InfluxDB versions available to "influx-local create -v <version>"${reset}`);
+        console.log(''.padEnd(78, '-'));
+        for (const id of FLAVOR_ORDER) {
+          const entries = filtered.filter((entry) => entry.flavor === id);
+          if (entries.length === 0) continue;
+          const f = FLAVORS[id];
+          console.log(`  ${colors.bright}${f.label}${reset} ${colors.dim}(auth: ${f.auth}, default port ${f.defaultPort})${reset}`);
+          const list = entries
+            .map((entry) => (entry.default ? wrap(entry.version, '32') : entry.version))
+            .join('  ');
+          console.log(`    ${list}`);
+          const def = entries.find((entry) => entry.default) || entries[0];
+          console.log(`    ${colors.dim}line alias: -v ${id[1]}.x  →  ${def.version}${reset}`);
+        }
+        console.log(''.padEnd(78, '-'));
+        console.log(`  ${colors.dim}Any other published version works too: create -v 2.7.5${reset}`);
+      }),
+    );
+
+  program
+    .command('create [name]')
+    .description('Create a new (stopped) instance with a pinned InfluxDB version; then run "setup" to provision it')
+    .option('-v, --influxdb <version>', 'InfluxDB version to pin (1.8.10, 2.7.11, 3.11.4, or a line alias 1.x/2.x/3.x)')
+    .option('-p, --port <port>', 'TCP port (default: first free port for the chosen line)')
+    .option('--host <host>', 'Bind address (default: 127.0.0.1)')
+    .option('--database <name>', 'Database (1.x/3.x) or bucket (2.x) — default: instance name')
+    .option('--measurement <name>', 'Sample measurement/table (1.x/3.x, default: items)')
+    .option('--org <name>', 'InfluxDB 2.x organization (default: instance name)')
+    .option('--admin-user <name>', 'Admin user (1.x/2.x, default: admin)')
+    .option('--app-user <name>', 'App user (1.x, default: app)')
+    .option('--admin-password <pw>', 'Admin password (1.x/2.x, default: auto-generated)')
+    .option('--app-password <pw>', 'App user password (1.x, default: auto-generated)')
+    .action(
+      handle(async (name, options) => {
+        const interactive = process.stdin.isTTY;
+        if (!name) {
+          if (!interactive) throw new Error('instance name is required: influx-local create <name>');
+          const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+          name = await new Promise((r) => readline.question(`  ${colors.bright}Instance name${reset}: `, r));
+          readline.close();
+        }
+        name = assertValidInstanceName(String(name).trim());
+        if (await configExists(name)) throw new Error(`instance "${name}" already exists`);
+
+        let version;
+        if (options.influxdb !== undefined) {
+          version = resolveVersionInput(options.influxdb);
+        } else if (interactive) {
+          version = await selectVersion(configMod.DEFAULT_VERSION);
+          if (version === null) {
+            console.log(`${colors.yellow}Aborted.${reset}`);
+            return;
+          }
+        } else {
+          version = configMod.DEFAULT_VERSION;
+        }
+
+        const flavor = flavorOf(version);
+        const nextPort = await manager.nextFreePort(flavor.defaultPort, options.host || '127.0.0.1');
+        let port = options.port !== undefined ? parseInt(options.port, 10) : nextPort;
+        if (Number.isNaN(port) || port <= 0 || port > 65535) throw new Error('port must be 1-65535');
+
+        let host = options.host || '127.0.0.1';
+        let database = options.database || name;
+        let measurement = options.measurement || 'items';
+        let org = options.org || name;
+        let adminUser = options.adminUser || 'admin';
+        let appUser = options.appUser || 'app';
+        let adminPassword = options.adminPassword !== undefined ? options.adminPassword : '';
+        let appPassword = options.appPassword !== undefined ? options.appPassword : '';
+
+        if (interactive) {
+          console.log(`${colors.cyan}Creating instance "${name}" — press Enter to accept each default:${reset}`);
+          const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+          const ask = (q) => new Promise((r) => readline.question(q, r));
+          try {
+            const pick = async (label, current) => {
+              const raw = (await ask(`  ${colors.bright}${label}${reset} (default: ${current}): `)).trim();
+              return raw === '' ? current : raw;
+            };
+            if (options.port === undefined) {
+              port = parseInt(await pick('Port', nextPort), 10);
+              if (Number.isNaN(port) || port <= 0 || port > 65535) throw new Error('port must be 1-65535');
+            }
+            if (!options.host) host = await pick('Host / bind IP', host);
+            if (!options.database) database = await pick(flavor.id === 'v2' ? 'Bucket name' : 'Database name', database);
+            if (flavor.capabilities.measurement && !options.measurement) {
+              measurement = await pick('Sample measurement', measurement);
+            }
+            if (flavor.id === 'v2' && !options.org) org = await pick('Organization', org);
+            if (flavor.id !== 'v3' && !options.adminUser) adminUser = await pick('Admin user', adminUser);
+            if (flavor.id === 'v1' && !options.appUser) appUser = await pick('App user', appUser);
+            if (flavor.id !== 'v3' && options.adminPassword === undefined) {
+              adminPassword = await pick('Admin password (blank = auto-generate)', 'auto-generate');
+              if (adminPassword === 'auto-generate') adminPassword = '';
+            }
+            if (flavor.id === 'v1' && options.appPassword === undefined) {
+              appPassword = await pick('App password (blank = auto-generate)', 'auto-generate');
+              if (appPassword === 'auto-generate') appPassword = '';
+            }
+          } finally {
+            readline.close();
+          }
+        }
+
+        // 2.x has no app user (access is scoped with tokens) and 3.x has no
+        // users at all — keep those keys out of the config.
+        const config = {
+          version,
+          port,
+          host,
+          database,
+          publicHost: '',
+        };
+        if (flavor.capabilities.measurement) config.measurement = measurement;
+        if (flavor.id === 'v2') config.org = org;
+        if (flavor.id !== 'v3') {
+          config.adminUser = adminUser;
+          if (flavor.id === 'v1') config.appUser = appUser;
+        }
+        configMod.assertValidInstanceName(name);
+        await saveConfig(name, config);
+        await configMod.saveMiseToml(name, version);
+
+        const saved = await loadConfig(name);
+        if (saved.flavor === 'v1') {
+          await configMod.writeCreds(name, 'v1', {
+            ADMIN_USER: saved.adminUser,
+            ADMIN_PW: adminPassword || configMod.randomPassword(),
+            APP_USER: saved.appUser,
+            APP_PW: appPassword || configMod.randomPassword(),
+          }, saved);
+        } else if (saved.flavor === 'v2') {
+          await configMod.writeCreds(name, 'v2', {
+            ADMIN_USER: saved.adminUser,
+            ADMIN_PW: adminPassword || configMod.randomPassword(),
+            ADMIN_TOKEN: configMod.randomToken(),
+            APP_TOKEN: '',
+            ORG: saved.org,
+            BUCKET: saved.database,
+          }, saved);
+        }
+
+        console.log(`${colors.green}✓ Instance "${name}" created (stopped), pinned to InfluxDB ${version}.${reset}`);
+        printConnection(saved);
+        if (saved.flavor === 'v3') {
+          console.log(`  ${colors.dim}The admin token is minted by the server during "setup".${reset}`);
+        } else {
+          console.log(`  ${colors.bright}creds:${reset}      ${saved.credsPath} (mode 0600)`);
+        }
+        console.log(`  ${colors.dim}Next: influx-local setup ${name}  (installs InfluxDB ${version}, provisions it, starts the server)${reset}`);
+      }),
+    );
+
+  program
+    .command('setup [name]')
+    .alias('bootstrap')
+    .description('Install the pinned version if missing, provision it, and start the instance')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .option('-s, --show-secrets', 'Print real secrets in connection DSNs')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const log = (m) => console.log(m);
+        const cfg = await loadConfig(name);
+        console.log(`${colors.cyan}Setting up InfluxDB ${cfg.version} instance "${name}"…${reset}`);
+        const result = await manager.setupInstance(name, { log });
+        if (result.online) {
+          console.log(`${colors.green}✓ Instance "${name}" repaired online — no restart needed.${reset}`);
+        }
+        await printInstanceResult(name, result, options, { verb: result.online ? 'repaired' : 'is ready' });
+      }),
+    );
+
+  program
+    .command('start [name]')
+    .description('Start an InfluxDB instance (auto-installs the pinned version when missing)')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .option('-s, --show-secrets', 'Print real secrets in connection DSNs')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const cfg = await loadConfig(name);
+        await manager.installTools(cfg).catch(() => {});
+        const log = (m) => console.log(m);
+        console.log(`${colors.cyan}Starting InfluxDB instance "${name}"…${reset}`);
+        const result = await manager.startInstance(name, { log });
+        if (result.alreadyRunning) {
+          console.log(`${colors.yellow}Instance "${name}" is already running (pid ${result.pid}).${reset}`);
+        } else {
+          console.log(`${colors.green}✓ InfluxDB instance "${name}" started (pid ${result.pid}).${reset}`);
+        }
+        printConnection(result.config, { showSecrets: options.showSecrets });
+        const status = await manager.getStatus(name, { detail: false });
+        printUris(status.uris, { showSecrets: options.showSecrets });
+      }),
+    );
+
+  program
+    .command('stop [name]')
+    .description('Stop a local InfluxDB instance')
+    .option('-f, --force', 'Terminate immediately instead of waiting for a graceful stop')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const log = (m) => console.log(m);
+        console.log(`${colors.cyan}Stopping InfluxDB instance "${name}"…${reset}`);
+        const result = await manager.stopInstance(name, { force: options.force, log });
+        if (result.alreadyStopped) {
+          console.log(`${colors.yellow}Instance "${name}" is already stopped.${reset}`);
+        } else if (options.force) {
+          console.log(`${colors.yellow}! Instance "${name}" terminated forcefully.${reset}`);
+        } else {
+          console.log(`${colors.green}✓ Instance "${name}" stopped gracefully.${reset}`);
+        }
+      }),
+    );
+
+  program
+    .command('restart [name]')
+    .description('Restart a local InfluxDB instance')
+    .option('-f, --force', 'Kill immediately if a graceful stop times out')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const log = (m) => console.log(m);
+        console.log(`${colors.cyan}Restarting InfluxDB instance "${name}"…${reset}`);
+        await manager.restartInstance(name, { force: options.force, log });
+        console.log(`${colors.green}✓ Instance "${name}" restarted.${reset}`);
+      }),
+    );
+
+  program
+    .command('status [name]')
+    .alias('ps')
+    .description('Check the status of an InfluxDB instance')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .option('-j, --json', 'Print machine-readable JSON')
+    .option('-s, --show-secrets', 'Print real secrets in connection DSNs')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const status = await manager.getStatus(name);
+        if (options.json) {
+          const { config, ...plain } = status;
+          if (!options.showSecrets && plain.uris) {
+            for (const key of Object.keys(plain.uris)) plain.uris[key] = maskSecrets(plain.uris[key]);
+          }
+          console.log(JSON.stringify(plain, null, 2));
+          return;
+        }
+        console.log(`${colors.bright}Instance:${reset}   ${status.name}`);
+        console.log(`${colors.bright}Status:${reset}     ${formatState(status.state)}${status.pid ? ` (pid ${status.pid})` : ''}`);
+        console.log(`${colors.bright}Flavor:${reset}     ${status.flavorLabel} — pinned ${status.version}${status.runningVersion ? `, running ${status.runningVersion}` : ''}`);
+        console.log(`${colors.bright}Host:${reset}       ${status.host}`);
+        console.log(`${colors.bright}Port:${reset}       ${status.port}`);
+        console.log(`${colors.bright}Endpoint:${reset}   ${status.endpoint}`);
+        if (status.flavor === 'v2') {
+          console.log(`${colors.bright}Org/Bucket:${reset} ${status.org} / ${status.database}`);
+          console.log(`${colors.bright}Admin user:${reset} ${status.adminUser}`);
+        } else {
+          console.log(`${colors.bright}Database:${reset}   ${status.database}${status.measurement ? ` (measurement: ${status.measurement})` : ''}`);
+          if (status.adminUser) console.log(`${colors.bright}Users:${reset}      admin=${status.adminUser}${status.appUser ? `  app=${status.appUser}` : ''}`);
+        }
+        console.log(`${colors.bright}Dir:${reset}        ${status.dataDir}`);
+        if (status.running) {
+          console.log(
+            `${colors.bright}Measurements:${reset} ${status.measurements == null ? '?' : status.measurements.join(', ') || '(none yet)'}`,
+          );
+          printUris(status.uris, { showSecrets: options.showSecrets });
+        } else {
+          console.log(`${colors.yellow}Start it with: influx-local start ${status.name}${reset}`);
+        }
+      }),
+    );
+
+  program
+    .command('list')
+    .alias('ls')
+    .description('List all local InfluxDB instances')
+    .option('-j, --json', 'Print machine-readable JSON')
+    .action(
+      handle(async (options) => {
+        const statuses = await manager.listStatuses();
+        if (options.json) {
+          console.log(JSON.stringify(statuses, null, 2));
+          return;
+        }
+        if (statuses.length === 0) {
+          console.log(`${colors.yellow}No instances found. Start one with "influx-local create [name]".${reset}`);
+          return;
+        }
+        console.log(`${colors.bright}Local InfluxDB Instances:${reset}`);
+        console.log(''.padEnd(78, '-'));
+        for (const s of statuses) {
+          const nameCell = wrap(s.name.padEnd(12), s.running ? '32' : '1');
+          console.log(
+            `  ${nameCell} | ${formatState(s.state).padEnd(16)} | ${String(s.version).padEnd(8)} | ${s.host}:${s.port}`,
+          );
+        }
+        console.log(''.padEnd(78, '-'));
+      }),
+    );
+
+  program
+    .command('rename <name> <newName>')
+    .description('Rename an instance (it must be stopped first)')
+    .action(
+      handle(async (name, newName) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const log = (m) => console.log(m);
+        const result = await manager.renameInstance(name, newName, { log });
+        console.log(`${colors.green}✓ Instance renamed: "${name}" -> "${result}".${reset}`);
+      }),
+    );
+
+  program
+    .command('clone <name> <newName>')
+    .alias('duplicate')
+    .description("Copy an instance's config + credentials to a new name (picks the next free port)")
+    .option('-p, --port <port>', 'Port for the clone (default: next free port)')
+    .action(
+      handle(async (name, newName, options) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        let port;
+        if (options.port !== undefined) {
+          port = parseInt(options.port, 10);
+          if (Number.isNaN(port) || port <= 0 || port > 65535) throw new Error('port must be 1-65535');
+        }
+        const log = (m) => console.log(m);
+        const result = await manager.cloneInstance(name, newName, { port, log });
+        console.log(`${colors.green}✓ Instance cloned: "${result.name}" on port ${result.port} (stopped, InfluxDB ${result.config.version}).${reset}`);
+        console.log(`  ${colors.dim}Next: influx-local setup ${result.name}${reset}`);
+      }),
+    );
+
+  program
+    .command('set-password <name>')
+    .description('Set an explicit password (1.x: admin/app users, 2.x: operator user)')
+    .option('--user <admin|app>', 'Which user to update', 'admin')
+    .option('-p, --password <pw>', 'New password (min 6 chars)')
+    .action(
+      handle(async (name, options) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        let password = options.password;
+        if (!password) {
+          if (!process.stdin.isTTY) throw new Error('--password is required on a non-interactive terminal');
+          const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+          password = await new Promise((r) =>
+            readline.question(`  New password for ${options.user} (min 6 chars): `, r),
+          );
+          readline.close();
+        }
+        const log = (m) => console.log(m);
+        const result = await manager.setPassword(name, { user: options.user, password, log });
+        console.log(
+          result.applied
+            ? `${colors.green}✓ ${options.user} password updated on the running server.${reset}`
+            : `${colors.green}✓ creds.env updated. Server is stopped — run "influx-local setup ${name}" to apply it.${reset}`,
+        );
+      }),
+    );
+
+  program
+    .command('users [name]')
+    .description('List users/tokens of an instance (built-in + server-side)')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const data = await manager.listUsers(name);
+        if (!data.running) {
+          console.log(`${colors.yellow}Server is stopped — showing the managed credentials only (start it to read the server).${reset}`);
+        } else if (data.error) {
+          console.log(`${colors.red}${data.error}${reset}`);
+        }
+        const width = Math.max(6, ...data.users.map((u) => u.user.length));
+        console.log(`${colors.bright}Users of "${name}":${reset}`);
+        for (const u of data.users) {
+          const roles = (u.roles || []).join(',') || '—';
+          const tag = u.builtin ? ` ${wrap('[managed]', '33')}` : '';
+          console.log(`  ${colors.bright}${u.user.padEnd(width)}${reset} @${String(u.db || '—').padEnd(16)} ${roles}${tag}`);
+        }
+      }),
+    );
+
+  program
+    .command('user-add <name> <username>')
+    .description('Create a user on a running instance')
+    .option('-p, --password <pw>', 'Password (min 6 chars)')
+    .option('--db <admin|database>', 'Target database (1.x only, default: instance database)')
+    .option('--privileges <list>', 'Comma-separated 1.x privileges: read,write,all (default: all)')
+    .action(
+      handle(async (name, username, options) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        if (!options.password) {
+          if (!process.stdin.isTTY) throw new Error('--password is required on a non-interactive terminal');
+          const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+          options.password = await new Promise((r) =>
+            readline.question(`  Password for "${username}" (min 6 chars): `, r),
+          );
+          readline.close();
+        }
+        const privileges = options.privileges ? options.privileges.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        const log = (m) => console.log(m);
+        const res = await manager.addUser(name, {
+          username,
+          db: options.db,
+          password: options.password,
+          privileges,
+          log,
+        });
+        console.log(`${colors.green}✓ Created "${res.user}" on ${res.db} (${res.privileges.join(', ')}).${reset}`);
+      }),
+    );
+
+  program
+    .command('user-password <name> <username>')
+    .description('Set an explicit password for any existing user')
+    .option('-p, --password <pw>', 'New password (min 6 chars)')
+    .action(
+      handle(async (name, username, options) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        if (!options.password) {
+          if (!process.stdin.isTTY) throw new Error('--password is required on a non-interactive terminal');
+          const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+          options.password = await new Promise((r) =>
+            readline.question(`  New password for "${username}" (min 6 chars): `, r),
+          );
+          readline.close();
+        }
+        const log = (m) => console.log(m);
+        const res = await manager.setAnyPassword(name, { username, password: options.password, log });
+        console.log(`${colors.green}✓ Password of "${res.user}" updated.${reset}`);
+      }),
+    );
+
+  program
+    .command('user-rm <name> <username>')
+    .description('Delete a user (managed users are protected)')
+    .action(
+      handle(async (name, username) => {
+        name = await resolveInstanceName(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const log = (m) => console.log(m);
+        const res = await manager.removeUser(name, { username, log });
+        console.log(`${colors.green}✓ Deleted "${res.user}".${reset}`);
+      }),
+    );
+
+  const configCmd = program.command('config').description('Manage instance configuration');
+
+  configCmd
+    .command('show [name]')
+    .description('Show configuration for an instance')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const cfg = await loadConfig(name);
+        const printable = { name: cfg.name, flavor: cfg.flavor, flavorLabel: cfg.flavorLabel, auth: cfg.auth };
+        for (const key of SETTABLE_KEYS) {
+          if (key === 'measurement' && !cfg.capabilities.measurement) continue;
+          if (key === 'org' && cfg.flavor !== 'v2') continue;
+          if ((key === 'adminUser' || key === 'appUser') && cfg.flavor === 'v3') continue;
+          if (key === 'appUser' && cfg.flavor !== 'v1') continue;
+          printable[key] = cfg[key];
+        }
+        printable.dataDir = cfg.dataDir;
+        printable.miseToml = cfg.miseTomlPath;
+        console.log(JSON.stringify(printable, null, 2));
+      }),
+    );
+
+  configCmd
+    .command('set <name> <key> <value>')
+    .description(`Set a configuration parameter (keys: ${SETTABLE_KEYS.join(', ')})`)
+    .action(
+      handle(async (name, key, value) => {
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        if (!SETTABLE_KEYS.includes(key)) {
+          throw new Error(`Invalid config key "${key}". Valid keys: ${SETTABLE_KEYS.join(', ')}`);
+        }
+        const cfg = await loadConfig(name);
+        if (key === 'port') {
+          const port = parseInt(value, 10);
+          if (Number.isNaN(port) || port <= 0 || port > 65535) {
+            throw new Error('Port must be a valid number between 1 and 65535.');
+          }
+          cfg.port = port;
+        } else if (key === 'version') {
+          const next = resolveVersionInput(value);
+          const nextFlavor = flavorOf(next);
+          if (nextFlavor.id !== cfg.flavor && (await manager.instanceHasData(cfg))) {
+            throw new Error(
+              `Refusing to switch "${name}" from ${cfg.flavorLabel} to ${nextFlavor.label}: InfluxDB stores its data in a\n` +
+                '  line-specific format (1.x meta/data/wal, 2.x bolt/engine, 3.x catalog). Create a new instance instead.',
+            );
+          }
+          cfg.version = next;
+        } else {
+          if (value === '' && key !== 'publicHost') {
+            throw new Error(`Value for "${key}" must not be empty.`);
+          }
+          cfg[key] = value;
+        }
+        await saveConfig(name, cfg);
+        if (key === 'version') await configMod.saveMiseToml(name, cfg.version);
+        console.log(`${colors.green}✓ Saved configuration for "${name}": ${key} = ${cfg[key]}${reset}`);
+        if (key === 'version') {
+          console.log(`${colors.dim}The mise toolchain for ${cfg.version} is installed on the next setup/install.${reset}`);
+        }
+        console.log(
+          `${colors.yellow}Note: If the instance is currently running, restart it ("influx-local restart ${name}") for changes to take effect.${reset}`,
+        );
+      }),
+    );
+
+  program
+    .command('rotate [name]')
+    .description('Rotate the managed secrets on the running server and update creds.env')
+    .option('--admin', 'Rotate only the admin credential(s)')
+    .option('--app', 'Rotate only the app credential(s) (1.x password / 2.x token)')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const users = options.admin && !options.app ? 'admin' : options.app && !options.admin ? 'app' : 'all';
+        const log = (m) => console.log(m);
+        console.log(`${colors.cyan}Rotating secrets for "${name}" (${users})…${reset}`);
+        const result = await manager.rotateInstance(name, { users, log });
+        const which = [result.changed.admin && 'admin', result.changed.app && 'app'].filter(Boolean).join(' + ');
+        console.log(`${colors.green}✓ ${which} secret(s) rotated. Old credentials are now rejected.${reset}`);
+      }),
+    );
+
+  program
+    .command('query [name] [statement]')
+    .description('Run one statement (1.x: InfluxQL, 2.x: Flux, 3.x: SQL); reads stdin when omitted')
+    .option('--admin', 'Use the admin credential instead of the app credential')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, statement, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        if (!statement) {
+          if (process.stdin.isTTY) throw new Error('provide a statement: influx-local query <name> "<statement>"');
+          const chunks = [];
+          for await (const chunk of process.stdin) chunks.push(chunk);
+          statement = Buffer.concat(chunks).toString('utf8').trim();
+        }
+        if (!statement) throw new Error('empty statement');
+        const res = await manager.queryInstance(name, statement, { admin: !!options.admin });
+        if (res.stdout) process.stdout.write(res.stdout.endsWith('\n') ? res.stdout : `${res.stdout}\n`);
+        if (res.code !== 0) {
+          if (res.stderr) process.stderr.write(res.stderr);
+          process.exitCode = res.code || 1;
+        }
+      }),
+    );
+
+  program
+    .command('logs [name]')
+    .description('Show server logs of an instance')
+    .option('-f, --follow', 'Follow log output in real-time')
+    .option('-n, --lines <count>', 'Number of lines to show from the tail', (v) => parseInt(v, 10), 200)
+    .option('-i, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return;
+        const { text, missing } = await manager.readLogTail(name, options.lines);
+        if (missing) {
+          console.error(`${colors.red}No logs found yet for "${name}" (nothing has been started).${reset}`);
+          process.exitCode = 1;
+          return;
+        }
+        process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+        if (!options.follow) return;
+        console.log(`${colors.dim}\n(following — press Ctrl+C to stop)${reset}`);
+        const cfg = await loadConfig(name);
+        let size = (await fs.stat(cfg.logPath)).size;
+        const interval = setInterval(async () => {
+          try {
+            const st = await fs.stat(cfg.logPath);
+            if (st.size > size) {
+              const fd = await fs.open(cfg.logPath, 'r');
+              const buf = Buffer.alloc(st.size - size);
+              await fd.read(buf, 0, buf.length, size);
+              await fd.close();
+              process.stdout.write(buf.toString('utf8'));
+              size = st.size;
+            } else if (st.size < size) {
+              size = st.size;
+            }
+          } catch (err) {}
+        }, 500);
+        process.on('SIGINT', () => {
+          clearInterval(interval);
+          process.exit(0);
+        });
+      }),
+    );
+
+  program
+    .command('shell [name]')
+    .description('Open the InfluxDB 1.x REPL against the instance (append args after "--")')
+    .option('--admin', 'Connect as the admin user instead of the app user')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const code = await manager.shellInstance(name, { admin: options.admin, args: shellExtraArgs });
+        if (code !== null && code !== 0) process.exitCode = code;
+      }),
+    );
+
+  program
+    .command('install [name]')
+    .description('Install the instance\'s pinned InfluxDB version through mise (idempotent)')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await resolveInstanceName(name);
+        if (name === null) return;
+        const cfg = await loadConfig(name);
+        const log = (m) => console.log(m);
+        console.log(`${colors.cyan}Installing the toolchain for instance "${name}"…${reset}`);
+        await manager.installTools(cfg, log);
+        console.log(`${colors.green}✓ InfluxDB ${cfg.version} is installed for "${name}".${reset}`);
+      }),
+    );
+
+  program
+    .command('doctor [name]')
+    .description('Diagnose an instance and its environment')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .option('-j, --json', 'Print machine-readable JSON')
+    .action(
+      handle(async (name, options) => {
+        name = mergeInstanceArg(name, options);
+        name = await prepareInstance(name);
+        if (name === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        const checks = await manager.doctorInstance(name);
+        if (options.json) {
+          console.log(JSON.stringify(checks, null, 2));
+          return;
+        }
+        console.log(`${colors.bright}Diagnostics for "${name}":${reset}`);
+        for (const c of checks) {
+          const mark = wrap(c.ok ? '✓' : '✗', c.ok ? '32' : '31');
+          const detail = c.detail ? ` ${colors.dim}— ${c.detail}${reset}` : '';
+          console.log(`  ${mark} ${c.label}${detail}`);
+        }
+        if (checks.some((c) => !c.ok)) process.exitCode = 1;
+      }),
+    );
+
+  program
+    .command('web')
+    .description('Launch the web dashboard for all instances')
+    .option('-H, --host <address>', 'Address to bind', '127.0.0.1')
+    .option('-p, --port <port>', 'Port to bind', (v) => parseInt(v, 10), 8788)
+    .option('-t, --token <token>', 'Require this token for API access (env: INFLUX_LOCAL_WEB_TOKEN)')
+    .action(
+      handle(async (options) => {
+        const token = options.token || process.env.INFLUX_LOCAL_WEB_TOKEN || '';
+        const loopback = options.host === '127.0.0.1' || options.host === 'localhost' || options.host === '::1';
+        if (!loopback && !token) {
+          throw new Error(
+            `Refusing to expose the dashboard on ${options.host} without a token — it can start/stop instances, rotate secrets and destroy data.\n` +
+              'Re-run with a token:  influx-local web --host 0.0.0.0 --token <secret>\n' +
+              '  (or set INFLUX_LOCAL_WEB_TOKEN)',
+          );
+        }
+        const { startWeb } = require('./web');
+        const { url } = await startWeb({ host: options.host, port: options.port, token });
+        if (process.stdout.isTTY) {
+          console.log(`${colors.green}✓ Web dashboard: ${colors.bright}${url}${reset}`);
+          console.log(`${colors.dim}Open it in your browser (or press Ctrl+C to stop).${reset}`);
+        }
+      }),
+    );
+
+  program
+    .command('destroy [name]')
+    .alias('rm')
+    .description('Stop the instance and delete ALL of its data')
+    .option('-y, --yes', 'Skip the confirmation prompt (for scripts)')
+    .option('-n, --instance <name>', 'Instance name (alternative to the positional argument)')
+    .action((name, options) => {
+      void (async () => {
+        let resolved;
+        try {
+          resolved = mergeInstanceArg(name, options);
+          resolved = await prepareInstance(resolved);
+          if (resolved === null) return console.log(`${colors.yellow}Aborted.${reset}`);
+        } catch (err) {
+          console.error(`${colors.red}Error: ${err.message}${reset}`);
+          process.exitCode = 1;
+          return;
+        }
+        const execute = async () => {
+          try {
+            console.log(`${colors.cyan}Destroying instance "${resolved}"…${reset}`);
+            const log = (m) => console.log(m);
+            await manager.destroyInstance(resolved, { log });
+            console.log(`${colors.green}✓ Instance "${resolved}" has been destroyed.${reset}`);
+          } catch (err) {
+            console.error(`${colors.red}Error: ${err.message}${reset}`);
+            process.exitCode = 1;
+          }
+        };
+        if (options.yes) return execute();
+        if (!process.stdin.isTTY) {
+          console.error(
+            `${colors.red}Error: Refusing to destroy "${resolved}" without confirmation on a non-interactive terminal. Re-run with --yes to proceed.${reset}`,
+          );
+          process.exitCode = 1;
+          return;
+        }
+        const cfg = await loadConfig(resolved);
+        const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+        readline.question(
+          `${colors.red}${colors.bright}WARNING: This will permanently delete ALL data under "${cfg.dataDir}"\n  (database files, logs, credentials) — irreversible.\nAre you sure you want to proceed? (y/N): ${reset}`,
+          async (answer) => {
+            readline.close();
+            if (answer.toLowerCase() === 'y') await execute();
+            else console.log('Action cancelled.');
+          },
+        );
+      })();
+    });
+
+  return program;
+}
+
+// Args after "--" are forwarded to the influx CLI (used by `shell`).
+let shellExtraArgs = [];
+function run(argv) {
+  shellExtraArgs = [];
+  const dashIdx = argv.indexOf('--');
+  let cliArgv = argv;
+  if (dashIdx !== -1) {
+    shellExtraArgs = argv.slice(dashIdx + 1);
+    cliArgv = argv.slice(0, dashIdx);
+  }
+  const program = buildProgram();
+  program.parse(cliArgv);
+}
+
+module.exports = { run, resolveVersionInput, versionCatalog, maskSecrets };