unicli

One interface. Across real software. Operation-first Agent-Computer Interface for real software.

<a href="https://olo-dot-io.github.io/Uni-CLI/">Website</a> · <a href="https://olo-dot-io.github.io/Uni-CLI/reference/sites">Operations</a> · <a href="https://www.npmjs.com/package/@zenalexa/unicli">npm</a> · <a href="./README.zh-CN.md">简体中文</a>

Uni-CLI discovers executable operations by intent, lets the caller select one declared substrate, and returns an inspectable result. Its catalog reaches APIs, logged-in browsers, desktop applications, local commands, files, operating-system services, and agent protocols without flattening them into one oversized tool.

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

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 | BM25 bilingual search returns a small ranked candidate set | | 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 |

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:

326 sites
1829 registered commands
1226 adapters
113 pipeline actions
9984 tests

Fixed core and host-discovered commands join at runtime.

| Surface | Sites | Operations | Examples | | --- | ---: | ---: | --- | | social | 33 | 372 | twitter, instagram, zhihu, 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 | 180 | codex, cursor, gh, stackoverflow | | ai | 25 | 215 | chatgpt, antigravity, chatwise, notebooklm | | scholarly | 22 | 80 | zotero, openreview, pubmed, arxiv | | patent | 17 | 42 | epo, espacenet, cipo, cnipa | | reference | 12 | 48 | marxists-cn, imdb, anilist, bangumi | | audio | 4 | 46 | spotify, netease-music, xiaoyuzhou, apple-podcasts | | content | 16 | 93 | 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 | 68 | 116 | 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 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.

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.

A minimal YAML adapter:

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.

v1.0.1 — Artemis · Glover

License

Apache-2.0

Summary

Install to Claude Code