@feralfile/cli 2.10.1 → 4.0.0

package/docs/README.md

@@ -1,6 +1,6 @@
 # ff-cli Documentation
 
-ff-cli is a set of deterministic commands for building DP-1 (Display Protocol 1) playlists and playing them on an Art Computer. 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. No LLM API key required. This doc covers install, config, and day‑to‑day usage.
+ff-cli is a set of deterministic commands for building DP-1 (Display Protocol 1) playlists and displaying them on an Art Computer. 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. No LLM API key required. This doc covers install, config, and day‑to‑day usage.
 
 For project-level planning and future agentic work, see `./PROJECT_SPEC.md`.
 
@@ -29,12 +29,15 @@ ff-cli setup --non-interactive --key-file /run/secrets/ff-signing.key \
 ```
 
 `--key` and `--key-file` together is an error, and an empty or unreadable key file is refused rather
-than quietly generating a new identity for the machine. See
+than quietly generating a new identity for the machine. Setup also never replaces a signing key that is
+already configured: `--generate-key`, `--key`, and `--key-file` refuse when a different key is in place,
+because that key owns every playlist you published (`publish --replace` and `unpublish` accept only it).
+Add `--force` to replace it anyway. See
 [Where the signing key can come from](./CONFIGURATION.md#where-the-signing-key-can-come-from).
 
 See the full configuration reference here: `./CONFIGURATION.md`.
 
-During setup, you can pick FF1 devices to add. Use `ff-cli device add` to add more devices later, and `ff-cli device list` to see what's configured. The first device is the default for `play` commands (override with `-d`).
+During setup, you can pick FF1 devices to add. Use `ff-cli device add` to add more devices later, and `ff-cli device list` to see what's configured. The first device is the default for `display` commands (override with `-d`).
 
 Manual config path:
 
@@ -52,7 +55,7 @@ ff-cli config validate
     "privateKey": "your_ed25519_private_key_hex_or_base64_here",
     "curatorName": "YOUR_CURATOR_NAME"
   },
-  "feed": { "baseURLs": ["https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1"] },
+  "feed": { "baseURLs": ["https://feed.feralfile.com/api/v1"] },
   "ff1Devices": {
     "devices": [
       {
@@ -74,8 +77,8 @@ See `./CONFIGURATION.md` for environment variable mappings.
 # Resolve a URL, on-chain coords, or wallet and build a playlist
 ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak -o playlist.json
 
-# Build and play it on your FF1 in one step
-ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
+# Build and display it on your FF1 in one step
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --display
 
 # Build from pre-structured params (JSON file or stdin)
 ff-cli build examples/params-example.json -o playlist.json
@@ -85,28 +88,29 @@ For development in this repo:
 
 ```bash
 npm run build
-node dist/index.js find https://objkt.com/tokens/hicetnunc/111068 --play
+node dist/index.js find https://objkt.com/tokens/hicetnunc/111068 --display
 ```
 
 If you're running from source without a build, use:
 
 ```bash
-npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --display
 ```
 
 ## Two ways to build a playlist
 
 ff-cli is deterministic: no chat, no model orchestration. There are two entry points for assembling a playlist.
 
-1. **`ff-cli find "<input>"`** — resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist. Add `--play` to build and play in one step. This is the fastest path for a single artwork, a collection/series, or a wallet.
+1. **`ff-cli find "<input>"`** — resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a DP-1 playlist ready to display. Add `--display` to build and display in one step. This is the fastest path for a single artwork, a collection/series, or a wallet.
 2. **`ff-cli build <params.json>`** — build from pre-structured `requirements` and `playlistSettings` (JSON file or stdin). Use this when you already have the contract, token IDs, feed names, or artwork ids and want explicit control over ordering, durations, and title.
 
 Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1 envelope, and validate it. Validation rejects malformed data rather than passing it through. Natural language lives in your coding agent (Claude Code, Codex) via the `ff-control` skill, which translates a request into one of these two commands.
 
 ## Commands (cheat sheet)
 
-- `build [params.json]` – Deterministic build from JSON or stdin
+- `build [params.json]` – Deterministic build from JSON or stdin. `ff-cli build --help` lists the requirement types and settings
   - Options: `-o, --output <file>`, `-v, --verbose`
+  - Exits 1 when any requirement finds nothing or fails, when named `tokenIds` do not all resolve, or when the send to `playlistSettings.deviceName` fails. The playlist is still saved when anything was collected; when nothing was, no file is written
 - `validate <file-or-url>` – Validate playlist structure only
 - `verify <file-or-url>` – Validate structure and verify signatures. On failure, the CLI labels structure issues separately from signature verification. dp1-js uses `--public-key` (or a key derived from `playlist.privateKey` / `PLAYLIST_PRIVATE_KEY` when omitted) **only** for legacy flat `signature` verification; DP-1 v1.1.0 `signatures[]` envelopes are verified without relying on that argument. If deriving or normalizing key material fails, the CLI prints a warning on stderr and continues without it (legacy verification still requires a usable key when the playlist uses a flat `signature`). The derived key is emitted as PEM. Supported key forms: hex with optional `0x`, PEM, or 32-byte raw public key as hex or base64
 - `sign <file>` – Sign playlist with a DP-1 v1.1.0 multi-signature envelope (private key string is forwarded to **`dp1-js`**; same hex or base64 PKCS#8 DER forms as `playlist.privateKey` in `./CONFIGURATION.md`). The command verifies the final envelope before writing output and refuses to persist tampered or otherwise unverifiable `signatures[]`.
@@ -116,14 +120,19 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - Signing **appends** by default, so repeated runs accumulate endorsements. That is only correct while the signed content is unchanged: editing a signed playlist moves bytes the earlier signatures cover, and the envelope check then refuses to write the result. `--replace-signatures` discards every existing entry — including a feed's own co-signature — and signs the document as it stands. It is the required step before `publish --replace`
   - **An in-place run refuses when it would discard a still-valid signature from another key**, since only its holder could make that signature again: write the result elsewhere with `-o, --output`, which leaves the original where it is. The refusal is about what cannot be recovered — an in-place run still proceeds when the only entries dropped are your own, or ones that no longer verify
   - `--replace-signatures` names each discarded entry by role and the last 8 characters of its `kid`, and verifies it against the document as it now stands. Your own earlier signature is replaced by the same run. Another key's entry that **still verifies** — which is every entry when the content was not edited, since the signing payload excludes `signatures` — is reported as removed; keep the previous file if you want it back. An entry that does **not** verify is reported as exactly that and no more: the command has only the document as it stands, so it cannot tell an edit from an entry that was never valid, and it does not guess. Roles are carried through as found (`agent`, `institution` and `licensor` are as valid as `curator`), and a flat legacy `signature` is reported as not checkable, since it carries no key or role at all
-- `play <source>` – Play a playlist file, playlist URL, or media URL on an FF1 device (runs `verify` before sending; only the CLI-synthesized media URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
-  - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
-- `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
+- `display <source>` – Display a playlist file, playlist URL, media URL, or web page on an FF1 device (`play` still works for existing scripts; runs `verify` before sending; only the CLI-synthesized media/web URL fallback is auto-signed when a signing key is configured; use `--skip-verify` to bypass the gate)
+  - Any URL that does not load as a playlist is sent as a single item: a media file displays as media, and anything else displays as a web page
+  - A URL that answers 404 or 410, a host that does not resolve, and a `.json` URL that does not load as a playlist are refused, so a missing page is never cast as an error page. `--web` checks the first two as well. Other failures to read the URL (a 403 from bot protection, a 5xx, a timeout) still send it, with a note, because the device fetches it itself
+  - Marketplace links (Art Blocks, OpenSea, objkt, Feral File, …) are sent to `find`, which resolves the artwork. `--web` displays the page itself instead
+  - Options: `-d, --device <name>`, `--web` (display the URL as a web page, skipping the marketplace redirect), `--skip-verify` (skip signature verification; not recommended)
+- `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a DP-1 playlist ready to display
   - Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses
   - OpenSea forms: `/assets/ethereum/{contract}/{tokenId}`, `/item/ethereum/{contract}/{tokenId}`, and `/collection/{slug}` (Ethereum collections; the slug is resolved from the public collection page, no API key needed)
   - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
-  - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `--no-play` (never cast; combine with `-y` to build and save without playing), `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes` (skip prompts; without `-o` or `--publish` it plays the playlist on a device, so add `--no-play` to skip casting), `--skip-verify`
-- `enrich <file>` – Add missing artist, title, and thumbnail metadata to a playlist that already exists. Resolves each item by its `provenance.contract` and writes an inline Ref Manifest; `source`, `duration`, `title`, and `id` are never touched. Drops the signature when it changes anything, so re-sign afterwards
+  - Options: `-o, --output <path>`, `-l, --limit <n>`, `--display`, `--no-display` (never cast; combine with `-y` to build and save without displaying; `-p`, `--play` and `--no-play` still work for existing scripts), `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes` (skip prompts; without `-o` or `--publish` it displays the playlist on a device, so add `--no-display` to skip casting), `--skip-verify`
+  - A wallet address picks one work by the artist at that address. For what a wallet owns, use `build` with a `query_address` requirement
+  - Without a terminal, pass `-y`: a question with no terminal to answer it fails with exit 1 and names the flag, rather than waiting or exiting 0 with nothing built
+- `enrich <file>` – Add missing artist, title, and thumbnail metadata to a playlist that already exists. Resolves each item by its `provenance.contract` and writes an inline Ref Manifest; `source`, `duration`, `title`, and `id` are never touched. Drops the signature when it changes anything, so re-sign afterwards. With the opt-in Raster token source no still image is supplied, so `enrich` adds artist and description but no thumbnail; thumbnails come from the default indexer source
   - DP-1 `evm` names a chain family rather than a network, so those items are skipped unless `--assume-ethereum` asserts which one they are. Getting that wrong attaches another artwork's metadata
   - Options: `-o, --output <file>`, `--force` (replace existing manifests), `--assume-ethereum`, `-v, --verbose`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
@@ -133,12 +142,19 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
   - Options: `-s, --server <index>`, `-o, --output <file>`. There is no `--key`: a fetch is a plain read and signs nothing
 - `unpublish <id-or-url>` – Delete a playlist from a feed server. Accepts a playlist id, a slug, or a feed URL. Requires the signing key to be an owner of the stored playlist, and confirms before deleting
   - Options: `-s, --server <index>`, `-y, --yes` (skip the confirmation), `-k, --key <privateKey>` (signs the delete authorization), `--key-file <path>` (the same key, read from a file)
+- `report` – Send a problem report privately to Feral File support and print its reference, `Support [<id>]`. The text comes from `--message` or `--file`, or from stdin when neither is given
+  - Options: `--message <text>`, `--file <path>`, `--email <address>` (where support may reply: a bare ASCII address such as `name@example.com`, no display name or angle brackets), `-d, --device <name>` (adds the Art Computer's device ID, FF OS version and branch, and asks it to upload its logs under the same reference), `--dry-run` (print the JSON and send nothing)
+  - Exits 1 only when the report did not reach support. See [Report a problem to Feral File support](#report-a-problem-to-feral-file-support)
 - `ssh <enable|disable>` – Manage SSH access on an FF1 device
   - Options: `-d, --device <name>`, `--pubkey <path>`, `--ttl <duration>`
 - `device list` – List all configured FF1 devices
 - `device add` – Add a device with mDNS or manual `--host`, `--name`, and `--id`
   - Options: `--host <host>`, `--name <name>`, `--id <id>`
-- `device pair [name]` – Securely receive relayer access from Feral File mobile
+- `device pair [name]` – Pair ff-cli with an FF1: on FF OS with secure control, show a QR code that an owner scans with "Add controller" in the Feral File app, then enroll with the role the owner picked (needs internet; the FF1 must already have an owner); on FF OS without secure control, display a one-time code for "Pair with ff-cli" in the app and store the relayer access it sends
+  - Options: `--label <label>`, `--timeout <seconds>` (10–600, default 300), `--resume` (finish a pairing an owner already approved), `-y, --yes` (move a corrupt controller file aside without asking), `--topic-handoff` (force the one-time-code path, e.g. when the FF1 is not on this LAN)
+- `device controllers [name]` – List an FF1's paired controllers, Play sites with a display grant, and pending requests (owner only)
+- `device revoke <controller-id> [name]` – Revoke a controller or deny its pending request (owner only)
+- `device unpair [name]` – Revoke ff-cli's own access on the FF1 (best effort), then delete its controller keys (always asks first; `-y, --yes` skips)
 - `device rename <name> <new-name>` – Rename a configured FF1 device (host, API key, and default status are untouched)
 - `device remove <name>` – Remove a configured FF1 device
 - `device default <name>` – Set the default FF1 device (used when `-d` is omitted)
@@ -148,19 +164,20 @@ Both paths run the same deterministic pipeline: fetch metadata, assemble a DP-1
 
 ### Find an artwork
 
-`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist.
+`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or wallet address into a DP-1 playlist ready to display.
 
 ```bash
-# Paste a URL and play it on your FF1
-ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+# Paste a URL and 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
 
-# Save without playing
+# Save without displaying
 ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 -o send-receive.json
 
-# Wallet address (owner lookup); cap the number of tokens with --limit
+# Wallet address: one work by the artist at that address; cap the number of tokens with --limit
+# (for what a wallet owns, use build with a query_address requirement)
 ff-cli find 0xaeE022552B539dB18297D7481b6D547C622488B3 -l 10 -o wallet.json
 
 # Build and publish to a configured feed server
@@ -178,7 +195,7 @@ cat params.json | ff-cli build -o playlist.json
 
 `params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`. Each requirement has a `type`:
 
-- `build_playlist` — `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
+- `build_playlist` — `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`. Omitting `tokenIds` asks for random tokens from the contract, which only the default indexer token source supports.
 - `feral_file_artwork` — `artworkId` (a Feral File public artwork id or `/exhibitions/artwork/{id}` URL)
 - `query_address` — `ownerAddress`, optional `quantity` (random selection)
 - `fetch_feed` — `playlistName`, `quantity`
@@ -211,8 +228,8 @@ copied from another document, or written before inline manifests existed has no
 and an empty tile in the app's grid — the app can draw a thumbnail from an
 image, video, or SVG source, but not from a live HTML work.
 
-`ff-cli enrich` fills that in from the indexer, keyed on each item's
-`provenance.contract`:
+`ff-cli enrich` fills that in from the configured token source (the Feral
+File indexer by default), keyed on each item's `provenance.contract`:
 
 ```bash
 ff-cli enrich playlist.json --assume-ethereum
@@ -222,8 +239,8 @@ ff-cli enrich playlist.json --assume-ethereum --force   # replace existing manif
 
 `--assume-ethereum` is needed for most playlists. DP-1 records an EVM
 coordinate as `chain: "evm"`, which names Ethereum, Polygon, Arbitrum,
-Optimism, Base and Zora alike, and the indexer's answer collapses back to the
-same word. Enrichment will not pick one for you, because the wrong member
+Optimism, Base and Zora alike, and the token source's answer collapses back to
+the same word. Enrichment will not pick one for you, because the wrong member
 returns a different artwork's artist and still — into a document you then sign.
 
 It writes `inlineManifest` and nothing else. Items with no
@@ -232,7 +249,7 @@ reported rather than guessed at, and items carrying an external `ref` are left
 alone because `ref` outranks an inline manifest at the device. The playlist is
 validated before and after; on failure the file is left untouched. Enriching
 changes the document, so the signature is removed and the playlist must be
-re-signed before playing:
+re-signed before displaying:
 
 ```bash
 ff-cli enrich playlist.json --assume-ethereum && ff-cli sign playlist.json
@@ -241,7 +258,7 @@ ff-cli enrich playlist.json --assume-ethereum && ff-cli sign playlist.json
 That role is fine for casting. Use `ff-cli sign playlist.json -r curator` if the enriched playlist is
 also going to a feed.
 
-### Validate, sign, and play
+### Validate, sign, and display
 
 ```bash
 # Optional explicit validation (build flows already validate)
@@ -250,28 +267,43 @@ npm run dev -- validate playlist.json
 # Sign (uses key and role from config, or overrides via --key / --role)
 npm run dev -- sign playlist.json -o signed.json
 
-# Play on configured default device (verifies playlists; only media URL fallbacks may be auto-signed)
-npm run dev -- play playlist.json
+# Display on configured default device (verifies playlists; only media URL fallbacks may be auto-signed)
+npm run dev -- display playlist.json
 
-# Play on a specific named device
-npm run dev -- play playlist.json -d "Living Room Display"
+# Display on a specific named device
+npm run dev -- display playlist.json -d "Living Room Display"
 
-# The play path performs a compatibility preflight check against the target FF1.
+# The display path performs a compatibility preflight check against the target FF1.
 # If the device reports an unsupported FF1 OS version, the command fails with
 # a clear version message before any cast request is sent.
 # It also retries transient local-network errors (for example intermittent
 # mDNS/Wi-Fi resolver failures) with a short backoff before returning a final error.
 
-# Play a hosted DP-1 playlist
-npm run dev -- play "https://cdn.example.com/playlist.json"
+# Display a hosted DP-1 playlist
+npm run dev -- display "https://cdn.example.com/playlist.json"
 
-# Play a media URL directly
-npm run dev -- play "https://example.com/video.mp4"
+# Display a media URL or any web page directly
+npm run dev -- display "https://example.com/video.mp4"
+npm run dev -- display "https://example.com/"
+
+# Display a page on a marketplace site as a page (display would otherwise send it to find)
+npm run dev -- display --web "https://feralfile.com/"
 
 # Skip signature verification only if you must send a non-conformant payload (not recommended)
-npm run dev -- play playlist.json --skip-verify
+npm run dev -- display playlist.json --skip-verify
 ```
 
+### Owner remote maintenance
+
+FFOS images containing `feral-tailscale` support opt-in persistent owner SSH on
+port 2222 through Tailscale. It requires the owner's authorized computer and SSH
+key and remains available independently of controld. The procedure checks for
+a complete installation. If support is absent, check the normal firmware release
+channel; enrollment waits until a version containing it is published and installed. Follow the [owner-access procedure](https://github.com/feral-file/ffos/blob/36e25cec84505271a7232d6936bb46a19fab5cfd/docs/OWNER_TAILSCALE.md)
+for enrollment, diagnostics, revocation and validation. The normal `ff-cli ssh`
+commands below continue to manage temporary support SSH on port 22; disabling
+support SSH does not revoke persistent owner access.
+
 ### SSH access
 
 ```bash
@@ -281,14 +313,52 @@ ff-cli ssh enable --pubkey ~/.ssh/id_ed25519.pub --ttl 30m -d "Living Room Displ
 # Disable SSH access
 ff-cli ssh disable -d "Living Room Display"
 
-# `ff-cli ssh` also performs the same FF1 OS compatibility preflight used by `play`.
+# `ff-cli ssh` also performs the same FF1 OS compatibility preflight used by `display`.
+```
+
+On newer FF OS, a claimed FF1 only accepts `ff-cli ssh` from a paired CLI: run
+`ff-cli device pair "Living Room Display"` once (an owner scans the code with
+"Add controller" in the Feral File app) before `ff-cli ssh enable|disable`. Unclaimed devices and older
+FF OS do not require pairing. On FF OS with secure control, `ssh` needs the
+**owner** role; a controller grant gets "This command needs owner access".
+
+### Report a problem to Feral File support
+
+```bash
+# Report what went wrong, with the Art Computer's logs
+ff-cli report -d "Living Room Display" --message "The work displays black on the Art Computer; in a desktop browser it renders."
+
+# From a file, with an address support can reply to
+ff-cli report --file report.txt --email you@example.com
+
+# Print exactly what would be sent, and send nothing
+ff-cli report -d "Living Room Display" --file report.txt --dry-run
 ```
 
+The report goes privately to Feral File support, the same pipeline the app's
+Support & Feedback feeds, and ff-cli prints its reference in the app's form,
+`Support [<id>]`. It carries the report text, `--email` when given, and the
+ff-cli, OS and Node versions; nothing else leaves the computer. A report that
+contains the configured signing key is refused.
+
+With `-d`, the report also carries the Art Computer's device ID, FF OS version
+and branch from its `/api/status`, and once the report is in, ff-cli asks that
+Art Computer to upload its logs under the same reference, with a short-lived
+key that works for that one report only. When ff-cli is paired with the Art
+Computer under secure control, the request is a sealed envelope over the LAN,
+or through the relayer when the LAN cannot reach it; otherwise it is a plain
+LAN request. The Art Computer takes it at once and uploads in the background,
+so it needs internet. On FF OS with secure control the request needs the **owner** role;
+a controller grant gets "This command needs owner access". A log request the
+Art Computer does not take prints a line and leaves the exit status at 0: the
+report itself reached support. The exit status is 1 only when the report did
+not, and the message says what to do next.
+
 ### Publish to feed server
 
 ```bash
-# Publish to first configured feed server
-npm run dev -- publish playlist.json
+# Publish to the first configured feed server (-s is required when more than one is configured)
+npm run dev -- publish playlist.json -s 0
 
 # Publish to specific server (if multiple configured)
 npm run dev -- publish playlist.json -s 0
@@ -432,6 +502,38 @@ ff-cli device remove kitchen
 ff-cli device default office
 ```
 
+### Pair ff-cli as a controller (secure control)
+
+Current FF OS only accepts commands from controllers an owner added. Pair once
+per FF1:
+
+```bash
+ff-cli device pair office
+#  Add ff-cli to office
+#  On an owner's phone, open this FF1 in the Feral File app, choose "Add controller", and scan this code:
+#  ...QR code, and the same text to paste...
+#  ✓ An owner added ff-cli to Office FF1 as controller. Finishing the pairing...
+#  ✓ ff-cli is paired with office as controller.
+
+ff-cli device pair office --resume        # finish a pairing an owner already approved
+ff-cli device controllers office          # owner only: who can control this FF1
+ff-cli device revoke <controller-id> office
+ff-cli device unpair office               # revoke this ff-cli on the FF1, delete its keys
+```
+
+The owner's app sends its answer over the Feral File relay, so pairing needs an
+internet connection, and the FF1 must already have an owner: ff-cli cannot be
+an FF1's first owner. ff-cli accepts only an answer bound to the code it showed
+and to the configured FF1. If nobody answers before `--timeout`, the pairing is
+not completed; run it again for a new code (it keeps the same controller keys).
+FF1s without secure control pair with a one-time code instead ("Pair with
+ff-cli" in the app); `--topic-handoff` forces that path. After pairing, `display`, `ssh` and the version preflight are sent encrypted and
+signed; the FF1 decides what each controller may do. `owner` covers every
+command; `controller` covers displaying art and status but not `ssh` or controller
+management. Keys are stored in `~/.config/ff-cli/controllers/<device ID>.json`
+(mode 0600). See `./CONFIGURATION.md#secure-control-pairing` for the file,
+roles, and error messages.
+
 Setup preserves existing devices when adding new ones. See selection rules and examples in `./CONFIGURATION.md`.
 
 ### Playlist signing (optional)
@@ -442,7 +544,7 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 
 ## Constraints
 
-- Max 20 items total across all requirements
+- Per-requirement caps: `build_playlist` up to 20 with `tokenIds` (100 without), `query_address` up to 100 when `quantity` is a number (omitted or `"all"` takes the whole wallet), `fetch_feed` up to 20. Requirements add up; there is no total cap beyond DP-1's 1024 items
 - Per-source caps enforced in utilities
 - Per-item timing: when no duration is given, video/audio items carry **no** `duration` and `display.loop: false`, so the player advances at end-of-stream (DP-1 §4.1) — the media plays its natural length. Static items use `defaultDuration` (10s unless configured). An explicit duration always wins.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.10.1",
-  "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",