@feralfile/cli 1.1.4 → 1.3.0

package/README.md

@@ -44,6 +44,56 @@ ff-cli config init
 ff-cli config validate
 ```
 
+## 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.
+
+```bash
+# Most satisfying: paste a URL, play it on your FF1
+ff-cli find https://www.artblocks.io/collection/ringers-by-dmitri-cherniak --play
+
+# Tezos / hic et nunc via Objkt (the alias resolves to a KT1 contract)
+ff-cli find https://objkt.com/tokens/hicetnunc/111068 --play
+
+# 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
+
+# Save without playing
+ff-cli find ethereum:0xababababab20053426ad1c782de9ea8444358070:5001410 --output send-receive.json
+```
+
+Sources: Art Blocks, Objkt, fxhash (canonical `/gentk/...`, live `/iteration/{slug}`, and project pages `/project/{slug}` / `/generative/{slug}`), OpenSea, SuperRare, Feral File, Neort (`/art/{id}`), raw on-chain coords, wallet addresses. Run `ff-cli find --help` for the full input list.
+
+**Known limitations**
+
+- **CryptoPunks (original)** don't index — the contract predates ERC-721 ([ff-indexer-v2#83](https://github.com/feral-file/ff-indexer-v2/issues/83)).
+- **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`.
+
+## Use with Claude Code
+
+ff-cli ships a [Claude Code](https://docs.claude.com/en/docs/claude-code) skill at `skills/ff-control/SKILL.md`. Install it once:
+
+```bash
+git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
+  && mkdir -p ~/.claude/skills \
+  && cp -r /tmp/ff-cli/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).
+
+## Use with Codex
+
+ff-cli ships the same `ff-control` skill in Codex's native skill format. Install it once:
+
+```bash
+git clone --depth=1 https://github.com/feral-file/ff-cli /tmp/ff-cli \
+  && mkdir -p ~/.codex/skills \
+  && cp -r /tmp/ff-cli/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).
+
 ## Dev Quick Start
 
 **Set your LLM API key first (default Claude):** `export ANTHROPIC_API_KEY='sk-ant-your-api-key-here'`

package/dist/index.js

@@ -19,6 +19,7 @@ const validate_1 = require("./src/commands/validate");
 const sign_1 = require("./src/commands/sign");
 const play_1 = require("./src/commands/play");
 const publish_1 = require("./src/commands/publish");
+const find_1 = require("./src/commands/find");
 const build_1 = require("./src/commands/build");
 const config_1 = require("./src/commands/config");
 const ssh_1 = require("./src/commands/ssh");
@@ -32,11 +33,11 @@ try {
 catch {
     packageJsonPath = (0, path_1.resolve)((0, path_1.dirname)(__filename), 'package.json');
 }
-const { version: packageVersion } = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, 'utf8'));
+const { version: packageVersion, description: packageDescription } = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, 'utf8'));
 const program = new commander_1.Command();
 program
     .name('ff-cli')
-    .description('CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)')
+    .description(packageDescription)
     .version(packageVersion)
     .addHelpText('after', `\nQuick start:\n  1) ff-cli setup\n  2) ff-cli chat\n\nDocs: https://github.com/feral-file/ff-cli\n`);
 program.addCommand(setup_1.setupCommand);
@@ -47,6 +48,7 @@ program.addCommand(validate_1.validateCommand);
 program.addCommand(sign_1.signCommand);
 program.addCommand(play_1.playCommand);
 program.addCommand(publish_1.publishCommand);
+program.addCommand(find_1.findCommand);
 program.addCommand(build_1.buildCommand);
 program.addCommand(config_1.configCommand);
 program.addCommand(ssh_1.sshCommand);

package/dist/package.json

@@ -0,0 +1,84 @@
+{
+    "name": "@feralfile/cli",
+    "version": "1.3.0",
+    "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/feral-file/ff-cli.git"
+    },
+    "homepage": "https://github.com/feral-file/ff-cli#readme",
+    "bugs": {
+        "url": "https://github.com/feral-file/ff-cli/issues"
+    },
+    "main": "dist/index.js",
+    "bin": {
+        "ff-cli": "dist/index.js"
+    },
+    "files": [
+        "dist",
+        "docs",
+        "config.json.example",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "clean": "node -e \"const fs=require('fs'); fs.rmSync('dist',{ recursive:true, force:true }); fs.rmSync('release',{ recursive:true, force:true });\"",
+        "build": "tsc",
+        "typecheck": "tsc --noEmit",
+        "bundle": "node build.js",
+        "bundle:dev": "node build.js --dev",
+        "release:asset": "./scripts/release/build-asset.sh",
+        "prepare": "husky",
+        "start": "node dist/index.js",
+        "dev": "tsx index.ts",
+        "smoke": "npm run build && node dist/index.js validate examples/sample-playlist-v11.json && node dist/index.js config validate",
+        "check": "npm run format:check && npm run lint && npm run test",
+        "verify": "npm run check && npm run smoke",
+        "prepublishOnly": "npm run verify",
+        "test": "node scripts/run-tests.js",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write \"**/*.{js,ts}\"",
+        "format:check": "prettier --check \"**/*.{js,ts}\""
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "nft",
+        "playlist",
+        "dp1",
+        "grok",
+        "cli"
+    ],
+    "author": "",
+    "license": "MIT",
+    "dependencies": {
+        "axios": "^1.6.2",
+        "bonjour-service": "^1.3.0",
+        "chalk": "^4.1.2",
+        "commander": "^11.1.0",
+        "dotenv": "^16.3.1",
+        "dp1-js": "2.0.0",
+        "ff1": "^1.0.0",
+        "fuzzysort": "^3.1.0",
+        "openai": "^4.58.1",
+        "viem": "^2.38.2"
+    },
+    "devDependencies": {
+        "@types/node": "^24.7.1",
+        "@typescript-eslint/eslint-plugin": "^8.46.0",
+        "@typescript-eslint/parser": "^8.46.0",
+        "esbuild": "^0.25.10",
+        "eslint": "^9.36.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.4",
+        "husky": "^9.1.7",
+        "prettier": "^3.6.2",
+        "tsx": "^4.20.6",
+        "typescript": "^5.9.3"
+    }
+}

package/dist/src/ai-orchestrator/index.js

@@ -116,7 +116,7 @@ const functionSchemas = [
         type: 'function',
         function: {
             name: 'query_requirement',
-            description: 'Query data for a requirement. Supports build_playlist (blockchain NFTs), query_address (all NFTs from address), and fetch_feed (feed playlists) types.',
+            description: 'Query data for a requirement. Supports build_playlist (blockchain NFTs), feral_file_artwork (Feral File artwork IDs/URLs), query_address (all NFTs from address), and fetch_feed (feed playlists) types.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -126,7 +126,7 @@ const functionSchemas = [
                         properties: {
                             type: {
                                 type: 'string',
-                                enum: ['build_playlist', 'fetch_feed', 'query_address'],
+                                enum: ['build_playlist', 'feral_file_artwork', 'fetch_feed', 'query_address'],
                                 description: 'Type of requirement',
                             },
                             blockchain: {
@@ -144,6 +144,10 @@ const functionSchemas = [
                                     type: 'string',
                                 },
                             },
+                            artworkId: {
+                                type: 'string',
+                                description: 'Feral File public artwork id or /exhibitions/artwork/{id} URL (REQUIRED for feral_file_artwork)',
+                            },
                             ownerAddress: {
                                 type: 'string',
                                 description: 'Owner wallet address (0x... for Ethereum, tz... for Tezos) - REQUIRED for query_address',
@@ -457,6 +461,9 @@ function buildOrchestratorSystemPrompt(params) {
         if (req.type === 'fetch_feed') {
             return `${i + 1}. Fetch ${req.quantity || 5} items from playlist "${req.playlistName}"`;
         }
+        else if (req.type === 'feral_file_artwork') {
+            return `${i + 1}. Resolve Feral File artwork ${req.artworkId}`;
+        }
         else if (req.type === 'query_address') {
             const quantityText = req.quantity === 'all' ? 'all ' : req.quantity ? req.quantity + ' random ' : 'all ';
             return `${i + 1}. Query ${quantityText}tokens from address ${req.ownerAddress}`;
@@ -512,6 +519,8 @@ DECISION LOOP
 1) For each requirement in order:
    - build_playlist: call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
      Returns array with minimal item data including id field. Collect the id values.
+   - feral_file_artwork: call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
+     Returns array with minimal item data including id field. Collect the id values.
    - query_address:
      • if ownerAddress endsWith .eth/.tez → resolve_domains([domain]); if resolved → use returned address; if not → mark failed and continue.
      • if ownerAddress is 0x…/tz… → call query_requirement(requirement, duration=${playlistSettings.durationPerItem || 10}).
@@ -599,6 +608,9 @@ async function buildPlaylistWithAI(params, options = {}) {
             if (req.type === 'fetch_feed') {
                 return `${i + 1}. Fetch ${req.quantity || 5} items from playlist "${req.playlistName}"`;
             }
+            else if (req.type === 'feral_file_artwork') {
+                return `${i + 1}. Resolve Feral File artwork:\n   - artworkId: "${req.artworkId}"`;
+            }
             else if (req.type === 'query_address') {
                 const quantityDesc = req.quantity === 'all'
                     ? 'all tokens (with pagination)'

package/dist/src/commands/build.js

@@ -35,9 +35,9 @@ exports.buildCommand = new commander_1.Command('build')
             if (!stdin.trim()) {
                 console.error(chalk_1.default.red('No parameters provided'));
                 console.log(chalk_1.default.yellow('\nUsage:'));
-                console.log('  ff1 build params.json');
-                console.log('  cat params.json | ff1 build');
-                console.log('  echo \'{"requirements":[...]}\' | ff1 build');
+                console.log('  ff-cli build params.json');
+                console.log('  cat params.json | ff-cli build');
+                console.log('  echo \'{"requirements":[...]}\' | ff-cli build');
                 process.exit(1);
             }
             params = JSON.parse(stdin);

package/dist/src/commands/chat.js

@@ -69,12 +69,12 @@ exports.chatCommand = new commander_1.Command('chat')
             validation.errors.forEach((error) => {
                 console.error(chalk_1.default.red(`  • ${error}`));
             });
-            console.log(chalk_1.default.yellow('\nRun: ff1 setup\n'));
+            console.log(chalk_1.default.yellow('\nRun: ff-cli setup\n'));
             process.exit(1);
         }
         // Non-interactive mode: content was passed as a positional argument.
         if (content) {
-            console.log(chalk_1.default.blue('\nFF1 Chat (non-interactive)\n'));
+            console.log(chalk_1.default.blue('\nff-cli chat (non-interactive)\n'));
             console.log(chalk_1.default.dim(`Model: ${modelName}\n`));
             console.log(chalk_1.default.yellow('Request:'), content);
             console.log();
@@ -103,7 +103,7 @@ exports.chatCommand = new commander_1.Command('chat')
             }
         }
         // Interactive mode.
-        console.log(chalk_1.default.blue('\nFF1 Chat\n'));
+        console.log(chalk_1.default.blue('\nff-cli chat\n'));
         console.log(chalk_1.default.dim('Describe the playlist you want. Ctrl+C to exit.'));
         console.log(chalk_1.default.dim(`Model: ${modelName}\n`));
         console.log(chalk_1.default.dim('Examples:'));

package/dist/src/commands/config.js

@@ -9,7 +9,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../config");
 // `config` is a single command with an action argument rather than a
 // commander subcommand group. Kept this way to preserve the existing
-// CLI surface (`ff1 config init|show|validate`) used in scripts.
+// CLI surface (`ff-cli config init|show|validate`) used in scripts.
 exports.configCommand = new commander_1.Command('config')
     .description('Manage configuration')
     .argument('<action>', 'Action: init, show, or validate')
@@ -20,7 +20,7 @@ exports.configCommand = new commander_1.Command('config')
             const { userPath } = (0, config_1.getConfigPaths)();
             const configPath = await (0, config_1.createSampleConfig)(userPath);
             console.log(chalk_1.default.green(`Created ${configPath}`));
-            console.log(chalk_1.default.yellow('\nNext: ff1 setup\n'));
+            console.log(chalk_1.default.yellow('\nNext: ff-cli setup\n'));
         }
         else if (action === 'show') {
             const config = (0, config_1.getConfig)();

package/dist/src/commands/device.js

@@ -24,14 +24,14 @@ deviceCommand
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
             console.log(chalk_1.default.red('config.json not found'));
-            console.log(chalk_1.default.dim('Run: ff1 setup'));
+            console.log(chalk_1.default.dim('Run: ff-cli setup'));
             process.exit(1);
         }
         const config = await (0, config_files_1.readConfigFile)(configPath);
         const devices = config.ff1Devices?.devices || [];
         if (devices.length === 0) {
             console.log(chalk_1.default.yellow('\nNo devices configured'));
-            console.log(chalk_1.default.dim('Run: ff1 device add'));
+            console.log(chalk_1.default.dim('Run: ff-cli device add'));
             console.log();
             return;
         }
@@ -82,7 +82,7 @@ deviceCommand
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
             console.log(chalk_1.default.red('config.json not found'));
-            console.log(chalk_1.default.dim('Run: ff1 setup'));
+            console.log(chalk_1.default.dim('Run: ff-cli setup'));
             process.exit(1);
         }
         const config = await (0, config_files_1.readConfigFile)(configPath);
@@ -155,7 +155,7 @@ deviceCommand
         if (nameConflict) {
             if (options.name) {
                 console.error(chalk_1.default.red(`\nError: device name "${deviceName}" is already used by another device (${nameConflict.host}).`));
-                console.error(chalk_1.default.dim('Use a different name or run "ff1 device remove" first.'));
+                console.error(chalk_1.default.dim('Use a different name or run "ff-cli device remove" first.'));
                 closePrompt();
                 process.exit(1);
             }
@@ -241,14 +241,14 @@ deviceCommand
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
             console.log(chalk_1.default.red('config.json not found'));
-            console.log(chalk_1.default.dim('Run: ff1 setup'));
+            console.log(chalk_1.default.dim('Run: ff-cli setup'));
             process.exit(1);
         }
         const config = await (0, config_files_1.readConfigFile)(configPath);
         const existingDevices = config.ff1Devices?.devices || [];
         if (existingDevices.length === 0) {
             console.log(chalk_1.default.yellow('\nNo devices configured'));
-            console.log(chalk_1.default.dim('Run: ff1 device add\n'));
+            console.log(chalk_1.default.dim('Run: ff-cli device add\n'));
             process.exit(1);
         }
         let result;