@feralfile/cli 1.5.0 → 2.0.0

package/docs/README.md

@@ -1,6 +1,6 @@
 # ff-cli Documentation
 
-Build DP-1 (Display Protocol 1) playlists from NFT data with either natural language (AI‑driven) or deterministic parameters. 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 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.
 
 For project-level planning and future agentic work, see `./PROJECT_SPEC.md`.
 
@@ -42,33 +42,6 @@ ff-cli config validate
 
 ```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
-    },
-    "grok": {
-      "apiKey": "xai-your-api-key-here",
-      "baseURL": "https://api.x.ai/v1",
-      "model": "grok-beta",
-      "supportsFunctionCalling": true
-    },
-    "gpt": {
-      "apiKey": "sk-your-openai-key-here",
-      "baseURL": "https://api.openai.com/v1",
-      "model": "gpt-4o",
-      "supportsFunctionCalling": true
-    },
-    "gemini": {
-      "apiKey": "your-gemini-key-here",
-      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
-      "model": "gemini-2.5-flash",
-      "supportsFunctionCalling": true
-    }
-  },
   "defaultDuration": 10,
   "playlist": {
     "privateKey": "your_ed25519_private_key_hex_or_base64_here"
@@ -92,13 +65,13 @@ See `./CONFIGURATION.md` for environment variable mappings.
 ## Quick Start
 
 ```bash
-# Chat
-ff-cli chat
+# 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
 
-# Or natural language in one shot
-ff-cli chat "Get 3 works from reas.eth" -o playlist.json
+# Build and play it on your FF1 in one step
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
 
-# Deterministic (no AI)
+# Build from pre-structured params (JSON file or stdin)
 ff-cli build examples/params-example.json -o playlist.json
 ```
 
@@ -106,38 +79,26 @@ For development in this repo:
 
 ```bash
 npm run build
-node dist/index.js chat
+node dist/index.js find https://objkt.com/tokens/hicetnunc/111068 --play
 ```
 
 If you're running from source without a build, use:
 
 ```bash
-npm run dev -- chat
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play
 ```
 
-## Recommended Deterministic Flow (LLM + Tools)
-
-The model orchestrates; deterministic tools keep us honest and DP1‑conformant.
+## Two ways to build a playlist
 
-1. Input: Share the essentials (contract + token IDs, or feed/URL names).
-2. Orchestration: The LLM parses your prompt and calls tools that:
-   - Fetch NFT metadata via OSS libs (`viem` for Ethereum, `@taquito/taquito` for Tezos)
-   - Validate DP1 schema with `dp1-js`
-   - Build a DP1 playlist envelope deterministically
-   - Optionally sign with Ed25519 (canonical JSON via `dp1-js`)
-3. Preview/send: Send to an FF1 on your LAN over HTTP (recommended). Point `ff1Devices.devices[].host` at a local relay if needed.
-4. Publish: Optional feed/registry publishing via the `publish` command.
+ff-cli is deterministic: no chat, no model orchestration. There are two entry points for assembling a playlist.
 
-Notes:
+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.
+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.
 
-- **Deterministic by design**: Validation rejects bad or hallucinated data; we loop until it's valid or stop.
-- **OSS‑first**: `viem` and `@taquito/taquito`, with room for local caching.
-- **Relay**: Swap the example host for a local Node/Hono relay; avoid vendor lock‑in.
+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)
 
-- `chat [content]` – AI-driven natural language playlists
-  - Options: `-o, --output <file>`, `-m, --model <name>`, `-d, --device <name>`, `-v, --verbose`
 - `build [params.json]` – Deterministic build from JSON or stdin
   - Options: `-o, --output <file>`, `-v, --verbose`
 - `validate <file-or-url>` – Validate playlist structure only
@@ -164,76 +125,63 @@ Notes:
 
 ## Usage Highlights
 
-### Natural language (AI)
+### Find an artwork
 
-```bash
-npm run dev -- chat "Get 3 works from reas.eth"
-npm run dev -- chat "Get 3 works from einstein-rosen.tez"
-npm run dev -- chat "Get tokens 52932,52457 from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0" -o playlist.json
-```
-
-Feed playlists (for example `Unsupervised`, `Social Codes`) depend on your configured feed servers and network reachability.
-Use exact or near-exact playlist titles for best results.
-
-If you prompt with a bare EVM address (for example `from 0x...`), the CLI now tries owner-address lookup first, then automatically falls back to contract lookup when no owned tokens are found.
-
-### One-shot complex prompt
-
-The model reads your request via the intent parser and turns it into structured `requirements` and `playlistSettings` (including shuffle, durations, and device). You can do everything in one line:
+`ff-cli find` resolves a URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist.
 
 ```bash
-# Mix sources, shuffle order, set per-item duration, and send to a named device
-npm run dev -- chat "From Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 get tokens 52932,52457 and from reas.eth get 2 works; shuffle the order; 7 seconds per item; send to device 'Living Room Display'." -o playlist.json -v
-```
+# Paste a URL and play it on your FF1
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
 
-How it works (at a glance):
+# Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
 
-- The intent parser maps your text to `requirements` (what to fetch) and `playlistSettings` (e.g., `durationPerItem`, `preserveOrder=false` for shuffle, `deviceName`, `feedServer`).
-- Deterministic tools fetch NFT metadata, build a DP‑1 playlist, and verify it.
-- If `deviceName` is present, the CLI will send the verified playlist to that FF1 device.
-- If `feedServer` is present (via "publish to my feed"), the CLI will publish the playlist to the selected feed server.
+# Save without playing
+ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 -o send-receive.json
 
-Use `--model claude|grok|gpt|gemini` to switch models, or set `defaultModel` in `config.json`.
+# Wallet address (owner lookup); cap the number of tokens with --limit
+ff-cli find 0xaeE022552B539dB18297D7481b6D547C622488B3 -l 10 -o wallet.json
 
-### Natural language publishing
-
-The intent parser recognizes publishing keywords and can both display and publish in one command:
-
-```bash
-# Build and publish
-npm run dev -- chat "Build playlist from Ethereum contract 0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0 with tokens 52932 and 52457; publish to my feed" -o playlist.json -v
-
-# Display on Art Computer AND publish to feed
-npm run dev -- chat "Get 3 from Unsupervised; shuffle; send to my Art Computer and publish to feed" -o playlist.json -v
+# Build and publish to a configured feed server
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --publish
 ```
 
-For Feral File built playlists, you can reference titles listed in the repository:
-`https://github.com/feral-file/dp1-feed/tree/main/playlists`
+Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses. Run `ff-cli find --help` for the full input list.
 
-Example:
+### Build from structured params
 
 ```bash
-npm run dev -- chat "Get 3 from Unsupervised"
+ff-cli build params.json -o playlist.json
+cat params.json | ff-cli build -o playlist.json
 ```
 
-Publishing keywords: "publish", "publish to my feed", "push to feed", "send to feed". The CLI will:
+`params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`. Each requirement has a `type`:
 
-1. Detect the keyword and call `get_feed_servers`
-2. If multiple servers → ask which one to use
-3. Build → verify → publish automatically
-4. Display playlist ID and server URL on success
+- `build_playlist` — `blockchain`, `contractAddress`, `tokenIds`, optional `quantity`
+- `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`
 
-If all configured feed servers are unreachable, the CLI now reports a feed availability error instead of "playlist not found".
+`playlistSettings` may set `title`, `durationPerItem`, `preserveOrder` (set `false` to shuffle), and `deviceName`. Feed playlists (for example `Unsupervised`, `Social Codes`) depend on your configured feed servers and network reachability; use exact or near-exact playlist titles for best results.
 
-### Deterministic (no AI)
-
-```bash
-npm run dev -- build params.json -o playlist.json
-cat params.json | npm run dev -- build -o playlist.json
+```json
+{
+  "requirements": [
+    {
+      "type": "build_playlist",
+      "blockchain": "ethereum",
+      "contractAddress": "0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0",
+      "tokenIds": ["52932", "52457"]
+    }
+  ],
+  "playlistSettings": {
+    "title": "My Mix",
+    "preserveOrder": false,
+    "durationPerItem": 7
+  }
+}
 ```
 
-`params.json` should include `requirements` and optional `playlistSettings`. See `examples/params-example.json`.
-
 ### Validate, sign, and play
 
 ```bash
@@ -348,7 +296,6 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 
 ## Links
 
-- Function calling details: `./FUNCTION_CALLING.md`
 - Examples: `./EXAMPLES.md`
 - Release assets: `./RELEASING.md`
 - DP1 spec: `https://github.com/display-protocol/dp1`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feralfile/cli",
-  "version": "1.5.0",
-  "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
+  "version": "2.0.0",
+  "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/feral-file/ff-cli.git"
@@ -51,7 +51,7 @@
     "nft",
     "playlist",
     "dp1",
-    "grok",
+    "feralfile",
     "cli"
   ],
   "author": "",
@@ -65,7 +65,6 @@
     "dp1-js": "2.0.0",
     "ff1": "^1.0.0",
     "fuzzysort": "^3.1.0",
-    "openai": "^4.58.1",
     "viem": "^2.38.2"
   },
   "devDependencies": {