ff-cli: Start Here
ff-cli is a command-line tool that builds DP-1 playlists from NFT and feed data and displays them on an Art Computer.
Use it when you want the shortest path from a URL, wallet, or set of tokens to visible playback on an Art Computer.
It needs no LLM API key.
First success in minutes
# 1) Install (shortest path)
npm i -g @feralfile/cli
# 2) Register your Art Computer (no prompts). The device ID (FF1-XXXXXXXX) is on
# the TV during Wi-Fi setup and in the Feral File app's device info.
ff-cli setup --non-interactive --device-host http://<device-id>.local:1111 --device-name "Living Room"
# 3) Build a playlist from an artwork or collection URL (or on-chain coords) and display it
ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display -y
You are successful when the works are on display on your Art Computer.
ff-cli find validates the playlist as part of the build, so a separate validate command is optional for this first run. To keep the playlist as a file and display it later:
ff-cli find https://objkt.com/tokens/hicetnunc/111068 -o playlist.json
ff-cli display playlist.json
Prefer to be asked? ff-cli setup with no flags walks you through the same registration.
Want natural language? ff-cli has no built-in chat. Drive it conversationally from a coding agent — Claude Code, Codex, or Cursor — using the ff-control skill; the agent translates your request into ff-cli commands. The home page carries the prompt and setup.
Install options
Primary
npm i -g @feralfile/cli
Alternate: installer (no sudo)
Installs the same npm package under ~/.local and links ff-cli into ~/.local/bin. Use it when a global npm install is refused for permissions. Needs Node.js 22 or newer.
set -o pipefail; curl -fsSL https://feralfile.com/ff-cli-install | bash && export PATH="$HOME/.local/bin:$PATH"
Alternate: one-off with npx
npx @feralfile/cli setup
npx @feralfile/cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --display
Setup options
ff-cli setup with no flags asks for the device address and name. The non-interactive form takes them as flags, and config validate checks the result:
ff-cli setup --non-interactive --device-host http://<device-ip>:1111 --device-name "Living Room"
ff-cli config validate
Setup runs without prompts whenever stdin is not a terminal. It generates a signing key when none is configured and keeps one that is. --generate-key, --key, and --key-file refuse to replace a configured key, because it owns the playlists you published; --force replaces it.
Commands by job
- Build playlist from an artwork or collection URL, on-chain coords, or an artist's address:
ff-cli find <input> - Build playlist from deterministic params, including what a wallet owns:
ff-cli build [params.json](ff-cli build --helplists the requirement types) - Validate a playlist file or URL:
ff-cli validate <file-or-url> - Sign a playlist:
ff-cli sign <file> - Display a playlist file, playlist URL, media URL, or any web page on the Art Computer:
ff-cli display <source>(a page that declares its DP-1 playlist displays the playlist;--webdisplays a page as a page) - Publish to feed server:
ff-cli publish <file> - Replace the playlist already stored under this document id, instead of creating a new one:
ff-cli publish <file> --replace - Save a published playlist from a feed server (the starting point for
--replace):ff-cli fetch <id-or-url> - Delete a playlist from a feed server (signed delete; owner key required):
ff-cli unpublish <id-or-url> - Manage SSH access on the Art Computer:
ff-cli ssh <enable|disable> - Report a problem to Feral File support:
ff-cli report --file <report.txt>(add-d "<name>"and the Art Computer uploads its logs under the same reference) - List configured devices:
ff-cli device list - Add a device:
ff-cli device add --host http://<device-ip>:1111 --name "<name>"(bareff-cli device addtries mDNS discovery) - Remove a device:
ff-cli device remove <name> - Configure and inspect setup:
ff-cli config <init|show|validate>
Every command that takes a signing key with -k, --key <privateKey> also takes --key-file <path>, which reads the same key material from a file instead of the command line. Pass one or the other, not both.
Owner remote maintenance
For an explicitly enrolled FF1 with firmware containing feral-tailscale, ff-cli can use the FF1's
Tailscale IPv4 address as its explicit host. Preserve its physical device ID and
existing name when replacing the configured host; there is no automatic
LAN/Tailscale failover. Persistent owner SSH uses port 2222 and remains separate
from ff-cli ssh, which manages temporary support access on port 22.
See the owner-access procedure. Follow the procedure’s full-image installation checks first. If support is absent, check the normal firmware release channel for availability; enrollment waits until a version containing owner access is published and installed. Tailscale must run on the computer executing the agent; a connected phone does not give a cloud agent access. Required pairing approvals still belong to the owner.
Copy-paste examples
Find from a URL or address
ff-cli find takes a marketplace URL, raw on-chain coordinates, or an artist's address and builds a playlist directly. No LLM API key required.
# Marketplace URL — paste from the artwork or collection page
ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak -o playlist.json
ff-cli find https://objkt.com/tokens/hicetnunc/111068 -o playlist.json
ff-cli find https://feralfile.com/exhibitions/artwork/{id} -o playlist.json
# Raw on-chain coordinates
ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 -o playlist.json
ff-cli find tezos:KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton:111068 -o playlist.json
# Artist address — displays one work by the artist at that address
# (for what a wallet owns, see "Build from structured params" below)
ff-cli find 0xf3860788d1597cecf938424baabe976fac87dc26 -o playlist.json
ff-cli find tz1fQTvvcCy5PTt8HcUSQTu64dH9mJjjDudi -o playlist.json
Supported sources: Objkt, fxhash (/gentk/..., /iteration/{slug}, /project/{slug}, /generative/{slug}), Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse, Raster, plus raw ethereum: / tezos: coords and 0x… / tz1.../tz2.../tz3... addresses.
Combine with --display, --publish, or --output to skip straight to delivery; see ff-cli find --help for the full flag set. In scripts and agents, add -y: without a terminal, a question fails with exit 1 and names the flag that answers it.
Build from structured params
ff-cli build takes a JSON parameters file (or stdin) and builds a playlist deterministically — no network guessing, no LLM. It exits 1 when a requirement finds nothing, named tokenIds do not all resolve, or the send to playlistSettings.deviceName fails. The playlist is still saved when anything was collected.
ff-cli build ./params.json -o playlist.json
What a wallet owns:
echo '{"requirements":[{"type":"query_address","ownerAddress":"0xf3860788d1597cecf938424baabe976fac87dc26","quantity":5}],"playlistSettings":{"title":"My collection"}}' \
| ff-cli build -o wallet.json
A minimal params.json for specific tokens from a contract:
{
"requirements": [
{
"type": "build_playlist",
"blockchain": "ethereum",
"contractAddress": "0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0",
"tokenIds": ["52932", "52457"]
}
]
}
Build from Feral File feed playlists
Feed playlists are fetched by name via a fetch_feed requirement. Pipe params straight to ff-cli build:
echo '{"requirements":[{"type":"fetch_feed","playlistName":"Unsupervised","quantity":3}]}' \
| ff-cli build -o playlist.json
Feed playlist requests depend on configured feed servers and network reachability. The current open-source feed implementation is display-protocol/dp1-feed-v2; see its Quick Start to run your own.
Display on your configured Art Computer
# Local playlist file
ff-cli display playlist.json
# Hosted playlist URL
ff-cli display "https://cdn.example.com/playlist.json"
# Direct media URL
ff-cli display "https://example.com/video.mp4"
# A web page that declares its DP-1 playlist: displays the playlist, not the page
ff-cli display "https://feralfile.com/exhibitions/e-volved-formulae-8an"
# Any other web page
ff-cli display "https://example.com/"
# A page on a marketplace site, as a page (display otherwise sends these to find)
ff-cli display --web "https://feralfile.com/"
A page declares its playlist with one <link> line in its head; Feral File exhibition pages do. To add it to your own pages, see Declare your page's playlist.
display refuses a URL that answers 404 or 410, or whose host does not resolve, so a typo is never cast as an error page.
Common failure points
config validatefails: runff-cli config show, fix the reported values, then re-run validation.displaycannot find device: check device host/name in config and make sure the Art Computer is reachable on your network. On managed networks (museums, offices), see Network Requirements.displayversion error: FF OS is below the minimum supported version for that command; update FF OS and retry.- Signature shape across the ecosystem: ff-cli emits the spec-current
signatures[], but some other tools still emit the legacy top-levelsignature. If you integrate with multiple tools, verify both forms validate as expected.
Deeper references
- Full usage and workflow docs: https://github.com/feral-file/ff-cli/blob/main/docs/README.md
- Configuration reference: https://github.com/feral-file/ff-cli/blob/main/docs/CONFIGURATION.md
- More examples: https://github.com/feral-file/ff-cli/blob/main/docs/EXAMPLES.md
- Agent skill prompt (
ff-control): https://github.com/feral-file/ff-cli/blob/main/skills/ff-control/SKILL.md - DP-1 protocol spec: https://github.com/display-protocol/dp1/blob/main/core/v1.1.0/spec.md
- DP-1 CLI (validate, sign, verify, publish): https://github.com/display-protocol/dp1-cli