arena-cli

name

arena-cli

description

CLI tools for Are.na: export blocks, enrich with vision AI, generate views. Use when: (1) exporting Are.na blocks incrementally, (2) enriching images with AI-generated titles/tags/patterns, (3) generating browsable HTML views, (4) searching blocks by UI patterns or tags, (5) visual search results when terminal output is insufficient. Triggers: "export arena", "enrich arena", "sync arena", "arena view", "search arena for [pattern]", "show me [pattern]".

arena-cli

CLI tools to export, enrich, and browse Are.na blocks locally.

Setup

First-time setup requires:

# In your project directory
echo "ARENA_TOKEN=your_token_here" >> .env
echo "ARENA_USER_SLUG=your_username" >> .env
echo "GEMINI_API_KEY=your_key_here" >> .env

Get your Are.na token from: https://dev.are.na/oauth/applications

Workflow

1. Export    →    2. Enrich    →    3. View/Search
   (blocks)       (vision AI)        (HTML + grep)

1. Export Blocks

# First run - exports all channels
npx ts-node scripts/export-blocks.ts

# Incremental update (only new blocks)
npx ts-node scripts/export-blocks.ts

# Specific channel
npx ts-node scripts/export-blocks.ts --channel=ui-ux-abc123

# With local image download
npx ts-node scripts/export-blocks.ts --images

Output: arena-export/blocks/{id}.json

2. Enrich with Vision AI

# Enrich all image blocks
npx ts-node scripts/enrich-blocks.ts

# Specific channel
npx ts-node scripts/enrich-blocks.ts --channel=ui-ux-abc123

# Preview without saving
npx ts-node scripts/enrich-blocks.ts --dry-run

# Re-enrich already processed
npx ts-node scripts/enrich-blocks.ts --force

Adds to each block:

• vision.suggested_title - Clean title
• vision.description - What's notable
• vision.tags - Searchable tags
• vision.ui_patterns - UI component patterns

3. Generate View

# Generate HTML
node scripts/gen-view.cjs

# Generate and open
node scripts/gen-view.cjs --open

Output: arena-export/view.html

4. Visual Search Results

When terminal output is insufficient (need to see actual images):

# Ad-hoc search - comma-separated patterns
node scripts/gen-search-view.cjs "dashboard,metric-cards" --open

# Multiple search groups
node scripts/gen-search-view.cjs "avatar,profile" "chart,graph" --open

# From config file
node scripts/gen-search-view.cjs --config=searches.json --open

Config file format (searches.json):

[
  { "name": "Dashboards", "patterns": ["dashboard", "metric-cards", "kpi"] },
  { "name": "Charts", "patterns": ["chart", "graph", "visualization"] }
]

Output: arena-export/search-results.html with image grid, grouped by category.

Searching

# Search by UI pattern
grep -l "inline-stats" arena-export/blocks/*.json

# Search by tag
grep -l '"dashboard"' arena-export/blocks/*.json

# Search with context
grep -B2 -A2 "leaderboard" arena-export/blocks/*.json

Block Schema

{
  "id": 12345,
  "title": "original-filename.png",
  "class": "Image",
  "image_url": "https://...",
  "channels": ["ui-ux-abc"],
  "vision": {
    "suggested_title": "Dark Trading Dashboard",
    "description": "Crypto dashboard with real-time charts",
    "tags": ["dashboard", "dark-mode", "trading"],
    "ui_patterns": ["metric-cards", "time-series-chart"]
  }
}

Environment Variables

Variable	Required	Description
ARENA_TOKEN	Yes	Are.na API token
ARENA_USER_SLUG	Yes	Your Are.na username
GEMINI_API_KEY	Yes	Google AI API key
ARENA_EXPORT_DIR	No	Export path (default: ./arena-export)

Customization

To customize the vision enrichment prompt, see references/enrichment-prompt.md.