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]", "获取", "查询", "抓取".
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
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]", "获取", "查询", "抓取".
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
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
error
null on success; structured on failure (see Step 5)
next_actions
HATEOAS hints — valid commands to run next, trust these
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
Strategy
Auth needed
How to set up
public
None
Works out of the box
cookie
Browser login
unicli auth setup <site> → log in once in browser
header
Cookie + CSRF
Same as cookie; auto-extracted per request
intercept
Browser session
unicli browser doctor --repair then unicli auth import <site> --domain <domain>
ui
Browser + interaction
Same; unicli clicks through login flow
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)
Code
Meaning
Action
0
Success
Read data
1
Generic error
Read error.reason + error.suggestion
2
Usage error
Fix arg syntax; run unicli describe <site> <cmd>
66
Empty result
Try different query terms or --limit
69
Service unavailable
unicli browser doctor --json, then doctor --repair
75
Temp failure / timeout
Retry once; if persistent, diagnose network/rate limit
77
Auth required
unicli auth import or explicit browser cookies
78
Config error
Read error.suggestion; check ~/.unicli/ config
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.
Budget rule: 1–2 primary sources + 1 supplementary per user question. Never
query the same site twice in one turn.
Skill Routing
Scenario
Load skill
Adapter fails with structured error envelope
unicli-repair
Search queries across platforms
unicli-smart-search
Browser automation, CDP sessions
unicli-browser
Creating a new adapter from scratch
unicli-explorer
One-shot URL → adapter generation
unicli-oneshot
Claude / Claude.ai commands
unicli-claude
Claude Code commands
unicli-claude-code
Hermes integration
unicli-hermes
Detailed command reference
unicli-usage
Efficiency Rules
Default output is md (Markdown). Use -f json for programmatic parsing.
Always set --limit — default varies per command (5–50); unset = potentially 100+.
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.
Adapter user overlay: fixes go to ~/.unicli/adapters/<site>/<cmd>.yaml
and survive npm update.
unicli doctor checks runtime health (Node version, Chrome, auth files,
adapter index). Run it when unexplained failures occur.
UNICLI_OUTPUT=json unicli <cmd> sets JSON globally without -f json per call.
