jackwener__opencli/docs/developer/yaml-adapter.md

YAML Adapter Guide

YAML adapters are the recommended way to add new commands when the site offers a straightforward API. They use a declarative pipeline approach — no TypeScript required.

Basic Structure

::: v-pre

site: mysite          # Site identifier
name: trending        # Command name (opencli mysite trending)
description: ...      # Help text
domain: www.mysite.com
strategy: public      # public | cookie | header
browser: false        # true if browser session is needed

args:                 # CLI arguments
  limit:
    type: int
    default: 20
    description: Number of items

pipeline:             # Data processing steps
  - fetch:
      url: https://api.mysite.com/trending

  - map:
      rank: ${{ index + 1 }}
      title: ${{ item.title }}

  - limit: ${{ args.limit }}

columns: [rank, title, score, url]

:::

Pipeline Steps

fetch

Fetch data from a URL. Supports template expressions for dynamic URLs.

::: v-pre

- fetch:
    url: https://api.example.com/search?q=${{ args.query }}
    headers:
      Accept: application/json

:::

map

::: v-pre Transform each item in the result array. Use ${{ item.xxx }} for field access and ${{ index }} for position.

- map:
    rank: ${{ index + 1 }}
    title: ${{ item.title }}
    url: https://example.com${{ item.path }}

:::

limit

Truncate results to N items.

::: v-pre

- limit: ${{ args.limit }}

:::

filter

Filter items by condition.

::: v-pre

- filter: ${{ item.score > 100 }}

:::

download

Download media files.

::: v-pre

- download:
    url: ${{ item.imageUrl }}
    dir: ./downloads
    filename: ${{ item.title | sanitize }}.jpg

:::

Template Expressions

::: v-pre Use ${{ ... }} for dynamic values:

Expression	Description
${{ args.limit }}	CLI argument
${{ item.title }}	Current item field
${{ index }}	Current index (0-based)
${{ item.x | sanitize }}	Pipe filters
:::

Real Example

See src/clis/hackernews/top.yaml.