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]", "获取", "查询", "抓取".
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.
