@zenalexa/unicli

Uni-CLI

Give agents every interface
Install once. Search, run, inspect, repair.

Website   Operations   npm   简体中文

Uni-CLI turns intent into a selected operation and a structured receipt across web, browser, desktop, local, and MCP surfaces.

npm install -g @zenalexa/unicli
unicli search "list the top Hacker News stories"
unicli hackernews top --limit 3 -f json

Check releases or open an interactive Y/N update choice.

unicli upgrade --check -f json
unicli upgrade

Persistent non-interactive Agent installations update in a detached worker by default. Structured output reports progress through meta.update.automatic_update. Interactive terminals keep the Y/N choice, and unicli upgrade --no-auto-update switches a machine back to explicit approval.

Route By Task

The catalog handles discovery and operation contracts. Execution then selects the strongest operator with the smallest effective scope. One provider runs; a failed path keeps its original cause and repair command.

Task boundary	Execution operator	Why
Public data or stable service contract	Structured API	Typed fields, explicit auth, stable provenance
Files, system state, local tools	Local runtime	Direct process and OS boundaries without browser state
Authenticated or private web contract	Browser protocol	Explicit profile, cookie session, or network contract
Page-only web flow	Semantic browser	DOM and CDP semantics with an explicit target and session
Native desktop application	Accessibility	Structured AX, UIA, or AT-SPI control trees
Pixel-only or unstructured interface	Visual computer use	Coordinate and visual observation when no stronger interface exists

unicli search "export my saved posts"     # discover and rank
unicli list --site reddit                  # inspect one surface
unicli browser doctor --json               # inspect browser delivery state
unicli repair reddit saved                 # verify a supported drift path

The Operation Contract

The public model stays compact.

intent → candidate operations → explicit selection → policy → substrate → receipt

Stage	Runtime behavior
Discover	Compiled intent and bilingual retrieval return a small ranked set with selection evidence
Select	The caller chooses one operation with a declared strategy and substrate
Govern	open, confirm, and locked profiles evaluate effect and capability scope
Act	The selected adapter, core command, browser, desktop, or protocol path executes
Observe	Every normal command returns a stable success or error envelope
Repair	Owned drift paths expose their source, failed boundary, and bounded verification command
Evolve	Recorded failures become isolated candidates that must pass paired and held-out evaluation

Uni-CLI supplies the interface runtime. The model, planner, agent loop, and sandbox remain independent choices.

Surfaces

Surface	Current runtime
Web	Public data, cookies, headers, downloads, uploads, publishing, search, and Chinese platforms
Browser	CDP navigation, semantic action, network, snapshots, screenshots, and post-action evidence
Desktop	Native controls, macOS services, design tools, Office, and media applications
Local	Subprocess bridges, files, PDF and paper workflows, media transforms, and developer CLIs
Protocols	Native CLI, MCP stdio, MCP Streamable HTTP, ACP, generated configs, and agent skills
Policy	Permission profiles, deny rules, scoped approvals, recordings, replay, and evidence

Static catalog

• 338 sites
• 1891 registered commands
• 1268 adapters
• 113 pipeline actions
• 10392 tests

Fixed core and host-discovered commands join at runtime.

Surface	Sites	Operations	Examples
social	33	396	twitter, zhihu, instagram, reddit
video	8	75	tiktok, youtube, bilibili, douyin
news	11	45	hackernews, bloomberg, bbc, 36kr
finance	10	67	eastmoney, xueqiu, binance, coingecko
shopping	13	47	amazon, jd, taobao, 1688
dev	37	185	codex, cursor, gh, stackoverflow
ai	25	215	chatgpt, antigravity, chatwise, notebooklm
scholarly	30	105	openreview, zotero, pubmed, arxiv
patent	17	42	epo, espacenet, cipo, cnipa
reference	12	47	marxists-cn, anilist, bangumi, imdb
audio	4	46	spotify, netease-music, xiaoyuzhou, apple-podcasts
content	16	90	lesswrong, danbooru, dlsite, weread
productivity	10	78	notion-app, ones, obsidian, quark
jobs	6	42	nowcoder, boss, 51job, linkedin
desktop	25	201	macos, freecad, blender, gimp
games	1	7	steam
utility	7	29	linear, bitwarden, todoist, qweather
other	72	123	slay-the-spire-ii, xiaoe, archive, ke
travel	1	4	ctrip

The generated operation catalog is the authoritative inventory.

Use It From An Agent

Native CLI

unicli search "download the latest arXiv paper on computer use" -f json
unicli arxiv search "computer use agents" --limit 5 -f json
unicli --auth-retry openreview conference "ICML.cc/2026/Conference" --rpm 20 -f json
unicli extract https://example.com --max-chars 1200

Piped output defaults to Markdown. Use -f json, yaml, csv, or compact when the next step needs a stable machine format. The OpenReview archive guide covers authenticated, resumable conference and multi-year research archives.

MCP

{
  "mcpServers": {
    "unicli": {
      "command": "npx",
      "args": ["-y", "@zenalexa/unicli-mcp"]
    }
  }
}

Equivalent command

npx -y @zenalexa/unicli mcp serve

The default profile exposes four meta-tools. Deferred and expanded profiles project adapter operations when the host needs tool-level discovery. Inspect the live projection with unicli mcp health -f json.

Local Computer

unicli compute apps --format compact
unicli compute snapshot --app Calculator --format compact
unicli compute find --app Calculator --role AXButton --title "7"
unicli compute click --ref <ref-from-find>

Desktop actions prefer accessibility references. Visual routes require an explicitly selected backend and never appear as a hidden fallback.

Results That Explain Themselves

Success

ok: true
schema_version: "2"
command: "hackernews.top"
meta:
  duration_ms: 412
  count: 3
  surface: web
data:
  - { rank: "1", title: "...", url: "...", author: "..." }
error: null

Failure

ok: false
schema_version: "2"
command: "reddit.saved"
data: null
error:
  code: auth_required
  adapter_path: "src/adapters/reddit/saved.yaml"
  step: 1
  suggestion: "Run: unicli auth setup reddit"
  retryable: false

Exit codes distinguish success, empty results, unavailable dependencies, temporary failures, auth, and configuration. See the output and exit-code reference.

Repair Drift At The Owned Boundary

Adapters stay agent-readable and locally replaceable.

run → read error.adapter_path → patch the owned step → save override → verify once

unicli repair <site> <command>

repair does not edit source or Git state. It reruns the original command as a bounded subprocess and succeeds only when the target returns ok: true with exit code 0. Local overrides under ~/.unicli/adapters/ survive npm updates.

For repeated failures, evolve adapter keeps proposal evidence, validation, and held-out cases separate. The agent supplies one isolated YAML candidate and a falsifiable prediction. Uni-CLI runs paired baseline and candidate evaluations, records prediction misses and regressions, and installs a user override only after the promotion gate passes.

unicli evolve adapter <site> <command> \
  --run <proposal-run> \
  --candidate <candidate.yaml> \
  --hypothesis "<expected mechanism>" \
  --expect <validation-case-id> \
  --risk <held-out-case-id> \
  --validation <validation-eval.yaml> \
  --held-out <held-out-eval.yaml> \
  --promote

Without --candidate, the command creates an editable draft. Every verification preserves its candidate snapshot, patch, and report as one hash-checked attempt. evolve verify --promote reuses the latest eligible attempt when the candidate is unchanged. Promotion and rollback recover after an interrupted write and serialize competing Agent processes. evolve inspect returns the complete attempt history, reports corrupt sessions, and evolve rollback restores the exact pre-promotion overlay.

The first evolution scope keeps the operation identity, input and output contracts, pipeline action topology, request methods and headers, and existing subprocess invocations fixed. Same-origin endpoint and extraction repairs remain editable. A replacement network origin requires an explicit --allow-origin <origin> declaration when the session is created.

A minimal YAML adapter follows.

site: example
name: search
description: Search example.com
transport: http
strategy: public
pipeline:
  - fetch: { url: "https://api.example.com/search?q=${{ args.query }}" }
  - select: data.results
  - map: { title: "${{ item.title }}", url: "${{ item.url }}" }
  - limit: "${{ args.limit }}"
args:
  - { name: query, type: string, required: true, positional: true }
  - { name: limit, type: int, default: 20 }
columns: [title, url]

Read the adapter format, pipeline reference, and self-repair guide.

Trust Boundaries

• Live browser cookies remain in process memory unless the user explicitly runs auth import or browser cookies.
• Browser automation uses Uni-CLI-owned profiles under ~/.unicli/. Chrome 136+ does not support remote debugging on its default user-data directory.
• unicli browser doctor --json reports the available delivery path and exact repair command without starting a browser provider.
• Permission rules authorize before browser, file, clipboard, subprocess, or desktop side effects. Explicit malformed policies fail closed.
• Visual routes require a real configured backend. Missing providers return a structured error.
• Invocation diagnostics exclude arguments, content, URLs, credentials, and raw errors; users can disable new events with UNICLI_NO_LOG=1.

The detailed behavior and storage paths live in Trust, Auth, and Limits.

Development

npm install
npm run typecheck
npm run lint
npm test
npm run verify   # full E2E and adapter coverage; required before release

Requires Node.js 22.19 or newer. See CONTRIBUTING.md for adapter and engine conventions.

Browse every published version on the generated release history. The same data is available to Agents through docs/public/release-history.json.

_{v1.2.1 — Artemis · Wiseman}

License

Apache-2.0