@feralfile/cli 3.0.0 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@ A small Node.js CLI for building DP-1 playlists of digital art.
 
 **Runtime:** Node.js 22 or newer (matches CI and the `dp1-js` dependency). That engine floor is a **breaking** change if you previously used Node 18 or 20—check the **GitHub Release** for the version you move to; release authors follow `docs/RELEASING.md` so the notes stay explicit.
 
-ff-cli is a set of deterministic commands for building DP-1–conformant playlists and playing them on an Art Computer: schema validation, indexing, JSON‑LD, signing, and device delivery. There's no built-in chat — natural language belongs in your coding agent (Claude Code, Codex), which drives ff-cli through the `ff-control` skill (see [Use with Claude Code](#use-with-claude-code)). No LLM API key required.
+ff-cli is a set of deterministic commands for building DP-1–conformant playlists and displaying them on an Art Computer: schema validation, indexing, JSON‑LD, signing, and device delivery. There's no built-in chat — natural language belongs in your coding agent (Claude Code, Codex), which drives ff-cli through the `ff-control` skill (see [Use with Claude Code](#use-with-claude-code)). No LLM API key required.
 
 ## Install
 
@@ -18,16 +18,16 @@ This installs a complete package (including `config.json.example` and the bundle
 
 ```bash
 npx @feralfile/cli setup
-npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
 ```
 
 ## Quick Start
 
 ```bash
 ff-cli setup
-ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
-ff-cli play "https://example.com/video.mp4"
-ff-cli play "https://example.com/"          # any web page
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --display
+ff-cli display "https://example.com/video.mp4"
+ff-cli display "https://example.com/"          # any web page
 ```
 
 If you need manual config actions instead of guided setup:
@@ -54,25 +54,27 @@ ff-cli setup -y --key "<private-key>" --role agent
 
 `--generate-key`, `--key`, and `--key-file` refuse to replace a signing key that is already configured, because that key owns the playlists you published. Add `--force` only when you mean to replace it.
 
-Without a terminal, `find` needs `-y` (it plays by default; add `--no-play` to only save). A question with no terminal to answer it exits 1 and names the flag.
+Without a terminal, `find` needs `-y` (it displays by default; add `--no-display` to only save). A question with no terminal to answer it exits 1 and names the flag.
 
 Device pairing is also scriptable on its own: `ff-cli device add --host http://<ip>:1111 --name <name>` skips mDNS discovery entirely.
 
+On FF OS with secure control, an FF1 only accepts commands from controllers an owner added. `ff-cli device pair <name>` shows a QR code; an owner scans it with **Add controller** in the Feral File app, and ff-cli enrolls with the role they picked. Pairing needs an internet connection and an FF1 that already has an owner (ff-cli cannot be the first owner); `--resume` finishes a pairing an owner already approved, and `ff-cli device unpair <name>` revokes ff-cli on the FF1 before deleting its keys. FF1s without secure control pair through a one-time code ("Pair with ff-cli" in the app) that hands over relayer access; ff-cli picks the path from the FF1's status, and `--topic-handoff` forces the one-time code. Details: [docs/CONFIGURATION.md](./docs/CONFIGURATION.md#secure-control-pairing).
+
 ## Find an artwork
 
-`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or a wallet address into a playable DP-1 playlist. The focus is computational and generative art; PFP collections and pre-ERC-721 contracts have limits noted below.
+`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or a wallet address into a DP-1 playlist ready to display. The focus is computational and generative art; PFP collections and pre-ERC-721 contracts have limits noted below.
 
 ```bash
-# Most satisfying: paste a URL, play it on your FF1
-ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+# Most satisfying: paste a URL, display it on your FF1
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
 
 # Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
-ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --display
 
 # Feral File artwork (public id can be hex or numeric — both forms resolve via /api/artworks)
-ff-cli find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --play
+ff-cli find https://feralfile.com/exhibitions/artwork/f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf --display
 
-# Save without playing
+# Save without displaying
 ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 --output send-receive.json
 ```
 
@@ -83,7 +85,7 @@ Sources: Art Blocks, Objkt, fxhash (canonical `/gentk/...`, live `/iteration/{sl
 - **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)). The opt-in Raster token source resolves them.
 - **Mainstream PFPs** (Azuki, BAYC, Pudgy Penguins) build a single-item playlist instead of a series — Raster's curation is effectively the series allowlist.
 - **Indexer 502s on burst load** are intermittent ([ff-indexer-v2#82](https://github.com/feral-file/ff-indexer-v2/issues/82)) — retry clears or use `--limit N`.
-- **The Raster token source is opt-in and under evaluation** (`tokenSource: "raster"`). It cannot list a contract, its Feral File metadata is a snapshot (an evolving work plays the version Raster recorded), and some Feral File works point at a retired image host and play black. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#tokensource).
+- **The Raster token source is opt-in and under evaluation** (`tokenSource: "raster"`). It cannot list a contract, its Feral File metadata is a snapshot (an evolving work displays the version Raster recorded), and some Feral File works point at a retired image host and display black. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#tokensource).
 
 ## Use with Claude Code
 
@@ -94,7 +96,7 @@ d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d
   && mkdir -p ~/.claude/skills && cp -r "$d/skills/ff-control" ~/.claude/skills/
 ```
 
-Claude Code will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+Claude Code will surface it when you ask to build a playlist, display an artwork or URL on an Art Computer, or publish to a feed. The skill validates config, builds, validates the playlist, and sends or publishes — reporting the failing command + exit code if anything breaks. Full prompt and exact flow: [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
 
 ## Use with Codex
 
@@ -105,15 +107,15 @@ d="$(mktemp -d)" && git clone --depth=1 https://github.com/feral-file/ff-cli "$d
   && mkdir -p ~/.codex/skills && cp -r "$d/skills/ff-control" ~/.codex/skills/
 ```
 
-Codex will surface it when you ask to build a playlist, play an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
+Codex will surface it when you ask to build a playlist, display an artwork or URL on an Art Computer, or publish to a feed. The installed skill is `skills/ff-control/SKILL.md`, so the execution flow stays defined in one place. Codex metadata and exact flow: [`skills/ff-control/agents/openai.yaml`](./skills/ff-control/agents/openai.yaml), [`skills/ff-control/SKILL.md`](./skills/ff-control/SKILL.md).
 
 ## Dev Quick Start
 
 ```bash
 npm ci
 npm run dev -- setup
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
-npm run dev -- play "https://example.com/video.mp4"
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display
+npm run dev -- display "https://example.com/video.mp4"
 ```
 
 ## Documentation
@@ -122,6 +124,7 @@ npm run dev -- play "https://example.com/video.mp4"
 - Configuration: `./docs/CONFIGURATION.md`
 - Examples: `./docs/EXAMPLES.md`
 - SSH access: `ff-cli ssh enable|disable` in `./docs/README.md`
+- Problem reports to Feral File support: `ff-cli report` in `./docs/README.md`
 
 ## Verification
 

package/config.json.example

@@ -7,7 +7,7 @@
   },
   "feedServers": [
     {
-      "baseUrl": "https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"
+      "baseUrl": "https://feed.feralfile.com/api/v1"
     },
     {
       "baseUrl": "http://localhost:8787"

package/dist/index.js

@@ -34,6 +34,9 @@ const enrich_1 = require("./src/commands/enrich");
 const config_1 = require("./src/commands/config");
 const ssh_1 = require("./src/commands/ssh");
 const device_1 = require("./src/commands/device");
+const report_1 = require("./src/commands/report");
+const hidden_alias_help_1 = require("./src/commands/helpers/hidden-alias-help");
+const relay_pairing_channel_1 = require("./src/utilities/control/relay-pairing-channel");
 // Load version from package.json. Try the built location first
 // (dist/index.js -> ../package.json) and fall back to dev (./package.json).
 let packageJsonPath = (0, path_1.resolve)((0, path_1.dirname)(__filename), '..', 'package.json');
@@ -49,13 +52,15 @@ program
     .name('ff-cli')
     .description(packageDescription)
     .version(packageVersion)
-    .addHelpText('after', `\nQuick start:\n  1) ff-cli setup\n  2) ff-cli play <url-or-playlist>\n\nDocs: https://github.com/feral-file/ff-cli\n`);
+    // Lists aliased commands by their name only (`display`, never `display|play`); see hiddenAliasHelp.
+    .configureHelp(hidden_alias_help_1.hiddenAliasHelp)
+    .addHelpText('after', `\nQuick start:\n  1) ff-cli setup\n  2) ff-cli display <url-or-playlist>\n\nDocs: https://github.com/feral-file/ff-cli\n`);
 program.addCommand(setup_1.setupCommand);
 program.addCommand(status_1.statusCommand);
 program.addCommand(validate_1.verifyCommand);
 program.addCommand(validate_1.validateCommand);
 program.addCommand(sign_1.signCommand);
-program.addCommand(play_1.playCommand);
+program.addCommand(play_1.displayCommand);
 program.addCommand(publish_1.publishCommand);
 program.addCommand(unpublish_1.unpublishCommand);
 program.addCommand(fetch_1.fetchCommand);
@@ -65,4 +70,7 @@ program.addCommand(build_1.buildCommand);
 program.addCommand(config_1.configCommand);
 program.addCommand(ssh_1.sshCommand);
 program.addCommand(device_1.deviceCommand);
+program.addCommand(report_1.reportCommand);
+// `device pair` joins its pairing channel on relay v2 when an endpoint is set.
+(0, relay_pairing_channel_1.installRelayPairingChannel)();
 program.parse();

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@feralfile/cli",
-    "version": "3.0.0",
-    "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
+    "version": "4.0.0",
+    "description": "CLI for building, signing, and displaying DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/feral-file/ff-cli.git"
@@ -68,10 +68,13 @@
         "dp1-js": "2.4.1",
         "ff1": "^1.0.0",
         "fuzzysort": "^3.1.0",
+        "jose": "6.2.12",
+        "qrcode-terminal": "0.12.0",
         "viem": "^2.56.3"
     },
     "devDependencies": {
         "@types/node": "^24.7.1",
+        "@types/qrcode-terminal": "0.12.2",
         "@typescript-eslint/eslint-plugin": "^8.46.0",
         "@typescript-eslint/parser": "^8.46.0",
         "esbuild": "^0.25.10",

package/dist/src/commands/build.js

@@ -30,7 +30,7 @@ Requirement types:
 
 playlistSettings (all optional):
   title, durationPerItem (seconds), preserveOrder (default true; false shuffles),
-  deviceName (play on that FF1 after building)
+  deviceName (display on that FF1 after building)
 
 Exit status: 1 when a requirement finds nothing or fails, when named tokenIds
 do not all resolve, or when the send to deviceName fails. The playlist is still

package/dist/src/commands/device.js

@@ -15,57 +15,71 @@ const device_rename_1 = require("../utilities/device-rename");
 const config_files_1 = require("./helpers/config-files");
 const device_discovery_1 = require("./helpers/device-discovery");
 const prompt_1 = require("./helpers/prompt");
-const ff1_compatibility_1 = require("../utilities/ff1-compatibility");
-const handoff_client_1 = require("../utilities/handoff-client");
-const topic_store_1 = require("../utilities/topic-store");
+const device_control_1 = require("./helpers/device-control");
 const device_removal_1 = require("./helpers/device-removal");
+const http_1 = require("../utilities/http");
+const support_report_1 = require("../utilities/support-report");
+const pairing_1 = require("../utilities/control/pairing");
+/** DEVICE_ID_STATUS_TIMEOUT_MS bounds the status read that names a manually added FF1 at an
+ *  address; a `.local` name gets the longer lanReadTimeoutMs deadline. */
+const DEVICE_ID_STATUS_TIMEOUT_MS = 3_000;
 const deviceCommand = new commander_1.Command('device').description('Manage configured FF1 devices');
 exports.deviceCommand = deviceCommand;
 deviceCommand
     .command('pair')
-    .description('Securely receive relayer access for a configured FF1 from the mobile app')
+    .description('Pair ff-cli with a configured FF1: on secure control, show a code an owner scans with "Add controller" in the Feral File app (needs internet and an owner); otherwise receive relayer access through a one-time code')
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .option('--label <label>', "Name the owner sees when adding ff-cli (default: this computer's hostname)")
+    .option('--timeout <seconds>', 'How long to wait for an owner, 10-600 (default: 300)')
+    .option('--resume', 'Finish a pairing an owner already approved, without a new code')
+    .option('-y, --yes', 'Move a corrupt controller file aside without asking')
+    .option('--topic-handoff', 'Use the one-time code and "Pair with ff-cli" in the app (FF OS without secure control); chosen automatically when the FF1 reports no secure control')
+    .action(async (name, options) => {
+    await runControlAction('Pairing failed:', () => (0, device_control_1.runPair)(name, options));
+});
+deviceCommand
+    .command('controllers')
+    .description('List the controllers paired with an FF1 (owner only)')
     .argument('[name]', 'Configured device name (uses the default device when omitted)')
     .action(async (name) => {
-    let receiver;
+    await runControlAction('Error:', () => (0, device_control_1.runControllers)(name));
+});
+deviceCommand
+    .command('revoke')
+    .description("Revoke a controller's access to an FF1, or deny its pending request (owner only)")
+    .argument('<controller-id>', 'Controller ID shown by `ff-cli device controllers`')
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .action(async (ctl, name) => {
+    await runControlAction('Error:', () => (0, device_control_1.runRevoke)(ctl, name));
+});
+deviceCommand
+    .command('unpair')
+    .description("Revoke ff-cli's access on an FF1 (best effort) and delete its controller keys")
+    .argument('[name]', 'Configured device name (uses the default device when omitted)')
+    .option('-y, --yes', 'Delete the keys without asking')
+    .action(async (name, options) => {
+    await runControlAction('Error:', () => (0, device_control_1.runUnpair)(name, options));
+});
+/**
+ * runControlAction runs a pairing/controller action and prints a failure as
+ * an error line plus its follow-up, setting a non-zero exit code.
+ *
+ * @param prefix - Error prefix
+ * @param action - Action to run
+ */
+async function runControlAction(prefix, action) {
     try {
-        const selected = (0, ff1_compatibility_1.resolveConfiguredDevice)(name);
-        if (!selected.success || !selected.device) {
-            throw new Error(selected.error || 'FF1 device is not configured correctly');
-        }
-        const device = selected.device;
-        if (!device.id) {
-            throw new Error(`Device "${device.name || device.host}" has no stable device ID. Re-add it with ff-cli device add before pairing.`);
-        }
-        receiver = await handoff_client_1.TopicHandoffReceiver.create();
-        console.log(chalk_1.default.blue('\nPair ff-cli with Feral File mobile\n'));
-        console.log(`  Device: ${chalk_1.default.bold(device.name || device.id)}`);
-        console.log(`  Device ID: ${chalk_1.default.dim(device.id)}`);
-        console.log("\nIn the mobile app, open this Art Computer's options and choose");
-        console.log(chalk_1.default.bold('“Pair with ff-cli”'), 'then enter:');
-        console.log(`\n  ${chalk_1.default.bold(receiver.shortCode)}\n`);
-        console.log('Before sharing, confirm the mobile security check matches:');
-        console.log(`\n  ${chalk_1.default.bold(receiver.verificationCode)}\n`);
-        console.log(chalk_1.default.dim(`This one-time code expires at ${receiver.expiresAt}. Waiting...`));
-        const payload = await receiver.receiveTopic({ expectedDeviceId: device.id });
-        (0, topic_store_1.storeTopicId)(device.id, payload.topicId);
-        console.log(chalk_1.default.green('\n✓ Relayer access stored in the operating system secure storage.\n'));
+        await action();
     }
     catch (error) {
-        console.error(chalk_1.default.red('\nPairing failed:'), error.message);
-        process.exitCode = 1;
-    }
-    finally {
-        if (receiver) {
-            try {
-                await receiver.close();
-            }
-            catch {
-                // The channel is short-lived and expires automatically. A close
-                // failure must not erase or misreport an already stored credential.
-            }
+        console.error(chalk_1.default.red(`\n${prefix}`), error.message);
+        if (error instanceof device_control_1.CommandFailure && error.details) {
+            console.error(chalk_1.default.dim(error.details));
         }
+        console.error();
+        process.exitCode = 1;
     }
-});
+}
 deviceCommand
     .command('list')
     .description('List all configured FF1 devices')
@@ -231,6 +245,37 @@ deviceCommand
                 return;
             }
         }
+        // A manual host has no discovered ID, and pairing needs one: without it
+        // `device pair` sent the user back here, which stored none again. The
+        // LAN status names the device; like an mDNS record it is unauthenticated
+        // and only labels the entry. It never replaces a stored ID: the rows this
+        // update can land on (the matched one, else upsertDevice's same-host or
+        // same-name row) are left alone when one already has an ID, and an ID
+        // another row already holds is not recorded here (that would merge the
+        // two rows or orphan a controller record keyed by the old ID).
+        if (options.host && !discoveredId) {
+            const targets = existingIndex !== -1
+                ? [existingDevices[existingIndex]]
+                : existingDevices.filter((d) => d.host === hostValue || d.name === deviceName);
+            if (!targets.some((d) => d.id)) {
+                const { device: status } = await (0, support_report_1.readDeviceStatus)({ name: deviceName, host: hostValue, apiKey: targets[0]?.apiKey }, (input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}, (0, pairing_1.lanReadTimeoutMs)(hostValue, DEVICE_ID_STATUS_TIMEOUT_MS)));
+                const statusId = status.device_id?.trim().toUpperCase();
+                const holder = statusId
+                    ? existingDevices.find((d) => !targets.includes(d) && d.id?.trim().toUpperCase() === statusId)
+                    : undefined;
+                if (!statusId || !/^FF1-[A-Z0-9]{4,}$/.test(statusId)) {
+                    console.log(chalk_1.default.dim('Could not read a device ID from the FF1; pairing needs --id FF1-XXXXXXXX.'));
+                }
+                else if (holder) {
+                    console.log(chalk_1.default.yellow(`The FF1 at ${hostValue} reports ${statusId}, which is already configured as "${holder.name || holder.host}". ` +
+                        'Not recording it here: remove that device first, or pass --id.'));
+                }
+                else {
+                    discoveredId = statusId;
+                    console.log(chalk_1.default.dim(`Device ID ${statusId} from the FF1's LAN status.`));
+                }
+            }
+        }
         const result = (0, device_upsert_1.upsertDevice)(existingDevices, { name: deviceName, host: hostValue, id: discoveredId, addresses: discoveredAddresses }, existingIndex !== -1 ? existingIndex : undefined);
         console.log(chalk_1.default.green(`\n${result.updated ? 'Updated' : 'Added'} device: ${deviceName}`));
         config.ff1Devices = { devices: result.devices };

package/dist/src/commands/enrich.js

@@ -272,7 +272,7 @@ async function syncDirectory(directory, filesystem) {
  *
  * Enrichment refuses to work on a document DP-1 rejects, and refuses to write
  * one. Writing an invalid playlist would replace the operator's file with
- * something sign, publish, and play all reject later, having reported success.
+ * something sign, publish, and display all reject later, having reported success.
  */
 function reportInvalid(stage, result) {
     console.error(chalk_1.default.red(`\n${stage}`));
@@ -404,7 +404,7 @@ exports.enrichCommand = new commander_1.Command('enrich')
         // fails at the device, which is the worst place to discover it.
         if (result.signatureInvalidated) {
             console.log(chalk_1.default.yellow('\n  Signature removed — the document changed.'));
-            console.log(chalk_1.default.dim(`  Re-sign before playing: ff-cli sign ${destination}`));
+            console.log(chalk_1.default.dim(`  Re-sign before displaying: ff-cli sign ${destination}`));
         }
         console.log();
     }

package/dist/src/commands/find.js

@@ -38,32 +38,53 @@ const RASTER_PAGE_SIZE = 100;
 /**
  * FIND_NON_INTERACTIVE_HINT is what `find` tells a caller without a terminal
  * when one of its questions comes up. `-y` answers every question with its
- * default, and that default is Play, so the hint names `--no-play` in the same
- * breath for a caller that only wants the file.
+ * default, and that default is to display, so the hint names `--no-display` in
+ * the same breath for a caller that only wants the file.
  */
-const FIND_NON_INTERACTIVE_HINT = 'Re-run with -y to accept the defaults (it builds the playlist and plays it on your FF1); add --no-play to only save it.';
+const FIND_NON_INTERACTIVE_HINT = 'Re-run with -y to accept the defaults (it builds the playlist and displays it on your FF1); add --no-display to only save it.';
 /**
  * playAPageHint points a caller who handed `find` a page it cannot resolve to
  * the command that shows a page as it is.
  *
  * @param {string} input - The URL the caller gave `find`
- * @returns {string} One line naming `ff-cli play --web`
+ * @returns {string} One line naming `ff-cli display --web`
  */
 function playAPageHint(input) {
-    return `To show this page itself on your FF1, run: ff-cli play --web "${input}"`;
+    return `To show this page itself on your FF1, run: ff-cli display --web "${input}"`;
+}
+/**
+ * displayIntent folds the hidden `--play` / `--no-play` spellings into
+ * `--display` / `--no-display`.
+ *
+ * The verb for art is display, not play (B&F weekly 2026-11-03; Canon
+ * reference/naming-brand.md §3.4), so `find` takes `--display` and
+ * `--no-display`. `-p, --play` and `--no-play` stay accepted, hidden from
+ * help, so existing scripts and agents keep working. Commander stores the two
+ * spellings under separate keys (`display`, `play`); this is the one place
+ * that reads both. The current spelling wins when a caller passes both.
+ *
+ * @param {FindOptions} options - Parsed `find` options
+ * @returns {boolean | undefined} true to display, false to never cast,
+ *   undefined when neither spelling was passed
+ */
+function displayIntent(options) {
+    return options.display ?? options.play;
 }
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
     .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address (picks one work by the artist at that address; for what a wallet owns, see `ff-cli build --help`)')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
-    .option('-p, --play', 'Play the playlist on an FF1 device after building')
-    .option('--no-play', 'Never cast to a device; combine with -y to build and save without playing')
-    .option('-d, --device <name>', 'Device to play on (used with --play; default: first configured)')
+    .option('--display', 'Display the playlist on an FF1 device after building')
+    .option('--no-display', 'Never cast to a device; combine with -y to build and save without displaying')
+    // The retired spellings of the two flags above, accepted but never listed; see displayIntent.
+    .addOption(new commander_1.Option('-p, --play').hideHelp())
+    .addOption(new commander_1.Option('--no-play').hideHelp())
+    .option('-d, --device <name>', 'Device to display on (used with --display; default: first configured)')
     .option('--publish', 'Publish the playlist to a configured feed server')
     .option('-s, --server <index>', 'Feed server index (used with --publish)')
-    .option('-y, --yes', 'Skip interactive prompts. Without --output or --publish, -y plays the playlist on a device; add --no-play to skip casting')
-    .option('--skip-verify', 'Skip signature verification before --play (mirrors `ff-cli play --skip-verify`)')
+    .option('-y, --yes', 'Skip interactive prompts. Without --output or --publish, -y displays the playlist on a device; add --no-display to skip casting')
+    .option('--skip-verify', 'Skip signature verification before --display (mirrors `ff-cli display --skip-verify`)')
     .action(async (input, options) => {
     try {
         console.log(chalk_1.default.blue('\nFind on Feral File CLI\n'));
@@ -73,10 +94,10 @@ exports.findCommand = new commander_1.Command('find')
             console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse, Raster. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
-            // A plain web page or media URL is not an artwork lookup at all; `play`
+            // A plain web page or media URL is not an artwork lookup at all; `display`
             // casts those directly, so name it rather than leave the caller stuck.
             if (/^https?:\/\//i.test(input.trim())) {
-                console.error(chalk_1.default.dim(`To play a web page or media URL as it is, run: ff-cli play "${input}"`));
+                console.error(chalk_1.default.dim(`To display a web page or media URL as it is, run: ff-cli display "${input}"`));
             }
             process.exit(1);
         }
@@ -87,7 +108,7 @@ exports.findCommand = new commander_1.Command('find')
                 return;
             }
             console.error(chalk_1.default.red(parsed.reason));
-            // `play` sends unrecognized pages on these hosts here, so the way out
+            // `display` sends unrecognized pages on these hosts here, so the way out
             // of that loop has to be printed on this side too.
             console.error(chalk_1.default.dim(playAPageHint(input)));
             process.exit(1);
@@ -282,7 +303,7 @@ async function resolveTarget(input, parsed, skipPrompt, limitOption) {
         // A wallet address reads naturally as "what this wallet owns", and this
         // path builds something else: one work by the artist at the address. Say
         // so every time, so neither a person nor an agent mistakes the result.
-        console.log(chalk_1.default.dim('find on an address plays one work by the artist at that address. ' +
+        console.log(chalk_1.default.dim('find on an address displays one work by the artist at that address. ' +
             'For what the wallet owns, use build with a query_address requirement (ff-cli build --help).'));
         const picked = await pickFromCatalog(catalog, skipPrompt);
         return {
@@ -323,11 +344,11 @@ async function resolveTokenListInput(input, limit, fallbackTitle = 'Resolved sou
 }
 /**
  * Resolve on-chain coords to a target. If Raster doesn't index this token,
- * fall back to single-token mode so we still build something playable.
+ * fall back to single-token mode so we still build something to display.
  *
  * Raster being unreachable gets the same fallback: it only enriches the find
  * (series enumeration, artist labels) — the coords in hand are enough to
- * build a playable single-token playlist, and a network blip on one optional
+ * build a single-token playlist to display, and a network blip on one optional
  * dependency must not kill the whole command (#97).
  */
 async function resolveCoords(coords) {
@@ -480,20 +501,23 @@ async function confirmMakePlaylist(count, hasMore) {
 /**
  * Decide which post-build actions to run.
  *
- * Precedence: explicit flags (--play / --publish) win and may combine. If no
- * flag is set, fall back to --yes default (Play) or an interactive 3-way
- * prompt. Save is unconditional and already done before this is called.
+ * Precedence: explicit flags (--display / --publish) win and may combine. If
+ * no flag is set, fall back to the --yes default (display) or an interactive
+ * 3-way prompt. Save is unconditional and already done before this is called.
  *
- * `--no-play` (commander sets `play === false`) is an opt-out that removes
- * casting from every path, including the `--yes` default and the interactive
- * prompt. It is additive: `--yes` alone keeps its deliberate "max-satisfaction
- * default for scripted use" of Play, and this must not change that. Because
- * `--no-play` already states the user's intent, it never opens the prompt.
+ * `--no-display` (commander sets `display === false`) is an opt-out that
+ * removes casting from every path, including the `--yes` default and the
+ * interactive prompt. It is additive: `--yes` alone keeps its deliberate
+ * "max-satisfaction default for scripted use" of displaying, and this must not
+ * change that. Because `--no-display` already states the user's intent, it
+ * never opens the prompt. The hidden `--play` / `--no-play` spellings mean the
+ * same (displayIntent). The internal action keeps its name, 'play'.
  */
 async function decideActions(options) {
     const flagActions = [];
-    const noPlay = options.play === false;
-    if (options.play) {
+    const display = displayIntent(options);
+    const noDisplay = display === false;
+    if (display) {
         flagActions.push('play');
     }
     if (options.publish) {
@@ -503,24 +527,34 @@ async function decideActions(options) {
         return flagActions;
     }
     // --output alone (with or without --yes) means "save mode" — the save was the action.
-    // --no-play likewise means the save was the action; never prompt or default to Play.
-    if (options.output || noPlay) {
+    // --no-display likewise means the save was the action; never prompt or default to display.
+    if (options.output || noDisplay) {
         return [];
     }
-    // --yes without --output defaults to Play (max-satisfaction default for scripted use).
+    // --yes without --output defaults to display (max-satisfaction default for scripted use).
     if (options.yes) {
         return ['play'];
     }
     return [await promptNextAction()];
 }
+/**
+ * promptNextAction asks what to do with a saved playlist when no flag said so.
+ *
+ * `p` and `play` stay accepted after the rename to display: a script that
+ * pipes its answer in must keep getting the same action.
+ *
+ * @returns {Promise<PostBuildAction>} The chosen action
+ * @throws {Error} On an answer that names no action
+ */
 async function promptNextAction() {
-    const prompt = (0, prompt_1.createPrompt)('The playlist is saved. Pass --play to cast it, or --publish to publish it.');
-    const answer = (await prompt.ask('Next? [P]lay on FF1 / just [S]ave / pub[L]ish to feed (default: Play): '))
+    const prompt = (0, prompt_1.createPrompt)('The playlist is saved. Pass --display to cast it, or --publish to publish it.');
+    const answer = (await prompt.ask('Next? [D]isplay on FF1 / just [S]ave / pub[L]ish to feed (default: Display): '))
         .trim()
         .toLowerCase();
     prompt.close();
     console.log();
-    if (!answer || answer === 'p' || answer === 'play' || answer === 'y' || answer === 'yes') {
+    const displayAnswers = ['', 'd', 'display', 'p', 'play', 'y', 'yes'];
+    if (displayAnswers.includes(answer)) {
         return 'play';
     }
     if (answer === 's' || answer === 'save' || answer === 'n' || answer === 'no') {
@@ -529,10 +563,10 @@ async function promptNextAction() {
     if (answer === 'l' || answer === 'pub' || answer === 'publish') {
         return 'publish';
     }
-    throw new Error(`Unrecognized choice: "${answer}". Use P, S, or L.`);
+    throw new Error(`Unrecognized choice: "${answer}". Use D, S, or L.`);
 }
 async function doPlay(playlist, deviceName, skipVerify) {
-    // Same verify → send gate `ff-cli play` uses, via the shared castPlaylist
+    // Same verify → send gate `ff-cli display` uses, via the shared castPlaylist
     // helper. `find`'s playlists are already signed by buildDP1Playlist (when a
     // key is configured), so no signing is requested here — an unsigned one
     // fails the verify gate with an actionable message instead of reaching the
@@ -553,7 +587,7 @@ async function doPlay(playlist, deviceName, skipVerify) {
                 'or pass --skip-verify to bypass.'));
         }
         else {
-            console.error(chalk_1.default.red('Play failed:'), result.error);
+            console.error(chalk_1.default.red('Display failed:'), result.error);
             if (result.deviceDetails) {
                 console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
             }
@@ -564,8 +598,8 @@ async function doPlay(playlist, deviceName, skipVerify) {
     if (result.verified) {
         console.log(chalk_1.default.green('✓ Verified\n'));
     }
-    console.log(chalk_1.default.blue('Play on FF1'));
-    console.log(chalk_1.default.green('✓ Playing'));
+    console.log(chalk_1.default.blue('Display on FF1'));
+    console.log(chalk_1.default.green('✓ Displaying'));
     if (result.deviceName) {
         console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
     }