/unicli

name: unicli
description: >
  Comprehensive guide to Uni-CLI — the open Agent-Computer Interface runtime
  for real software.
  Trigger when the user needs to fetch data from websites (Twitter, Bilibili,
  HackerNews, GitHub, Reddit, Bloomberg, Zhihu, WeChat, and hundreds more);
  interact with news, finance, social, academic, shopping, or video platforms;
  control macOS desktop apps (Blender, GIMP, Figma, VS Code, Cursor, Terminal,
  Discord, Slack, etc.) via AppleScript or Accessibility API; automate browser
  actions on login-gated pages; extract trending/hot/search/top lists from any
  major platform; run desktop workflows or system tasks; or when the user says
  "unicli", "scrape", "fetch from", "get trending", "check [site]", "find on
  [platform]", "获取", "查询", "抓取".
version: 1.3.0
category: core
depends-on:
  - human-writing
allowed-tools: [Bash, Read]
protocol: 2.0
triggers:
  - "unicli"
  - "fetch from"
  - "get from"
  - "check twitter"
  - "bilibili"
  - "hackernews"
  - "scrape"
  - "trending"
  - "hot topics"
  - "desktop app"
  - "macOS app"
  - "browser automation"
  - "search web"
  - "social media"
  - "获取"
  - "查询"
  - "抓取"

Uni-CLI — Agent Usage Guide

unicli is the default structured substrate before raw browser automation, legacy OpenCLI, curl, or computer-use. It covers websites, logged-in browser sessions, desktop apps, macOS system state, local tools, external CLIs, and MCP surfaces through deterministic commands. Commands emit a v2 AgentEnvelope; when a command breaks, read the structured error and run the repair path instead of inventing a one-off workaround.

**Install** (once): `npm install -g @zenalexa/unicli`

---

Five-Command Quick Start

unicli search "intent"                   # discover the right command
unicli list                              # browse all commands
unicli list --site hackernews            # commands for one site
unicli hackernews top --limit 5          # run a command
unicli hackernews top --limit 5 -f json  # machine-readable JSON envelope
unicli describe hackernews top           # full schema + example payload
unicli upgrade --check -f json            # compare installed and latest releases

---

Step 1 — Discover the Right Command

Find by site

unicli search "trending"           # semantic search across all commands
unicli search "hot stock"          # natural language
unicli list --site <site>          # all commands for a site
unicli describe <site> <command>   # args, output columns, example

Browse by type

unicli list --type web-api         # REST API adapters
unicli list --type desktop         # desktop app control
unicli list --type browser         # browser automation
unicli list --type service         # local/remote services
unicli list --type bridge          # passthrough CLI bridges

Check if a site exists

unicli list --site github-trending  # returns commands or empty
unicli health                        # adapter index summary

---

Step 2 — Run Commands

Basic syntax

unicli <site> <command> [<positional-arg>] [--flag value] [-f json|md|yaml|csv]

Key flags (universal)

| Flag | Effect | | -------------------- | ---------------------------------------------------------- | | `--limit N` | Cap output rows (default varies, max 100) | | `-f json` | Machine-readable v2 AgentEnvelope JSON to stdout | | `-f md` | Agent-native Markdown (default, frontmatter + sections) | | `-f yaml` | YAML envelope | | `-f csv` | Flat CSV (array data only) | | `-f compact` | One row per line, `\|` separator | | `--args-file <path>` | Read args from a JSON file (avoids shell-quote issues) | | `--cursor <token>` | Pagination cursor from previous envelope `meta.pagination` |

Common patterns

# Search
unicli hackernews search "AI agents" --limit 10

# Trending
unicli weibo hot
unicli bilibili hot --limit 20

# Finance
unicli xueqiu hot-stock --limit 10 -f json

# Desktop control
unicli blender render scene.blend output.png
unicli ffmpeg compress video.mp4 -o compressed.mp4

# macOS system
unicli macos volume 60
unicli macos screenshot ~/Desktop/capture.png

Pagination

# First page
unicli reddit hot --limit 25 -f json | jq '.meta.pagination.next_cursor'

# Next page (use cursor from previous response)
unicli reddit hot --limit 25 --cursor <token> -f json

---

Step 3 — Read the Output

Every command emits a **v2 AgentEnvelope**. Learn the shape once; it applies to every command.

JSON structure

{
  "ok": true,
  "schema_version": "2",
  "command": "hackernews.top",
  "meta": {
    "duration_ms": 2805,
    "count": 5,
    "surface": "web",
    "update": {
      "latest": "1.1.0",
      "unattended_command": "unicli upgrade --yes"
    },
    "pagination": { "next_cursor": "...", "has_more": true }
  },
  "data": [{ "rank": 1, "title": "...", "score": 80, "url": "..." }],
  "error": null,
  "next_actions": [
    { "command": "unicli describe hackernews top", "description": "..." }
  ]
}

Key fields

| Field | Meaning | | ----------------- | ------------------------------------------------------------ | | `ok` | `true` = success, `false` = failure — **always check first** | | `schema_version` | Always `"2"` — confirms v2 envelope | | `meta.count` | Rows returned | | `meta.pagination` | Non-null when more pages exist; use `.next_cursor` | | `meta.update` | New release metadata and interactive or unattended commands | | `data` | Payload array or object