unicli-explorer

name	unicli-explorer
description	Create new Uni-CLI adapters by exploring websites and APIs. Use when adding support for a new site, desktop app, or service that unicli doesn't cover yet.
version	1.0.0
triggers	["create adapter","new adapter","add site","explore site"]
allowed-tools	["Bash","Read","Write"]
protocol	2

When to Use

Adding a new website, API, or local app to Uni-CLI's adapter catalog (~20-line YAML files).

Workflow

1. Discover the API

unicli browser start                     # Ensure Chrome is running
unicli operate open <target-url>         # Navigate to target page
unicli operate state                     # Inspect DOM structure
unicli operate network                   # List captured JSON API requests
unicli operate click <ref>               # Trigger lazy-loaded APIs
unicli operate network                   # Check for new requests

2. Choose Strategy

Condition	Strategy	Browser?
fetch(url) returns data	public	No
Needs login cookies	cookie	Yes
Needs CSRF/Bearer token	header	Yes
Complex signed requests	intercept	Yes
No API, DOM only	ui	Yes

3. Write YAML Adapter

Create src/adapters/<site>/<command>.yaml:

site: mysite
name: mycommand
description: What this command does
type: web-api
strategy: public
args:
  query: { type: str, required: true, positional: true }
  limit: { type: int, default: 20 }
pipeline:
  - fetch:
      {
        url: "https://api.example.com/search",
        params: { q: "${{ args.query }}" },
      }
  - select: data.results
  - map: { title: "${{ item.title }}", url: "${{ item.url }}" }
  - limit: ${{ args.limit }}
columns: [title, url]

4. Test

npm run dev -- mysite mycommand "test" --limit 3
npm run verify

5. Self-Repair

When adapters break: read error JSON adapter_path -> fix the ~20-line YAML -> save to ~/.unicli/adapters/<site>/<cmd>.yaml -> unicli test <site>.

Key Pipeline Steps

fetch, fetch_text, parse_rss, html_to_md, select, map, filter, sort, limit, exec, navigate, evaluate, intercept, click, type, wait, press, scroll, snapshot, download, set, if, each, parallel

Pipe Filters

${{ item.field | join(', ') | truncate(100) }} -- available: join, urlencode, slice, replace, lowercase, uppercase, trim, default, split, first, last, length, strip_html, truncate