3.0.0

Breaking

These change what an existing command or script sees. Each one replaces a silent wrong result with a failure that names the fix (#137, #138).

• setup will not replace a signing key that is already in use. --generate-key, --key, and --key-file refuse when a different key is configured (in config.json, or in PLAYLIST_PRIVATE_KEY when config holds none). That key owns every playlist you published, and publish --replace and unpublish accept only it. Add --force to replace it on purpose. Plain ff-cli setup --non-interactive still makes a key when none exists and keeps one that does.
• Prompts with no answer fail instead of exiting 0. When stdin is not a terminal, a question (for example find's "Build playlist?") exits 1 and names the flag that answers it (find: -y). Before, end-of-input exited 0 with nothing built, and an open pipe waited forever. Piped answers still work.
• build exits 1 when part of the request did not happen. That means a requirement that fails or finds nothing, named tokenIds that do not all resolve, or a failed send to playlistSettings.deviceName. The playlist is still saved when anything was collected.
• play refuses URLs that do not exist. An HTTP 404 or 410, a host that does not resolve, or a .json URL that does not load as a playlist exits 1 before anything is sent. Before, the URL was cast as an error page and reported "Playing". Other read failures (403, 5xx, timeouts) still send, with a note.
• device add treats the same IP on another port as another device. Before, it replaced the existing entry while printing "Added device". .local names still match across ports.
• The installer at https://feralfile.com/ff-cli-install installs from npm. It installs into ~/.local/ff-cli and links ~/.local/bin/ff-cli, and needs Node.js 22+ and npm. Releases no longer ship prebuilt binaries, so the old download 404'd. FF_CLI_BASE_URL is gone; FF_CLI_VERSION, FF_CLI_INSTALL_DIR, and FF_CLI_BIN_DIR still work.

New

• play --web <url> plays any page as a web page, including pages on marketplace sites that play otherwise sends to find (for example https://feralfile.com). Before, play and find pointed at each other for those pages.
• build --help documents the params schema and every requirement type. An unknown type lists the valid ones.
• find on an address says it builds one work by the artist at that address. For what a wallet owns, use build with query_address.
• status names the config paths it checked when it finds none.
• Token source: tokenSource: "raster" reads token data from Raster's public API. It is opt-in and under evaluation; the Feral File indexer stays the default. See docs/CONFIGURATION.md#tokensource.
• IPFS: media on the legacy ipfs.bitmark.com gateway is routed through the Feral File gateway.

Docs and the agent skill

• README, docs/README.md, and the ff-control skill cover the above, plus a bootstrap an agent can finish without a terminal.
• Owner remote maintenance over Tailscale is documented (firmware with feral-tailscale required).
• docs.feralfile.com's Agents and ff-cli pages are updated in feral-file/docs#224.