@thinremote/thinr-cli 1.2.0-alpha.1 → 1.3.0

package/commands/device/logs.js

@@ -0,0 +1,178 @@
+// @ts-check
+import { createDeviceAPI } from '../../lib/device-api.js';
+import { getDevice } from '../../lib/devices.js';
+import { getProductLogs } from '../../lib/product/logs.js';
+import { inputError } from '../../lib/errors.js';
+import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { error as errorStyle, muted, warning } from '../../lib/format.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+
+// Single-quote for /bin/sh: wrap in '…' and escape embedded single quotes.
+function shq(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function buildCommand({ follow, tail, unit, since, path }) {
+    const n = Number.isFinite(tail) && tail >= 0 ? tail : 100;
+    if (path) {
+        const follower = follow ? '-F' : '';
+        return `tail -n ${n} ${follower} -- ${shq(path)}`.trim();
+    }
+    const parts = ['journalctl', '--no-pager', '--output=short', `-n ${n}`];
+    if (follow) parts.push('-f');
+    if (unit) parts.push(`-u ${shq(unit)}`);
+    if (since) parts.push(`--since ${shq(since)}`);
+    return parts.join(' ');
+}
+
+/**
+ * Resolve the command to stream when --source is in play. Looks up the
+ * device's product, reads its logs config (with the synthetic fallback
+ * when the property is unset), and picks either the requested source
+ * or the default. Returns `{ command, source, fallback }` so the
+ * caller can surface what it picked.
+ */
+async function resolveProductSource({ deviceId, sourceName, user }) {
+    const device = await getDevice(deviceId, user);
+    const productId = device?.product;
+    if (!productId) {
+        throw inputError(
+            `Device "${deviceId}" is not bound to a product — --source needs a product to look up the log source on.`,
+        );
+    }
+    const cfg = await getProductLogs(productId, user);
+    const fallback = !!(/** @type {any} */ (cfg).__fallback);
+    const picked = sourceName
+        ? cfg.sources.find((s) => s.name === sourceName)
+        : cfg.sources.find((s) => s.name === cfg.default) || cfg.sources[0];
+    if (!picked) {
+        const available = cfg.sources.map((s) => s.name).join(', ') || '(none)';
+        const err = /** @type {Error & { code?: string }} */ (
+            new Error(
+                sourceName
+                    ? `Source "${sourceName}" is not configured on product "${productId}". Available: ${available}`
+                    : `No log sources configured on product "${productId}".`,
+            )
+        );
+        err.code = 'not_found';
+        throw err;
+    }
+    return { command: picked.command, source: picked.name, product: productId, fallback };
+}
+
+export function registerLogsCommand(device) {
+    device
+        .command('logs <deviceId>')
+        .helpGroup('Observability:')
+        .description('Stream or tail device logs (journalctl by default, or a file path)')
+        .option('-f, --follow', 'Keep streaming until interrupted (Ctrl+C)')
+        .option('-n, --tail <n>', 'Number of initial lines to show', (v) => parseInt(v, 10), 100)
+        .option('--unit <name>', 'Filter by systemd unit (journalctl only)')
+        .option('--since <when>', 'Show entries since a time expression (journalctl only)')
+        .option('--path <file>', 'Follow a file instead of journalctl')
+        .option(
+            '--source [name]',
+            'Stream a log source configured on the device\'s product (omit name to use the default)',
+        )
+        .option('-j, --json', 'Buffer output and emit a single JSON envelope (not allowed with --follow)')
+        .action(async (deviceId, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+
+            if (opts.follow && opts.json) {
+                printErr('--json and --follow cannot be combined', { code: 'invalid_args', exitCode: 2 });
+            }
+            if (opts.path && (opts.unit || opts.since)) {
+                printErr('--unit and --since only apply to journalctl mode', { code: 'invalid_args', exitCode: 2 });
+            }
+            if (opts.source !== undefined && (opts.path || opts.unit || opts.since)) {
+                printErr(
+                    '--source is mutually exclusive with --path, --unit and --since (the source command is sent verbatim)',
+                    { code: 'invalid_args', exitCode: 2 },
+                );
+            }
+
+            const user = getGlobalUser(cmd);
+            let commandStr;
+            if (opts.source !== undefined) {
+                const sourceName = typeof opts.source === 'string' ? opts.source : null;
+                let resolved;
+                try {
+                    resolved = await resolveProductSource({
+                        deviceId,
+                        sourceName,
+                        user,
+                    });
+                } catch (err) {
+                    const { message, code } = classifyError(err);
+                    printErr(message, { code });
+                    return;
+                }
+                commandStr = resolved.command;
+                if (!isJsonMode()) {
+                    const tag = resolved.fallback ? ' (fallback)' : '';
+                    process.stderr.write(
+                        muted(`[source: ${resolved.source} on ${resolved.product}${tag}]\n`),
+                    );
+                }
+            } else {
+                commandStr = buildCommand({
+                    follow: !!opts.follow,
+                    tail: opts.tail,
+                    unit: opts.unit,
+                    since: opts.since,
+                    path: opts.path,
+                });
+            }
+
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                if (isJsonMode()) {
+                    let stdout = '';
+                    let stderr = '';
+                    const { exitCode, timedOut, cancelled } = await api.execStream(commandStr, {
+                        onStdout: (s) => {
+                            stdout += s;
+                        },
+                        onStderr: (s) => {
+                            stderr += s;
+                        },
+                    });
+                    if (cancelled) printErr('Interrupted', { code: 'cancelled', exitCode: 130 });
+                    if (timedOut) printErr('Command timed out on the device', { code: 'timeout' });
+                    printOk({ command: commandStr, stdout, stderr, exitCode: exitCode ?? null });
+                    process.exit(exitCode ?? 1);
+                }
+                let cancelFn = null;
+                const onSigint = () => cancelFn?.();
+                process.on('SIGINT', onSigint);
+                const { exitCode, timedOut, cancelled } = await api.execStream(commandStr, {
+                    onStdout: (s) => process.stdout.write(s),
+                    onStderr: (s) => process.stderr.write(s),
+                    onCancel: (fn) => {
+                        cancelFn = fn;
+                    },
+                });
+                process.off('SIGINT', onSigint);
+                if (timedOut) {
+                    console.error(errorStyle('\nError: log stream timed out on the device.'));
+                }
+                if (cancelled) {
+                    // Follow mode always ends via Ctrl+C — suppress the
+                    // noisy [interrupted] banner in that case.
+                    if (!opts.follow) console.error(warning('\n[interrupted]'));
+                    process.exit(130);
+                }
+                process.exit(exitCode ?? 0);
+            } catch (error) {
+                const { message, code } = classifyError(error);
+                if (isJsonMode()) printErr(message, { code });
+                console.error(errorStyle(`Error [${code}]: ${message}`));
+                if (error.response) {
+                    console.error(errorStyle(`Status: ${error.response.status}`));
+                    console.error(errorStyle(`Body: ${JSON.stringify(error.response.data)}`));
+                }
+                process.exit(1);
+            }
+        });
+}

package/commands/device/property.js

@@ -5,12 +5,18 @@ import {
     getDeviceProperties,
     formatDeviceProperties,
 } from '../../lib/property.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, ensureConfigured } from './_shared.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    extractField,
+    runDeviceCommand,
+} from './_shared.js';
 
 export function registerPropertyCommand(device) {
     device
         .command('property <deviceId> [propertyId]')
+        .helpGroup('State & resources:')
         .description('List device properties, or read one by ID')
         .option('-j, --json', 'Output as JSON')
         .option('-f, --field <field>', 'Extract a sub-field (dot path, e.g. data.value)')
@@ -18,33 +24,29 @@ export function registerPropertyCommand(device) {
             applyJsonFlag(opts);
             ensureConfigured();
             if (!propertyId) {
-                const spinner = createSpinner(`Getting properties for ${deviceId}...`).start();
-                try {
-                    const result = await getDeviceProperties(deviceId);
-                    spinner.succeed(`Properties for ${deviceId} retrieved successfully`);
-                    if (isJsonMode()) printOk(result);
-                    else console.log(formatDeviceProperties(deviceId, result));
-                } catch (error) {
-                    spinner.fail('Property retrieval failed');
-                    const { message, code } = classifyError(error);
-                    printErr(message, { code });
-                }
+                await runDeviceCommand({
+                    start: `Getting properties for ${deviceId}...`,
+                    fn: () => getDeviceProperties(deviceId),
+                    success: `Properties for ${deviceId} retrieved successfully`,
+                    failure: 'Property retrieval failed',
+                    onSuccess: (result) => {
+                        if (isJsonMode()) printOk(result);
+                        else console.log(formatDeviceProperties(deviceId, result));
+                    },
+                });
                 return;
             }
-            const spinner = createSpinner(`Retrieving property for ${deviceId}...`).start();
-            try {
-                const property = await getDeviceProperty(deviceId, propertyId);
-                spinner.succeed(`Property ${propertyId} for ${deviceId} found`);
-                const value = opts.field
-                    ? opts.field.split('.').reduce((obj, key) => obj && obj[key], property)
-                    : property;
-                if (isJsonMode()) printOk(value);
-                else if (opts.field) console.log(value);
-                else console.log(formatDeviceProperty(deviceId, propertyId, property));
-            } catch (error) {
-                spinner.fail('Property retrieval failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Retrieving property for ${deviceId}...`,
+                fn: () => getDeviceProperty(deviceId, propertyId),
+                success: `Property ${propertyId} for ${deviceId} found`,
+                failure: 'Property retrieval failed',
+                onSuccess: (property) => {
+                    const value = extractField(property, opts.field);
+                    if (isJsonMode()) printOk(value);
+                    else if (opts.field) console.log(value);
+                    else console.log(formatDeviceProperty(deviceId, propertyId, property));
+                },
+            });
         });
 }

package/commands/device/proxy.js

@@ -5,6 +5,7 @@ import { ensureConfigured, runInteractive } from './_shared.js';
 export function registerProxyCommands(device) {
     device
         .command('tcp <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create a TCP proxy (no TLS). Default target: 22.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .action((deviceId, target, opts) =>
@@ -16,6 +17,7 @@ export function registerProxyCommands(device) {
 
     device
         .command('tls <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create a TLS proxy. Default target: 443.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .action((deviceId, target, opts) =>
@@ -27,6 +29,7 @@ export function registerProxyCommands(device) {
 
     device
         .command('http <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create an HTTP proxy. Default target: 80.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .option('--no-open', 'Do not open the browser')

package/commands/device/resource.js

@@ -4,12 +4,19 @@ import {
     listDeviceResourcesWithSchemas,
     formatDeviceResourcesWithSchemas,
 } from '../../lib/resource.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, collectInput, ensureConfigured } from './_shared.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    collectInput,
+    ensureConfigured,
+    extractField,
+    runDeviceCommand,
+} from './_shared.js';
 
 export function registerResourceCommand(device) {
     device
         .command('resource <deviceId> [resource]')
+        .helpGroup('State & resources:')
         .description('List device resources, or call one by name')
         .option('-j, --json', 'Output as JSON')
         .option('-f, --field <field>', 'Extract a sub-field from the result (dot path)')
@@ -18,34 +25,28 @@ export function registerResourceCommand(device) {
             applyJsonFlag(opts);
             ensureConfigured();
             if (!resource) {
-                const spinner = createSpinner(`Getting resources for ${deviceId}...`).start();
-                try {
-                    const entries = await listDeviceResourcesWithSchemas(deviceId);
-                    spinner.succeed(`Successfully retrieved resources for ${deviceId}`);
-                    if (isJsonMode()) printOk(entries);
-                    else console.log(formatDeviceResourcesWithSchemas(deviceId, entries));
-                } catch (error) {
-                    spinner.fail('Resource retrieval failed');
-                    const { message, code } = classifyError(error);
-                    printErr(message, { code });
-                }
+                await runDeviceCommand({
+                    start: `Getting resources for ${deviceId}...`,
+                    fn: () => listDeviceResourcesWithSchemas(deviceId),
+                    success: `Successfully retrieved resources for ${deviceId}`,
+                    failure: 'Resource retrieval failed',
+                    onSuccess: (entries) => {
+                        if (isJsonMode()) printOk(entries);
+                        else console.log(formatDeviceResourcesWithSchemas(deviceId, entries));
+                    },
+                });
                 return;
             }
-            const spinner = createSpinner(
-                `Calling resource ${resource} for ${deviceId}...`,
-            ).start();
-            try {
-                const result = await callDeviceResource(deviceId, resource, opts.input);
-                spinner.succeed(`Resource ${resource} returned successfully for ${deviceId}`);
-                const value = opts.field
-                    ? opts.field.split('.').reduce((obj, key) => obj && obj[key], result)
-                    : result;
-                if (isJsonMode()) printOk(value);
-                else console.log(value);
-            } catch (error) {
-                spinner.fail('Resource call failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Calling resource ${resource} for ${deviceId}...`,
+                fn: () => callDeviceResource(deviceId, resource, opts.input),
+                success: `Resource ${resource} returned successfully for ${deviceId}`,
+                failure: 'Resource call failed',
+                onSuccess: (result) => {
+                    const value = extractField(result, opts.field);
+                    if (isJsonMode()) printOk(value);
+                    else console.log(value);
+                },
+            });
         });
 }

package/commands/device/status.js

@@ -1,26 +1,47 @@
 // @ts-check
 import { getDeviceStatus, formatDeviceStatus } from '../../lib/status.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, ensureConfigured } from './_shared.js';
+import { getMonitoringData } from '../../lib/monitoring.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import { applyJsonFlag, ensureConfigured, runDeviceCommand } from './_shared.js';
 
 export function registerStatusCommand(device) {
     device
         .command('status <deviceId>')
-        .description('Check device status and stats')
+        .helpGroup('Discovery:')
+        .description('Check device status, data transfer and the latest monitoring sample')
         .option('-j, --json', 'Output as JSON')
         .action(async (deviceId, opts) => {
             applyJsonFlag(opts);
             ensureConfigured();
-            const spinner = createSpinner(`Checking status of ${deviceId}...`).start();
-            try {
-                const status = await getDeviceStatus(deviceId);
-                spinner.succeed(`Device ${deviceId} found`);
-                if (isJsonMode()) printOk(status);
-                else console.log(formatDeviceStatus(deviceId, status));
-            } catch (error) {
-                spinner.fail('Status check failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Checking status of ${deviceId}...`,
+                // Fetch the server-side stats and the latest monitoring sample
+                // in parallel — the monitoring call is best-effort, we still
+                // render the stats section if the bucket query fails or the
+                // device never published.
+                fn: async () => {
+                    const [statusResult, monitoringResult] = await Promise.allSettled([
+                        getDeviceStatus(deviceId),
+                        getMonitoringData({ device: deviceId, items: 1, sort: 'desc' }),
+                    ]);
+                    if (statusResult.status === 'rejected') throw statusResult.reason;
+                    const monitoring =
+                        monitoringResult.status === 'fulfilled' &&
+                        Array.isArray(monitoringResult.value) &&
+                        monitoringResult.value.length > 0
+                            ? monitoringResult.value[0]
+                            : null;
+                    return { status: statusResult.value, monitoring };
+                },
+                // Skip the success banner: the detail block below speaks
+                // for the "found" state and the failure path prints its
+                // own clear error.
+                success: null,
+                failure: 'Status check failed',
+                onSuccess: ({ status, monitoring }) => {
+                    if (isJsonMode()) printOk({ ...status, monitoring });
+                    else console.log(formatDeviceStatus(deviceId, status, monitoring));
+                },
+            });
         });
 }

package/commands/device/transfer.js

@@ -0,0 +1,236 @@
+// @ts-check
+import { readFile as readLocalFile, writeFile as writeLocalFile, stat as statLocal } from 'fs/promises';
+import { createReadStream } from 'fs';
+import { Transform } from 'node:stream';
+import { basename } from 'path';
+import cliProgress from 'cli-progress';
+import { createDeviceAPI } from '../../lib/device-api.js';
+import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { success, hint, formatBytes, formatETA } from '../../lib/format.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+
+/**
+ * Build a single-line progress bar for a byte-counted transfer.
+ * Disabled when stdout isn't a TTY or when the caller asked for JSON
+ * output — in both cases the caller resorts to a simpler log line.
+ */
+function makeTransferBar(totalBytes) {
+    // cli-progress counts characters literally when sizing the line,
+    // so ANSI escape codes inside barChars / placeholders would make
+    // the whole thing truncate. Keep the bar and its columns plain;
+    // the theme lives on the surrounding "Uploading" / "Uploaded"
+    // lines instead.
+    const sizeW = 9;
+    const rateW = 12;
+    const etaW = 11;
+    const bar = new cliProgress.SingleBar({
+        // `{eta}` is reserved by cli-progress (plain seconds, no label);
+        // use a different placeholder name so our "ETA 12s" string
+        // actually shows up instead of being silently overridden.
+        format: `  {bar} {percentage}%  {transferred}/{total_human}  {rate}  {countdown}`,
+        barCompleteChar: '█',
+        barIncompleteChar: '░',
+        barsize: 24,
+        hideCursor: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    });
+    const startedAt = Date.now();
+    bar.start(totalBytes, 0, {
+        transferred: formatBytes(0).padStart(sizeW),
+        total_human: formatBytes(totalBytes).padEnd(sizeW),
+        rate: '—'.padStart(rateW),
+        countdown: 'ETA —'.padEnd(etaW),
+    });
+    const onProgress = (ev) => {
+        const loaded = ev?.loaded ?? 0;
+        const elapsed = (Date.now() - startedAt) / 1000;
+        const rate = elapsed > 0 ? loaded / elapsed : 0;
+        const remaining = Math.max(0, totalBytes - loaded);
+        const etaSeconds = rate > 0 ? remaining / rate : Infinity;
+        bar.update(loaded, {
+            transferred: formatBytes(loaded).padStart(sizeW),
+            total_human: formatBytes(totalBytes).padEnd(sizeW),
+            rate:
+                elapsed > 0.2
+                    ? `${formatBytes(rate)}/s`.padStart(rateW)
+                    : '—'.padStart(rateW),
+            countdown:
+                elapsed > 0.5 && Number.isFinite(etaSeconds)
+                    ? `ETA ${formatETA(etaSeconds)}`.padEnd(etaW)
+                    : 'ETA —'.padEnd(etaW),
+        });
+    };
+    const finish = () => {
+        const elapsed = (Date.now() - startedAt) / 1000;
+        const averageRate = elapsed > 0 ? totalBytes / elapsed : 0;
+        bar.update(totalBytes, {
+            transferred: formatBytes(totalBytes).padStart(sizeW),
+            total_human: formatBytes(totalBytes).padEnd(sizeW),
+            rate:
+                elapsed > 0
+                    ? `${formatBytes(averageRate)}/s`.padStart(rateW)
+                    : '—'.padStart(rateW),
+            countdown: 'done'.padEnd(etaW),
+        });
+        bar.stop();
+        return { elapsed, averageRate };
+    };
+    return { onProgress, finish };
+}
+
+/**
+ * Split `push` and `pull` into two plain commands instead of the
+ * scp-style single `cp` with `<deviceId>:` prefixes. Intent is obvious
+ * from the verb and the argument order is always the same: device id,
+ * then source, then destination — no ambiguity about "which side is
+ * local".
+ */
+export function registerTransferCommands(device) {
+    device
+        .command('push <deviceId> <localPath> <remotePath>')
+        .helpGroup('Filesystem:')
+        .description('Upload a local file to the device (use trailing "/" on remote to keep the source basename)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, localPath, remotePath, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            const finalRemote = remotePath.endsWith('/')
+                ? remotePath + basename(localPath)
+                : remotePath;
+
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const fileStat = await statLocal(localPath);
+                const totalBytes = fileStat.size;
+                const useBar = !isJsonMode() && !!process.stdout.isTTY;
+                if (!useBar) {
+                    // No progress bar needed — keep the simpler,
+                    // whole-buffer path that other callers also use.
+                    const content = await readLocalFile(localPath);
+                    await api.writeFile(finalRemote, content);
+                    if (isJsonMode()) {
+                        printOk({
+                            direction: 'push',
+                            device: deviceId,
+                            local: localPath,
+                            remote: finalRemote,
+                            bytes: content.byteLength,
+                        });
+                    } else {
+                        console.log(
+                            success(`Uploaded ${localPath} → ${deviceId}:${finalRemote}`) +
+                                ' ' +
+                                hint(`(${formatBytes(content.byteLength)})`),
+                        );
+                    }
+                    return;
+                }
+                console.log(
+                    hint(`Uploading ${localPath} → ${deviceId}:${finalRemote}`),
+                );
+                const { onProgress, finish } = makeTransferBar(totalBytes);
+                // A Transform between the file stream and axios counts
+                // bytes only when the downstream (axios → HTTP socket)
+                // accepts them. Backpressure means the count rises at
+                // the speed of the slowest link, so the bar tracks
+                // actual network progress instead of the speed of the
+                // local disk read. axios' own onUploadProgress would
+                // otherwise report the buffer fill, not the wire.
+                const stream = createReadStream(localPath, { highWaterMark: 64 * 1024 });
+                let loaded = 0;
+                const meter = new Transform({
+                    transform(chunk, _enc, cb) {
+                        loaded += chunk.length;
+                        onProgress({ loaded, total: totalBytes });
+                        cb(null, chunk);
+                    },
+                });
+                stream.pipe(meter);
+                await api.writeFile(finalRemote, meter, true, {
+                    contentLength: totalBytes,
+                });
+                const { elapsed, averageRate } = finish();
+                console.log(
+                    success(`Uploaded ${localPath} → ${deviceId}:${finalRemote}`) +
+                        ' ' +
+                        hint(
+                            `(${formatBytes(totalBytes)} in ${elapsed.toFixed(1)}s, ${formatBytes(averageRate)}/s avg)`,
+                        ),
+                );
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('pull <deviceId> <remotePath> <localPath>')
+        .helpGroup('Filesystem:')
+        .description('Download a remote file from the device to local disk')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, remotePath, localPath, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            const finalLocal = localPath.endsWith('/')
+                ? localPath + basename(remotePath)
+                : localPath;
+
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const useBar = !isJsonMode() && !!process.stdout.isTTY;
+                if (!useBar) {
+                    const buf = await api.readFile(remotePath);
+                    await writeLocalFile(finalLocal, buf);
+                    if (isJsonMode()) {
+                        printOk({
+                            direction: 'pull',
+                            device: deviceId,
+                            remote: remotePath,
+                            local: finalLocal,
+                            bytes: buf.byteLength,
+                        });
+                    } else {
+                        console.log(
+                            success(`Downloaded ${deviceId}:${remotePath} → ${finalLocal}`) +
+                                ' ' +
+                                hint(`(${formatBytes(buf.byteLength)})`),
+                        );
+                    }
+                    return;
+                }
+                // First HEAD-like round-trip isn't available; axios
+                // surfaces `total` on the first onDownloadProgress
+                // frame if the server sent Content-Length. Start the
+                // bar deferred until we know the total.
+                console.log(
+                    hint(`Downloading ${deviceId}:${remotePath} → ${finalLocal}`),
+                );
+                /** @type {ReturnType<typeof makeTransferBar> | null} */
+                let bar = null;
+                const buf = await api.readFile(remotePath, {
+                    onProgress: (ev) => {
+                        if (!bar && ev?.total) bar = makeTransferBar(ev.total);
+                        bar?.onProgress(ev);
+                    },
+                });
+                if (!bar) bar = makeTransferBar(buf.byteLength);
+                const { elapsed, averageRate } = bar.finish();
+                await writeLocalFile(finalLocal, buf);
+                console.log(
+                    success(`Downloaded ${deviceId}:${remotePath} → ${finalLocal}`) +
+                        ' ' +
+                        hint(
+                            `(${formatBytes(buf.byteLength)} in ${elapsed.toFixed(1)}s, ${formatBytes(averageRate)}/s avg)`,
+                        ),
+                );
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+}