@zenalexa/unicli

Uni-CLI

English · 简体中文

The universal computer-control platform for agents: an agent control plane for real software.

Install once, search by intent, and run the smallest governed operation across websites, browsers, desktop apps, local tools, files, operating systems, and agent protocols. Browser automation, computer-use sandboxes, MCP servers, local code execution, accessibility, screenshots, app wrappers, and external CLIs are action substrates below one loop: intent in, governed action out, evidence back, repair or reroute until the result is delivered.

Docs · Operation catalog · Agent index

_{Native CLI · MCP · ACP · JSON/Markdown envelopes · browser CDP · visual fallback · macOS desktop AX · 313 surfaces · 9117 tests}

One agent-to-computer control loop. Many substrates. One receipt.
Search by intent, act through the best available software boundary, observe the result, and keep the path repairable across CLI, MCP, ACP, CI, and skills.

Install And Run In 30 Seconds

npm install -g @zenalexa/unicli
unicli do "find the Hacker News frontpage"
unicli extract https://example.com --max-chars 1200
unicli compute snapshot --app Calculator --format compact
npx @zenalexa/unicli mcp serve

Agent problem	Uni-CLI answer
"What can control this?"	unicli search and unicli do turn intent into ranked operation plans
"Which boundary should act?"	Web, browser, desktop, subprocess, protocol, and visual substrates share one runtime
"Can I run it safely?"	permission profiles expose open, confirm, and locked execution modes
"What happened?"	every run returns an AgentEnvelope with data, context, retryability, and evidence hooks
"The path failed."	unicli delivery turns run evidence into diagnosis, next experiment, execution, and repair bounds
"Expose it to my agent host."	unicli mcp serve, ACP, native CLI, and JSON streams expose the same operation contracts

Why It Exists

The next software user is not only a person with a mouse. It is an agent with a task, a context window, a permission budget, and a need for evidence. Vehicle assistants work because navigation, media, climate, and driving assistance sit behind a bounded control surface. General computers need the same idea at larger scale: browser state, desktop apps, local tools, files, OS services, accessibility trees, screenshots, protocol servers, and website-specific paths must become one controllable environment.

Uni-CLI is that control surface. It is not a browser library, a computer-use VM, a natural-language shell, an MCP server, or a pile of site wrappers. Those are all useful substrates. Uni-CLI sits above them and turns agent intent into governed software action with an evidence receipt and a repairable path.

The platform combines pieces that usually live apart, but they are not separate product identities:

• operation contracts for reusable actions across websites, apps, OS state, local tools, files, and protocols;
• substrate adapters for HTTP, browser CDP, desktop accessibility, subprocesses, visual fallback, MCP, ACP, and external CLIs;
• an invocation kernel that validates args, evaluates policy, executes through the selected substrate, and returns one envelope;
• an evidence and delivery loop that diagnoses failure, records the next hypothesis, reroutes or repairs, and decides whether the objective is done.

The Computer-Control Loop

Every serious agent operation follows the same loop.

Step	What Uni-CLI gives the agent
Intent	unicli search and unicli do map a task to candidate operations, args, auth mode, examples, and risk signals
Select	operation contracts choose the smallest boundary that can act: API, browser, desktop, subprocess, protocol, visual
Govern	open, confirm, and locked profiles block risky effects before requests, writes, or spawns
Act	the shared kernel invokes the selected substrate instead of forking wrapper-specific behavior
Observe	AgentEnvelope v2 returns data, context, retryability, timing, and evidence hooks
Diagnose	unicli delivery assess classifies failures as product drift, missing context, policy block, or upstream trouble
Repair	unicli delivery trajectory and repair-candidate keep the next experiment bounded by evidence
Deliver	evidence gates decide whether the objective is satisfied, still active, blocked, or exhausted
Expose	the same operation can be called by humans, agents, MCP clients, ACP clients, CI, and scripts

What Makes It Different

If you start from...	You usually get...	Uni-CLI makes it a substrate under...
Browser automation	powerful page control	operation contracts, auth posture, evidence, delivery, and repair
Computer-use sandboxes	screen, mouse, keyboard, and benchmark environments	the same agent-to-computer loop used by local apps, browsers, CLIs, and protocols
Natural-language local execution	flexible shell and code access	typed operation boundaries, policy, receipts, and reusable command contracts
MCP server collections	easy agent attachment but high resident tool weight	a compact search-first path plus MCP profiles when the host requires MCP
Per-app or per-site wrappers	deep access to one surface	one governed runtime across web, desktop, local tools, files, and agent protocols

What It Controls

Uni-CLI treats the computer as the environment and each controllable boundary as a substrate. The substrate can be high-level and typed, or low-level and visual; the receipt remains the same.

Layer	What it controls
Operation contracts	reusable actions with args, output shape, auth posture, safety metadata, source path, and repair path
Web and APIs	public, cookie, header, browser-intercept, download, upload, publish, extract, and search workflows
Browser sessions	CDP navigate/click/type/fill/select/wait/network/screenshot/snapshot/evidence
Desktop and OS	macOS apps, Accessibility refs, screenshots, clipboard, calendar, brightness, app actions, and local system state
Local tools/files	subprocess bridges, external binaries, PDF and paper workflows, file transforms, media tools, and developer CLIs
Agent protocols	native CLI, JSON stream, MCP, ACP, Streamable HTTP, OpenAI-compatible routes, generated configs, and skills
Policy and evidence	permission profiles, deny rules, approvals, run recording, replay, probe, compare, browser session leases, render-aware evidence, movement checks, and stale-ref details
Delivery and repair	unicli delivery assess, run, trajectory, and repair-candidate for objective-level evidence gates, diagnoses, hypotheses, executed attempts, reroutes, and bounded repairs

Built For Agent Runtimes

Uni-CLI is intentionally boring at the boundary. It speaks processes, files, JSON, Markdown, and standard protocols. That makes it usable from agent runtimes, shell scripts, CI, and any host that can spawn a subprocess or attach an MCP server.

The runtime is agent-friendly in ways that matter during long tasks:

• commands are discoverable by intent, not by memorizing names;
• outputs are stable enough to pipe to jq, save as evidence, or feed back into another tool call;
• auth failures, empty results, timeouts, and blocked actions are distinct exit states;
• repair instructions point to the owned file instead of asking the agent to guess what changed upstream;
• generated docs, llms.txt, AGENTS.md, MCP profiles, and skills all describe the same operation contracts.

Capability Map

Layer	Examples
Intent and discovery	search, do, generated operation catalog, docs index, compact catalog, AGENTS surface
Operation contract	args, output, auth posture, effect, safety, capability, source path, repair path
Action substrates	HTTP, RSS, CDP, AX/UIA/AT-SPI, subprocess, visual, protocol, app-specific adapters
Local computer control	compute apps, snapshot, find, click, type, press, scroll, doctor compute
Policy and evidence	permission profiles, deny rules, approvals, run recording, replay, probe, compare
Delivery and repair	objective specs, trajectories, repair candidates, reroutes, evidence gates
Runtime exposure	native CLI, MCP stdio, MCP Streamable HTTP, ACP, package exports, agent skills

For Agents

Use search first, then run the smallest matching command.

unicli search "connect slack messages" --limit 5
unicli slack search "deploy incident" -f json
unicli anilist characters "Sparkle" --limit 5 -f json
unicli danbooru tags sparkle --limit 5 -f json
unicli arxiv download 1706.03762 --output ./papers -f json
unicli pdf read ./papers/1706.03762.pdf --first_page 1 --last_page 3 -f json
unicli macos app-actions --app WhatsApp -f json
unicli macos automation-smoke -f json
unicli repair slack search

Output defaults to structured Markdown for non-TTY and agent-user-agent runs. Force a machine format when you need one:

UNICLI_OUTPUT=json unicli reddit hot --limit 10
unicli hackernews top --limit 5 -f yaml
unicli --record --permission-profile confirm twitter search "coding agents" -f json
unicli runs list -f json
unicli runs show <run_id> -f json
unicli runs probe <run_id> -f json
unicli runs replay <run_id> --permission-profile confirm --yes --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli runs compare <run_id> <replay_run_id> -f json
unicli runs compare <run_id> <replay_run_id> --min-score 1 --min-context-score 1 --min-overall-score 1 -f json
unicli --permission-profile locked --yes --remember-approval word set-font "Inter"
unicli approvals list -f json
unicli approvals revoke <approval_key> -f json
unicli browser evidence --render-aware --expect-domain example.com -f json

Protocol entry points:

npx @zenalexa/unicli mcp serve
npx @zenalexa/unicli mcp serve --transport streamable --port 19826
unicli acp
unicli agents recommend codex
unicli agents matrix

ACP is supported for editors and bridge tooling. The primary runtime path stays native CLI, JSON stream, or MCP when those routes are available.

Local Computer Control

unicli compute controls installed apps through native accessibility, Electron CDP, and visual fallback transports.

unicli compute apps
unicli compute snapshot --app Calculator --format compact
unicli compute find --role button --name 5 --first
unicli compute find --role input --text 8 --first
unicli compute click @e7
unicli doctor compute --json
npx @zenalexa/unicli mcp serve --profile computer-use

Start with Compute, Electron App Control, and Compute Troubleshooting.

Coverage

The catalog is intentionally broad. Every command is discoverable, typed, and repairable. Recent coverage includes scholarly paper download/read workflows, ACG/anime/manga/wiki discovery, booru tag search, visual-novel catalogs, and Japanese/romaji-aware entity lookup.

The wall below is generated from active manifest sites with real logo support. Badge counts exclude quarantined commands. The full generated catalog stays in unicli list and the docs site.

social

video

news

finance

shopping

dev

ai

scholarly

reference

audio

content

productivity

desktop

games

utility

other

See the live catalog:

unicli list
unicli list --site macos
unicli ext list
unicli ext list --tag agent

Browse the same generated catalog on the docs site: https://olo-dot-io.github.io/Uni-CLI/reference/sites

Output Contract

Every normal command returns a v2 envelope. mcp serve and acp are protocol servers and keep their raw stdio protocol.

ok: true
schema_version: "2"
command: "twitter.search"
meta:
  duration_ms: 412
  count: 20
  surface: web
data:
  - { id: "...", text: "...", author: "..." }
error: null

Errors are meant to be acted on:

ok: false
schema_version: "2"
command: "twitter.search"
meta:
  duration_ms: 91
data: null
error:
  code: auth_required
  message: "401 Unauthorized"
  adapter_path: "src/adapters/twitter/search.yaml"
  step: 1
  suggestion: "Run: unicli auth setup twitter"
  retryable: false
  alternatives: ["twitter.timeline", "twitter.profile"]

Exit codes: 0 ok, 66 empty, 69 unavailable, 75 temporary failure, 77 auth, 78 config.

Self-Repair

Adapters are small YAML files by default. A failed command gives an agent enough context to patch the broken part without waiting for a package release.

1. Run the command.
2. Read the error envelope.
3. Open error.adapter_path.
4. Patch the failing step.
5. Save the override in ~/.unicli/adapters/<site>/<command>.yaml.
6. Verify with unicli repair <site> <command>.

Local overrides survive npm updates.

Write An Adapter

site: example
name: search
description: "Search example.com"
transport: http
strategy: public
capabilities: [fetch, select, map, limit]
minimum_capability: http.fetch
trust: public
confidentiality: public
quarantine: false
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]

Docs:

• Documentation site
• Getting started
• Integrations
• Adapter format
• Pipeline reference
• Exit codes

Trust And Limits

• Auth-required sites use local cookie files under ~/.unicli/cookies/<site>.json, with local browser profile import as the first repair path.
• Browser adapters use background-first daemon/CDP sessions. Chrome/CDP runs against Uni-CLI automation profiles under ~/.unicli/; Chrome 136+ blocks remote debugging on the default user-data-dir. RemoteDebuggingAllowed policy can disable remote debugging entirely, but it cannot make default profile CDP supported again.
• unicli browser doctor --json reports default_path, per-check next_step commands, chrome_remote_debugging, and self_repair.safe_command; run unicli browser doctor --repair for the safe local CDP repair without touching the user's default Chrome profile.
• Permission profiles are user-selected runtime policy. The default is open; stricter confirm and locked profiles require --yes or UNICLI_APPROVE=1 for blocked operations. Add --remember-approval with --yes to store the same command capability and resource scope under ~/.unicli/approvals.jsonl. Resource scope covers stable metadata such as domain, account surface, app, process family, and path argument slots. Use unicli approvals list, revoke, and clear to inspect or remove remembered scopes. The file stores scope metadata; runtime args stay out of approval memory.
• Local deny rules live at ~/.unicli/permission-rules.json, or at UNICLI_PERMISSION_RULES_PATH. They match site, command, effect, capability dimensions, and resource metadata, then block before --yes and remembered approvals. Runtime guards also check fetched domains, browser navigation targets, download and output paths, and subprocess executables before the request, write, or process spawn happens.
• Run recording is opt-in. Use --record or UNICLI_RECORD_RUN=1 when you need append-only evidence under ~/.unicli/runs.
• Visual fallback routes require a configured real backend. Declared-but-unavailable providers fail closed with structured errors.
• User adapters and repairs live in ~/.unicli/adapters/; committed adapters remain the package baseline.
• If a site blocks automation or changes a private API, Uni-CLI returns a clear failure envelope.

Development

npm install
npm run typecheck
npm run lint
npm run verify

License

Apache-2.0

_{v0.225.1 — Apollo · Conrad}