unbound-cli 1.13.0 → 1.15.0

package/src/lib/analytics-query.js

@@ -0,0 +1,216 @@
+/**
+ * Flag parsing and query-string construction for `unbound analytics tool-use`.
+ * Pure functions — no network, no process state — so they are unit-testable.
+ */
+
+const TIME_WINDOWS = [
+  'ONE_DAY',
+  'THREE_DAYS',
+  'SEVEN_DAYS',
+  'FOURTEEN_DAYS',
+  'THIRTY_DAYS',
+  'THREE_MONTHS',
+];
+
+const FORMATS = ['table', 'json', 'csv'];
+
+const RISK_LEVELS = ['Low', 'Medium', 'High'];
+
+const INITIATORS = {
+  user: 'USER_INTENTIONAL',
+  agent: 'AGENT_INITIATED',
+  unknown: 'UNKNOWN',
+};
+
+// The backend rejects a custom range wider than this.
+const MAX_RANGE_DAYS = 90;
+
+const DEFAULT_TIME_WINDOW = 'THIRTY_DAYS';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 1000;
+// Lower for the table: past roughly a screenful nobody reads the rows, they
+// scroll past them. json is parsed rather than read, so it keeps the full cap.
+const MAX_TABLE_LIMIT = 100;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function parseList(value) {
+  if (value === undefined || value === null) return [];
+  const items = Array.isArray(value) ? value : String(value).split(',');
+  return items.map((v) => String(v).trim()).filter(Boolean);
+}
+
+function resolveFormat(opts) {
+  if (opts.json && opts.format && opts.format !== 'json') {
+    throw new Error(`Cannot combine --json with --format ${opts.format}.`);
+  }
+  const format = opts.json ? 'json' : (opts.format || 'table');
+  if (!FORMATS.includes(format)) {
+    throw new Error(`Invalid --format "${format}". Must be one of: ${FORMATS.join(', ')}.`);
+  }
+  return format;
+}
+
+function resolveWindow(opts) {
+  const hasStart = Boolean(opts.start);
+  const hasEnd = Boolean(opts.end);
+
+  if (hasStart !== hasEnd) {
+    throw new Error('--start and --end must be used together.');
+  }
+
+  if (hasStart) {
+    if (opts.timeWindow) {
+      throw new Error('Cannot combine --time-window with --start/--end. Pick one.');
+    }
+    for (const [flag, value] of [['--start', opts.start], ['--end', opts.end]]) {
+      if (!DATE_RE.test(value)) {
+        throw new Error(`Invalid ${flag} "${value}". Expected YYYY-MM-DD.`);
+      }
+    }
+    const start = new Date(`${opts.start}T00:00:00Z`);
+    const end = new Date(`${opts.end}T00:00:00Z`);
+    // Round-tripped, not just checked for NaN: Date rolls an impossible day
+    // into the next month, so 2026-02-30 parses happily as March 2.
+    const isRealDate = (value, parsed) =>
+      !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+    if (!isRealDate(opts.start, start) || !isRealDate(opts.end, end)) {
+      throw new Error('--start and --end must be real calendar dates (YYYY-MM-DD).');
+    }
+    if (start > end) {
+      throw new Error('--start must be on or before --end.');
+    }
+    const spanDays = Math.round((end - start) / 86400000);
+    if (spanDays > MAX_RANGE_DAYS) {
+      throw new Error(`Date range is ${spanDays} days; the maximum is ${MAX_RANGE_DAYS}.`);
+    }
+    return { start_date: opts.start, end_date: opts.end };
+  }
+
+  const timeWindow = (opts.timeWindow || DEFAULT_TIME_WINDOW).toUpperCase().replace(/-/g, '_');
+  if (!TIME_WINDOWS.includes(timeWindow)) {
+    throw new Error(
+      `Invalid --time-window "${opts.timeWindow}". Must be one of: ${TIME_WINDOWS.join(', ')}.`
+    );
+  }
+  return { time_window: timeWindow };
+}
+
+function resolveLimit(opts, format = 'json') {
+  if (opts.limit === undefined) return DEFAULT_LIMIT;
+  const limit = Number(opts.limit);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error(`Invalid --limit "${opts.limit}". Must be a positive integer.`);
+  }
+  const max = format === 'table' ? MAX_TABLE_LIMIT : MAX_LIMIT;
+  if (limit > max) {
+    throw new Error(
+      `--limit cannot exceed ${max} for ${format} output. ` +
+      (format === 'table'
+        ? `Use --format json for up to ${MAX_LIMIT}, or --format csv to export everything.`
+        : 'Use --format csv to export everything.')
+    );
+  }
+  return limit;
+}
+
+function resolveOffset(opts) {
+  if (opts.offset === undefined) return 0;
+  const offset = Number(opts.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error(`Invalid --offset "${opts.offset}". Must be zero or a positive integer.`);
+  }
+  return offset;
+}
+
+function resolveRiskLevels(opts) {
+  const wanted = parseList(opts.risk);
+  return wanted.map((raw) => {
+    const match = RISK_LEVELS.find((level) => level.toLowerCase() === raw.toLowerCase());
+    if (!match) {
+      throw new Error(`Invalid --risk "${raw}". Must be one of: ${RISK_LEVELS.join(', ')}.`);
+    }
+    return match;
+  });
+}
+
+function resolveInitiators(opts) {
+  const wanted = parseList(opts.initiator);
+  return wanted.map((raw) => {
+    const mapped = INITIATORS[raw.toLowerCase()];
+    if (!mapped) {
+      throw new Error(
+        `Invalid --initiator "${raw}". Must be one of: ${Object.keys(INITIATORS).join(', ')}.`
+      );
+    }
+    return mapped;
+  });
+}
+
+/**
+ * Turn parsed commander options into the export endpoint's query object.
+ * Repeated keys are represented as arrays; buildQueryString expands them.
+ */
+function buildQuery(opts, { format, extra = {} } = {}) {
+  const query = {
+    format: format === 'table' ? 'json' : format,
+    ...resolveWindow(opts),
+    ...extra,
+  };
+
+  if (query.format === 'json') {
+    // `format` is the caller's intent; query.format is what the server speaks,
+    // and the table asks the server for json. The cap follows the intent.
+    query.limit = resolveLimit(opts, format);
+    const offset = resolveOffset(opts);
+    if (offset) query.offset = offset;
+  }
+
+  const lists = {
+    tool_types: parseList(opts.tool).map((t) => t.toUpperCase().replace(/-/g, '_')),
+    user_ids: parseList(opts.user),
+    policy_ids: parseList(opts.policy),
+    command_families: parseList(opts.family),
+    server: parseList(opts.server),
+    risk_levels: resolveRiskLevels(opts),
+    intent_attribution: resolveInitiators(opts),
+  };
+
+  for (const [key, values] of Object.entries(lists)) {
+    if (values.length) query[key] = values;
+  }
+
+  return query;
+}
+
+function buildQueryString(query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  return params.toString();
+}
+
+module.exports = {
+  DEFAULT_LIMIT,
+  DEFAULT_TIME_WINDOW,
+  FORMATS,
+  INITIATORS,
+  MAX_LIMIT,
+  MAX_TABLE_LIMIT,
+  MAX_RANGE_DAYS,
+  RISK_LEVELS,
+  TIME_WINDOWS,
+  buildQuery,
+  buildQueryString,
+  parseList,
+  resolveFormat,
+  resolveLimit,
+  resolveOffset,
+  resolveWindow,
+};

package/src/lib/downloads.js

@@ -0,0 +1,343 @@
+/**
+ * The generated-download job flow: start, poll, fetch.
+ *
+ * A CSV export is prepared by a background worker and served from object
+ * storage, so every caller does the same three steps. They live here so
+ * `unbound download` and `analytics tool-use --format csv` cannot drift apart.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const api = require('../api');
+const output = require('../output');
+
+const DOWNLOADS_PATH = '/api/v1/downloads';
+const MAX_EXPORT_ROWS = 25000;
+
+const POLL_INTERVAL_MS = 2000;
+// The worker's own soft limit is 30 minutes. Waiting slightly past it means a
+// job that dies at that limit surfaces as its own failure rather than as ours.
+const MAX_WAIT_MS = 1_860_000;
+// How long a finished export stays fetchable, matching the server's retention.
+const RETENTION_HOURS = 6;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The download kinds the server offers, for help text and tab-completion.
+ *
+ * Advisory only — an unlisted kind is still sent through, so a producer added
+ * to the backend is usable without waiting for a CLI release. The server is the
+ * authority on what exists and answers 400 for anything it does not know.
+ */
+const KINDS = {
+  'logs-export': {
+    summary: 'Every LLM call: prompt, model, tokens, status, user and task ID.',
+    filters: ['model_ids', 'application_ids', 'status_codes', 'application_owner_email',
+      'application_types', 'tool_types'],
+  },
+  'logs-tasks-export': {
+    summary: 'One row per task (agent session), with its thread ID.',
+    filters: ['model_ids', 'tool_types', 'application_owner_email', 'user_ids'],
+  },
+  'analytics-export': {
+    summary: 'Tool Use rows. Needs dataset=terminal-runs|mcp-actions|unsanctioned|mcp-servers.',
+    filters: ['dataset', 'risk_levels', 'command_families', 'server', 'intent_attribution',
+      'policy_ids', 'tool_types', 'user_ids'],
+  },
+  'analytics-tasks-export': {
+    summary: 'Analytics > Tasks, optionally narrowed to one heatmap day.',
+    filters: ['user_ids', 'tool_types', 'date', 'tz'],
+  },
+  'users-export': {
+    summary: 'Analytics > Users: per-user cost, tokens and activity.',
+    filters: ['user_ids', 'sort_field', 'sort_order'],
+  },
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function fetchHint(jobId) {
+  return `Fetch it within ${RETENTION_HOURS} hours:\n    unbound download get ${jobId}`;
+}
+
+function isJobId(value) {
+  return UUID_RE.test(String(value || '').trim());
+}
+
+// The server names the file, but it must not be able to choose where the file
+// lands. Keep the basename only, so "../../.zshrc" cannot escape the cwd.
+function safeFilename(name, fallback) {
+  const base = path.basename(String(name || '').trim());
+  return base && base !== '.' && base !== '..' ? base : fallback;
+}
+
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}
+
+// Counting rows happens synchronously inside both calls below, and on a wide
+// window it measured ~4s against production. The 30s default left too little
+// headroom, so an export that was merely slow to admit failed as a timeout.
+const ADMISSION_TIMEOUT_MS = 120000;
+
+/** Ask how many rows a selection holds, without starting anything. */
+function checkCount(kind, queryString) {
+  return api.get(`${DOWNLOADS_PATH}/${kind}/count/${queryString ? `?${queryString}` : ''}`,
+    { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+/** Start a job. Resolves the job row; the file does not exist yet. */
+function startJob(kind, queryString) {
+  return api.post(`${DOWNLOADS_PATH}/${kind}/${queryString ? `?${queryString}` : ''}`,
+    { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+/**
+ * Start a job at a producer's own endpoint rather than the generic one.
+ *
+ * The analytics export lives behind its own path but enqueues the same job, and
+ * its admission runs the same synchronous count — so it needs the same timeout.
+ */
+function startExportAt(path) {
+  return api.post(path, { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+function getJob(jobId) {
+  return api.get(`${DOWNLOADS_PATH}/${jobId}/`);
+}
+
+/**
+ * Poll a job until it stops being queued or running.
+ *
+ * The interrupt handler is registered before the spinner's, which exits the
+ * process on its own SIGINT — registering after would mean never printing the
+ * job id, and an unreachable export is the whole reason `download get` exists.
+ */
+async function waitForJob(jobId, title) {
+  // A caller with no dataset to name degrades the label to just "export".
+  const label = title ? `${title} export` : 'export';
+  let spin = null;
+  const onInterrupt = () => {
+    if (spin) spin.stop();
+    output.info(`The ${label} is still being prepared. ${fetchHint(jobId)}`);
+    process.exit(130);
+  };
+  process.on('SIGINT', onInterrupt);
+  // Printed before the wait, not only on interrupt: a hard kill (a script's
+  // timeout, a closed terminal) never runs the handler, and without the id the
+  // finished file is unreachable for its whole retention window.
+  output.info(`Export ${jobId} started.`);
+  spin = output.spinner(`Preparing ${label}…`);
+
+  try {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    for (;;) {
+      const job = await getJob(jobId);
+
+      if (job.status === 'completed') {
+        spin.stop();
+        return job;
+      }
+      if (job.status === 'failed') {
+        throw new Error(job.error || 'The export failed while it was being prepared.');
+      }
+      if (job.status === 'expired') {
+        throw new Error(`This export has expired. Exports are kept for ${RETENTION_HOURS} hours.`);
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `The ${label} is taking longer than expected and is still running.\n  ${fetchHint(jobId)}`
+        );
+      }
+
+      const rows = Number(job.row_count) || 0;
+      spin.update(rows > 0 ? `Preparing ${label}… ${rows.toLocaleString()} rows` : `Preparing ${label}…`);
+      await sleep(POLL_INTERVAL_MS);
+    }
+  } catch (err) {
+    spin.stop();
+    throw err;
+  } finally {
+    process.removeListener('SIGINT', onInterrupt);
+  }
+}
+
+/**
+ * Sign a URL for a finished job and stream it to disk or stdout.
+ *
+ * The presigned URL is a bearer capability for as long as it lives, so it is
+ * never printed, logged, or written anywhere — only piped straight through.
+ */
+/**
+ * Move the finished download onto its final path.
+ *
+ * A server-chosen name is linked rather than renamed. rename() replaces
+ * silently, and the whole transfer sits between the existence check and this
+ * point, so anything created in the meantime would be overwritten. link() fails
+ * with EEXIST instead, which is the guarantee this is supposed to make.
+ *
+ * An explicit -o is the user naming the file, so there rename is correct.
+ */
+function placeFile(partial, target, { replace, name }) {
+  if (replace) {
+    fs.renameSync(partial, target);
+    return;
+  }
+  try {
+    fs.linkSync(partial, target);
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      throw new Error(
+        `${name} already exists here. Pass -o <file> to choose where this export goes.`
+      );
+    }
+    throw err;
+  }
+  fs.unlinkSync(partial);
+}
+
+async function downloadJob(job, destinationPath, title) {
+  const { url, filename } = await api.get(`${DOWNLOADS_PATH}/${job.id}/url/`);
+  const name = safeFilename(filename || job.filename, `unbound-export-${job.id}.csv`);
+  const destination = destinationPath || (process.stdout.isTTY ? name : null);
+
+  // The server picks this name, so it must not land on top of anything: a
+  // backend could otherwise drop a file called `.zshrc` into whatever directory
+  // the command ran in. Checked up front only to fail before a long download;
+  // placeFile is what actually enforces it. An explicit -o is the user's own
+  // choice and may replace a file, but only once the download has succeeded.
+  if (destination && !destinationPath && fs.existsSync(path.resolve(destination))) {
+    throw new Error(
+      `${name} already exists here. Pass -o <file> to choose where this export goes.`
+    );
+  }
+
+  let target = null;
+  let partial = null;
+  try {
+    const { bytes } = await api.fetchToStream(url, {
+      onHeaders: () => {
+        if (!destination) return process.stdout;
+        target = path.resolve(destination);
+        // Written to a sibling temp file and renamed on success. Streaming
+        // straight to `target` would truncate an existing file the moment the
+        // stream opened, so a transfer that failed halfway would destroy it.
+        // 'wx' fails rather than following a symlink or reusing a leftover.
+        partial = `${target}.part-${process.pid}`;
+        return fs.createWriteStream(partial, { flags: 'wx', mode: 0o600 });
+      },
+    });
+
+    if (target) {
+      placeFile(partial, target, { replace: Boolean(destinationPath), name });
+      partial = null;
+      const rows = Number(job.row_count) || 0;
+      const what = title ? `${title} row(s)` : 'row(s)';
+      output.success(`Exported ${rows.toLocaleString()} ${what} to ${target} (${formatBytes(bytes)})`);
+    }
+    return target;
+  } catch (err) {
+    // A half-written export parses as valid CSV and reads as a complete one, so
+    // drop it. Only ever the temp file — the user's own file is untouched.
+    if (partial) {
+      try {
+        fs.unlinkSync(partial);
+      } catch {
+        // Nothing was written, or it is already gone.
+      }
+    }
+    throw err;
+  }
+}
+
+/** Start, wait, and save in one call. */
+async function runExport(kind, queryString, { output: destination, title } = {}) {
+  const job = await startJob(kind, queryString);
+  const finished = await waitForJob(job.id, title);
+  await downloadJob(finished, destination, title);
+  return finished;
+}
+
+/** Fetch an already-started job, waiting first if it is still running. */
+async function fetchExisting(jobId, { output: destination, title } = {}) {
+  if (!isJobId(jobId)) {
+    throw new Error(`"${jobId}" is not a valid export id. It looks like 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6.`);
+  }
+  const job = await getJob(jobId);
+
+  if (job.status === 'failed') {
+    throw new Error(job.error || 'This export failed while it was being prepared.');
+  }
+  if (job.status === 'expired') {
+    throw new Error(`This export has expired. Exports are kept for ${RETENTION_HOURS} hours.`);
+  }
+  const ready = job.status === 'completed' ? job : await waitForJob(jobId, title);
+  await downloadJob(ready, destination, title);
+  return ready;
+}
+
+/**
+ * Turn a server refusal into something a human or an agent can act on.
+ *
+ * `byJobId` changes what a 404 means: looking up a job that does not exist, has
+ * been swept, or belongs to another organization is indistinguishable by
+ * design, and none of those are "the backend is too old".
+ */
+function describeError(err, what = 'export', { byJobId = false, listing = false } = {}) {
+  if (err instanceof api.ApiError) {
+    if (err.statusCode === 404) {
+      if (byJobId) {
+        return `No export with that ID. It may have expired — exports are kept for ${RETENTION_HOURS} hours.`;
+      }
+      // Reading a table and preparing a file fail for different reasons, and
+      // telling someone their backend lacks background exports when they only
+      // asked to list rows sends them after the wrong thing.
+      return listing
+        ? `This Unbound backend does not serve ${what} yet.`
+        : `This Unbound backend does not serve the ${what} yet. ` +
+          'It needs a backend version that includes background CSV exports.';
+    }
+    if (err.statusCode === 405) {
+      return `This Unbound backend is too old for this CLI: it still streams the ${what} ` +
+        'instead of preparing it in the background. Upgrade the backend, or pin the CLI to 1.14.0.';
+    }
+    if (err.statusCode === 403) {
+      return listing
+        ? 'Admin role required. Analytics > Tool Use is restricted to organization admins.'
+        : 'Admin role required. Exporting data is restricted to organization admins.';
+    }
+    if (err.statusCode === 422) {
+      const rows = Number(err.body?.row_count);
+      const limit = Number(err.body?.limit) || MAX_EXPORT_ROWS;
+      if (Number.isFinite(rows) && rows > 0) {
+        return `This selection holds ${rows.toLocaleString()} rows, over the ${limit.toLocaleString()}-row export limit. ` +
+          'Narrow the date range or add filters.';
+      }
+    }
+  }
+  return err.message;
+}
+
+module.exports = {
+  DOWNLOADS_PATH,
+  KINDS,
+  MAX_EXPORT_ROWS,
+  RETENTION_HOURS,
+  checkCount,
+  describeError,
+  downloadJob,
+  fetchExisting,
+  fetchHint,
+  formatBytes,
+  getJob,
+  isJobId,
+  placeFile,
+  runExport,
+  safeFilename,
+  startExportAt,
+  startJob,
+  waitForJob,
+};

package/src/output.js

@@ -1,3 +1,5 @@
+const { sanitizeForTerminal } = require('./chartRender');
+
 /**
  * Output formatting utilities for the Unbound CLI.
  * Provides table, JSON, and key-value output for terminal display.
@@ -49,6 +51,70 @@ function table(rows, columns) {
   }
 }
 
+const MIN_COLUMN_WIDTH = 6;
+
+function clip(value, width) {
+  // Sanitize before measuring: these cells carry commands and prompts recorded
+  // from agents, so an OSC or CSI sequence in one would otherwise reach the
+  // terminal and could rewrite the title, the clipboard, or earlier output.
+  const text = sanitizeForTerminal(value).replace(/\s+/g, ' ').trim();
+  if (text.length <= width) return text;
+  if (width <= 1) return text.slice(0, width);
+  return `${text.slice(0, width - 1)}…`;
+}
+
+/**
+ * Render log rows as a table that fits the terminal.
+ *
+ * Unlike table(), every cell is collapsed to one line and clipped to a share of
+ * the available width, so a 4KB prompt or a long command cannot flood the
+ * screen. Pass { wide: true } to print values in full.
+ *
+ * @param {string[]} headers
+ * @param {Array<string[]>} rows - cells aligned to headers
+ * @param {{wide?: boolean, maxWidth?: number}} [opts]
+ */
+function logTable(headers, rows, opts = {}) {
+  if (!rows || rows.length === 0) {
+    console.log(c.dim('No results found.'));
+    return;
+  }
+
+  const natural = headers.map((header, i) =>
+    Math.max(String(header).length, ...rows.map((row) => clip(row[i], Number.POSITIVE_INFINITY).length))
+  );
+
+  let widths = natural;
+  if (!opts.wide) {
+    // process.stdout.columns is undefined when piped, so fall back to the
+    // COLUMNS convention before the default.
+    const envColumns = Number.parseInt(process.env.COLUMNS, 10);
+    const terminalWidth =
+      opts.maxWidth || process.stdout.columns || (Number.isInteger(envColumns) && envColumns > 0 ? envColumns : 120);
+    const gutters = 2 * (headers.length - 1);
+    const budget = Math.max(terminalWidth - gutters, headers.length * MIN_COLUMN_WIDTH);
+    const total = natural.reduce((a, b) => a + b, 0);
+
+    if (total > budget) {
+      // Give every column its minimum first, then share what's left in
+      // proportion to how much each column actually wants.
+      const spare = Math.max(budget - headers.length * MIN_COLUMN_WIDTH, 0);
+      const over = natural.map((w) => Math.max(w - MIN_COLUMN_WIDTH, 0));
+      const overTotal = over.reduce((a, b) => a + b, 0) || 1;
+      widths = natural.map((w, i) =>
+        Math.min(w, MIN_COLUMN_WIDTH + Math.floor((over[i] / overTotal) * spare))
+      );
+    }
+  }
+
+  const line = (cells) =>
+    cells.map((cell, i) => clip(cell, widths[i]).padEnd(widths[i])).join('  ').trimEnd();
+
+  console.log(headers.map((h, i) => c.bold(c.dim(clip(h, widths[i]).padEnd(widths[i])))).join('  ').trimEnd());
+  console.log(widths.map((w) => '─'.repeat(w)).join('  '));
+  for (const row of rows) console.log(line(row));
+}
+
 function json(data) {
   console.log(JSON.stringify(data, null, 2));
 }
@@ -80,13 +146,18 @@ function info(msg) {
 function spinner(message) {
   if (!process.stderr.isTTY) {
     console.error(message);
-    return { stop: () => {}, succeed: (msg) => success(msg), fail: (msg) => error(msg) };
+    // update() stays silent when piped: a progress line reprinted every poll
+    // would bury the real output in a log.
+    return { stop: () => {}, update: () => {}, succeed: (msg) => success(msg), fail: (msg) => error(msg) };
   }
 
   const frames = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2827', '\u2807', '\u280F'];
   let i = 0;
+  let text = message;
   const interval = setInterval(() => {
-    process.stderr.write(`\r${c.cyan(frames[i++ % frames.length])} ${message}`);
+    // Clear to end of line first: a shorter message must not leave the tail of
+    // a longer one behind.
+    process.stderr.write(`\r\x1b[K${c.cyan(frames[i++ % frames.length])} ${text}`);
   }, 80);
 
   function clear() {
@@ -99,6 +170,7 @@ function spinner(message) {
 
   return {
     stop: clear,
+    update(msg) { text = msg; },
     succeed(msg) { clear(); success(msg); },
     fail(msg) { clear(); error(msg); },
   };
@@ -349,4 +421,4 @@ function multiSelect(message, options) {
   });
 }
 
-module.exports = { table, json, keyValue, success, error, warn, info, spinner, select, multiSelect, colors: c };
+module.exports = { table, logTable, json, keyValue, success, error, warn, info, spinner, select, multiSelect, colors: c };