Unicli

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)

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

When meta.update appears, inspect automatic_update. Persistent non-interactive installations schedule the exact release automatically. Confirm with unicli --version before retrying a version-sensitive task. Use unicli upgrade --no-auto-update when the environment requires explicit approval. Non-interactive commands never prompt.

Markdown format (default)

When piped or called by an agent, the default format is md — YAML frontmatter followed by formatted sections. Use -f json for programmatic parsing.

Parse with jq

unicli hackernews top -f json | jq '.[].title'           # WRONG: data is nested
unicli hackernews top -f json | jq '.data[].title'       # correct
unicli hackernews top -f json | jq '.data[] | {title, url}'
unicli xueqiu hot -f json | jq '.data[] | select(.change | tonumber > 5)'

Step 4 — Authentication

unicli uses a strategy cascade that auto-probes on first run. Most sites need no manual setup — the cascade promotes from public → cookie → header automatically.

Strategy ladder

For robust logged-in reuse, prefer the explicit current browser paths:

unicli browser profiles --json
unicli auth import <site> --domain <domain>
unicli browser cookies <domain> --profile-id <id>
unicli browser doctor --json
unicli browser doctor --repair

Auth setup workflow

# First time — unicli guides you through browser login
unicli auth setup twitter

# Verify credentials are stored
unicli auth status twitter

# List all authenticated sites
unicli auth list

# Re-authenticate when cookies expire (exit code 77)
unicli auth setup <site>

Live browser/CDP cookies remain in process memory by default. Explicit imports create plaintext JSON at ~/.unicli/cookies/<site>.json; never read, print, or edit values directly—use unicli auth.

Step 5 — Handle Errors

Exit code → action (primary decision tree)

Failure envelope fields

{
  "ok": false,
  "error": {
    "code": "auth_required",
    "exit_code": 77,
    "message": "No cookie file found for twitter",
    "adapter_path": "adapters/twitter/search.yaml",
    "step": 1,
    "retryable": true,
    "suggestion": "Run `unicli auth setup twitter` to authenticate",
    "remedy": {
      "command": "unicli auth setup twitter",
      "message": "Open browser to complete login"
    }
  }
}

Hard rules

• ALWAYS check ok first before reading data.
• NEVER retry on exit 2 (usage error — fix the args, not the adapter).
• Follow error.remedy.command exactly — it is generated from the adapter schema.
• Load unicli-repair only for established drift codes such as selector_miss, parse_error, empty_result, or a proven endpoint/schema change. Auth, challenge, network, and rate-limit failures are not source repair evidence.

Browser Mode (Escalation Path)

Use browser mode when: a site requires JavaScript rendering, login-gated access, interaction (click/type/scroll), or the API adapter returns exit 69.

unicli browser doctor --json     # probe broker/providers/sessions; starts nothing
unicli browser doctor --repair   # start only the windowless broker
unicli browser start             # lazily acquire a managed hidden target
unicli browser --focus start     # explicit existing-Chrome foreground control
unicli browser status            # broker/provider/session/lease truth
unicli browser open <url>        # navigate to page
unicli browser state             # DOM accessibility tree with [ref] IDs
unicli browser find --css h2     # query specific elements
unicli browser click <ref>       # interact
unicli browser type <ref> "text" # fill input
unicli browser extract           # extract full page text
unicli browser screenshot        # capture to file

For a guided browser automation workflow, load skill unicli-browser.

Browser commands are background-first on macOS and desktop systems. Managed targets are hidden. Existing-Chrome targets use a verified non-activating background contract unless --focus is explicit. Doctor/status/session probes allocate no browser or about:blank target.

Composition Patterns

Multi-source research

# Tech trends: query 3 sources
unicli hackernews top --limit 10 -f json | jq '.data[].title'
unicli reddit hot --limit 10 -f json | jq '.data[].title'
unicli github-trending daily --limit 10 -f json | jq '.data[].name'

Cross-platform topic search

for site in hackernews reddit twitter; do
  echo "=== $site ===" && unicli $site search "AI agents" --limit 5
done

Data pipeline (pipe to jq)

unicli bilibili hot -f json \
  | jq '.data[] | select(.view | tonumber > 1000000) | {title, view, up}'

Budget rule: 1–2 primary sources + 1 supplementary per user question. Never

query the same site twice in one turn.

Skill Routing

Efficiency Rules

1. Default output is md (Markdown). Use -f json for programmatic parsing.
2. Always set --limit — default varies per command (5–50); unset = potentially 100+.
3. MCP server (unicli mcp serve) starts with 4 discovery/run meta-tools. --profile deferred or --expanded projects the loaded adapter catalog; use unicli mcp health -f json for current counts instead of copying them.
4. Adapter user overlay: fixes go to ~/.unicli/adapters/<site>/<cmd>.yaml and survive npm update.
5. unicli doctor checks runtime health (Node version, Chrome, auth files, adapter index). Run it when unexplained failures occur.
6. UNICLI_OUTPUT=json unicli <cmd> sets JSON globally without -f json per call.

Reference Index

MCP Server

unicli mcp serve                    # 4 tools: run, list, search, explore
unicli mcp serve --profile deferred # lightweight stub per adapter operation
unicli mcp serve --expanded         # full-schema tool per adapter operation
unicli mcp serve --profile computer-use # dedicated desktop + browser controls