@feralfile/cli 1.1.1

package/dist/src/utilities/playlist-verifier.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Playlist Verification Utility.
+ * Delegates signature-shape handling to dp1-js and keeps the CLI as a thin
+ * orchestration layer.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPlaylist = verifyPlaylist;
+exports.validatePlaylist = validatePlaylist;
+exports.verifyPlaylistFile = verifyPlaylistFile;
+exports.printVerificationResult = printVerificationResult;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = require("fs");
+const module_1 = require("module");
+/**
+ * Cryptographically verify a playlist via dp1-js (after parsing succeeds).
+ *
+ * Unlike {@link validatePlaylist}, this forwards to dp1-js `verifyPlaylist`. The
+ * library verifies DP-1 v1.1.0 `signatures[]` envelopes from embedded material.
+ * dp1-js uses the optional public key argument only for legacy flat `signature`
+ * strings, not for `signatures[]`. The CLI may still derive a public key from
+ * `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when `--public-key` is omitted;
+ * dp1-js ignores that value unless the playlist uses the legacy path. Legacy
+ * `signature` payloads need the matching public key via `--public-key` or
+ * derivation as above.
+ *
+ * Use {@link validatePlaylist} for structure-only checks (`validate` command).
+ *
+ * @param playlist - Playlist object
+ * @param publicKey - Optional Ed25519 key material for legacy `signature` verification.
+ * PEM SPKI, 64-character hex (optional `0x`), 32-byte base64, or SPKI DER base64 are normalized to PEM before calling dp1-js. If derivation from config fails or PEM normalization fails, the CLI logs a short warning, drops the optional key material, and still calls dp1-js (so DP-1 v1.1.0 `signatures[]` verification can succeed without relying on legacy key arguments).
+ * @returns Verification result with `valid` and optional `error` / `details`
+ */
+async function verifyPlaylist(playlist, publicKey) {
+    try {
+        const result = await parseDp1Playlist(playlist);
+        if (result && 'error' in result && result.error) {
+            return {
+                valid: false,
+                error: result.error.message,
+                details: result.error.details || [],
+            };
+        }
+        const dp1 = await loadDp1();
+        const verifyFn = dp1.verifyPlaylist;
+        if (typeof verifyFn !== 'function') {
+            throw new Error('dp1-js does not expose verifyPlaylist');
+        }
+        let key = publicKey?.trim() || undefined;
+        if (!key) {
+            try {
+                const { getPlaylistConfig } = await Promise.resolve().then(() => __importStar(require('../config')));
+                const privateKeyMaterial = getPlaylistConfig().privateKey;
+                if (privateKeyMaterial) {
+                    const { deriveEd25519PublicKeyForVerify } = await Promise.resolve().then(() => __importStar(require('./ed25519-key-derive')));
+                    key = deriveEd25519PublicKeyForVerify(privateKeyMaterial);
+                }
+            }
+            catch (err) {
+                console.warn(chalk_1.default.yellow(`Could not derive a verify public key from playlist config (${err.message}); continuing verification without it.`));
+                key = undefined;
+            }
+        }
+        if (key) {
+            try {
+                const { normalizeVerifyPublicKeyToPem } = await Promise.resolve().then(() => __importStar(require('./ed25519-key-derive')));
+                key = normalizeVerifyPublicKeyToPem(key);
+            }
+            catch (err) {
+                console.warn(chalk_1.default.yellow(`Could not normalize public key for dp1-js (${err.message}); continuing verification without it.`));
+                key = undefined;
+            }
+        }
+        const ok = await verifyFn(playlist, key);
+        return ok ? { valid: true } : { valid: false, error: 'Playlist signature verification failed' };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Verification failed: ${error.message}`,
+        };
+    }
+}
+/**
+ * Validate playlist structure without checking signatures.
+ *
+ * This is the parse-only path used by `validate`. It keeps the CLI
+ * semantics aligned with the repo contract: schema/shape validation is
+ * separate from cryptographic verification.
+ */
+async function validatePlaylist(playlist) {
+    try {
+        const result = await parseDp1Playlist(playlist);
+        if (result && 'error' in result && result.error) {
+            return {
+                valid: false,
+                error: result.error.message,
+                details: result.error.details || [],
+            };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Verification failed: ${error.message}`,
+        };
+    }
+}
+async function parseDp1Playlist(playlist) {
+    const module = (await loadDp1());
+    const parseFn = module.parseDP1Playlist;
+    if (typeof parseFn !== 'function') {
+        throw new Error('dp1-js does not expose parseDP1Playlist');
+    }
+    return parseFn(playlist);
+}
+/**
+ * Loads the published DP-1 implementation bundled with the CLI (`dp1-js`).
+ * Local checkout overrides via environment are intentionally unsupported so
+ * resolution stays deterministic across machines and CI.
+ */
+async function loadDp1() {
+    const require = (0, module_1.createRequire)(__filename);
+    return require('dp1-js');
+}
+/**
+ * Verify playlist file
+ *
+ * Reads playlist from file and validates structure.
+ *
+ * @param {string} playlistPath - Path to playlist JSON file
+ * @returns {Promise<Object>} Verification result
+ * @returns {boolean} returns.valid - Whether playlist is valid
+ * @returns {Object} [returns.playlist] - Validated playlist object
+ * @returns {string} [returns.error] - Error message if invalid
+ * @returns {Array<Object>} [returns.details] - Detailed validation errors
+ * @example
+ * const result = await verifyPlaylistFile('playlist.json');
+ * if (result.valid) {
+ *   console.log('Playlist is valid');
+ * }
+ */
+async function verifyPlaylistFile(playlistPath) {
+    try {
+        // Check if file exists
+        try {
+            await fs_1.promises.access(playlistPath);
+        }
+        catch {
+            return {
+                valid: false,
+                error: `Playlist file not found: ${playlistPath}`,
+            };
+        }
+        // Read and parse playlist file
+        const playlistContent = await fs_1.promises.readFile(playlistPath, 'utf-8');
+        let playlistData;
+        try {
+            playlistData = JSON.parse(playlistContent);
+        }
+        catch (parseError) {
+            return {
+                valid: false,
+                error: `Invalid JSON: ${parseError.message}`,
+            };
+        }
+        // Verify using dp1-js (optional key is derived for legacy signature path only inside dp1-js).
+        const result = await verifyPlaylist(playlistData);
+        if (result.valid) {
+            return {
+                valid: true,
+                playlist: playlistData,
+            };
+        }
+        return {
+            valid: false,
+            error: result.error,
+            details: result.details,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Failed to verify playlist file: ${error.message}`,
+        };
+    }
+}
+/**
+ * Prints verification results to the console.
+ *
+ * For failed results, `failureKind` distinguishes DP-1 structure parsing (the `validate`
+ * path and the first half of `verify`) from cryptographic verification (the second half
+ * of `verify` only). Defaults to `structure`.
+ *
+ * @param result - Verification result
+ * @param filename - Optional source label (path or URL)
+ * @param options - When `result.valid` is false, `failureKind` selects the failure headline
+ */
+function printVerificationResult(result, filename, options) {
+    if (result.valid) {
+        console.log(chalk_1.default.green('\nPlaylist is valid'));
+        if (filename) {
+            console.log(chalk_1.default.dim(`  File: ${filename}`));
+        }
+        if (result.playlist) {
+            console.log(chalk_1.default.dim(`  Title: ${result.playlist.title}`));
+            console.log(chalk_1.default.dim(`  Items: ${result.playlist.items?.length || 0}`));
+            console.log(chalk_1.default.dim(`  DP Version: ${result.playlist.dpVersion}`));
+            if (Array.isArray(result.playlist.signatures)) {
+                console.log(chalk_1.default.dim(`  Signatures: ${result.playlist.signatures.length}`));
+            }
+            else if (result.playlist.signature && typeof result.playlist.signature === 'string') {
+                console.log(chalk_1.default.dim(`  Signature: ${result.playlist.signature.substring(0, 30)}...`));
+            }
+        }
+        console.log();
+    }
+    else {
+        const kind = options?.failureKind ?? 'structure';
+        const headline = kind === 'signature'
+            ? '\nPlaylist signature verification failed'
+            : '\nPlaylist validation failed';
+        console.log(chalk_1.default.red(headline));
+        if (filename) {
+            console.log(chalk_1.default.dim(`  File: ${filename}`));
+        }
+        console.log(chalk_1.default.red(`  Error: ${result.error}`));
+        if (result.details && result.details.length > 0) {
+            const detailsHeading = kind === 'signature' ? '\n  Details:' : '\n  Validation errors:';
+            console.log(chalk_1.default.yellow(detailsHeading));
+            result.details.forEach((detail) => {
+                console.log(chalk_1.default.yellow(`    • ${detail.path}: ${detail.message}`));
+            });
+        }
+        console.log();
+    }
+}

package/dist/src/utilities/ssh-access.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * SSH access control for FF1 devices.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendSshAccessCommand = sendSshAccessCommand;
+const logger = __importStar(require("../logger"));
+const ff1_compatibility_1 = require("./ff1-compatibility");
+/**
+ * Send an SSH access command to an FF1 device.
+ *
+ * @param {Object} params - Function parameters
+ * @param {boolean} params.enabled - Whether to enable SSH access
+ * @param {string} [params.deviceName] - Device name to target (defaults to first configured)
+ * @param {string} [params.publicKey] - SSH public key to authorize (required for enable)
+ * @param {number} [params.ttlSeconds] - Time-to-live in seconds for auto-disable
+ * @returns {Promise<Object>} Result object
+ * @returns {boolean} returns.success - Whether the command succeeded
+ * @returns {string} [returns.device] - Device host used
+ * @returns {string} [returns.deviceName] - Device name used
+ * @returns {Object} [returns.response] - Response from device
+ * @returns {string} [returns.error] - Error message if failed
+ * @throws {Error} When device configuration is invalid or missing
+ * @example
+ * // Enable SSH for 30 minutes
+ * const result = await sendSshAccessCommand({
+ *   enabled: true,
+ *   publicKey: 'ssh-ed25519 AAAAC3... user@host',
+ *   ttlSeconds: 1800,
+ * });
+ */
+async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds, }) {
+    try {
+        if (enabled && (!publicKey || !publicKey.trim())) {
+            return {
+                success: false,
+                error: 'Public key is required to enable SSH access',
+            };
+        }
+        const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName);
+        if (!resolved.success || !resolved.device) {
+            return {
+                success: false,
+                error: resolved.error || 'FF1 device is not configured correctly',
+            };
+        }
+        const device = resolved.device;
+        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'sshAccess');
+        if (!compatibility.compatible) {
+            return {
+                success: false,
+                error: compatibility.error || 'FF1 OS does not support SSH access command',
+                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
+            };
+        }
+        let apiUrl = `${device.host}/api/cast`;
+        if (device.topicID && device.topicID.trim() !== '') {
+            apiUrl += `?topicID=${encodeURIComponent(device.topicID)}`;
+            logger.debug(`Using topicID: ${device.topicID}`);
+        }
+        const request = {
+            enabled,
+        };
+        if (publicKey && publicKey.trim()) {
+            request.publicKey = publicKey.trim();
+        }
+        if (typeof ttlSeconds === 'number') {
+            request.ttlSeconds = ttlSeconds;
+        }
+        const requestBody = {
+            command: 'sshAccess',
+            request,
+        };
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (device.apiKey) {
+            headers['API-KEY'] = device.apiKey;
+        }
+        const response = await fetch(apiUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(requestBody),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.error(`SSH access request failed: ${response.status} ${response.statusText}`);
+            logger.debug(`Error details: ${errorText}`);
+            return {
+                success: false,
+                error: `Device returned error ${response.status}: ${response.statusText}`,
+                details: errorText,
+            };
+        }
+        const responseData = (await response.json());
+        logger.info('SSH access command succeeded');
+        logger.debug(`Device response: ${JSON.stringify(responseData)}`);
+        return {
+            success: true,
+            device: device.host,
+            deviceName: device.name || device.host,
+            response: responseData,
+        };
+    }
+    catch (error) {
+        logger.error(`Error sending SSH access command: ${error.message}`);
+        return {
+            success: false,
+            error: error.message,
+        };
+    }
+}

package/dist/src/utils.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.savePlaylist = savePlaylist;
+exports.loadPlaylist = loadPlaylist;
+exports.formatFileSize = formatFileSize;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+/**
+ * Save playlist to a JSON file
+ * @param {Object} playlist - The playlist object
+ * @param {string} filename - Output filename
+ * @returns {Promise<string>} Path to the saved file
+ */
+async function savePlaylist(playlist, filename) {
+    const outputPath = path_1.default.resolve(process.cwd(), filename);
+    // Ensure the playlist is properly formatted
+    const formattedPlaylist = JSON.stringify(playlist, null, 2);
+    await fs_1.promises.writeFile(outputPath, formattedPlaylist, 'utf-8');
+    return outputPath;
+}
+/**
+ * Load playlist from a JSON file
+ * @param {string} filename - Input filename
+ * @returns {Promise<Object>} The playlist object
+ */
+async function loadPlaylist(filename) {
+    const filePath = path_1.default.resolve(process.cwd(), filename);
+    const content = await fs_1.promises.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+}
+/**
+ * Format file size in human-readable format
+ * @param {number} bytes - Size in bytes
+ * @returns {string} Formatted size
+ */
+function formatFileSize(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(2)} ${units[unitIndex]}`;
+}

package/docs/CONFIGURATION.md

@@ -0,0 +1,206 @@
+# Configuration Guide
+
+This guide explains how to configure ff-cli, field by field. Configuration priority is:
+
+- `config.json` (highest)
+- `.env`
+- built‑in defaults (lowest)
+
+## Getting started
+
+```bash
+# Create example config and edit it
+npm run dev -- config init
+
+# Validate your configuration
+npm run dev -- config validate
+
+# Show current config summary
+npm run dev -- config show
+```
+
+## Top‑level fields
+
+- **defaultModel** (string)
+  - The default AI model key to use. Must match a key under `models`.
+  - Used by orchestration to pick API, timeouts, and model identifier.
+
+- **defaultDuration** (number, seconds)
+  - Intended default per‑item display duration. Some flows pass an explicit duration; when omitted, utilities fall back to 10s.
+
+## models
+
+Each key under `models` defines a model configuration used by the AI orchestrator.
+
+- `<modelName>.apiKey` (string): API key for the provider.
+- `<modelName>.baseURL` (string): Base API URL.
+- `<modelName>.model` (string): Model identifier (e.g., `grok-beta`, `gpt-4o`).
+- `<modelName>.availableModels` (string[], optional): Display/help only.
+- `<modelName>.timeout` (number, ms): HTTP timeout for requests.
+- `<modelName>.maxRetries` (number): Retry count for requests.
+- `<modelName>.temperature` (number): Generation temperature.
+- `<modelName>.maxTokens` (number): Token cap.
+- `<modelName>.supportsFunctionCalling` (boolean): Must be true; otherwise the CLI rejects the model.
+
+Environment variable helpers:
+
+- Anthropic (Claude): `ANTHROPIC_API_KEY`
+- Grok: `GROK_API_KEY`, `GROK_MODEL`, `GROK_API_BASE_URL`
+- OpenAI: `OPENAI_API_KEY`
+- Gemini: `GEMINI_API_KEY`
+
+## browser
+
+Optional settings used where headless/browser‑like behavior is needed.
+
+- `browser.timeout` (number, ms): Operation timeout (default 90000).
+- `browser.sanitizationLevel` ("none" | "low" | "medium" | "high" | 0‑3): Converted to numeric via `sanitizationLevelToNumber()`; invalid values are flagged during validation.
+
+## playlist
+
+Used for signing DP‑1 playlists.
+
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`.
+
+  **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) pass the private key string through to **`dp1-js`** (`SignMultiEd25519`) without an extra decoding step in ff-cli. `dp1-js` recognizes **hex** (optional `0x`) or **base64** encodings of the PKCS#8 DER blob produced by the OpenSSL examples below, then loads the key for Ed25519. Use those formats; ff-cli does not add a separate normalizer ahead of the library.
+- `playlist.role` (string): DP-1 signing role that travels with the private key. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`).
+### Generate an Ed25519 private key
+
+You can generate a key locally. The CLI accepts either base64 (preferred) or hex
+
+OpenSSL (recommended):
+
+```bash
+# Base64 (preferred)
+openssl genpkey -algorithm ED25519 -outform DER | base64 | tr -d '\n'
+
+# Hex (alternative)
+openssl genpkey -algorithm ED25519 -outform DER | xxd -p -c 256
+```
+
+Paste either value into `playlist.privateKey`:
+
+- Hex example (either is valid):
+  - `0xabc123...` (with prefix)
+  - `abc123...` (without prefix)
+- Base64 example: `uQd9m8S...==`
+
+If you need a different role, set `playlist.role` to one of the DP-1 signing roles such as `agent`, `feed`, `curator`, `institution`, or `licensor`. The CLI rejects any other string before it reaches `dp1-js`.
+
+If you already have a base64 key and want hex, convert it:
+
+```bash
+echo -n "<BASE64_KEY>" | base64 -d | xxd -p -c 256
+```
+
+## feed
+
+DP‑1 Feed API configuration.
+
+- `feed.baseURLs` (string[]): Array of DP‑1 Feed Operator API v1 base URLs. The CLI queries all feeds in parallel.
+- Legacy support: `feed.baseURL` (string) is still accepted and normalized to an array.
+- Default: `https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1` if not set.
+- Compatibility: API v1 of the DP‑1 Feed Operator server. See the repository for endpoints and behavior: [dp1-feed](https://github.com/display-protocol/dp1-feed).
+
+Endpoints used by the CLI:
+
+- `GET /api/v1/playlists` (supports `limit`, `offset`, and sorting)
+- `GET /api/v1/playlists/{id}`
+
+Environment variable alternative:
+
+```env
+FEED_BASE_URLS=https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
+```
+
+## ff1Devices
+
+Configure devices you want to play content on.
+
+- `ff1Devices.devices` (array of objects):
+  - `name` (string): Friendly device label. Free‑form; pick anything memorable.
+  - `host` (string): Device base URL. For LAN devices, use `http://<ip>:1111`. The device typically listens on port `1111`.
+
+During `ff-cli setup`, the CLI will attempt local discovery via mDNS (`_ff1._tcp`). If devices are found, you can pick one and the host will be filled in automatically. If discovery returns nothing, setup falls back to manual entry.
+
+You can also manage devices independently with:
+
+- `ff-cli device add` – Add a device interactively (with mDNS discovery), or non-interactively with `--host` and `--name`.
+- `ff-cli device list` – Show all configured devices.
+- `ff-cli device remove <name>` – Remove a device by name.
+- `ff-cli device default <name>` – Promote a device to the top of the list so it is used when `-d` is omitted.
+
+Setup and `device add` both preserve existing devices. Adding a device with the same host as an existing one updates it in place.
+
+Selection rules when sending:
+
+- If you omit `-d`, the first configured device is used.
+- If you pass `-d <name>`, the CLI matches the device by `name` (exact match). If not found, you’ll see an error listing available devices.
+
+Compatibility checks:
+
+- `play` and `ssh` perform a compatibility preflight before sending commands to FF1. The CLI gets the device version by calling `POST /api/cast` with `{ "command": "getDeviceStatus", "request": {} }` and reads `message.installedVersion` from the response.
+
+- Minimum supported FF1 OS versions:
+  - `play` (`displayPlaylist`): `1.0.0` or newer
+  - `ssh` (`sshAccess`): `1.0.9` or newer
+
+- If the CLI cannot get a version from the device (e.g. network or malformed response), it continues and sends the command.
+- If the detected version is below the minimum, the command fails early with an error that includes the detected version.
+
+Troubleshooting note:
+
+- If you get an unsupported-version error, update your FF1 OS and retry. If version detection seems inconsistent, check that device host and key are correct and retry with the device directly reachable.
+
+Examples:
+
+```bash
+# Send to first device
+npm run dev -- play playlist.json
+
+# Play on a specific device by exact name
+npm run dev -- play playlist.json -d "Living Room Display"
+```
+
+Minimal `config.json` example (selected fields):
+
+```json
+{
+  "defaultModel": "claude",
+  "models": {
+    "claude": {
+      "apiKey": "sk-ant-your-api-key-here",
+      "baseURL": "https://api.anthropic.com/v1/",
+      "model": "claude-sonnet-4-6",
+      "supportsFunctionCalling": true
+    }
+  },
+  "defaultDuration": 10,
+  "playlist": {
+    "privateKey": "your_ed25519_private_key_hex_or_base64_here",
+    "role": "agent"
+  },
+  "feed": {
+    "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"]
+  },
+  "ff1Devices": {
+    "devices": [
+      {
+        "name": "Living Room Display",
+        "host": "http://192.168.1.100:1111"
+      }
+    ]
+  }
+}
+```
+
+## Security and validation
+
+- Do not commit secrets. Keep `config.json`, `.env`, and keys out of version control.
+- Validate changes regularly:
+
+```bash
+npm run dev -- config validate
+```
+
+If configuration is invalid, the CLI prints actionable errors and a non‑zero exit code.