@zenalexa/unicli

Uni-CLI

English · 简体中文

The open Agent-Computer Interface runtime for real software.

One searchable boundary between agents and websites, logged-in browsers, desktop apps, local tools, files, operating-system services, and agent protocols. Uni-CLI ranks cataloged operations by intent, runs the selected operation through its declared software substrate under policy, wraps the result in a stable success/error envelope, and keeps failure diagnosable and repairable.

Docs · Operation catalog · Agent index

_{Native CLI · MCP · ACP · JSON/Markdown envelopes · task-directed operators · browser CDP · explicit visual control · macOS desktop AX · 326 static adapter surfaces · 9984 tests}

Find the operation. Cross the boundary. Keep the outcome inspectable.
Discover → select → govern → act → observe → repair.

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

The agent needs to know...	Uni-CLI answer
What can act on this task?	unicli search and plan-only unicli do retrieve a small ranked set; the agent explicitly invokes one result
Which boundary will act?	Each operation declares its strategy and substrate: API, file, CLI, browser, desktop, protocol, or visual
What will the action affect?	Operation contracts expose arguments, auth, capability scope, effect, risk, and approval posture
What did the call return?	AgentEnvelope always distinguishes success from error; supporting operations add artifacts, recordings, or post-state evidence
The path drifted—what now?	Structured errors can name the owned source, failed step, retryability, alternatives, and next repair command
How does my agent call it?	Native CLI is canonical; MCP projects adapter operations through default, deferred, or expanded profiles

Why It Exists

Models are only half of an agent system. The other half is the interface they use to perceive state, choose actions, cross software boundaries, and interpret feedback. Human interfaces are optimized for eyes, hands, and memory. Raw APIs and giant tool lists are optimized for developers or protocols. Neither is a complete interface for a model with a bounded context window and a task to finish.

Uni-CLI owns that missing boundary: the Agent-Computer Interface (ACI). It does not choose the model or orchestrate the agent's reasoning. It makes real software discoverable and operable, then returns structured results the agent can inspect. Evidence-capable operations can additionally record artifacts, state deltas, or trajectories. Browser automation, app harnesses, MCP, WebMCP, accessibility, subprocesses, and visual control remain replaceable substrates below the interface.

The Agent-Computer Interface Loop

The six verbs are the compact product story. The executable architecture stays more explicit: unicli architecture audit reports nine runtime stages — intent, select, govern, act, observe, diagnose, repair-or-reroute, deliver, and expose.

Product concern	Current runtime truth
Discover	search and plan-only do rank candidate operations from intent; neither command performs the external action
Select	the agent or caller selects an operation whose contract declares a strategy and substrate; Uni-CLI does not yet arbitrate all alternatives
Govern	open, confirm, and locked profiles evaluate supported operation effects and capability scopes
Act	adapter commands run through the shared adapter kernel; fixed core commands keep their own native CLI handlers
Observe	every rendered call has a stable success/error envelope; operation-specific evidence is optional and never inferred from dispatch alone
Repair	structured errors and delivery tools can bound a diagnosis, reroute, or verification attempt where the operation supplies that context

diagnose and deliver make observation actionable; expose projects the runtime into agent-facing entry points. Adapter operations are shared by native CLI and the MCP profiles. Fixed core commands are currently canonical on the native CLI; command-by-command protocol parity is an explicit roadmap item.

What Makes It Different

If you start from...	It is excellent at...	Uni-CLI's distinct boundary
App/site-to-CLI harnesses	creating a deep structured interface for one surface	discovering and running many interfaces through one catalog and structured failure model
Browser agents or browser MCP	perceiving, planning, and acting inside a browser	using browser control as one substrate without becoming the model or planner
Hosted SaaS integration platforms	managed OAuth, users, triggers, and cloud toolkits	open, local-first access to the user's actual browser, desktop, files, and local tools
MCP registries and operations systems	cataloging, running, proxying, or governing MCP servers	exposing adapter operations while also reaching non-MCP software through native commands
Discovery standards such as ARD	publishing where capabilities exist	checking a local executable path, invoking it, reporting its result, and repairing drift

Uni-CLI is not an agent framework, model runtime, hosted integration marketplace, enterprise MCP gateway, or operating system. It is the interface runtime those systems can call when an agent needs to use real software.

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, and skills describe the catalog; MCP profiles project adapter operations, while fixed-core parity remains roadmap work.

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

The MCP gateway supports stateless 2026-07-28 requests and initialization-based 2025-11-25 clients. Modern calls can negotiate the server-directed durable Tasks extension; legacy Tasks remain isolated on their original wire contract. See MCP Protocol Eras.

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 plans one task-compatible provider before execution: platform accessibility for native windows, CDP for exact browser/Electron renderers, process control for app launch, and explicit visual control for pixel-only targets.

unicli compute apps
unicli -f json compute route snapshot --params '{"app":"Calculator"}'
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 Task-Directed Capability Routing, Compute, Electron App Control, and Compute Troubleshooting.

Coverage

The catalog is intentionally broad. Catalog rows are discoverable and typed; that is inventory evidence, not proof that a third-party endpoint or login is healthy today. Fixture shape, live endpoint health, and authenticated-browser health are tracked as separate evidence layers and never added together as one "working commands" claim. Recent inventory 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 once with unicli repair <site> <command>.
7. Inspect representative rows from the original command.

unicli repair never edits source or git state. It re-runs the original command as a bounded subprocess and succeeds only when the target envelope is ok=true and its process exits 0; failures preserve the target error and exit code. Local overrides survive npm updates. See Self-Repair.

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 commands can read a live local browser/CDP session into memory. They do not persist it by default. unicli auth import and unicli browser cookies are explicit plaintext-JSON persistence paths under ~/.unicli/cookies/<site>.json (POSIX: directory 0700, file 0600).
• Browser adapters use one owner-only Browser Runtime Broker. The default managed provider is hidden and uses Uni-CLI automation profiles under ~/.unicli/; Agent sessions own distinct targets while declared profile partitions can share login/storage. Existing Chrome requires the native host and explicit background or foreground visibility. Install it with unicli browser native-host install --browser chrome, then use unicli browser native-host extension-path to locate the unpacked extension. Empty profiles require explicit unicli browser start --ephemeral or UNICLI_BROWSER_EPHEMERAL=1. 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, profile_source, chrome_remote_debugging, and broker/provider/session/lease evidence. unicli browser doctor --repair starts only the windowless broker and never starts a browser provider.
• 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 JSON or YAML rules live at ~/.unicli/permission-rules.json, or at UNICLI_PERMISSION_RULES_PATH. Schema v1 remains deny-only. Schema v2 adds deny-first allow/deny rules, an explicit default, and bounded argument constraints (min, max, max_length, RE2 pattern, allowed). Rules can also match site, command, effect, capability dimensions, and resource metadata. Direct browser/operate, compute, and computer-use MCP calls authorize before broker, transport, overlay, file, clipboard, or desktop side effects. Denials outrank --yes and remembered approvals. An explicit missing or malformed policy fails closed; the absent implicit default file leaves policy disabled. Pipeline runtime guards additionally check fetched domains, navigation targets, download/output paths, and subprocess executables at their resolved boundary.
• Run recording is opt-in. Use --record or UNICLI_RECORD_RUN=1 when you need append-only evidence under ~/.unicli/runs.
• Privacy-safe invocation diagnostics are recorded by default as 30-day, owner-only UTC JSONL files under ~/.unicli/logs/events; arguments, content, URLs, credentials, and raw errors are excluded. Inspect aggregates with unicli usage report -f json, configure retention with UNICLI_LOG_RETENTION_DAYS, or disable new events with UNICLI_NO_LOG=1.
• Explicit visual routes require a configured real backend. A missing selected provider fails closed with a structured error; execution never changes providers implicitly.
• 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

_{v1.0.1 — Artemis · Glover}